Spec To Done

Spec to Done

Route work through SPECIFY → PLAN → EXECUTE ↔ REPLAN → REPORT.

This skill decides and hands off. It holds no planning, execution, or reporting rules — those live in the skills it routes to, and duplicating them here would create a second source of truth that drifts. If you catch yourself explaining how to write a task or a report, stop and hand off instead.

Step 1 — Locate the work first

Derive a slug from the goal — short kebab-case — and look at spec-interview/<slug>/. If the user is resuming and the slug is unknown, list the folders and ask which one.

Match on the goal, not on the slug. If a folder already exists, compare its stored goal to what the user is asking for now — the Goal: line in PLAN.md or SPEC.md (older SPECs may only have a Summary — use it); failing that, the scope restatement that opens state.md. If none of these exists yet, ask the user whether the folder is the same work before touching it. Different work can produce the same slug — two "export" features, two "cleanup" tasks. When the stored goal is not this goal, do not resume it: pick a distinguishing slug and start fresh. Silently continuing an unrelated run corrupts both records.

Locating comes before deciding, because the gate below must never fire on work that already exists.

Step 2 — Does new work need the loop?

Only for work with no folder yet. An existing run is never subject to this gate — it already has a contract and a ledger, and finishing it outside them would strand the record it was keeping.

Most new work does not need the loop. It costs a requirements interview, a plan file, a verification and a ledger entry per task, and a replan checkpoint after each one. That overhead buys traceability and resilience over a long horizon; on a small change it buys nothing.

Run the loop when at least two of these hold:

• the work is more than a handful of tasks;
• it will not finish in one sitting, or will outlive one context window;
• getting the requirements wrong is expensive to undo;
• execution is likely to discover things that change the approach;
• someone needs to audit afterwards what was done and on what evidence;
• the work will be handed between people, sessions, or agents.

Otherwise just do the work. Say in one line that you are skipping the loop and why — do not run a ceremony to look thorough.

Between the extremes, offer the middle: plan-from-spec and execute-plan on a stated goal, skipping the SPEC interview.

Step 3 — Route on what exists

First matching row wins.

Replanning is never a direct route from here. execute-plan owns its replan gate, calls plan-from-spec itself, and closes the Gate: line afterwards — only it writes the ledger. Do not intercept that loop.

Interrupted mid-loop

Every task has an entry, but the run is not finished. Read the last entry's Gate: line:

This is why execute-plan closes every entry with Gate:. Without it, an interrupted run and a terminally blocked one look identical from the folder.

Reopening after replan exhausted

replan exhausted means no valid plan existed under the conditions of that moment — not that the goal is dead. When the user returns saying the blocker is resolved — access granted, decision made, dependency available — do not start a new run and do not re-gate the work. Hand off to execute-plan with the user's report: it owns the replan loop, so it confirms the resolution — observably when a check exists, by the user's explicit confirmation (attested) otherwise — and then invokes plan-from-spec in replan mode itself, with the resolution as the trigger. Routing straight to the planner from here would bypass the owner of the gate and the ledger. The exhausted entry's Gate: becomes replan reopened (plan version N), so the stop and the restart both survive in the ledger even after later replans replace the plan text.

Non-product work with unclear requirements

Do not send this to spec-from-scratch — its interview and output are shaped for product work, and it would force user journeys and launch criteria onto research, operations, or physical-world goals.

Clarify it here instead, in as few questions as it takes: what does done look like, what must not happen, and what constrains the approach. As soon as you can name at least one checkable outcome condition, hand to plan-from-spec with the goal stated directly. If the goal resists that after a couple of rounds, say so — a goal with no checkable outcome cannot be planned, only discussed.

Step 4 — Hand off cleanly

One stage at a time. Name the skill you are invoking and why, then let it own its own contract, gates, and output. Do not pre-chew its work, and do not second-guess its gates from here — a readiness gate that fails means another round in that stage, not an override from this one.

When a stage escalates to the user — an unreachable acceptance criterion, a destructive action, a missing credential — surface it and stop. Escalations are the user's decision, and routing around one defeats the point of having it.

Resuming

When the user asks where things stand, read the folder and state it plainly before routing:

Goal:        <from PLAN.md, SPEC.md, or state.md>
Plan:        version <N>, <M> tasks
Progress:    <k> done, <k> unresolved
Last entry:  <task id, status, and its Gate line>
Blockers:    <from the ledger, or none>
Next:        <the row that matched in step 3>

The ledger is the source of truth for progress, not memory of the conversation.

When the user wants one stage only

Honor it. "Just write me a plan" ends at plan-from-spec. "Just tell me what happened" is completion-report alone. Do not drag someone through the whole loop because they touched one part of it.