task-lifecycle.mdx

June 8, 2026 ยท View on GitHub

Overview

Minimal branch_pr lifecycle

This repository is configured for branch_pr, so the normal guarded route is:

  1. Preflight.
  2. Create the task and approve the plan.
  3. work start ... --worktree on base, then execute implementation on the task branch/worktree.
  4. Run task start-ready, implement, and commit implementation changes in the task worktree.
  5. Keep PR artifacts current with pr open / pr update; normal pr open also publishes and links the hosted PR.
  6. Run task verify-show and verify on the task branch, then wait for required remote checks.
  7. finish on the task branch with --commit <git-rev> and --pre-merge-closure.
  8. Run integrate on the base branch only after verification and remote checks pass.
  9. Clean up the task worktree/branch after hosted merge closure.
agentplane config show
agentplane quickstart
agentplane task list
git status --short --untracked-files=no
git status --short --untracked-files=all
agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree
agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."
git add <changed-files>
git commit -m "Implement <task>"
agentplane task verify-show <task-id>
agentplane pr open <task-id> --branch task/<task-id>/<slug> --author <ROLE>
agentplane pr update <task-id>
agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."
agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev> --pre-merge-closure
bun run workflow:wait-remote-checks
agentplane integrate <task-id> --branch task/<task-id>/<slug> --run-verify
agentplane cleanup merged --finalize

direct remains supported, but here it is an explicit alternative rather than the default guarded route. Local agentplane integrate defaults to merge so task branch commits stay in base history. On protected bases, the GitHub PR finalization path prefers rebase merge so task commits remain visible without an extra GitHub merge commit. Pass --merge-strategy squash only when compacting history is intentional.

Default branch names are task/<task-id>/<slug> for implementation and task-close/<task-id>/<sha12> for close-tail evidence. The repository can override the prefixes with branch.task_prefix and branch.task_close_prefix; the rest of the shape is fixed.

AgentPlane-owned automation boundaries

