spek-plan

Version check first. Before running any other command, run go run . version check.

• On status: "match", continue with the skill and produce no version-related output.
• On "mismatch" or "missing", the installed Spektacular files are out of date: relay the response's action message to the user, ask them to re-run go run . init <agent>, and wait for their decision before continuing.
• Never modify or re-install any installed files yourself — refreshing the installation is always an explicit, user-initiated re-run of init.

STOP. Read this before running any command below. A single successful CLI call — including the very first plan new — is NOT task completion. It is not a milestone to report back to the user. It is one step out of many in a workflow that you must keep driving, turn after turn, without stopping, until the CLI itself tells you the workflow is finished. If you find yourself about to say "successfully completed" or summarize results after calling plan new or plan goto even once, you are wrong — go back and read the instruction field you just received, do what it says, and call goto again.

What this skill does

This skill drives a multi-step interactive workflow that produces a complete implementation plan — the assembled plan.md, context.md, and research.md documents committed to the plan store — from an existing spec. The workflow is owned by the go run . CLI, not by you — the CLI is the state machine and you are the executor, and the CLI (not the filesystem) is how you reach every plan document.

On each turn, the CLI returns JSON containing an instruction field. That instruction describes exactly one step (e.g. discovery, data structures, phases, testing approach, walkthrough, …). You must:

1. Read the instruction carefully.
2. Perform the step — this may mean researching the codebase, spawning subagents, interviewing the user, or committing a plan document to the store.
3. When the step is complete, run the goto command named at the bottom of the instruction to advance the state machine.
4. Read the next instruction from the new JSON response and repeat.

This is a loop. Do not stop after the first step. Keep looping — step → goto → next instruction → step — until a returned instruction tells you the workflow is finished. Only then should you report completion to the user.

Concretely: do not stop after plan new. That command only starts the workflow — it returns the first instruction (the overview step), not a finished plan. Seeing a clean JSON response with no error is not a signal to stop; it is the signal to keep going. Reporting success, summarizing "plan initialized," or handing control back to the user at this point is the single most common way this skill is executed incorrectly — do not do it.

The workflow ends with a mandatory walkthrough review. After the three documents are committed to the store, the CLI renders the walkthrough step: walk the user through the committed plan section by section, apply any requested changes immediately through go run . plan file write, and only advance to finished once the user gives an explicit affirmative answer to a direct closing question. Committed documents are not completion — the workflow is finished, and the plan approved, only after the user signs off during the walkthrough and the finished step has run.