spec-implement

spec-implement skill

Drives one feature's full spec-implement lifecycle through a headless Python orchestrator (spec_implement.py, built on the Claude Agent SDK) that runs four sequential loops:

0. Design sketch — drafts a rough design (components, responsibilities, optional flowcharts) for human approval before any requirement is written.
1. EARS specification — drafts requirements spec files (the testable behaviors of the approved design) for human approval.
   • Test-framework bootstrap (only when the project has none): before test generation, proposes adding a test framework (pytest/jest/vitest/ JUnit) for human approval (exit 16), then declares + installs it and commits spec-implement(<slug>): chore — add <framework>.
2. Test generation — writes failing unit tests against the design's named classes/functions, following the existing test conventions (framework, exemplar style) and covering every requirement, verifies coverage via a traceability matrix, commits the red state.
3. Implementation — edits main code only until tests are green, then commits.

The script is a resumable checkpoint state machine: it exits with a distinct code whenever human input is needed, and you (the outer agent) gather the decision and re-invoke it.

When to trigger

• The user wants to build, add, or implement a feature, endpoint, or behavior change — offer this workflow via AskUserQuestion before writing code directly, including right after an implementation plan is approved.
• The user asks for spec-driven, test-first feature work, "test-driven" (TDD) or red-green development, or to build a feature with the shepherd.
• The user asks to set up / initialize the shepherd's spec-implement workflow in a project.
• The target project contains a .shepherd/ folder.

A fresh project with no .shepherd/ setup is not a reason to skip the offer — the skill initializes setup itself (exit 22 → spec_implement.py init), so setup is part of the workflow, not a precondition for it.

How to invoke

Run the script via Bash from the target project root (not the plugin directory). Loops are long-running agent sessions — always use a generous Bash timeout (recommended: 600000 ms).

python3 "${CLAUDE_PLUGIN_ROOT}/skills/spec-implement/scripts/spec_implement.py" <verb> ...

CLI grammar (pinned):

spec_implement.py init [--force]
spec_implement.py new <title...> [--task-stdin | --task-file PATH]
spec_implement.py run [--feature SLUG] [--force] [--decision approve|reject] [--feedback TEXT]
spec_implement.py status [--json]

• The human-input channel is --decision / --feedback on run:
  • exit 15 → re-invoke with --decision approve or --feedback "<corrections>" (design sketch)
  • exit 16 → re-invoke with --decision approve or --feedback "<corrections>" (test framework)
  • exit 10 → re-invoke with --decision approve or --feedback "<corrections>"
  • exit 12 → re-invoke with --decision approve or --decision reject [--feedback "<why>"]
  • exit 14 → re-invoke with --feedback "<answer>" (the implementer's question)
• --force overrides BRANCH_MISMATCH (21) only; never anything else.
• All informational output on stdout; errors on stderr; the exit code is the protocol.

Routing the request

• Brand-new task statement → pipe the full requirements via a heredoc:

  python3 "${CLAUDE_PLUGIN_ROOT}/skills/spec-implement/scripts/spec_implement.py" new "<short title>" --task-stdin <<'EOF'
  <full task statement: requirements, defaults, edge cases, acceptance criteria>
  EOF
  

  Note the slug it prints, then spec_implement.py run --feature <slug>. The task statement is the design and spec agents' ONLY source of truth — they never see this conversation. Carry over every concrete detail the user stated: defaults (page sizes, limits, timeouts), edge cases, error behaviors, acceptance criteria. Do not condense to a title; a detail dropped here is invisible to every later loop. Prefer the heredoc; never write the statement to a fixed-named file (those collide across concurrent agents).

  If the heredoc delivers empty stdin (the Windows+WSL Bash-tool boundary silently drops piped stdin), fall back to --task-file: Write the statement to a unique scratch path under .shepherd/ (gitignored, dirty-tree-excepted), then pass it — the engine reads and unlinks it:

  python3 "${CLAUDE_PLUGIN_ROOT}/skills/spec-implement/scripts/spec_implement.py" new "<short title>" \
    --task-file .shepherd/task-<short-title>.md
  

• Existing feature slug → spec_implement.py run --feature <slug> directly.

• Neither → bare spec_implement.py run and let branch convention or exit 20 resolve it.

Once the slug is known, thread --feature <slug> through every subsequent invocation.

Exit-code protocol

Before any run invocation, read ${CLAUDE_PLUGIN_ROOT}/skills/spec-implement/references/playbook.md — it carries the full exit-code table (codes 0, 10, 11, 12, 13, 14, 15, 16, 20, 21, 22, 1) and the per-code playbook. Branch on $? after every invocation and follow the playbook exactly. Do not improvise responses to exit codes from memory.

On a fresh (e.g. marketplace) install the first invocation may fail with missing required package(s) — nothing has installed the engine's Python deps yet. The playbook's Dependency bootstrap covers this: install claude-agent-sdk + pyyaml without sudo, then retry. Don't surface it as a fatal error.

Boundaries — never violate these

• Never fight the PreToolUse hooks. The script enforces design/spec/test/ implementation boundaries mechanically (writes denied outside allowed paths). A denial is a design decision, not an obstacle: do not retry via different tools, shell redirection, or any other workaround.
• Never hand-create commits matching spec-implement(...). Commits like spec-implement(<slug>): chore/red/green ... are made exclusively by the script; they are audit artifacts of the spec-implement choreography.
• Never edit files under .shepherd/features/*/.spec-implement/ by hand. state.json, traceability.json, and reports/ are owned by the script. Reading them is fine (and expected, to present reports to the human).
• Human interaction is yours: the script never prompts. Use AskUserQuestion to collect approvals, corrections, and decisions, then re-invoke run with --decision / --feedback.