spec-driven-development
JanSzewczyk/spec-driven-development
Spec-Driven Development framework delivered as a Claude Code plugin — drives every feature through a canonical spec → clarify → plan → tasks → implement → review flow with TDD enforcement, blocking typecheck/lint hooks, and per-task routing to your existing specialist sub-agents.
Instalação
npx convez-ai JanSzewczyk/spec-driven-development1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
🧩 SDD Framework for Claude Code
Spec-Driven Development for Claude Code — spec is the source of truth, code is its consequence.
Features • Quick Start • Architecture • Documentation
👋 Why SDD
Vibe coding (loose prompt → AI guesses → iterate by trial and error) works for demos but produces spaghetti in production: every fix breaks something else, security gaps multiply, the codebase becomes unmaintainable.
SDD fixes this by enforcing canonical phases: constitution → spec → clarify → plan → tasks → implement → review. AI is forced to read and confirm a plan before writing a single line of code. Verification agents and blocking hooks make the feedback loop tight enough that the model cannot skip validation steps.
SDD inverts traditional AI-assisted coding. Instead of "vibe coding" (vague prompt → AI guesses → fix loop), the specification is the source of truth and code is its mechanical consequence.
This framework is the synthesis of:
- GitHub Spec Kit (canonical phases)
- BMAD Method (sharding, role-based sub-agents)
- Amazon Kiro (hooks, Mermaid generation)
- OpenSpec (lightweight CLI for legacy code)
- Custom Claude Code workflows (slash commands, plan mode, custom agents)
The unique contribution of this framework: per-task routing to your existing specialist sub-agents (storybook-tester, nextjs-backend-engineer, testing-strategist, etc.) so SDD orchestrates your stack instead of duplicating it.
✨ Features
- 📋 Canonical SDD phases:
constitution → spec → clarify → plan → tasks → implement → review - 🏥
/sdd-doctor— preflight audit + one-command init - 🎭 Orchestration of existing sub-agents (does not duplicate — invokes specialist agents from the plugin marketplace via the Task tool)
- 🏷️ Tagged tasks — every task in
tasks.mdhastype,agent,skills→ auto-routing to the right specialist - 🪝 Auto-feedback hooks — typecheck + lint block Claude via exit code 2
- 🌿 Conventional Commits branches —
/spec feat user login→ branchfeat/user-login - 📐 TDD-first — tests always before implementation
- 🧠 Context discipline — sub-agents receive only their scope, skills load on demand
- 🔍 Drift detection — built-in
sdd-drift-detectorand/analyzekeep spec, plan, tasks, and code consistent
📖 Table of Contents
- 👋 Why SDD
- ✨ Features
- 🚀 Quick Start
- 🔄 The SDD Flow
- 🏗️ Architecture
- ⌨️ Slash Commands Reference
- 🤖 Sub-agents Reference
- 📋 End-to-end Example
- 📁 File Structure
- ⭐ Best Practices
- 🚫 Anti-patterns
- 🧩 Design Decisions
- 🔧 Troubleshooting
- 🤝 Contributing
- 📝 Changelog
- 📜 License
- 🙏 Acknowledgments
- 📧 Contact & Support
🚀 Quick Start
1. Install the plugin (one-time, per machine)
claude plugin install https://github.com/JanSzewczyk/spec-driven-development
Then enable it in your user settings (~/.claude/settings.json):
{
"enabledPlugins": {
"sdd@janszewczyk": true
}
}
(Depending on your Claude Code version, the claude plugin install command may handle this for you.)
Verify the install:
claude plugin list | grep sdd
You should see sdd@0.2.0. Once installed, the plugin's 9 slash commands, 4 verification sub-agents, and the sdd-doctor skill are available in every project — no per-project copy required.
2. Initialize a project
Open the target project in Claude Code and run:
/sdd-doctor init # copies CLAUDE.md.template, specs/_template.md, capabilities.md, settings.json
/sdd-doctor check # confirms 10/10 — plugin found, per-project files present
/constitution # edit CLAUDE.md — must be <2,500 tokens
What init does:
- Copies
CLAUDE.mdandspecs/_template.mdinto the project (skips if already present — never overwrites). - Generates
.claude/capabilities.mdby scanning your installed plugin marketplace (so it reflects the specialist agents and skills you actually have). - Generates
.claude/settings.jsonwith PostToolUse hooks pointing at the plugin's ownhooks/typecheck.pyandhooks/lint.sh.
3. Build your first feature
/spec feat user can reset password via email
/clarify
/plan # run in Plan Mode (Shift+Tab)
/tasks
/implement T1.1
...
/review
Forking the plugin for your own organization
If you want a customized copy (e.g. with org-specific routing rules in capabilities.md.template):
- Fork this repo to your GitHub org and update the
homepagefield inplugin.json. - (Optional) Edit
skills/sdd-doctor/templates/capabilities.md.templateto pre-populate task-type routing for your stack. - (Optional) Edit
skills/sdd-doctor/templates/CLAUDE.md.templateto seed your standard "WHAT NOT TO DO" rules. - Bump the
versioninplugin.jsonand tag a release. - Users install your fork with
claude plugin install https://github.com/<your-org>/sdd-plugin.
🔄 The SDD Flow
flowchart TD
A[/sdd-doctor init/] --> B[/constitution/]
B --> C[/spec feat user login/]
C --> D[/clarify/]
D --> E[/plan in Plan Mode/]
E --> F[Human reviews plan.md]
F --> G[/tasks/]
G --> H[/implement T1.1/]
H --> I{type ends with -test?}
I -->|yes| J[Write tests<br/>red phase]
I -->|no| K[Route to specialist<br/>per task.agent]
J --> L[Hook: typecheck + lint]
K --> L
L -->|fail exit 2| K
L -->|pass| M[sdd-spec-guard]
M -->|missing AC| K
M -->|satisfied| N{more tasks?}
N -->|yes| H
N -->|no| O[/review/]
O --> P[sdd-spec-guard + sdd-drift-detector + sdd-reviewer + skills]
P -->|GO| Q[git commit + gh pr create]
P -->|NO-GO| H
| Phase | Command | What happens |
|---|---|---|
| Constitution | /constitution | Edit CLAUDE.md — tech stack, conventions, WHAT NOT TO DO (<2,500 tokens) |
| Specify | /spec <type> <description> | Validate clean git, create branch <type>/<slug>, generate specs/<slug>/spec.md (business only — no code) |
| Clarify | /clarify | AI reads spec.md and asks 5-10 targeted gap questions; updates spec with answers |
| Plan | /plan | Generate plan.md with Mermaid diagrams, data model, API surface, file-by-file change list. Run in Plan Mode. |
| Tasks | /tasks | Decompose plan into YAML tasks with type, agent, skills auto-routed via capabilities.md |
| Implement | /implement <task-id> | TDD loop + delegation to specialist agent per task.agent; hooks enforce typecheck + lint |
| Review | /review | sdd-spec-guard + sdd-drift-detector + sdd-reviewer + domain skills → verdict GO/NO-GO → commit + PR |
| Analyze | /analyze | Diagnostic — find drift between spec ↔ plan ↔ tasks ↔ code (run anytime) |
🏗️ Architecture
🧱 Three-tier agent hierarchy
┌─────────────────────────────────────────────────────────────┐
│ ORCHESTRATOR (main Claude session) │
│ • Reads CLAUDE.md, capabilities.md, spec/plan/tasks │
│ • Routes work to specialist agents via Task tool │
│ • Runs verification agents at review time │
└─────────────────────────────────────────────────────────────┘
↓ Task tool ↓ Task tool
┌───────────────────────────┐ ┌──────────────────────────────┐
│ SPECIALIST AGENTS │ │ VERIFICATION AGENTS │
│ (plugin-based, YOUR stack)│ │ (generic SDD, 4 agents) │
│ • storybook-tester │ │ • sdd-spec-guard │
│ • nextjs-backend-engineer │ │ • sdd-drift-detector │
│ • testing-strategist │ │ • sdd-reviewer │
│ • (other from marketplace) │ │ • sdd-ui-critic │
└───────────────────────────┘ └──────────────────────────────┘
↓ "Use skill: X"
┌─────────────────────────────────────────────────────────────┐
│ SKILLS (in-context references, loaded on demand) │
│ • @szum-tech/server-actions, design-system, ... │
│ • react-doctor, accessibility-audit │
│ • find-skills (dynamic discovery) │
└─────────────────────────────────────────────────────────────┘
This framework adds:
- 1 skill (
sdd-doctor) - 9 slash commands (
sdd-doctor,constitution,spec,clarify,plan,tasks,implement,review,analyze) - 4 verification agents (
sdd-spec-guard,sdd-drift-detector,sdd-reviewer,sdd-ui-critic) - 2 hooks (
typecheck.py,lint.sh)
All specialist agents and skills already exist in the plugin marketplace — SDD orchestrates them, it does not duplicate them.
🏷️ Per-task routing
Every task in tasks.md carries a YAML block:
- id: T1.2
type: ui-component-test
agent: storybook-tester
skills: [storybook-testing, design-system]
acceptance: play function asserts form validation
files: [LoginForm.stories.tsx]
When the user runs /implement T1.2:
- Orchestrator parses
tasks.md, locates T1.2. - Load skills: emits
Use skill: storybook-testing,Use skill: design-system. - Delegate: invokes the
Tasktool withsubagent_type: storybook-tester. The prompt contains only:- The relevant
spec.mdsection (Summary + AC + Edge cases) - The relevant fragment of
plan.md(for this task only) - Acceptance criteria
- The relevant
- Specialist (storybook-tester) writes the story + interaction test.
- Hook PostToolUse runs typecheck + lint after every Write.
- Spec-guard verifies the diff satisfies the AC.
- Status in
tasks.md:draft→in-progress→review.
🧠 Context management
Three techniques prevent context bloat:
- Per-task delegation — specialists receive only their scope (spec + plan sections, never the whole feature)
- Skills on-demand —
Use skill: Xonly loads when needed - Fresh chat per Story — open a new Claude session between stories;
tasks.mdstatus is the handover document
CLAUDE.md token limit: <2,500 tokens. When you exceed it, shard per module:
CLAUDE.md(root, cross-cutting concerns)apps/web/CLAUDE.md(frontend-specific)apps/api/CLAUDE.md(backend-specific)packages/ui/CLAUDE.md(component library)
🪝 Verification hooks
PostToolUse hooks in .claude/settings.json run after every Edit/Write/MultiEdit:
typecheck.py— runstsc --noEmitfor TypeScript ormypy --strictfor Python on the modified filelint.sh— runs ESLint for JS/TS or Ruff for Python
If typecheck or lint fails, the hook exits with code 2. Claude receives the stderr output and is forced to fix the issue before taking the next action. There is no way to "forget" about validation.
📇 Capabilities registry — hybrid mode
.claude/capabilities.md has two kinds of sections:
<!-- auto-generated -->— overwritten by/sdd-doctor initon every run (it scans~/.claude/plugins/cache/)<!-- user-override -->— preserved untouched, the safe place to keep customizations
This lets you re-run init (e.g., after installing a new plugin) without losing your custom task-type routing rules.
Example schema:
## Specialist agents (delegate implementation work)
<!-- auto-generated -->
- **storybook-tester** (szum-tech) — Storybook stories + interaction tests
- **nextjs-backend-engineer** (szum-tech) — Server Actions, route handlers
- **testing-strategist** (szum-tech) — test strategy planning
## Skills (load into context on demand)
<!-- auto-generated -->
- `@szum-tech/server-actions` — Server Action patterns
- `@szum-tech/design-system` — components, design tokens, OKLCH palette
- ...
## Stack profile
<!-- auto-generated -->
- framework: nextjs
- language: typescript
- tests: vitest, playwright
## Task type → routing rules
<!-- user-override -->
| Task type | Specialist agent | Skills to load |
|---------------------|---------------------------|-----------------------------------------|
| ui-component-test | storybook-tester | storybook-testing, design-system |
| server-action | nextjs-backend-engineer | server-actions, error-handling |
| ... | ... | ... |
⌨️ Slash Commands Reference
🏥 /sdd-doctor [check|init|fix <ids>]
Preflight audit and auto-setup. 10 checks: CLAUDE.md, specs/_template.md, plugin installed, plugin enabled, capabilities.md valid, settings.json hooks, git + gh, tooling, specialist agents discoverable, project type detected.
check(default) — report only, statuses ✅/⚠️/❌init— generate all missing files + auto-detect plugins → fillcapabilities.md+ adjust hooks to detected stackfix <N>— repair specific check by ID
📜 /constitution
Edit CLAUDE.md at the project root. Warns when token count exceeds 2,500 and suggests sharding per module.
🌿 /spec <type> <description>
Phase 1 — Specify. Requires <type> ∈ {feat, fix, chore, refactor, docs} (Conventional Commits).
Steps:
- Verify clean git tree (
git status --porcelain) — STOP if dirty - Parse
<type>and generatefeature_slug(kebab-case) andfeature_title(Title Case) - Create branch
<type>/<feature_slug> - Generate
specs/<feature_slug>/spec.mdfrom_template.md
⛔ The spec file is business-only — no code, no tech stack details.
❓ /clarify
Phase 2 — Clarify. AI reads the current spec.md and asks 5-10 targeted questions about gaps (ambiguous requirements, missing edge cases, vague acceptance criteria). When the user answers, the spec is updated automatically.
🗺️ /plan
Phase 3 — Plan. Run in Plan Mode (Shift+Tab) so Claude has edits disabled and can only read/analyze.
Generates plan.md with:
- High-level approach
- Data model (Mermaid ER diagram)
- Component diagram (Mermaid flowchart)
- API surface table
- File-by-file change list
- Reused utilities (citing existing code paths)
- Risks & mitigations
After generation, human review of plan.md is mandatory before proceeding to /tasks.
🧩 /tasks
Phase 4 — Tasks. Decompose plan.md into a tagged task list:
- id: T<story>.<n>
title: <one-line description>
type: <matches capabilities.md task type>
agent: <specialist agent OR orchestrator>
skills: [<skills to load>]
status: draft
acceptance: <measurable AC from spec.md>
files: [<files to create or modify>]
TDD discipline depends on the task family:
- Logic tasks (server actions, route handlers, hooks, utilities): classic strict TDD — the first task in each Story is a failing unit test, then implementation.
- UI components (React/Next.js): contract-first TDD in 3 tasks per component — strict TDD fails for components because a test importing a non-existent component breaks with "Module not found" (not a meaningful red phase). The 3-task decomposition is:
ui-contract— define the inline TypeScript props interface and a skeleton component returning<div data-testid="..." />. Props live inline in the.tsxfile — never as a separate.types.ts.ui-component-test— import the component (no module-not-found), write tests + Storybook story that fail with meaningful assertion errors.ui-component— flesh out the skeleton until tests pass.
/tasks auto-emits 3 tasks per component without you asking.
🔨 /implement <task-id>
Phase 5 — Implement one task. Pipeline:
- Mark task
in-progress - Phase validation — depends on
type:- Logic tasks: if not a test task, require the sibling test task with
status: review|done. - UI tasks (contract-first TDD chain):
ui-component-testrequires siblingui-contractdone;ui-component(full impl) requires siblingui-component-testdone. - On missing prerequisite → STOP, instruct user to run
/implement <prerequisite-id>first.
- Logic tasks: if not a test task, require the sibling test task with
- Load skills from
task.skills - If
task.agent ≠ orchestrator→ delegate viaTasktool withsubagent_type: <task.agent>, passing only the relevant spec + plan slice - Hooks run automatically (typecheck + lint, exit 2 on failure)
sdd-spec-guardverifies the diff satisfies the task's acceptance criteria- Mark task
review
⛔ One task per /implement invocation. Bulk implementation defeats the purpose.
🔍 /review
Phase 6 — Final audit before PR. Runs in sequence:
- Full test suite
sdd-spec-guardover the entire feature diffsdd-drift-detectorover spec ↔ plan ↔ tasks ↔ codesdd-revieweragent invokes domain skills (react-doctor,accessibility-audit, etc.) based on the diff- Generates
specs/<slug>/review.mdwith verdict GO / NO-GO - On GO:
git commit(Conventional Commits format) +gh pr createwith body linking tospec.md - On NO-GO: list concrete blockers
📊 /analyze
Diagnostic tool — run anytime to detect drift between spec ↔ plan ↔ tasks ↔ code. Useful before /review to avoid a NO-GO verdict.
Outputs a markdown matrix:
- ✅ Aligned items (spec AC → plan → task → commits)
- ⚠️ Drift items (with file paths and suggested fixes)
- 🔴 Critical conflicts (spec says X, code does contradictory Y)
⛔ Read-only — never edits files.
🤖 Sub-agents Reference
This framework introduces only 4 new generic agents. Everything else is your existing plugin specialists, invoked via Task tool with subagent_type.
🛡️ sdd-spec-guard
Purpose: Verify that a code diff satisfies all Acceptance Criteria from spec.md and does not introduce out-of-scope changes.
Called by: /implement (per task) and /review (whole feature).
Output: JSON
{
"satisfied": true | false,
"ac_satisfied": ["AC1", "AC2"],
"ac_missing": [
{"id": "AC3", "description": "...", "reason": "no implementation in diff"}
],
"out_of_scope": [
{"file": "src/Header.tsx", "summary": "logo change unrelated to auth flow"}
],
"non_goal_violations": []
}
Strict constraints: never writes code, never suggests fixes (only reports gaps), never judges code quality (that's sdd-reviewer's job).
🔀 sdd-drift-detector
Purpose: Find inconsistencies between documentation layers (spec.md, plan.md, tasks.md) and the current code state.
Called by: /review and /analyze.
Cross-checks performed:
- Spec → Plan: every AC has a corresponding entry in plan.md
- Plan → Tasks: every file in plan.md's "File-by-file" list has a covering task
- Tasks → Code: tasks marked
done/reviewactually changed their declaredfiles - Spec → Code: AC coverage in test files;
TODO/FIXMEin code matches Open Questions in spec
Output: Markdown report with severity tiers (✅ Aligned / ⚠️ Drift / 🔴 Critical) and a suggested fix per drift item.
🧐 sdd-reviewer
Purpose: Final quality audit before PR. Orchestrates domain-specific audits and decides GO/NO-GO.
Called by: /review.
Pipeline:
- Run full test suite (command from CLAUDE.md)
- Check coverage thresholds
- Invoke relevant skills + agents based on the diff:
react-doctorskill if.tsx/.jsxfiles changedaccessibility-auditskill if UI components touchedsdd-ui-criticsub-agent if UI files in diff (visual review via browser MCP — see below)@szum-tech/server-actionsskill if server actions added
- Verify commit messages follow Conventional Commits
- Generate
specs/<slug>/review.mdwith verdict - Block GO if any test fails or any critical a11y/security violation exists
Output: JSON {verdict: "GO" | "NO_GO", blockers: [...], warnings: [...]}
🎨 sdd-ui-critic
Purpose: Visual review of changed UI components — captures Storybook screenshots via a browser MCP and evaluates them for design-system adherence, layout regressions, and rendering issues.
Called by: sdd-reviewer (transitively from /review) when the diff contains .tsx/.stories.tsx files.
Requirements: A browser MCP server connected (e.g. Claude_in_Chrome, Claude_Preview, or Playwright MCP) plus a running Storybook (default http://localhost:6006). If either is missing, the agent returns verdict SKIPPED and the review continues without blocking.
Output: JSON
{
"verdict": "OK" | "WARNINGS" | "ISSUES" | "SKIPPED",
"skip_reason": "no_mcp | storybook_unreachable | null",
"components_reviewed": ["LoginForm", "Header"],
"findings": [
{
"component": "LoginForm",
"severity": "issue",
"category": "design-system",
"detail": "Submit button uses raw #3B82F6 — should use --color-primary-500",
"screenshot": "./.sdd-screenshots/LoginForm.png"
}
]
}
Severity classification: issue (visible bug, blocks GO), warning (suboptimal but functional), info (observation). SKIPPED never blocks /review — it surfaces an infrastructure note instead.
Screenshots are saved under ./.sdd-screenshots/ — add this path to .gitignore.
📋 End-to-end Example
Feature: "User can reset password via email".
Install + initialize
Install the plugin once per machine, then in any project:
cd ~/Projects/my-app && git init
In Claude Code:
/sdd-doctor init # auto-detects Next.js 15 + TS + Vitest + Storybook
/sdd-doctor check # ✅ READY (10/10)
/constitution # fill Tech stack, Run/build, WHAT NOT TO DO
Spec phase
/spec feat user can reset password via email
Effects:
- ✅ Clean git verified
- ✅ Branch
feat/user-can-reset-password-via-emailcreated - ✅
specs/user-can-reset-password-via-email/spec.mdgenerated
You open the spec, fill in:
- User stories (Reset via email, optional MFA)
- Acceptance criteria (AC1: token valid for 1h, AC2: rate-limited to 3 attempts, …)
- Edge cases (unknown email — silent success per security best practice)
Clarify
/clarify
Claude asks:
- AC1: should expired tokens return 410 or 401?
- AC2: is the rate limit per IP, per email, or both?
- Edge case: what if SMTP delivery fails — retry or fail loud?
- ...
You answer in chat. Spec is updated.
Plan
Enable Plan Mode (Shift+Tab):
/plan
Generates specs/.../plan.md:
- Data model (Mermaid ER):
User,PasswordResetToken - Component diagram (Mermaid):
ResetForm → Action → Service → DB + Mailer - API surface:
POST /actions/resetPassword - File-by-file change list (8 files)
- Reused:
packages/errors/AuthError,packages/db/prismaClient
Read plan.md manually, correct anything wrong.
Tasks
/tasks
Generates tasks (note the contract-first 3-task decomposition for the UI component):
# Story S1: UI — ResetPasswordForm (contract-first TDD, 3 tasks)
- id: T1.1
title: ResetPasswordForm contract + skeleton
type: ui-contract
agent: orchestrator
skills: [design-system]
status: draft
acceptance: |
Inline TypeScript props interface defined in ResetPasswordForm.tsx.
Component exports a skeleton returning <div data-testid="reset-password-form" />.
files: [apps/web/src/components/ResetPasswordForm.tsx]
- id: T1.2
title: ResetPasswordForm tests + story
type: ui-component-test
agent: storybook-tester
skills: [storybook-testing, design-system]
status: draft
acceptance: |
Tests import the component (no module-not-found).
Assertions fail with meaningful errors.
Storybook story renders skeleton.
files:
- apps/web/src/components/__tests__/ResetPasswordForm.test.tsx
- apps/web/src/components/ResetPasswordForm.stories.tsx
- id: T1.3
title: ResetPasswordForm implementation
type: ui-component
agent: orchestrator
skills: [design-system]
status: draft
acceptance: All tests from T1.2 pass. spec AC1 satisfied.
files: [apps/web/src/components/ResetPasswordForm.tsx]
# Story S2: backend logic — classic strict TDD (2 tasks)
- id: T2.1
title: Tests for resetPassword server action
type: unit-test
agent: orchestrator
skills: [unit-testing]
status: draft
acceptance: failing tests covering spec AC2 + AC3
files: [apps/web/src/app/actions/__tests__/resetPassword.test.ts]
- id: T2.2
title: resetPassword server action
type: server-action
agent: nextjs-backend-engineer
skills: [server-actions, error-handling, t3-env-validation]
status: draft
acceptance: spec AC2, AC3 — all tests from T2.1 pass
files: [apps/web/src/app/actions/resetPassword.ts]
Implement
/implement T1.1
type: ui-contract (orchestrator). Defines the inline ResetPasswordFormProps interface and a skeleton component (<div data-testid="reset-password-form" />) — no logic yet. Hook validates typecheck/lint.
/implement T1.2
type: ui-component-test (agent: storybook-tester). Prerequisite T1.1 is done, so tests CAN import the component meaningfully. Specialist writes tests + Storybook story. Tests fail with meaningful assertion errors (not module-not-found).
/implement T1.3
type: ui-component (orchestrator). Prerequisite T1.2 is done. Orchestrator fleshes out the skeleton until all tests from T1.2 pass. sdd-spec-guard confirms diff matches spec AC.
/implement T2.1
Classic strict TDD test task — orchestrator writes failing tests (red phase), confirms proper failure reasons.
/implement T2.2
agent: nextjs-backend-engineer — Task tool with subagent_type: nextjs-backend-engineer. Specialist implements the server action with proper validation, error handling, and env-var validation per loaded skills.
Review
/review
Pipeline executes:
- Tests: 23/23 passed
sdd-spec-guard: all 4 AC satisfiedsdd-drift-detector: no driftsdd-reviewer: orchestrates skills + visual reviewreact-doctorskill: 89/100accessibility-auditskill: 0 criticalsdd-ui-criticsub-agent: verdictOK— screenshots saved to.sdd-screenshots/(orSKIPPEDif no browser MCP / Storybook available)- Conventions: OK
- Verdict: GO
- Commit:
feat(reset-password): add email-based reset flow - PR opened with body referencing
specs/user-can-reset-password-via-email/spec.md
Typical timeline
| Step | Time |
|---|---|
/sdd-doctor init | 30 s |
/spec | 1 min (Claude generates, you edit business spec) |
/clarify × 2 | 5 min (Q&A) |
/plan (Plan Mode) | 3 min (analysis + generation) |
| Human review of plan.md | 5-10 min |
/tasks | 1 min |
/implement × 8-15 tasks | 1-3 h (most of the time here) |
/review | 5 min |
| Total | ~2-4 h for a medium feature |
Without SDD a similar feature is 4-6 h with frequent rework. With SDD: 2-4 h, deterministic.
📁 File Structure
In your project (after /sdd-doctor init)
Only per-project artifacts. Commands / agents / verification skills live in the installed plugin, not in your project.
your-project/
├── CLAUDE.md # root constitution (<2,500 tokens)
├── specs/
│ ├── _template.md # base template for new specs
│ └── <feature-slug>/
│ ├── spec.md # business specification
│ ├── plan.md # architecture + Mermaid diagrams
│ ├── tasks.md # YAML task list with routing tags
│ └── review.md # generated by /review
├── .claude/
│ ├── capabilities.md # hybrid: auto-generated + user-overrides
│ └── settings.json # PostToolUse hooks → plugin hook scripts
├── apps/web/CLAUDE.md # (optional) module-scoped constitution
└── apps/api/CLAUDE.md # (optional) module-scoped constitution
In the plugin (installed once per machine)
spec-driven-development/ # or your own forked plugin path
├── plugin.json # manifest
├── README.md / LICENSE / CHANGELOG.md / CONTRIBUTING.md / .github/
├── skills/
│ └── sdd-doctor/
│ ├── SKILL.md # skill metadata + instructions
│ ├── check.py # 10-point readiness check
│ ├── init.py # copies templates into target project
│ └── templates/ # bundled templates copied by `init`
│ ├── CLAUDE.md.template
│ ├── capabilities.md.template
│ ├── settings.json.template # ${PLUGIN_ROOT} placeholder
│ └── specs/_template.md
├── commands/ # 9 slash commands (auto-discovered)
│ ├── sdd-doctor.md
│ ├── constitution.md / spec.md / clarify.md / plan.md
│ ├── tasks.md / implement.md / review.md / analyze.md
├── agents/ # 4 verification sub-agents
│ ├── sdd-spec-guard.md
│ ├── sdd-drift-detector.md
│ ├── sdd-reviewer.md
│ └── sdd-ui-critic.md # optional — needs browser MCP
└── hooks/
├── typecheck.py # exit 2 = blocks Claude
└── lint.sh
⭐ Best Practices
Ten actionable rules drawn from the source materials (Spec Kit, BMAD, Kiro, OpenSpec, Anthropic guidance):
- 🧪 Force AI to validate its own work. Every task's
acceptancefield must be measurable. Hooks make typecheck/lint non-skippable. For logic (server actions, hooks, utilities) use classic strict TDD — failing test first, then implementation. For UI components use contract-first TDD: define inline props interface + skeleton component, then tests + Storybook story (which now fail with meaningful assertion errors, not module-not-found), then full implementation. Props interface lives inline in the.tsxfile — never as a separate.types.ts. - ✂️ Shard large specs. Never hand a giant PRD to an implementer agent. Break it into Epic → Story → Task. Each specialist receives only its slice.
- 📁 Separate
CLAUDE.mdper module. Root for cross-cutting,apps/web/CLAUDE.mdfor frontend,apps/api/CLAUDE.mdfor backend. Frontend code shouldn't burn tokens reading database rules. - 🔒 Use Plan Mode before edits.
/planand/clarifyideally run in Plan Mode (Shift+Tab) so Claude cannot accidentally modify files during exploration. - 👤 Human-in-the-loop on
plan.md. Always read the generated plan before/tasks. This is the cheapest moment to correct course. - 🌿 One branch per feature.
/specenforces it. Conventional Commits naming (feat/...,fix/...). - 🤝 Use sub-agents for large reads. Don't grep 50 files in the main session — invoke a
Tasktool sub-agent and receive only a summary. - 🔄 Keep spec ↔ code in sync. When you change code manually, update the spec. Use
/analyzeto detect drift periodically. - 💬 Fresh chat per Story. Open a new Claude session when switching to a new Story.
tasks.mdstatus is your handover document. - ❓ Embrace the Clarify phase. Letting AI ask questions before planning surfaces gaps that would otherwise burn implementation cycles.
🚫 Anti-patterns
What to avoid — common failure modes when adopting SDD:
- ❌ Skipping
/clarify"because I know what I want." Open questions almost always surface real gaps. - ❌ Skipping human review of
plan.md. Claude can hallucinate architecture, especially on unusual stacks. - ❌ Multiple
/implementcalls in one chat. Context bloats, hallucinations rise. One task per session is the ideal. - ❌ Manual
git commitinstead of/review. You bypasssdd-spec-guard/sdd-drift-detector/sdd-reviewer. - ❌ Code or tech details in
spec.md. The spec is a business document. Implementation belongs in plan.md and code. - ❌ Bloated
CLAUDE.md. Above ~2,500 tokens, Claude starts ignoring the bottom. Shard per module. - ❌
--dangerously-skip-permissionsin production. A hallucinated bash command can destroy your system. - ❌ Implementing without a spec. SDD only works if every feature has its
specs/<slug>/spec.mdfirst.
🧩 Design Decisions
Why this framework looks the way it does:
| Decision | Rationale |
|---|---|
| Per-project, not global | Different projects have different stacks, different specialist agents, different routing rules. A global framework would force homogeneity. |
| Only 4 new agents | The rest already exists in the plugin marketplace (storybook-tester, nextjs-backend-engineer, …). Duplicating them would be wasted effort and version drift. |
| YAML tags in tasks.md | Explicit > heuristic. The user knows exactly which agent will be invoked for each task. |
Conventional Commits in /spec | Branch names and commit messages aligned with industry standard. Compatible with semantic-release, changeset, etc. |
| Hook exit code 2 | The strongest possible feedback signal for Claude. Cannot be ignored or skipped — Claude must fix the failure before continuing. |
| Skills loaded on demand | No global pre-loading means smaller context per task. Skills are referenced from capabilities.md and loaded only when the task type requires them. |
Plan Mode before /implement | Forces human review and blocks destructive changes before a plan exists. |
| Hybrid capabilities.md | <!-- auto-generated --> sections reflect installed plugins. <!-- user-override --> sections preserve customizations. Re-running init is safe. |
| CLAUDE.md at root, not in .claude/ | Claude Code reads CLAUDE.md from the project root by default. Putting it in .claude/ would require manual loading. |
| Framework lives in the plugin, project owns its specs | Commands, agents, hooks, and the doctor skill ship with the plugin (installed once per machine). The project keeps only what is genuinely project-specific: CLAUDE.md, specs/, capabilities.md, settings.json. Plugin updates roll out by reinstalling; project data is never overwritten. |
🔧 Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
/sdd-doctor check shows ❌ on check #9 (specialist agents) | No plugins installed | Install relevant plugins (e.g., @szum-tech marketplace) and re-run /sdd-doctor init |
| Hooks not firing after Edit | settings.json not loaded | Verify .claude/settings.json exists and chmod +x .claude/hooks/* |
/spec fails with "uncommitted changes" | Working tree dirty | git stash or commit current changes first |
/implement keeps producing the same code despite hook failures | typecheck error not propagating | Check that typecheck.py exits with code 2 on failure; verify tsc/mypy is installed |
/tasks produces tasks with agent: orchestrator for everything | capabilities.md routing rules don't match task descriptions | Edit the <!-- user-override --> routing rules section in capabilities.md |
sdd-spec-guard always returns satisfied: true even for incomplete code | Acceptance criteria in spec.md are too vague | Rewrite AC to be measurable (input X → output Y) |
Plan Mode disabled but /plan still works | Plan Mode is recommended but not required | For correctness this is fine; for safety enable Plan Mode (Shift+Tab) |
New specialist agent installed but not appearing in capabilities.md | init not re-run | /sdd-doctor init to rescan plugins |
🤝 Contributing
Contributions are welcome! See CONTRIBUTING.md for the development setup, the local smoke-test loop, style guidelines, and the PR checklist.
In short:
- Fork the repository and create a feature branch (
git checkout -b feat/new-skill) - Make changes inside the plugin (
commands/,agents/,skills/,hooks/,skills/sdd-doctor/templates/) - Run the smoke test (
check.pytheninit.pyagainst a fresh empty directory) - Update the README's File Structure / reference sections and add a
CHANGELOG.mdentry under[Unreleased] - Open a Pull Request
📝 Changelog
See CHANGELOG.md for the full version history. This project follows Keep a Changelog and Semantic Versioning.
📜 License
This project is licensed under the MIT License. See the LICENSE file for details. © 2026 Jan Szewczyk.
🙏 Acknowledgments
SDD is a synthesis of ideas from the spec-driven and agentic-coding ecosystem:
- GitHub Spec Kit — canonical phases
- BMAD Method — sharding and role-based sub-agents
- Amazon Kiro — hooks and Mermaid generation
- OpenSpec — lightweight CLI for legacy code
- Anthropic Claude Code — slash commands, plan mode, custom agents, and the plugin system this framework is built on
📧 Contact & Support
- 🐛 Open an issue
- ⭐ Star this repository
- 👨💻 Check out the maintainer's GitHub profile
Made with ❤️ by Jan Szewczyk
If this framework helped you, please consider giving it a ⭐ on GitHub!