pillip/claude-dev-kit

Turn a PRD into shipped code you can trust without re-reading it. claude-kit is a **verification & delegation control plane** for Claude Code — it delegates work to the strongest runtime capability available, then makes the result trustworthy: deterministic gates, separate-context auditors, and provenance contracts around every artifact.
Why claude-kit?
**Positioning: verification & delegation control plane.** The kit's bet is that AI productivity is bottlenecked not by the model but by trust. As frontier models get stronger, "can the model do it" stops being the question — "can you merge what it did without re-reading all of it" remains. Teaching the model *how* to work depreciates with every model release; verifying *what* it produced does not. So the kit delegates work to the strongest runtime capability available and concentrates on what survives model progress:
- **Runtime delegation**: when Claude Code ships a capability that does the job better (/deep-research, /code-review, /security-review), the kit probes for it and delegates instead of re-implementing it in prompts. Today: /review, /brainstorm, /bizanalysis. Flagged next: test execution (SPEC-019).
- **Verification layer**: results pass deterministic gates (checkpoint scripts, schema validators) — and where an LLM step could silently distort output, a refute-first auditor running in a **separate context** from the generator verifies it before anything is saved.
- **Durable artifacts as contracts**: issues.md, SPECs, and sprint_state.md are the interface between sessions, people, and models — append-only registries, schema-validated, lock-guarded for concurrent writes.
- **Structured pipeline**: every issue goes through spec (when required) → implement → review → ship, enforced structurally by the sprint state machine — not by instructions the model could skip.
- **Decision capture**: non-trivial issues require a SPEC (/spec → docs/specs/SPEC-NNN.md) — Problem / Options ≥2 / measurable Trade-offs / Decision / Rollback — validated by script before it counts.
- **Automatic feedback loops**: review findings create follow-up issues, test failures trigger root-cause analysis, preventable patterns become native-memory lessons recalled in later sessions.
- **Zero configuration**: install the plugin and all agents/skills/hooks/gates are ready.
In short: claude-kit doesn't try to make Claude Code smarter — it makes Claude Code's output **trustworthy and auditable at merge time**.
Architecture — the delegation idiom
The kit's core pattern (SPEC-018/019), applied to every capability the runtime can own:
1. **Probe** — scripts/has_skill.py checks whether the runtime exposes the capability (/deep-research, /code-review, /security-review). Runtime built-ins leave no filesystem trace, so "unknown" means attempt-and-degrade — never silently skip.
2. **Delegate** — the runtime skill does the work it does best; the kit stops re-implementing it in prompts.
3. **Synthesize** — a deterministic script (synthesize_from_deep_research.py, synthesize_review_notes.py) maps the runtime's output into the kit's fixed artifact contracts: findings never dropped, severities copied verbatim, uncovered sections rendered as a literal "no data" line instead of filled in.
4. **Audit** — where an LLM step could silently distort results, a refute-first auditor in a separate context (research-auditor, synthesizer-auditor) verifies the output against upstream — verbatim quotes, no scope changes, no silent drops — and a non-ok verdict **blocks the save**. Where the merge step is fully deterministic (synthesize_review_notes.py), unit tests own that guarantee instead.
5. **Degrade** — when the runtime capability is absent, a kit-internal fallback (source capture + claim validation, the degraded reviewer dimensions) keeps the artifact contract intact, and the run is telemetry-tagged as degraded.
Coverage today: /review, /brainstorm, /bizanalysis. Flagged next: test execution (SPEC-019). The criterion for everything else — what stays prompt, what becomes a contract, what becomes a deterministic check — is the three-bucket classification in docs/evolution_audit.md (SPEC-055).
Overview
claude-kit takes a PRD (Product Requirements Document) as input and orchestrates AI agents to support the entire development lifecycle — from requirements analysis to code review and deployment.
**Core Principles:**
- **Platform-first**: never re-implement what a Claude Code runtime capability does better — probe and delegate (see the delegation idiom above)