codez-sdd-runner

Spec-Driven Development runner for Claude Code. Automate the full cycle: Requirements → Design → Tasks → Execution.

Write specs, let Claude execute them task by task — with verification, retry, and auto-commit.

How it works

You describe a feature
    ↓
SDD creates 3 spec files:
  requirements.md  →  design.md  →  tasks.md
    ↓
sdd-runner spawns Claude sessions to execute each task:
  parse task → build prompt → claude -p → verify → git commit → next
    ↓
All tasks done. Ship it.

Install

npm install -g codez-sdd-runner

Prerequisites:

• Node.js >= 18
• Claude CLI installed and authenticated
• Python 3 (for config parsing in runner)
• Git

Quick Start

# 1. Initialize config in your project
cd your-project
sdd init

# 2. Create your spec (manually or with Claude Code)
mkdir -p docs/specs/my-feature
# Write requirements.md, design.md, tasks.md

# 3. Run it
sdd run docs/specs/my-feature

# 4. Check progress
sdd status docs/specs/my-feature

Commands

| Command | Description | |---------|-------------| | sdd init | Create sdd.config.json and copy templates | | sdd run <spec-dir> | Execute all tasks in a spec directory | | sdd status <spec-dir> | Show task completion progress | | sdd parse <tasks.md> | Parse tasks.md to JSON (--next / --stats) |

Run options

sdd run docs/specs/auth --model sonnet    # Use a different model
sdd run docs/specs/auth --max-retries 2   # Retry failed tasks up to 2 times
sdd run docs/specs/auth --auto            # Skip checkpoint pauses

Configuration

sdd.config.json at your project root:

{
  "model": "opus",
  "maxRetries": 1,
  "maxConsecutiveFailures": 3,
  "specDir": "docs/specs",
  "autoCommit": true,
  "commitPrefix": "feat(sdd)",
  "verify": {
    "build": "npm run build",
    "test": "npm test",
    "lint": "npm run lint",
    "typecheck": "npx tsc --noEmit"
  },
  "context": {
    "projectInstructions": "CLAUDE.md",
    "memory": "docs/decisions.md",
    "projectMap": "docs/architecture.md"
  },
  "postTaskFiles": {
    "changelog": "CHANGELOG.md",
    "projectMap": "docs/architecture.md",
    "memory": "docs/decisions.md"
  },
  "timeouts": {
    "S": 600,
    "M": 900,
    "L": 1200,
    "XL": 1800
  }
}

Key settings

• model — Claude model for task execution (opus, sonnet, haiku)
• verify — Commands run after each task. Use "full" in tasks.md to run all 5 checks
• context — Files injected into every task prompt (project instructions, decisions, architecture)
• postTaskFiles — Files Claude should update after completing tasks (set to null to disable)
• timeouts — Seconds per complexity level (S/M/L/XL)

tasks.md Format

# Tasks

- [ ] 1. Set up database schema
    - _Requirements: REQ-1, REQ-2_
    - _Verify: build_
    - _Complexity: M_
    - Create users and sessions tables
  - [ ] 1.1 Write Prisma schema
      - _Verify: build_
      - _Complexity: S_
  - [ ] 1.2 Generate migration
      - _Depends: 1.1_
      - _Complexity: S_
- [ ] 2. Implement auth endpoints
    - _Requirements: REQ-3_
    - _Verify: test_
    - _TDD: true_
    - _Complexity: L_
- [ ] 3. Checkpoint — integration review
    - _Pause: true_

Annotations

| Annotation | Values | Purpose | |-----------|--------|---------| | _Requirements: REQ-1, REQ-2_ | Comma-separated IDs | Links to requirements.md sections for prompt injection | | _Verify: build_ | build / test / lint / full / custom command | Post-task verification | | _Complexity: M_ | S / M / L / XL | Timeout control | | _Depends: 1.1, 1.2_ | Comma-separated task IDs | Dependency — waits for these to complete | | _Pause: true_ | true / false | Pause for manual review before executing | | _TDD: true_ | true / false | Force test-driven development | | _Browser: true_ | true / false | Enable browser visual verification | | _BrowserURL: http://..._ | URL | Target URL for browser check | | _BrowserCheck: description_ | Natural language | Expected UI state |

Execution Pipeline

For each task, the runner:

1. Parse — Read tasks.md, find next executable task (respects dependencies)
2. Build prompt — Inject project context + spec sections + task details
3. Execute — claude -p --dangerously-skip-permissions --model <model>
4. Verify — Run configured verification commands (build/test/lint/full)
5. Review — Lightweight spec compliance check via Claude Haiku
6. Commit — Auto git commit with task ID in message
7. Loop — Next task, or stop after 3 consecutive failures

Claude Code Skill

Copy skill/SKILL.md to .claude/skills/sdd/SKILL.md in your project to enable the /spec slash command in Claude Code.

Three Execution Modes

| Mode | How | Best for | |------|-----|----------| | SDD Runner | sdd run <spec> in a standalone terminal | Hands-off batch execution | | Manual | Claude Code reads tasks.md, executes interactively | Tasks needing discussion | | Kiro | Push spec to Kiro IDE via kiro-bridge MCP | Parallel execution |

License

MIT