菜单
Spec-driven, autonomous end-to-end: branch → plan + test matrix → implement (tests alongside) → self-review → gap-analysis vs spec → close gaps → rigorous downstream verification → PR + evidence report
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/SteveVitali/agent-skills --skill implement-spec命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
基于 SOC 职业分类
| name | implement-spec |
| license | MIT |
| description | Spec-driven, autonomous end-to-end: branch → plan + test matrix → implement (tests alongside) → self-review → gap-analysis vs spec → close gaps → rigorous downstream verification → PR + evidence report |
| inputs | [{"name":"spec","required":true,"description":"The authoritative spec/ticket to implement — a file path (preferred) or inline instructions. This is the CONTRACT the gap-analysis phase diffs the implementation against."},{"name":"base_branch","required":false,"description":"Branch to create from (default: current branch)"},{"name":"branch_name","required":false,"description":"Name for the feature branch (username/short-description; will ask if not provided and not autonomous)"},{"name":"worktree","required":false,"description":"If given, run in this git worktree path instead of the current checkout (isolation from other concurrent agents). The workflow assumes the worktree + branch already exist unless told to create them."},{"name":"autonomous","required":false,"description":"Default true. When true, run to completion without check-ins — surface only at the end with the PR link + evidence report. When false, pause for plan confirmation on large/cross-cutting tasks."},{"name":"ledger","required":false,"description":"Default true. Maintain the durable run ledger (Phase 0.4). Disabling removes crash/compaction resumability — only for short single-sitting tasks."},{"name":"self_review","required":false,"description":"Default true. Run Phase 3 two-pass self-review. When false, the Phase 6.0 green gate still applies."},{"name":"gap_analysis","required":false,"description":"Default true. Run Phase 4 spec gap analysis. When false, acceptance criteria are only checked implicitly by Phase 5 verification."},{"name":"tests","required":false,"description":"Default true. Derive the AC test matrix (1.4), write tests alongside implementation (Phase 2), run unit/integration suites (5.1–5.2). When false, existing suites must still pass."},{"name":"live_verification","required":false,"description":"Default true. Run Phase 5.3 interactive/agentic live verification where the change has a runtime surface."},{"name":"evidence_report","required":false,"description":"Default true. Produce the Phase 6.4 evidence report + PR AC/evidence table. When false, finish with a standard PR summary."}] |
Turn an authoritative spec into a reviewable, spec-complete, rigorously-verified PR — autonomously.
This extends a conventional implement-and-PR workflow (context-loading, implementation discipline, self-review-before-commit, clean PR) with the two phases a spec-driven autonomous run needs: gap analysis vs the spec (Phase 4) and rigorous downstream verification (Phase 5). The output is a PR plus an evidence report that proves completeness/correctness against the spec — not just "it builds."
When to use this skill: when there is an authoritative written spec, when the run must be fully autonomous to completion, and when "done" means provably matches the spec (not just "compiles + self-reviewed"). For a rough idea that just needs a quick clean PR, use a lighter ticket workflow instead.
Every rigor phase can be disabled independently (all default on). Opting out trades assurance for speed — the table states what you lose. No toggle disables the Phase 6.0 green gate: existing builds and affected test suites must pass regardless.
| Input | Disables | You lose |
|---|---|---|
ledger=false | Phase 0.4 run ledger (keep that state in-context instead) | Crash/compaction resumability; durable gap-table evidence |
self_review=false | Phase 3 | Design critique + mechanical checklist pass before the spec diff |
gap_analysis=false | Phase 4 | The explicit spec-completeness proof; ACs checked only via Phase 5 |
tests=false | 1.4 test matrix, new tests in Phase 2, 5.1–5.2 new-test runs | Regression protection for the new logic |
live_verification=false | Phase 5.3 | End-to-end proof on the running system |
evidence_report=false | Phase 6.4 + the PR AC/evidence table | The per-AC evidence trail; PR gets a standard summary |
Sensible presets: full (all on — the default); fast-follow (gap_analysis=false live_verification=false)
for small mechanical changes against a precise spec; prototype (tests=false evidence_report=false) for
explicitly throwaway spikes. When in doubt, leave everything on.
If worktree was provided, all git/build/test commands run inside that worktree. Pin it up front so no
command leaks into the wrong checkout (critical when other agents share the machine):
export TASK_ROOT="${worktree:-$(git rev-parse --show-toplevel)}"
# Run EVERY subsequent command with cwd = $TASK_ROOT: `cd` once in a persistent shell, or set the command's
# working directory in harnesses that forbid `cd`.
# If the repo's local-dev tooling needs a worktree/instance pin (ports, slots), export it here too.
git rev-parse --show-toplevel # confirm you are where you think you are
If the worktree does not yet exist and the operator asked you to create it, create it from the base ref (see 0.2). Otherwise assume it exists and is on the intended branch.
BASE_BRANCH = provided base_branch, else git branch --show-current.branch_name: if not provided and autonomous=false, ask; if not provided and autonomous=true, derive one
(username/short-description) from the spec title and proceed. Branch names follow username/short-description.If the branch/worktree still need creating:
git fetch origin
# either an in-place branch:
git checkout "$BASE_BRANCH" && git pull origin "$BASE_BRANCH" && git checkout -b "$branch_name"
# …or an isolated worktree off a remote ref (preferred when other agents are active):
git worktree add -b "$branch_name" "$TASK_ROOT" "$BASE_BRANCH"
Record the exact base commit for the gap-analysis + PR:
git rev-parse HEAD # base tip you branched from
spec is a file path, read the whole file (and any companion docs it points
to). Extract two structured lists you will use in Phase 4:
AGENTS.md (or CLAUDE.md), each affected subproject's AGENTS.md, and any
agent_docs/ reference library the repo maintains (style guides, common pitfalls, data-model docs,
local-dev and build/test guides).ledger=false)Context is lossy over a run this long — compaction and session resets degrade exactly the fine-grained early details Phase 4 depends on. Everything the later phases need must live on disk, not in the context window. Create one ledger file in a stable, gitignored scratch location — honor the repo's canonical agent scratch dir if it defines one, else default to a shared dir under the main worktree:
SCRATCH="${AGENT_SCRATCH_DIR:-$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/.agents/scratch}"
mkdir -p "$SCRATCH" # must be gitignored; never commit ledger files
LEDGER="$SCRATCH/implement-spec_${branch_name//\//-}_$(date +%Y%m%d).md"
Seed it with: spec path, base commit, branch, and the Phase 0.3 requirements + acceptance-criteria checklist; leave placeholder sections for the test matrix (1.4), the gap table (4.1), and the evidence log (5.4). Keep it current at every phase transition. The ledger is three things at once:
git log and continues), andProduce a brief implementation plan (skip only for genuinely trivial specs) and record it in the ledger.
detect-targets script or equivalent), run it on your planned file list; otherwise derive the exact
build/test/lint commands for each affected package from its agent docs or build system.Before changing anything, confirm the baseline is green: the mapped targets build/pass at the base commit, and — if the change has a runtime surface you will dev-test in Phase 5 — the local stack starts clean. Pre-existing breakage discovered mid-run gets misattributed to your change and burns hours; find it now, while attribution is unambiguous.
tests=false)Translate every acceptance criterion into concrete planned tests before implementing: unit tests for pure logic, integration tests for the seams, live scenarios for runtime behavior (these become the 5.3 matrix). Write the matrix into the ledger. Deriving tests from the spec now — rather than from the finished code later — keeps them asserting what the spec demands instead of what the implementation happens to do.
autonomous=true (default): do NOT pause. Record the plan (you'll include it in the final report) and
proceed. The spec is the pre-approved contract — a mid-run check-in defeats the autonomous mandate.autonomous=false, large/cross-cutting task: present the plan and wait for confirmation before Phase 2.Adopt the implementation persona:
You are a Staff Engineer who writes production-quality code — code your most critical colleague would approve on first review. Before writing, think about the contract (in/out/failure modes), what adjacent code looks like (match its idioms and level of abstraction), the edge cases (empty inputs, missing data, concurrency, network failures), and what the reviewer will look for. While writing: follow existing patterns over personal preference; prefer simple/obvious over clever; handle errors explicitly; name for the reader; make the minimum change that fully addresses the requirement.
Implement the spec in the planned order, writing each logical group's tests (per the 1.4 matrix) as part of
implementing that group — not as a Phase-5 afterthought. Keep the build green as you go — after each logical
group, run that subproject's build/test/lint commands (the ones its AGENTS.md / agent_docs prescribe) rather than accumulating
a large unverified diff. Do not commit yet — verification and review happen before the first commit (the
one-clean-commit principle), except that a long autonomous run MAY checkpoint-commit between
logical groups if that de-risks the run; if so, keep messages descriptive and squash-or-keep at your discretion.
Honor the conventions established by the AGENTS.md hierarchy and agent_docs you loaded in Phase 0.3, and by the
code adjacent to your change — the language/style rules, build-system constraints, and any "ask-first"
boundaries for the subproject you're in. Match the surrounding code over personal preference; when a convention
is documented (style guide, common-pitfalls doc), follow it exactly.
self_review=false)Invoke the self-review skill (skills/self-review/SKILL.md) and follow it completely. Pass 1
(mechanical: the repo's verification command + mechanical checklists) and Pass 2 (Staff-Engineer design
critique with full file reads). Fix everything it
surfaces and re-verify. Max 3 verify-fix-review iterations. If design concerns persist after 3, record them in
the ledger for the final report and proceed; a mechanical failure (red build or failing tests) is different —
it may never be carried forward and blocks the PR gate (6.0).
Independence matters more than effort here. A reviewer that just wrote the code is a biased reviewer — it "knows what it meant." Where the harness supports subagents, run Pass 2 in a fresh context given only the spec, the diff, and the ledger — not your implementation history. Where it doesn't, enforce the discipline manually: re-read every changed file from disk in full and argue each judgment from what is actually there, never from memory of writing it.
gap_analysis=false)The core addition of this workflow. Self-review asked "is this good code?"; this phase asks "does it fully satisfy what the spec demanded?" — an orthogonal check. A change can be beautiful and still miss half the spec.
Start by re-reading the spec file in full and rebuilding the requirements + AC list fresh. Do not diff the code against your Phase 0.3 extraction alone: that extraction is itself unverified — a gap analysis against your own summary inherits its blind spots, and hours of context churn degrade it further. Diff the fresh list against the ledger's list (catches extraction drift), then against the implementation (catches real gaps).
For every requirement and every acceptance criterion from the spec, record a row in the ledger's gap table:
| item (spec §) | status: met / partial / missed | evidence (file:line, symbol, test) | if partial/missed: why + the fix |
Rules:
partial or missed.Like Pass 2, the gap walk benefits from independence: where the harness supports it, have a fresh-context subagent (spec + diff + ledger only) perform or double-check it.
For each partial/missed, don't just patch mechanically — reason from first principles about the best way
to close it given the codebase patterns and the spec's intent. Prefer the fix that a reviewer familiar with the
spec would consider obviously correct. If a spec requirement turns out to be genuinely infeasible or wrong,
do NOT silently skip it — record the conflict explicitly for the final report and choose the closest faithful
alternative.
Implement every closure (with tests, per 1.4). After closing, re-run Phase 3 self-review on the new changes
(design + mechanical), then re-walk the gap table until every row is met with evidence (or explicitly,
defensibly deferred with a recorded reason). Keep the ledger's gap table current as rows close. Max 3
close-verify iterations.
Prove correctness + completeness at three levels. Do as many as apply to the change; skip a level only when
the change genuinely has no surface for it, and say so in the report. Use the build/test tooling the AGENTS.md /
agent_docs for this subproject prescribe (build wrappers, test-runner invocation, lint/typecheck commands,
local-dev launcher) — discover them in Phase 0.3 rather than assuming a stack.
Run the full suites for the affected packages — the tests written in Phase 2 per the 1.4 matrix, plus the spec's required suites; all green. If gap closure (4.3) introduced logic whose tests don't exist yet, write them now. Tests must verify behavior and contracts, not just exercise code paths for coverage (see the self-review Pass-2 test criteria). Any pure logic the spec introduces (algorithms, selectors, scorers, state machines) gets direct, deterministic tests over its real edge cases.
Exercise the wired components end-to-end against the real seams the change touches (public interfaces, storage, config, cross-module calls) — not just the units in isolation. Assert the spec's integration acceptance criteria (round-trips, state transitions, inclusion/exclusion behavior, toggles, back-compat when the new surface is empty). Use whatever driving mechanism fits the seam (in-process test, CLI invocation, HTTP request, etc.).
live_verification=false) (the heart of this phase — do this wherever the change has a runtime surface)Goal: prove to yourself, empirically, that the change behaves as the spec says — the way a careful human would, by running the real thing and inspecting real signals. Not "a test passed" — "I drove the live system through representative cases and observed the expected behavior."
agent_docs/local-dev guide). Keep it isolated from other agents on the machine — use this
worktree's own slot/ports/instances, not shared ones. If the change is compiled, ensure the running process
actually contains your change before trusting anything: assert the live build == your HEAD (a version/gitSha
endpoint, a process-start-time-after-build check, or the subproject's documented freshness guard). A
compiled change that isn't actually running invalidates every interactive result — this is the single most
common way live verification lies to you.As you run each level, capture concrete evidence in the ledger's evidence log — the command/interaction and the salient observed output (test summaries, sample responses, log excerpts, state reads, screenshots/render confirmations). Synthesize the interactive verification into a short narrative: what you drove, what you observed, and why it proves the behavior — the same account you'd give a colleague who asked "how do you know this works?" If any check couldn't be run (missing fixture, environment limitation), say so explicitly — an unrun check is never reported as passed.
If any code changed since the last clean mechanical-verification pass (Phase 4/5 fixes), re-run it now. A red build or
failing test may never reach a ready-for-review PR. If it can't be fixed within the bounded iterations, either
stop and surface it as a hard blocker, or open the PR as --draft with the failure stated at the top of the
body. Unresolved design notes may ship with the report; a red build may not.
Review git status and stage intentionally — every staged file should correspond to the change (cross-check
against the gap table's evidence column). Do not blanket git add -A: long runs produce stray one-off
scripts/fixtures, and those belong in the scratch dir, not the PR. Exclude agent-harness dirs
(e.g. .windsurf/, .claude/, .cursor/, .dev/, .agents/) unless the spec's scope explicitly includes
them.
git status --short # review everything the run touched
git add <files that belong to the change>
git diff --cached --stat # confirm the staged set matches the intended change
git diff --cached --quiet || git commit -m "<descriptive message: what changed + why, ≤72-char summary line>"
git push -u origin "$branch_name"
gh pr create --base "$BASE_BRANCH" --head "$branch_name" \
--title "<concise title>" --body "<structured description>"
# or, if it exists: gh pr edit "$branch_name" --title "<title>" --body "<description>"
PR body: Summary (what + why) · What changed (files/areas) · Design decisions · Verification (what was built/tested/driven) · a link/reference to the spec it implements · a condensed acceptance-criteria → evidence table (from the ledger), so the PR is self-reviewing and the proof survives outside the chat transcript.
evidence_report=false: replace with a concise standard summary)The ledger is the source of truth — derive the report from it, don't reconstruct from memory. Return to the operator, in the final message:
gh pr view "$branch_name" --json url --jq '.url').osascript -e 'display notification "PR is up with a spec-completeness evidence report" with title "implement-spec" sound name "Glass"'
When autonomous=true (default): run Phases 0→6 to completion without stopping for check-ins. The only
surfaces are (a) a hard blocker you genuinely cannot resolve (missing creds, an ambiguous spec contradiction that
changes the design) — surface it concisely and stop; and (b) the final report. Do not ask "should I proceed?"
between phases — the spec is the approval. Prefer making a defensible decision and recording it in the report
over pausing.
If the run is interrupted (crash, context exhaustion, reboot), a fresh session resumes from the ledger +
git log: re-read the spec, the ledger's phase status, and the gap table, then continue from the first
incomplete step. Never restart a partially-complete run from scratch.
These compose on top when needed; they are not on the default critical path.