Wf Spec Drive

Drive a Spec Through the Lifecycle

Advance the spec at the first argument toward a target state (default complete), one or more legal transitions at a time, reporting the new state at the end of every turn. This is the orchestrator: it reads reality, picks the next step, runs the right /wf-spec-* sub-skill (or transition API call), and stops at gates.

It is built to be re-invoked: under a /goal the Stop-hook evaluator re-runs you each turn with the remaining work, so each turn must (a) make concrete progress and (b) end by stating the spec's current status in your message, so the evaluator can judge whether the goal is met. Within a turn, carry the spec through every legal, non-gated transition you can; end the turn at a gate, at the target, or when the next step waits on work outside this session.

The canonical lifecycle

Seven states. status is the single source of truth; transitions must follow the legal edges below — there is no implemented/in_progress state, and validated → complete is ILLEGAL. A spec reaches complete only through testing, where a drift verdict is rendered.

vague      → drafted | archived
drafted    → validated | stale | archived
validated  → testing | stale
testing    → complete | stale | archived
complete   → stale | archived
stale      → drafted | validated | archived
archived   → drafted            (resurrection)

Server-automatic vs. agent-initiated:

How status changes (hybrid)

By default there is no server: advance the status by editing the spec's frontmatter along a legal edge and committing it, exactly as the other skills do.

Where a transition API is present, prefer it because it is authoritative, validates the edge, runs drift / stale fan-out, and commits: POST /api/specs/transition with { "action": "<action>", "path": "<workspace-relative spec path>" }. Actions: dispatch, undispatch, archive, unarchive, validate, stale, unstale, dismiss-stale, force-complete, migrate. /wf-spec-dispatch uses the same endpoint.

Whether you edit frontmatter or call the API, only ever move along a legal edge above. Never write an illegal jump (e.g. validated → complete).

Note there is no API action to enter testing or to complete from validated directly; the server enters testing on task-done, and force-complete only does testing → complete. The direct-implement path (below) therefore walks validated → testing → complete itself.

Step 1: Read reality

1. Read the spec's frontmatter: status, dispatched_task_id, depends_on, affects, and whether it has a child-spec directory (non-leaf).
2. If dispatched_task_id is set, check the linked task's status (done / in_progress / failed) on the board, where one exists.
3. Establish the target (arg 2, default complete) and confirm the spec is not already there or past it.

Step 2: Pick the next step (decision table)

Match the current status and choose the next action toward the target:

Dependencies: before implementing/dispatching, confirm every depends_on is complete (per the sub-skills' own gates). If a dependency is not complete and the target requires it, drive the dependency first or report the block.

Step 3: Gate check before acting

Pause and ask the user (do not execute) when the next step is:

• Dispatch to the board (creates outward work / a running task).
• Archive (retires the spec + descendants; relocates files).
• Stale fan-out across a dependency tree (marks other people's specs stale) — manual stale on a spec with dependents.
• force-complete (overrides the drift gate).

For all other steps (refine, validate, breakdown, implement-direct, wrap-up of a spec you implemented this run), proceed without pausing.