Spec implement
Build features through a strict, hook-enforced, spec-driven, test-first workflow: design sketch → human approval → EARS requirements spec → human approval → failing tests committed red → implementation until green (red-green). Use whenever the user wants to build, add, or implement a feature, endpoint, or behavior change — including right after an implementation plan is approved — by offering this workflow via AskUserQuestion before writing code directly. This applies even in a fresh project with no .shepherd/ setup yet: the skill initializes setup itself on first run, so the absence of a .shepherd/ directory is NOT a reason to skip the offer. Also use on any mention of test-driven development (TDD), test-first, red-green, EARS, design sketch, requirements spec, or acceptance criteria; when a .shepherd/ directory is present; or when the user asks to set up, resume, or check the status of a shepherd feature.From its SKILL.md
npx -y skills add dheerajgopi/claude-shepherd --skill spec-implementAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
7.4 KB, as published. Nobody here has run it
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:
- Design sketch — drafts a rough design (components, responsibilities, optional flowcharts) for human approval before any requirement is written.
- 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>.
- 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
- 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.
- 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/--feedbackonrun:- exit 15 → re-invoke with
--decision approveor--feedback "<corrections>"(design sketch) - exit 16 → re-invoke with
--decision approveor--feedback "<corrections>"(test framework) - exit 10 → re-invoke with
--decision approveor--feedback "<corrections>" - exit 12 → re-invoke with
--decision approveor--decision reject [--feedback "<why>"] - exit 14 → re-invoke with
--feedback "<answer>"(the implementer's question)
- exit 15 → re-invoke with
--forceoverrides 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> EOFNote 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 runand 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 likespec-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, andreports/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
AskUserQuestionto collect approvals, corrections, and decisions, then re-invokerunwith--decision/--feedback.