Spec To Plan

spec-to-plan — work a converged spec forwards into a buildable plan

The skill is named spec-to-plan; the product/CLI it drives is the devague plan command group. (The prior leg — turning a vague idea into a spec — is the sibling /think skill.) It is the forward peer of the working-backwards spec engine: where /think converges on what to build, /spec-to-plan converges on how to build it.

A plan is seeded from a converged frame and tracks tasks against the spec's coverage targets. The CLI is deterministic and move-driven — you (the agent) choose the next move; the CLI tracks state and tells you what's still missing. Run devague plan learn for the method and devague plan explain <move> for any single move.

How to run

The entry point is scripts/spec-to-plan.sh. Invoke it from the repository you are speccing (plans persist under .devague/ in the current directory, alongside the frames they derive from):

bash .claude/skills/spec-to-plan/scripts/spec-to-plan.sh <move> [args...]
bash .claude/skills/spec-to-plan/scripts/spec-to-plan.sh status

It resolves the CLI portably — an installed devague on PATH (the normal case), falling back to uv run devague inside the devague checkout, else an install hint. Every move — including status — is forwarded verbatim as devague plan <move>, so you can equally call the CLI directly (devague plan <move> …).

Moves

Risk kinds (shared with the frame engine): unknown_nonblocking, unknown_blocking, out_of_scope, follow_up.

status — the next-move verb

status is a first-class, read-only CLI verb (devague plan status, internalised from this wrapper in 0.11.0 — issue #30). It composes devague plan list + devague plan converge and prints where the current plan stands, the remaining gaps, and the recommended next move derived from the first gap. Like converge/export it re-checks the live source frame (so frame drift surfaces as an error), but it never mutates state. Pass --json for the structured payload ({plan, total, ready_for_plan, blockers, warnings, parked_items, required_next_moves}).

plan: my-feature    (1 plan total)
convergence: NOT passed — 2 gap(s):
  - coverage target c5 (boundary) has no confirmed task
  - task t2 has no acceptance criteria

recommended next move (first gap):
  cover c5: devague plan task "<summary>" --covers c5 --accept "<...>"

Run it whenever you're unsure what to do next.

After every successful, non-exempt move (status itself is exempt, since reporting the next move is already its whole purpose) the CLI also prints a next: <recommended move> line to stderr. Follow that hint or run devague plan status — either gets you the same recommended next move.

Hard rules (do not violate)

These are the point of the method — convergence must mean something.

• Seed from a converged spec only. plan new refuses a frame that hasn't converged. The plan's coverage targets are the spec's confirmed claims and honesty conditions — there is nothing honest to plan against until the spec converges.
• LLM proposals stay proposed. A task captured with --origin llm lands as proposed. Never confirm your own proposal. Confirmation is a user-only decision — surface the proposed task and let the user confirm or reject it.
• Cover every target; criteria on every task. The gate requires every coverage target to be covered by a confirmed task, and every confirmed task to carry at least one acceptance criterion. Don't hand-wave a task as "done-ish."
• Never fake coverage to satisfy the gate — defer instead. If a target is deliberately out of scope (a later milestone, a separately reviewed change), do not write a task that merely mentions it so coverage goes green. That is the exact dishonesty devague#85 was filed about: a task claiming a target it does not deliver looks perfectly healthy to the gate. Run devague plan defer <target-id> --reason "<why>" — the target stops blocking converge and is named, with its reason, in the exported plan's Deferred targets section, so the exclusion is visible to a reviewer instead of implied by absence. Deferring is a scoping decision: surface it to the user, don't take it unilaterally.
• Keep the graph honest. Dependencies must reference real tasks and form an acyclic graph; the gate rejects dangling deps and cycles.
• Park real unknowns as risks; don't paper over them. A genuinely unknown decision is an unknown_blocking risk — it holds back convergence, by design.
• Converge against the live frame. converge/export re-load the source frame every time. If the frame was deleted or has regressed below convergence, they refuse — re-converge the spec (in /think) first.
• File the record the moment the thing happens, never at closeout — written late is written flattering (issue 97).

Coaching toward small, file-disjoint, TDD-gated tasks

When authoring a plan that will be built via parallel execution (fanned out to multiple agents via the downstream /assign-to-workforce skill), prefer the following discipline to maximize parallelism and minimize merge friction:

Acceptance criteria are the testable contract; instruction is the working guidance

Two fields now do two distinct jobs on every task (shipped: devague#53 t5):

• --accept "<criterion>" (repeatable) — the testable contract: what a test suite checks to prove the task done. Write each as something a cheaper model can be validated against test-first: name the files or modules the task owns, the observable behavior that proves it done, and the compatibility constraints ("pre-existing plans load with no error"). A criterion a subagent can't be validated against alone is a summary, not a contract.
• --instruction "<text>" (at task time) / instruct <tN> "<text>" (afterwards) — verbatim working guidance carried to the subagent: the approach to take, which files to touch first, anything the acceptance criteria don't spell out. Write it yourself; never invent filler to satisfy the gate. Changing it on an already-confirmed task flips the task back to proposed — the user re-confirms.

devague plan converge warns (non-blocking) when a confirmed task carries no instruction:

task t1 has no instruction — attach operator guidance with `devague plan instruct t1 "<text>"`

Neither field replaces the other: acceptance criteria stay the pass/fail gate; instruction is what a subagent reads before it starts, quoted verbatim (never paraphrased) into the brief — see The waves --json payload below.