spec

Specification-driven development — create structured plans from requirements, execute them autonomously in the background, and track progress to completion.

Workflows

new — create a plan

Explore requirements and produce a multi-phase implementation plan with objectives, design decisions, and per-phase specs. Every task carries the complete, ready-to-write code it will produce. Before new reports a plan ready, a mandatory code-completeness gate scans every task and rejects stubs, placeholder markers, omitted code, and prose-only descriptions; it reruns after repairs and fails closed if literal code cannot be resolved. --validate still adds the broader multi-agent validation pass.

Enumerable sets in the objective or intent are tabulated: rote replacements, target sets to search or touch, and enumerated requirement lists each get a row-per-item table under .codevoyant/spec/{plan}/tables/, enumerated from the codebase (never from memory), with every requirement row carrying an Intent ref back to intent.md. A completeness gate re-runs each table's enumeration, checks every intent item appears in a row and every row is owned by exactly one task, and fails the plan on any dropped item, orphan row, or drift.

Two ways to give the objective:

• Inline objective — a description; planning starts immediately.
• Bare name — just a name; new scaffolds .codevoyant/spec/{name}/intent.md, prints its path (and opens it in your editor when possible), and stops. Fill it in, then re-run /spec new {name} and it plans from your intent, asking only what's still unclear. (Legacy drafts stay under .codevoyant/plans/{name}/ until the v1→v2 store migration runs; reads fall back to it.)

/spec new add OAuth login to the settings page  # inline objective → plans now
/spec new auth-refactor                          # bare name → writes intent.md to fill in
/spec new auth-refactor                          # re-run after filling → plans
/spec new https://linear.app/team/issue/ENG-42  # seed from Linear issue
/spec new https://github.com/org/repo/issues/7  # seed from GitHub issue
/spec new my-feature --branch                   # create/switch to a branch (name derived from the slug)
/spec new my-feature --branch feature-branch    # create/switch to a branch with an explicit name
/spec new my-feature --worktree                 # create a worktree under .codevoyant/worktrees/<branch>
/spec new my-feature --worktree ../wt           # create a worktree at an explicit path
/spec new my-feature --branch feat --worktree ../wt  # branch + worktree at an explicit path
/spec new --blank                               # empty template, no planning session
/spec new my-feature --bg                       # create and immediately start background execution
/spec new my-feature --validate                 # run a validation pass on the plan before finishing
/spec new my-feature --persistent               # EXPERIMENTAL — doc-aware planning

--branch and --worktree are independent — each does one thing, and neither implies the other. --branch creates or switches to a branch (bare: derived from the plan slug; with a name: that name). --worktree creates a worktree (bare: .codevoyant/worktrees/<branch>; with a path: that path). Both delegate to the shared /git worktree routine.

--persistent is an experimental doc-aware mode: docs are written first, every phase is scoped to the doc globs it may write, and cross-module interaction happens only through documented public interfaces. Cross-module changes are discouraged by default (Rule 7): a phase that must write across module boundaries has to call the crossing out with a reason and a rejected restructure, and the executor refuses uncalled-out crossings. It requires valid docs in the repo (docs/ with globs: frontmatter plus an architecture index or a component doc with a public API/interface section); new refuses to plan blind otherwise. See the skill's references/doc-aware.md for the full model.

Pass a Linear, GitHub, or GitLab issue URL as the first argument to pre-fill requirements from the issue title, description, and comments.

go — execute a plan

Spawn an autonomous background agent that reads implementation files, updates plan checkboxes in real time, runs tests at phase boundaries, and sends a desktop notification on completion. Independent phases run in parallel on a fast (light) executor for responsiveness, escalating to a heavier tier only when a phase hits genuine trouble.

/spec go                                # auto-selects most recently updated plan
/spec go my-feature                     # execute specific plan
/spec go my-feature --yes               # skip all confirmations
/spec go my-feature --commit            # allow git commits during execution
/spec go my-feature --silent            # suppress desktop notification on completion

guide — interactive walkthrough

Walk through a plan phase by phase, task by task, with tutorial-style guidance. After each task you decide: proceed, skip, or improvise.

/spec guide                             # auto-selects most recently updated plan
/spec guide my-feature                  # guide specific plan
/spec guide my-feature --phase 2        # start at phase 2

Pass --vim to inject editor key binding hints at each task step:

/spec guide my-plan --vim               # vim hints

update — apply annotations

Process inline annotations written directly in plan files, or accept a conversational description of changes.

/spec update                            # auto-selects most recently updated plan
/spec update my-feature                 # apply annotations in specific plan
/spec update my-feature --bg            # apply in background, notify when done
/spec update my-feature --persistent    # EXPERIMENTAL — doc-aware update

Two annotation forms, both written as HTML comments so they never collide with real markdown blockquotes: <!-- > instruction --> on a standalone line (minor) applies to the block below; content <!-- >> instruction --> inline (major) applies to that line only.

--persistent (experimental) applies the doc-aware model to plan edits: every change is checked against the plan's Doc Globs: scope, and edits that cross it are flagged as boundary callouts for explicit confirmation.

split — split a large plan

Split an existing plan into two independently executable plans at a chosen phase boundary.

/spec split                             # auto-selects most recently updated plan
/spec split my-feature                  # pick a phase boundary interactively

review — review plan quality

Check a plan for complete ready-to-write code before any other review, then assess ambiguous tasks, missing validation steps, unrealistic ordering, and dependency gaps before running go.

/spec review                            # auto-selects most recently updated plan
/spec review my-feature                 # review specific plan

Produces a review.md report and auto-fixes mechanical issues. The code-completeness gate is blocking: review cannot report a ready verdict until every implementation task passes it. Run this before /spec go.

refresh — sync checklist status

Review what has been done and update checkboxes and phase markers in plan.md to reflect current state.

/spec refresh                           # auto-selects most recently updated plan
/spec refresh my-feature                # refresh specific plan
/spec refresh my-feature --bg           # refresh in background, notify when done

clean — session wrap-up

Stop running agents, triage remaining active plans, and optionally export session artifacts before clearing.

/spec clean                             # full session wrap-up across all plans
/spec clean my-feature                  # clean up a specific plan only

polish — strip AI verbosity from execution outputs

Run a cleanup pass on files modified during a plan's execution. Removes comments that restate code, rhetorical flair in docs, and unnecessary preamble.

/spec polish                            # auto-selects most recent plan
/spec polish my-plan                    # polish a specific plan's output files

Never changes code logic. Reads execution-log.md to find modified files, runs parallel cleanup agents per file, and reports what was removed.

allow — pre-approve permissions

Write the allow entries needed for /spec go to run without permission prompts.

/spec allow                             # write to project .claude/settings.json
/spec allow --global                    # write to ~/.claude/settings.json

help — list commands

/spec help                              # list all spec commands with descriptions

Annotations

Annotate a plan file with <!-- @agent: guidance --> or <!-- @edit: instruction -->, then run /spec update <plan>. See skills/shared/annotations.md.