Overdeck Planning Lifecycle

pan plan <id> is the plan-ONLY verb: it starts a planning session for an issue and produces a PRD and xBRIEF, but it does not start the work agent. Use pan start <id> when you want planning and work in one command.

Use --auto when the user wants the planning agent to run non-interactively and infer defensible defaults. Use --probe when the plan needs an adversarial pre-finalize self-pass; --effort high enables the same probe instructions automatically.

Available commands

pan plan <id> [--auto] [--auto-start] [--probe] [--model <model>] [--harness claude-code|pi|codex] [--effort low|medium|high] [--local|--remote]
pan plan finalize [-w <path>] [--json] [--no-promote] [--no-quality-lint] [--no-prd]
pan plan done <id> [--no-prd]

Starting planning

pan plan PAN-1071

This calls the dashboard planning endpoint, creates the planning workspace, and starts the planning agent. The dashboard can also start the same flow from the issue card's Plan… action.

Auto-planning

pan plan PAN-1071 --auto

Auto-planning runs the same planning agent without interactive questions:

• The agent must not ask the user questions.
• Ambiguous but non-contradictory choices are resolved with defensible defaults.
• Inferred choices are recorded in plan.autoDecisions[] with a summary and rationale.
• The agent escalates only when authoritative inputs genuinely contradict each other.

The dashboard issue card's Auto-plan action sends the same auto: true request.

Probe pass

pan plan PAN-1071 --probe

--probe adds an adversarial self-review section to the planning prompt before finalize. The planner attacks hidden assumptions, ambiguous "done" criteria, unhandled failure modes, and missing dependency edges, then records acted-on findings in continue.json decisions with a PROBE: prefix. --effort high includes this section automatically.

Auto-start after planning

pan start PAN-1071

pan start <id> is the paved-road way to plan (non-interactively by default) and start the work agent in one command. The work agent auto-starts after planning finalizes.

The legacy --auto-start flag on pan plan <id> is deprecated and kept only through the deprecation window. It stamped autoSpawnOnFinalize: true into the planning agent state so pan plan finalize could start the work agent after it promoted the plan; use pan start <id> instead.

Finalizing (pan plan finalize)

Run this from inside the planning workspace after the planning agent has produced a complete .overdeck/spec.vbrief.json.

pan plan finalize

What it does:

1. Reads .overdeck/spec.vbrief.json from the current workspace (walks up if needed).
2. Validates the tasks already stored in plan.items[], including their declared dependencies.
3. Flips the spec's plan.status from draft to proposed.
4. Calls the dashboard's complete-planning endpoint to promote the canonical spec into .pan/specs/ in the project repo (or the configured plan-home repo for polyrepo projects), commit and push the feature branch, transition the tracker state to Planned, and terminate the planning session — same flow as pan plan done and the dashboard Done button.
5. Returns a summary of finalized xBRIEF tasks and promotion status, or JSON with --json.

Use -w <path> to point at another workspace. Use --no-promote to leave the spec at status=proposed without promoting (rare; for humans who want to review the plan in the dashboard before clicking Done). Finalize runs xBRIEF quality lint by default; use --no-quality-lint only as a loud one-run emergency bypass when the plan must be promoted despite known quality issues.

PRD-first gate

Finalize and complete-planning refuse to promote a plan unless a PRD draft of at least 20 lines exists for the issue. roles/plan.md has always required the PRD as the first artifact; this gate makes it mechanical. The gate searches, in order, for <ISSUE-ID>.md (uppercase then lowercase) under <projectRoot>/.pan/drafts/ then <workspace>/.pan/drafts/; the first existing file with ≥20 lines satisfies it. A found-but-thinner draft fails with its line count; a fully missing draft fails naming the canonical path to write. pan start <id> --auto is structurally exempt (it synthesizes a minimal xBRIEF and never POSTs complete-planning, so the gate cannot block it). Use --no-prd (on finalize or done) only for a genuinely trivial issue that went through interactive planning anyway — it prints a yellow ⚠ PRD gate SKIPPED warning and tells the endpoint to skip the check too.

Completing planning (pan plan done)

pan plan done <id> exists for cases where finalize was run with --no-promote, or where a planning agent crashed between writing the spec and promoting. It calls the same complete-planning endpoint that finalize chains to.

pan plan done PAN-1071

This promotes the workspace xBRIEF to .pan/specs/ in the project repo, syncs xBRIEF tasks, and transitions the tracker state to Planned. It is subject to the same PRD-first gate as finalize; pass --no-prd only for a genuinely trivial issue.

Related commands

• pan start <id> — the paved road: plan (if needed) and start implementation in one command.
• pan tell <id> <message> — send feedback to a running planning or work agent.
• pan kill <id> — stop a planning or work agent without deleting the workspace.

See also

• roles/plan.md — planning role prompt.
• docs/XBRIEF.md — xBRIEF schema, artifact locations, lifecycle states.