sddw
Spec-Driven Development Workflow for Claude Code.
- Write requirements, optionally analyse the codebase, then design architecture, then taskify (as hybrid task files referencing
design.md), then implement each task separately, then verify the result, then self-improve the workflow
- The agent guides you through every step — researches, proposes options, confirms your decisions
- Every step produces exactly one spec type. Every step reads specs from previous steps.
/clear context between steps — each step works within a focused context window- Two interaction modes: guided dialog (default) or fully
--auto
- Lightweight and easily customizable — just markdown files, no runtime dependencies
Why
The standard way to use AI coding agents is short, interactive prompts: describe what you want, get code, fix it, repeat. This works for small tasks but breaks down for anything non-trivial — context gets lost between sessions, architectural decisions live only in chat history, and there's no artifact a teammate can review before code is written.
sddw inverts this. Instead of prompting for code, you collaborate with the agent to write specifications — requirements, architecture, interface contracts, task breakdowns. The specs become the primary artifact: reviewable by peers, version-controlled, persistent across sessions. Code generation is then a mechanical step guided by approved specs, not a creative leap from a vague prompt.
Detailed specifications reduce AI code errors by up to 50% (Piskala, 2026), security defects by 73% (Marri, 2026), and architecture-misaligned PRs by 60% (GitHub Spec Kit). sddw is designed for medium to large projects that don't fit into a single context window. By splitting work into discrete steps — requirements, codebase analysis, design, per-task implementation — each step operates within a focused context where models are more accurate, rather than a sprawling conversation where critical details get lost.
Install
git clone https://github.com/sermakarevich/sddw.git ~/.claude/sddw
cd ~/.claude/sddw && bash bin/install.sh
For development (symlink from local repo):
git clone https://github.com/sermakarevich/sddw.git
cd sddw && bash bin/install.sh --local
Interaction Modes
Every step supports two interaction modes:
| Mode | Flag | Behavior |
|---|
| Interactive | (default) | Full guided dialog — one question at a time, every section confirmed |
| Auto | --auto | Fully autonomous — no questions, best-judgment decisions |
Usage
Vibecoding — --auto. The agent decides everything.
Agentic engineering — default mode. You stay in control: review proposals, add missing context, ask questions, approve each spec section before it's written, and validate the output spec.
Steps
- Requirements — collaboratively produce a feature spec with user stories, FRs, and acceptance criteria
- Code Analysis (optional) — scan existing codebase for patterns, interfaces, and conventions
- Design — produce a cross-cutting
design.md with architecture, models, and decisions
- Taskify — break the feature into hybrid task files referencing
design.md
- Implement — execute one task at a time following TDD and commit protocols
- Verify — validate the implementation against requirements and acceptance criteria
- Self-Improve — analyse execution across all steps and propose workflow improvements
- Design & Taskify — combined alias: run design and taskify in one shot (
/sddw:design_and_taskify)
- Chat — fast-track interaction with an existing feature: questions, edits, quick fixes
- Help — workflow overview, list features, check feature status
1. Requirements
/sddw:requirements <feature-name> [--auto]
Collaboratively produce a requirements spec through guided dialog:
- Discover — understand the feature through one-at-a-time questions
- Research & Propose — research SOTA, codebase, domain; propose each section with ranked options
- Confirm & Generate — user approves each block, spec is written
Output: .sddw/<feature-name>/requirements.md
Sections: Purpose, User Stories, Functional Requirements, Acceptance Criteria, Constraints
2. Code Analysis (optional)
/sddw:code-analysis <feature-name> [--auto]
Analyse the existing codebase to ground design decisions in reality:
- Discover — understand which areas of the codebase matter most
- Research & Propose — scan for patterns, interfaces, flows, conventions
- Confirm & Generate — user approves each section, analysis is written