Raw capture — raw/sddw.md

url: https://github.com/sermakarevich/sddw date_fetched: 2026-07-05 backfilled: true

Spec-Driven Development Workflow for Claude Code.

• Write requirements, optionallyanalyse the codebase, thendesignarchitecture, thentaskify(as hybrid task files referencingdesign.md), thenimplementeach task separately, thenverifythe result, thenself-improvethe 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.
• /clearcontext 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

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.

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

Every step supports two interaction modes:

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.

• 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.mdwith 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

/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

/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

Output: .sddw/code-analysis.md (shared across features) Sections: Relevant Patterns, Key Interfaces, Existing Flows, Conventions

Skip this step for greenfield projects with no existing codebase.

/sddw:design <feature-name> [--auto]

Produce a cross-cutting design.md through guided dialog:

• Discover— understand architectural preferences and constraints
• Research & Propose— propose architecture, data models, contracts, and decisions
• Confirm & Generate— user approves each block,- design.mdis written

Output: .sddw/<feature-name>/design/design.md

/sddw:taskify <feature-name> [--auto]

Break the feature into hybrid task files based on requirements and design:

• Discover— understand task granularity preferences
• Research & Propose— propose task breakdown in dependency order
• Confirm & Generate— user approves task list, task files are written

Output:

.sddw/<feature-name>/
└── design/
    ├── design.md
    └── tasks/
        ├── task-1-<slug>.md  # hybrid: files, criteria, references design.md
        ├── task-2-<slug>.md
        └── ...

Each task file includes task-specific details inline and references design.md for architecture, models, and shared contracts, so the implementation agent has full context without duplication.

/sddw:design_and_taskify <feature-name> [--auto]

Runs the design and taskify steps in one shot. Use this for small features where iterating on architecture independently is not needed.

/sddw:implement <feature-name> --task <N> [--auto]

Execute a single task from the design spec:

• Discover— select task, check dependencies, gather context
• Research & Propose— scan codebase, propose implementation approach and TDD applicability
• Execute— implement following TDD protocol, commit protocol, and deviation handling

Each task file is a hybrid — the agent loads it alongside design.md so it has full context.

After each task, a completion report (task-N-<slug>.done.md) is written to implement/tasks/, documenting what was done, deviations, and difficulties.

/sddw:verify <feature-name> [--auto]

Verify the implementation against requirements after all tasks are complete:

• Assess— load artifacts, detect test runner, check task completion status
• Verify— run test suite, cross-check each FR's acceptance criteria, review done criteria
• Report & Remediate— produce verification report, create remediation tasks if issues found

Output:

.sddw/<feature-name>/
└── verify/
    └── report.md    # FR-by-FR pass/fail, test results, deviations, warnings

If issues are found, remediation tasks are created as additional task files in design/tasks/ (continuing the numbering). These can be executed with /sddw:implement and then verified again — the loop repeats until all checks pass.

/sddw:self-improve <feature-name> [--auto]

Analyse the completed feature's execution across all workflow steps. Identify what went wrong (or could be better) and propose concrete improvements to the workflow itself:

• Analyse— extract signals: deviations, difficulties, remediation task origins, spec gaps
• Diagnose— classify findings by workflow step, identify patterns, propose improvements
• Apply— present proposals with diff previews, apply approved changes to workflow files

Output:

.sddw/<feature-name>/
└── self-improve/
    └── report.md    # findings, proposals, applied/skipped changes

Each improvement targets a specific workflow component (instruction, questionnaire, or spec) with a concrete diff. The workflow evolves with every feature — gaps found during one feature prevent the same issues in the next.

/sddw:chat <feature-name> [--auto]

Fast-track interaction with a feature that already has artifacts. Skips the full questionnaire ceremony — just load context and talk.

• Questions— ask anything about the feature; answered from loaded artifacts and codebase
• Spec updates— edit requirements, FRs, acceptance criteria, or task files in-place
• Quick implementation— small code changes following TDD and commit protocols
• Status— check feature progress

Chat assumes you know what you want and only pauses for scope-affecting changes or ambiguous requests.

If a request is too large (new task files, new architecture, >3 files), chat redirects you to the full workflow.

/sddw:help [list | status <feature-name>]

• /sddw:help— workflow overview and available commands
• /sddw:help list— list all features with progress indicators
• /sddw:help status <feature-name>— detailed feature status: which steps are done, task progress, completion reports

Each step is assembled from four modular components:

A command wires these together:

┌──────────────────────────────────────────────────────────┐
│ commands/<step>.md                                       │
│                                                          │
│  @instructions/<step>.md        ← process rules          │
│  @questionnaires/<step>.md      ← dialog flow            │
│  @specs/<step>.md               ← output format          │
│                                                          │
│  reads:  .sddw/<feature>/<previous_step>.md  ← input     │
│  writes: .sddw/<feature>/<current_step>.md   ← output    │
└──────────────────────────────────────────────────────────┘

Each component lives in its own folder so they can be reused, tested, and evolved independently. The command file itself stays small — just references and glue.

Every step follows a three-phase dialog: Discover → Research & Propose → Confirm & Generate. One question at a time, structured options, every spec block confirmed by the user before generation.