SDD — Spec-Driven Development: Claude Code commands and templates for a lean 4-step workflow (specify → plan → tasks → implement)

sdd-plan.md

Plan: {Feature Name}

Spec: spec.md | Date: {TODAY}

Approach

[2–3 sentences: what we're building, the key architectural decision, and why that approach.]

Files

Create

File	Purpose
path/to/new-file	[what it does]

Modify

File	Change
path/to/existing	[what changes and why]

Auxiliary Work

• Update README: [which section]
• Update docs: apps/docs/src/content/docs/[page]
• Screenshots needed: [what to capture]

Risks

sdd-spec.md

Spec: {Feature Name}

Issue: #{N} | Mode: Normal | Date: {TODAY}

Why

[Problem this solves or user need it addresses.]

What Changes

• [Concrete change 1 — UI, behavior, or data. Not implementation details.]
• [Concrete change 2]
• [Concrete change 3]

Requirements

• R001 (MUST): [Critical requirement — core functionality]
• R002 (MUST): [Critical requirement]
• R003 (SHOULD): [Important but not blocking]
• R004 (COULD): [Nice to have]

Scenarios

[Behavior Area]

When [user action or system event] Then [expected outcome]

When [edge case or variant] Then [expected outcome]

Out of Scope

• [What this intentionally does NOT cover]

---

Exploration Findings

Affected Files

File	Why it matters
path/to/file	Will be modified to...

Reference Implementations

File	Pattern to follow	Lines
path/to/ref	How to do X	10–50

Key Snippets

// Pattern to follow

sdd-tasks.md

Tasks: {Feature Name}

Plan: plan.md | Date: {TODAY}

Format

• [P] = Can run in parallel | [A] = Agent-eligible

---

Phase 1: Core Implementation (Sequential)

• T001 {title} — path/to/file

  • Do: [Exact action — file path + what to write or change]
  • Verify: build passes / type checks

• T002 {title} (depends on T001) — path/to/file

  • Do: [...]
  • Verify: [...]

• T003 {title} (depends on T002) — path/to/file

  • Do: [...]
  • Verify: [...]

• T004 Wire up / register (depends on T003) — path/to/file

  • Do: [...]
  • Verify: nx build ngx-dev-toolbar passes

---

Phase 2: Quality (Parallel — launch agents in single message)

• T005 [P][A] Unit tests — test-expert

  • Files: path/to/file.spec.ts
  • Pattern: Jest, AAA, Angular TestBed, signals (computed/effect)
  • Reference: path/to/existing.spec.ts

• T006 [P][A] Docs update — docs-expert

  • Files: README.md, apps/docs/src/content/docs/[page].md
  • Scope: [from Auxiliary Work section in plan.md]

---

Progress

Phase	Tasks	Status
Phase 1	T001–T004	[ ]
Phase 2	T005–T006	[ ]

sdd.implement.md

description	SDD — Spec-Driven Development: execute tasks, run checkpoints, commit and open PR.

Steps

1. Load

Find the most recently modified directory under specs/ that contains tasks.md.

Read in parallel:

• specs/{NNN}-{slug}/tasks.md — all Phase 1 and Phase 2 tasks
• specs/{NNN}-{slug}/spec.md — feature name, requirements, scenarios (for CP1 verification)
• specs/{NNN}-{slug}/plan.md — approach, files, issue number if present
• specs/{NNN}-{slug}/state.json — current step/task (if exists; note if resuming mid-implement)

Determine commit scope from the primary directory being modified (e.g., toolbar, ui, core). If unclear, omit scope.

Determine issue number from plan.md or spec.md if present.

If no tasks found, stop: "Run /sdd.specify, /sdd.plan, and /sdd.tasks first."

Update specs/{NNN}-{slug}/state.json:

{ "step": "implement", "task": "T001", "updated": "{TODAY}" }

---

Context Recovery (if resuming)

If state.json shows step = "implement" and task = "T00N":

1. Check if worktree exists at .claude/worktrees/{NNN}-{slug}/ — if so, cd into it
2. If no worktree exists, use EnterWorktree with name: "{NNN}-{slug}" to create one
3. Verify branch name: git branch --show-current — if it starts with worktree-, rename it: git branch -m {NNN}-{slug}
4. Read spec.md for feature context
5. Read tasks.md — [x] = done, [ ] = remaining
6. Resume from the first unchecked task
7. Do NOT re-run completed tasks — trust the checkmarks and existing commits

---

2. Create Worktree + Branch

Use Claude's built-in EnterWorktree tool with name set to {NNN}-{slug}.

This will:

• Create a worktree at .claude/worktrees/{NNN}-{slug}/
• Create a new branch based on HEAD
• Switch the session's working directory into the worktree

Immediately after EnterWorktree, verify you are inside the worktree:

pwd

The output must contain .claude/worktrees/{NNN}-{slug}. If pwd does NOT show the worktree path, cd into .claude/worktrees/{NNN}-{slug}/ before continuing.

Immediately rename the branch (EnterWorktree adds a worktree- prefix):

git branch -m {NNN}-{slug}

Verify the rename succeeded:

git branch --show-current

It should print {NNN}-{slug} (no worktree- prefix). The branch name for Step 8 is {NNN}-{slug}.

Copy the spec artifacts into the worktree:

cp -r {REPO_ROOT}/specs/{NNN}-{slug}/ specs/{NNN}-{slug}/

Where {REPO_ROOT} is the main working tree root (the parent of .claude/worktrees/). This makes spec.md, plan.md, tasks.md, and state.json available inside the worktree.

All subsequent steps run from the worktree.

If EnterWorktree fails (worktree already exists from a previous run):

cd .claude/worktrees/{NNN}-{slug}
git branch --show-current

If the branch name starts with worktree-, rename it: git branch -m {NNN}-{slug}

---

3. Phase 1 — Sequential Core Implementation

Execute tasks T001 → T002 → ... through all Phase 1 tasks in order.

For each task:

1. Perform the work described in the Do field
2. Run the Verify check
3. Mark complete in specs/{NNN}-{slug}/tasks.md: - [ ] → - [x]
4. Update specs/{NNN}-{slug}/state.json — set task to the next task ID (or null after the last task)

Deviation rules:

Situation	Action
Bug, import error, or type mismatch	Fix silently — note for CP1
Missing dependency	Fix silently — note for CP1
Architectural approach needs to change	STOP. Explain to user and ask how to proceed.
Task is impossible as written	STOP. Explain why and ask how to proceed.

After the last Phase 1 task, start in background:

nx build ngx-dev-toolbar

---

4. Phase 2 — Parallel Agents (normal mode only)

Skip if spec.md shows mode is "minimal".

Launch all [P][A] tasks in a single message as parallel subagents:

test-expert subagent (T005 — always in normal mode):

Write Jest unit tests for the changed files. Follow AAA pattern (Arrange / Act / Assert). Use Angular TestBed for component tests. Test signals using computed and effect where relevant. Place spec files adjacent to source files.

Files to test: {list from T005} Reference existing spec files for patterns: {existing .spec.ts from project}

Mark T005 complete in specs/{NNN}-{slug}/tasks.md when done.

docs-expert subagent (T006 — only if plan.md flagged docs work):

{If Astro docs page needed}: Create or update the docs page at apps/docs/src/content/docs/... following the structure of existing pages. Feature: {name}. Public API from spec: {from spec.md requirements}.

{If README update needed}: Add the new tool/feature to the tools list and usage section in README.md. Follow existing entry format. Only update for new public-facing tools or major API changes.

Mark T006 complete in specs/{NNN}-{slug}/tasks.md when done.

Wait for both subagents to complete before proceeding to CP1.

---

5. Checkpoint 1 — Code Review

Display exactly this format, then use the AskUserQuestion tool:

--- CP1: Implementation ---
Phase 1: T001–T00N complete
Phase 2: tests written, docs updated  (or "N/A — minimal mode")

Changes:
- path/to/file: [one line description]
- path/to/file: [one line description]

Silent fixes: [list any, or "none"]

Verification:
- [ ] {scenario from spec}  →  expected result
- [ ] {edge case from spec}  →  expected result

Run tests: nx test ngx-dev-toolbar

Call AskUserQuestion with these options:

• Continue — proceed to Phase 2 / commit
• Fix — user provides fix notes in the "Other" field; address the issue, update tasks.md, return to CP1

Start in background: git fetch origin main

---

6. Checkpoint 2 — Test Results

Only show this checkpoint if the user ran tests after CP1.

Display exactly this format, then use the AskUserQuestion tool:

--- CP2: Test Results ---
{Pass — all N tests passing}

  — or —

{Which tests failed and why (brief diagnosis)}

Call AskUserQuestion with these options:

• Continue — proceed to CP3
• Fix — user provides fix notes in the "Other" field; fix failing tests, return to CP2

---

7. Checkpoint 3 — Commit + PR

Display exactly this format, then use the AskUserQuestion tool:

--- CP3: Commit & PR ---
Commit: {type}({scope}): {short description}
        Closes #{N}  (omit if no issue)

PR title:  {type}({scope}): {short description}
PR body:
  ## What
  - [bullet from spec What Changes / Summary]
  - [bullet from spec What Changes / Summary]

  ## Why
  [one sentence from spec Why / Summary]

  ## Testing
  - [verify step from tasks]
  - [verify step from tasks]

  Closes #{N}  (omit if no issue)

Call AskUserQuestion with these options:

• Approve — proceed to commit and PR
• Edit commit — user provides notes in the "Other" field; apply changes to commit message, redisplay CP3
• Edit PR — user provides notes in the "Other" field; apply changes to PR body, redisplay CP3

---

8. Commit + PR

Stage the changed files explicitly (no git add -A). Always include the spec artifacts (specs/{NNN}-{slug}/) alongside implementation files:

git add path/to/file1 path/to/file2 ... specs/{NNN}-{slug}/

Commit using conventional commit format:

git commit -m "{type}({scope}): {short description}" -m "Closes #{N}"

Rules:

• type: feat, fix, refactor, docs, or chore
• scope: lowercase, from primary directory modified (e.g., toolbar). Omit if unclear.
• Short description: imperative, lowercase, no period, max 72 chars
• Closes #N line: only if issue number exists
• No Co-Authored-By or attribution lines

Push and open PR (use the branch name obtained from git branch --show-current in Step 2):

git push -u origin {branch-name}
gh pr create \
  --title "{type}({scope}): {short description}" \
  --body "$(cat <<'EOF'
## What

- [bullet from spec]
- [bullet from spec]

## Why

[one sentence from spec]

## Testing

- [verify step from tasks]
- [verify step from tasks]

Closes #{N}
EOF
)"