In branch_pr, agents should treat task brief and task next-action --explain as the live boundary for operations AgentPlane already owns. Run the emitted command, then recompute the route before doing another lifecycle step.

  • work start / work resume own task branch and worktree setup; do not hand-roll branch names or worktree creation when the route packet gives an exact command.
  • pr open / pr update own PR artifacts, branch publication, and hosted PR creation/linking; do not edit .agentplane/tasks/<task-id>/pr/* or create the hosted PR manually unless the route explicitly delegates a fallback.
  • pr update / pr check own PR artifact freshness; do not repair stale PR metadata with manual edits or amend commits.
  • evaluator run records quality_review.evaluated_sha for the last non-task-artifact commit; if the current quality report is stale, rerun the evaluator on current HEAD instead of creating an amend commit just to align the SHA.
  • integrate queue / integrate --run-verify own the serialized merge lane and hosted-check gate; do not merge, rebase, squash, or rewrite task branch history outside that route.
  • finish --pre-merge-closure, task hosted-close-pr, and hosted close own close-tail evidence; do not recreate close-tail artifacts after upstream close has landed.
  • cleanup merged owns merged branch/worktree cleanup; do not silently delete task worktrees or remote branches outside the cleanup route.

Route decision commands

When a branch_pr task has been interrupted, partially verified, or merged through hosted close, prefer the route-decision commands before manually combining low-level diagnostics:

agentplane task status <task-id> --route
agentplane task next-action <task-id>
agentplane work resume <task-id>
agentplane flow repair <task-id> --dry-run

These commands read task state, workflow mode, current checkout, PR metadata, hosted PR state, and close-tail state, then print a single next action plus blockers. flow repair is intentionally dry-run in this release: it classifies drift and prints the commands that would repair it, but it does not mutate task, branch, PR, or close-tail state.

Minimal direct lifecycle

If the repository is intentionally operating in direct, the shortest agent-first route is:

  1. Preflight.
  2. Create the task and approve the plan.
  3. task start-ready.
  4. Implement changes.
  5. task verify-show -> verify.
  6. finish with --result and --commit.
agentplane config show
agentplane quickstart
agentplane task list
git status --short --untracked-files=no
git status --short --untracked-files=all
agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."
agentplane task verify-show <task-id>
agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."
agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev>

Everything else in this document is either mode-specific detail or a fallback path.

A task moves through the same core stages in both modes:

  1. Intake: a need is identified and recorded.
  2. Plan: ORCHESTRATOR drafts a plan and requests approval.
  3. Create: PLANNER creates the task, assigns ownership, and sets dependencies.
  4. Start: the executor marks the task DOING with a structured comment.
  5. Implement: code, docs, and artifacts are produced.
  6. Verify: checks are run (if configured) and a verification outcome is recorded.
  7. Commit: changes are committed with the task ID suffix.
  8. Finish: the task is closed with a Verified note, commit metadata, and an Agent Change Record refresh when acr.write_on_finish=true.
  9. Evidence projection: validate the task-local Agent Change Record against task, policy, verification, finish, and Git evidence.
  10. Project and integration projections (optional): advanced maintenance surfaces can export or regenerate derived task projections from the current backend state.

Task creation targets executable work only. Task graph planning splits work into atomic tasks, each assigned to one specific owner.

The differences between modes are about where work happens and who performs closure.

Lifecycle flow

flowchart TD
  A[Intake: need discovered] --> B[Plan: ORCHESTRATOR drafts plan]
  B --> C{Approval granted?}
  C -- No --> B
  C -- Yes --> D[Create task: PLANNER assigns owner + deps]
  D --> E[Start: executor sets DOING and Start comment]
  E --> F[Implement changes + docs]
  F --> G[Verify: run checks and record outcome]
  G --> H[Commit with task suffix]
  H --> I[Finish: Verified comment + commit metadata]
  I --> J[Export snapshot if needed]

direct mode (single checkout)

Where work happens: in the current checkout.

Who closes the task: the executor (often CODER/DOCS/TESTER) after the implementation commit.

Key outputs:

  • Task README and status updates are written directly in the repo.
  • Verification records are appended to the task README under ## Verification via agentplane verify ....
  • PR artifacts are optional in this mode.

Sequence diagram (direct)

sequenceDiagram
  autonumber
  participant U as User
  participant O as ORCHESTRATOR
  participant P as PLANNER
  participant E as Executor (CODER/DOCS/TESTER)
  participant CLI as agentplane CLI
  participant B as Backend
  participant G as Git

  U->>O: Request change
  O->>U: Plan + approval request
  U-->>O: Approve
  O->>P: Plan executable task graph
  P->>CLI: task new / update
  CLI->>B: Write task + deps
  E->>CLI: start <task-id>
  CLI->>B: Update task status + comment
  E->>G: Implement changes
  E->>CLI: verify <task-id> --ok --by <id> --note <text>
  CLI->>B: Append verification record
  E->>CLI: guard commit / commit
  CLI->>G: Create commit
  E->>CLI: finish <task-id> --author <id> --body <text> --result <one-line>
  CLI->>B: Close task + store commit metadata
  CLI->>B: Refresh task-local acr.json when enabled
  E->>CLI: acr validate / acr explain (optional)

branch_pr mode

Where work happens: in a per-task branch/worktree.

Who closes the task: INTEGRATOR on the base branch after merge.

Key outputs:

  • PR artifacts are required under .agentplane/tasks/<task-id>/pr/.
  • Canonical task writes happen on the base branch only.
  • Handoff notes are appended during review and carried into closure.
  • Hosted PRs and server-side required checks are separate from local agentplane pr ... artifacts.

Sequence diagram (branch_pr)

sequenceDiagram
  autonumber
  participant U as User
  participant O as ORCHESTRATOR
  participant P as PLANNER
  participant E as Executor (CODER/DOCS/TESTER)
  participant I as INTEGRATOR
  participant CLI as agentplane CLI
  participant B as Backend
  participant G as Git

  U->>O: Request change
  O->>U: Plan + approval request
  U-->>O: Approve
  O->>P: Plan executable task graph
  P->>CLI: task new / update
  CLI->>B: Write task + deps
  E->>CLI: work start <task-id>
  CLI->>G: Create branch + worktree
  E->>CLI: start <task-id>
  CLI->>B: Update task status + comment
  E->>G: Implement changes
  E->>G: Commit changes
  E->>CLI: pr open / update
  CLI->>B: Write PR artifacts
  CLI->>G: Publish/link hosted PR
  E->>CLI: verify <task-id> --ok --by <id> --note <text>
  CLI->>B: Append verification record
  E->>G: Wait for required hosted checks
  G-->>E: Required checks green
  I->>CLI: pr check / integrate
  CLI->>G: Merge to base (merge commit by default)
  CLI->>B: Refresh diffstat + README summary
  I->>CLI: finish <task-id> --author <id> --body <text> --result <one-line>
  CLI->>B: Close task + store commit metadata
  CLI->>B: Refresh task-local acr.json when enabled
  I->>CLI: acr validate / acr explain (optional)

Guardrails and policies

  • Approvals: plan, network, and verification approvals are enforced via config (agents.approvals.*).
  • Preflight depth:
    • agentplane preflight uses quick mode by default (fast, no backend task-list probe).
    • agentplane preflight --mode full adds backend task-list readiness checks.
  • Status comments: start/block/finish require structured text (Start/Blocked/Verified).
  • Allowed status transitions:
    • TODO -> DOING|BLOCKED
    • DOING -> DONE|BLOCKED
    • BLOCKED -> TODO|DOING
  • Status-commit major transitions:
    • TODO -> DOING
    • DOING -> BLOCKED
    • BLOCKED -> DOING
    • DOING -> DONE
  • Two-stage verification:
    • ## Verify Steps is the ex-ante verification contract (criteria/protocol addressed to the verifier).
    • ## Verification is the ex-post append-only record written by agentplane verify ....
  • Task-local observations:
    • Active doc_version=3 tasks use ## Findings for local deviations, follow-ups, and incident candidates.
    • Policy incidents are curated separately; they are not written directly from every task.
  • Primary-tag verification policy:
    • Verify-step and verification requirements are controlled by tasks.verify.require_steps_for_primary and tasks.verify.require_verification_for_primary.
  • branch_pr verify logs: agentplane integrate --run-verify executes frontmatter verify: commands and appends output to .agentplane/tasks/<task-id>/pr/verify.log.
  • Agent Change Record: ACR is generated from the same lifecycle evidence, defaulting to .agentplane/tasks/<task-id>/acr.json; it must validate against task state rather than become a separate task source of truth.
  • Commit policy: commit subjects must include the task ID suffix.
  • Preferred close flow (single command):
    • In direct, agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --commit <git-rev> closes task metadata and creates the deterministic close commit in one step by default.
  • Exceptional/manual close paths:
    • Use --no-close-commit only when you need to leave close handling manual.
    • In branch_pr, or when you want to be explicit, use --close-commit.
    • Add --close-unstage-others when unrelated staged files are present and you are using explicit --close-commit.
  • Docs updates: task README sections are updated via agentplane task doc set; keep the active doc_version contract explicit when editing task docs.
  • Advanced closure and maintenance commands: exceptional close helpers, hosted-close recovery, projection export, and task migration commands are not part of the normal user lifecycle. Use agentplane help --all when maintaining Agentplane itself or recovering legacy state.

Lifecycle and close taxonomy

The close surface is locked around one rule: a close command must make the task state, task README, and git history agree about the terminal outcome. The commands below differ by workflow mode and by whether the task is closed as completed work, a no-op, a duplicate, or a hosted PR outcome.

Normal users should use finish for task completion and pr close commands only for hosted PR lifecycle. The no-op, duplicate, hosted-close, hosted-close-pr, and migration helpers are advanced maintenance surfaces. They remain implemented and available through agentplane help --all, but they are intentionally not part of the public happy path.