plan-workflow

Plan — workflow

You are operating the Plan layer: a coarse, resumable roadmap (PLAN.md) that sequences Phases, each carried by one or more Changes. Plan sits above the change engine (OpenSpec by default); it never duplicates a change's granular tasks. Read DESIGN.md in this plugin for the full rationale; this file is the operational guide.

Vocabulary (use exactly)

• Plan — the roadmap (PLAN.md); one active plan per program.
• Phase — a coarse, sequenced chunk: goal + deliverables + acceptance + status.
• Change — a unit of work that carries a phase's tasks (an OpenSpec change by default). Keep OpenSpec's word: propose / apply / archive a change.
• Invariants — the cross-cutting definition-of-done across every phase.
• Divergence — a recorded, signed-off deviation from a source of truth.

Linking verb: carry — "a phase is carried by changes."

The discipline rules (enforce these)

• R1 Coarse, never duplicated — granular tasks live only in the carrying change. The plan states goal/deliverables(coarse)/acceptance/status. Never copy a task list into the plan.
• R2 Point, don't restate — link sources of truth; never re-explain them.
• R3 Every phase maps to changes — name the change(s), each with a lifecycle state: not yet proposed → proposed → applying → landed → archived.
• R4 Status reflects reality — keep checkboxes/status current so the plan is resumable.
• R5 Divergences recorded, never silent — write deviations inline, with rationale + sign-off.
• R6 Invariants are a DoD overlay — a phase that breaks one is not done.
• R7 Plans are kept — archive completed plans, never delete.

The engine seam

The plan's header declares its change engine (Engine: OpenSpec). Drive whatever is declared; default to OpenSpec (openspec/changes/, the opsx:* commands). To carry a phase, propose a change via that engine. Never hard-assume OpenSpec is the only option, but do default to it.

Locating things

• Active plan: PLAN.md at the repo root (the one well-known location).
• Archived plans: plans/archive/YYYY-MM-DD-<program>.md.
• The PLAN.md template ships with this plugin at ${CLAUDE_PLUGIN_ROOT}/templates/PLAN.md.
• Change state (OpenSpec): openspec list --json, and the openspec/changes/ + openspec/changes/archive/ directories.

---

Procedures

Each plan:* command runs the matching procedure. Natural language routes here too (e.g. "let's start a new plan" → new; "where are we?" → status).

new — start a new plan

1. Guard the active plan. If PLAN.md exists and has unfinished phases ([ ]/[~]), STOP and confirm intent. Offer:
   • (a) archive it as-is and carry unfinished phases forward into the new plan,
   • (b) archive it as-is and drop the unfinished work,
   • (c) cancel — they meant to keep working the current plan. If PLAN.md exists and is complete, archive it first (see archive).
2. Discuss (conversational, like exploring at plan altitude): the program's goal and scope, the sources of truth, and the sequencing strategy. Do not rush to write the file.
3. Draft coarse phases — each with a goal, an acceptance bar, and dependency order. Coarse only (R1): no granular task lists.
4. Write PLAN.md from ${CLAUDE_PLUGIN_ROOT}/templates/PLAN.md: fill the header (Program, Status: active, Engine, Started date, Sources of truth), list the phases, and mark every carrying change not yet proposed. State the cross-cutting invariants and the out-of-scope list.

status — where are we

1. Read PLAN.md. Read change state via openspec list --json (or the declared engine's equivalent).
2. Report: current phase, each phase's state, the lifecycle state of each carrying change, and what's next. Surface any drift you notice (see validate), but don't fix it unasked.

next — what to build next

1. From PLAN.md, find the next unstarted deliverable/phase respecting dependency order.
2. Summarize what it is and its acceptance bar, then hand off to the change engine to carry it — for OpenSpec, propose the change (opsx:propose), and record the change name + proposed state on that phase in PLAN.md.

advance — land a deliverable/phase

1. Confirm the work actually landed (the carrying change applied/archived; tests green; acceptance met; invariants R6 still hold).
2. Update PLAN.md: flip the checkbox(es) to [x], update the phase Status with a date and a one-line outcome, and set the carrying change's lifecycle state (e.g. landed or archived).
3. Record any divergence (R5) discovered while landing.

archive — finalize a completed plan

1. Verify the plan is complete (all phases [x], or the user has explicitly accepted remaining work as out-of-scope).
2. In PLAN.md, set Status: complete and stamp the Completed date.
3. Move it to plans/archive/YYYY-MM-DD-<program>.md (creating plans/archive/ if needed). The date is the completion date; the suffix is the program identity (e.g. 2026-06-11-minerva-v3.md).
4. Offer to chain into new for the next program.

validate — drift check (R3/R4)

Reconcile the plan against real change state and report mismatches; fix only what the user approves. Check:

• every Carried by: <name> resolves to a real change (active or archived);
• every [x] phase's change is archived (not still active);
• every archived change is reflected by a [x]/landed phase (no silent drift);
• sources-of-truth links resolve.

This runs as an agent-driven check today (read PLAN.md + openspec list); a fast CLI is a future, optional addition.

Guardrails

• Don't violate R1: if you're tempted to paste a task list into the plan, that's the change's job — link it instead.
• Don't silently update status that isn't real (R4) or hide a deviation (R5).
• Keep plans prose. Don't impose a rigid schema or frontmatter.
• One active plan. Don't create a second PLAN.md without archiving the first.