Rules:

• PR title matches commit message exactly
• Closes #N only if issue exists — omit otherwise
• No "Generated with Claude Code" or any AI attribution

---

9. Summary

Display exactly this format:

--- Done ---
Feature: {Feature Name}
Commit:  {type}({scope}): {description}
PR:      {PR URL}
Branch:  {branch-name}

sdd.plan.md

description	SDD — Spec-Driven Development: write a lean implementation plan.
handoffs	label agent prompt send Generate Tasks sdd.tasks Generate tasks for this plan true

Steps

1. Load Context

If $ARGUMENTS is provided, use specs/{$ARGUMENTS}/ as the target directory. Otherwise, find the most recently modified directory under specs/ that contains a spec.md.

Read in parallel:

• specs/{NNN}-{slug}/spec.md — feature name, requirements, scenarios
• specs/{NNN}-{slug}/state.json — current step/task (if exists)

If no spec found, stop: "Run /sdd.specify first."

Update specs/{NNN}-{slug}/state.json:

{ "step": "plan", "task": null, "updated": "{TODAY}" }

---

2. Write specs/{NNN}-{slug}/plan.md

# Plan: {Feature Name}

**Spec**: [spec.md](./spec.md) | **Date**: {TODAY}

## Approach

[2–3 sentences: what we're building, the key architectural decision, and why that approach.]

## Files

### Create

| File | Purpose |
|------|---------|
| `path/to/new-file` | [what it does] |

### Modify

| File | Change |
|------|--------|
| `path/to/existing` | [what changes and why] |

## Risks

[Only if genuinely non-obvious risks exist. Omit section entirely otherwise.]

- [Risk]: [Mitigation]

Skip: research.md, data-model.md, contracts/, quickstart.md, constitution checks, auxiliary work flags, Mermaid diagrams (unless data flow is non-obvious).

---

3. Checkpoint — Plan Review

Display the full contents of plan.md, then use the AskUserQuestion tool with:

--- Plan ready for review ---
[paste plan.md content]

Call AskUserQuestion with these options:

• Approve — proceed to summary and offer sdd.tasks handoff
• Edit — user provides edit notes in the "Other" field; apply changes, update plan.md, redisplay checkpoint

Do NOT proceed to tasks or close the command until the user responds.

• On Approve: show the summary below and offer the sdd.tasks handoff.
• On Edit: apply the changes, update plan.md, then redisplay this checkpoint.

---

4. Summary

Display exactly this format:

--- Plan complete ---
Feature: {Feature Name}
Plan:    specs/{NNN}-{slug}/plan.md  —  {N} files to create, {N} to modify

Next: /sdd.tasks {NNN}-{slug}

sdd.specify.md

description	SDD — Spec-Driven Development: write a lean spec for rapid iteration.
handoffs	label agent prompt send Build Plan sdd.plan Create a lean plan for this spec true

User Input

$ARGUMENTS

If $ARGUMENTS is empty, stop and say: "Provide a feature description: /sdd.specify <description>"

---

Steps

1. Parse Input

Extract the feature description from $ARGUMENTS.

Generate a concise slug (2–4 words, action-noun format, lowercase, hyphens):

• "add clickable file references" → clickable-file-refs
• "fix payment timeout bug" → fix-payment-timeout
• Preserve technical terms (OAuth2, JWT, API)

---

2. Determine Spec Number + Create Directory

Scan specs/ locally for directories matching [0-9]+-*:

• Extract the highest number N found; use N+1 as the new number.
• If no spec dirs exist, start at 1.

mkdir -p specs/{NNN}-{slug}

Write specs/{NNN}-{slug}/state.json:

{ "step": "specify", "branch": "{NNN}-{slug}", "task": null, "updated": "{TODAY}" }

---

3. Explore Inline

Without spawning a subagent, read 2–3 relevant files to understand the feature area:

• Run Glob and Grep searches in parallel (single message, multiple tool calls) to find files related to the feature description
• Read key sections to understand patterns, architecture, and constraints

---

4. Detect Complexity

Based on what you found in Explore, classify the change:

Signal	Mode
Touches 1 existing file, change is <10 lines	minimal
Pure style or config tweak	minimal
Touches 2+ files, or adds a new component/service	normal
Introduces new public behavior or API	normal

If unclear, default to normal.

---

5. Write specs/{NNN}-{slug}/spec.md

# Spec: {Feature Name}

**Branch**: {NNN}-{slug} | **Date**: {TODAY}

## Summary

[2–3 sentences: what the feature does and why it's needed.]

## Requirements

- **R001** (MUST): [Critical requirement — testable and unambiguous]
- **R002** (MUST): [Critical requirement]
- **R003** (SHOULD): [Important but not blocking]

## Scenarios

### {Behavior Area}

**When** [user action or system event]
**Then** [expected outcome]

### {Edge Case or Secondary Flow}

**When** [condition]
**Then** [outcome]

## Out of Scope

- [What this intentionally does NOT cover]

Skip: clarification rounds, formal edge case analysis, exploration findings section, quality checklists.

---

6. Minimal Mode — Write plan.md + tasks.md

Skip this step if mode is normal.

Write specs/{NNN}-{slug}/plan.md:

# Plan: {Feature Name}

**Spec**: specs/{NNN}-{slug}/spec.md | **Date**: {TODAY}

## Approach

[1–2 sentences describing the implementation strategy.]

## Files to Change

- `path/to/file` — [what changes]

## Phase 1 Tasks

| ID | Do | Verify |
|----|-----|--------|
| T001 | [task description] | [verification step] |

Write specs/{NNN}-{slug}/tasks.md:

# Tasks: {Feature Name}

## Phase 1 — Core

- [ ] **T001** · [task description]
  - **Do**: [specific action]
  - **Verify**: [how to confirm it works]

Update specs/{NNN}-{slug}/state.json:

{ "step": "tasks", "branch": "{NNN}-{slug}", "task": null, "updated": "{TODAY}" }

---

7. Summary

Minimal mode — display exactly this format:

--- Specify complete (Fast Mode) ---
Feature: {Feature Name}  |  Branch: {NNN}-{slug}
Spec:    specs/{NNN}-{slug}/spec.md
Plan:    specs/{NNN}-{slug}/plan.md
Tasks:   specs/{NNN}-{slug}/tasks.md

Next: /sdd.implement {NNN}-{slug}

Normal mode — display exactly this format:

--- Specify complete ---
Feature: {Feature Name}  |  Branch: {NNN}-{slug}
Spec:    specs/{NNN}-{slug}/spec.md

Next: /sdd.plan {NNN}-{slug}

sdd.tasks.md

description	SDD — Spec-Driven Development: generate a lean phased task list.
handoffs	label agent prompt send Implement sdd.implement Implement the tasks true

Steps

1. Load Context

If $ARGUMENTS is provided, use specs/{$ARGUMENTS}/ as the target directory. Otherwise, find the most recently modified directory under specs/ that contains both spec.md and plan.md.

Read in parallel:

• specs/{NNN}-{slug}/spec.md — feature name, requirements, scenarios
• specs/{NNN}-{slug}/plan.md — approach, files to create/modify
• specs/{NNN}-{slug}/state.json — current step/task (if exists)

If no spec/plan found, stop: "Run /sdd.specify and /sdd.plan first."

Update specs/{NNN}-{slug}/state.json:

{ "step": "tasks", "task": null, "updated": "{TODAY}" }

---

2. Write specs/{NNN}-{slug}/tasks.md

# Tasks: {Feature Name}

**Plan**: [plan.md](./plan.md) | **Date**: {TODAY}

## Format

- `[P]` = Can run in parallel  |  `[A]` = Agent-eligible

---

## Phase 1: Core Implementation (Sequential)

- [ ] **T001** {title} — `path/to/file`
  - **Do**: [Exact action — file path + what to write or change]
  - **Verify**: [build passes / UI shows X / type checks]

- [ ] **T002** {title} *(depends on T001)* — `path/to/file`
  - **Do**: [...]
  - **Verify**: [...]

- [ ] **T003** {title} *(depends on T002)* — `path/to/file`
  - **Do**: [...]
  - **Verify**: [...]

---

## Phase 2: Quality (Parallel — launch agents in single message)

- [ ] **T004** [P][A] Unit tests — `test-expert`
  - **Files**: `path/to/file.spec.ts`
  - **Pattern**: [test framework and patterns used in this project]
  - **Reference**: `path/to/existing.spec.ts`

---

## Progress

| Phase | Tasks | Status |
|-------|-------|--------|
| Phase 1 | T001–T00N | [ ] |
| Phase 2 | T004 | [ ] |

Phase rules:

• Phase 1: all core implementation tasks in dependency order (T001, T002, ...) — always sequential
• Phase 2: always include unit tests; only include a docs task if plan.md explicitly flagged docs work
• Omit Phase 2 entirely for trivial single-file changes
• Use [P][A] markers only in Phase 2

Skip: dependency graphs, user story labels ([US1] etc.), parallel execution analysis, formal validation steps.

---

3. Summary

Display exactly this format:

--- Tasks complete ---
Feature: {Feature Name}
Tasks:   specs/{NNN}-{slug}/tasks.md  —  {N} tasks ({N} sequential, {N} parallel)

Next: /sdd.implement {NNN}-{slug}