dev-spec-kit

dev-spec-kit

Spec-driven development with a Verified Traceability Graph — every requirement bound to a passing check.

dev-spec-kit is a spec-driven development tool you drive from Claude Code (Spec-Kit-compatible layouts). Built for Claude Code first; other assistants later. It turns a request into EARS acceptance criteria with @check bindings, derives evidence-bound tasks, and — unlike every other SDD tool — proves the requirement → code → test → PR edges with real executed checks. A task physically cannot be marked done while a bound check is failing or unrun. Proofs carry the tested tree-hash, so committing tested code keeps them green while changed code goes stale — drift you can see and fix with one command.

Built on graphify (the code knowledge graph) — dev-spec-kit overlays the proven spec/test/PR edges and their traffic-light states on top.

Status: v0 — fully usable from source; npm publish as dev-spec-kit is deferred until the app-dogfood phase completes (see .dev-spec-kit/DEFER.md).

The loop

dev-spec-kit route "add idle session expiry"        # front door: research | quick | full-spec (+ security floor)
# write .dev-spec-kit/specs/sessions.md — EARS + @check bindings
dev-spec-kit spec tasks                              # spec → evidence-bound tasks (re-derive syncs bindings)
dev-spec-kit task start R-AUTH-03
dev-spec-kit check run R-AUTH-03 "SessionTest#idle" --stack java-maven --expect-red   # TDD red, journaled
# implement…
dev-spec-kit check run R-AUTH-03 "SessionTest#idle" --stack java-maven               # green proof @ tree-hash
dev-spec-kit task done R-AUTH-03                     # THE GATE — refuses without green proofs
dev-spec-kit verify --stamp --advance                # prove EVERY bound criterion in ONE suite run, then
                                              # auto-advance fully-proven tasks (the fast path)
dev-spec-kit spec lint                               # static drift: orphaned @check refs (also a pre-commit gate)
dev-spec-kit graph build                             # Verified Traceability Graph + boards (exit 1 on drift)
dev-spec-kit drift                                   # re-verify anything stale/red in one move
dev-spec-kit approve R-AUTH-03 --note "ship it"      # human gate as a signed artifact
dev-spec-kit pr --title "Session expiry"             # graph-derived PR body (+ blast radius); guard blocks non-green PRs

What's inside

• Hard gates (PreToolUse hooks): PR creation blocked unless every proof is green (missing graph blocks too) · in-flight specs/tests/gate-config are tamper-protected (dev-spec-kit unlock = journaled, time-boxed escape hatch) · opt-in DENY→FORCE→ALLOW investigative gate · PreCompact auto-saves RESUME.md.
• Verification & drift: dev-spec-kit verify --stamp proves EVERY bound criterion from ONE suite run (no per-criterion cold starts); --advance auto-advances fully-proven tasks. dev-spec-kit spec lint statically catches orphaned @check refs (renamed/moved tests) — folded into dev-spec-kit doctor, a pre-commit gate, and a Stop hook. dev-spec-kit spec draft-tests scaffolds a failing, bound stub per unbound criterion. dev-spec-kit graph build flags circular dependsOn chains.
• The judge kind: an LLM verdict for the genuinely-unmeasurable (tone, error-copy actionability, a transcript vs a rubric) — recorded as a second-class proof (rendered ⚖️ judged, never an executed green) and blocked on full obligations by default. Default harness mode is free (the Claude Code agent supplies the verdict, no API key); optional api mode calls a small Anthropic model headlessly.
• Config-driven policy engine: ~40 knobs in .dev-spec-kit/config.json — TDD, flaky retries, kind-aware runners (unit/integration/api/e2e/visual/parity/judge), app spin-up lifecycle for e2e, custom stacks as pure config, gate packs (security/contracts/nfr/rollback) with trigger words that floor risky requests to full-spec.
• Laws (.dev-spec-kit/laws.md + scoped laws/*.md): always-on / file-match / summon-on-demand rules, personal→project inheritance, #[[file:…]] doc injection — dev-spec-kit laws shows what's in force.
• Continuity: locked append-only journal with actor/model metadata · emoji audit trail (dev-spec-kit log) · generated LEDGER.md/TRACKING.md/RESUME.md boards that cannot lie · warn-on-repeat from the learnings ledger · dev-spec-kit dashboard (emoji cockpit with completion %, traffic lights, drift banner, the code graph, and every .dev-spec-kit/*.md rendered readable).
• Parallelism: dev-spec-kit wave plan/start/done — no-shared-files waves, fetch-first worktrees branched from origin's current tip (stale-base disasters designed out), merge-gated provenance-checked cleanup.

Commands