sddw
Spec-Driven Development Workflow for Gemini CLI. An 8-step pipeline: Requirements → Code Analysis → Design → Taskify → Implement → Task Revi
Open source Open in the app JSON README (API)
About
Spec-Driven Development Workflow for Gemini CLI. An 8-step pipeline: Requirements → Code Analysis → Design → Taskify → Implement → Task Review → Verify → Self-Improve. Specifications are the source of truth, code is a verified artifact.
Details
- Kind
- Plugins
- Topic
- Developer tools
- Publisher
- christianmerkwirth
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.1.0
- Stars
- 3
- Last push
- 2026-06-20T11:18:24Z
- Repository state
- ativo
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
christianmerkwirth/sddw-gemini
README
# `sddw-gemini`
Spec-Driven Development Workflow for [Gemini CLI](https://github.com/google-gemini/gemini-cli).
- Write **requirements**, optionally **analyse the codebase**, then **design** architecture, then **taskify** (as hybrid task files referencing `design.md`), then **implement** each task separately, **task-review** each implemented task, 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.
- Two interaction modes: guided dialog (default) or fully `--auto`
- Lightweight and easily customizable — just markdown and TOML files, no runtime dependencies
Also available for [Claude Code](https://github.com/sermakarevich/sddw).
## 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
```bash
gemini extensions install https://github.com/christianmerkwirth/sddw-gemini
```
For development (link from local repo):
```bash
git clone https://github.com/christianmerkwirth/sddw-gemini
cd sddw-gemini
gemini extensions link .
```
## Commands
| Command | Description |
|---------|-------------|
| `/sddw:requirements <feature> [--auto]` | Generate requirements spec |
| `/sddw:code-analysis <feature> [--auto]` | Analyse existing codebase (optional) |
| `/sddw:design <feature> [--auto]` | Generate cross-cutting `design.md` |
| `/sddw:taskify <feature> [--auto]` | Generate hybrid task files from `design.md` |
| `/sddw:design_and_taskify <feature> [--auto]` | Combined alias: design + taskify in one shot |
| `/sddw:implement <feature> --task <N> [--auto]` | Implement a single task |
| `/sddw:task-review <feature> --task <N> [--auto]` | Review a single implemented task |
| `/sddw:verify <feature> [--auto]` | Verify implementation against requirements |
| `/sddw:self-improve <feature> [--auto]` | Analyse execution and improve workflow |
| `/sddw:chat <feature> [--auto]` | Fast-track interaction with an existing feature |
| `/sddw:help [list \| status <feature>]` | Workflow overview and feature status |
## 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 |
## Workflow
### 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
Output: `.sddw/code-analysis.md` (shared across features)
Skip this step for greenfield projects with no existing codebase.
### 3. Design
```
/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.md` is written
Output: `.sddw/<feature-name>/design/design.md`
### 4. Taskify
```
/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.
### Design & Taskify (Combined Alias)
```
/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.
### 5. Implement
```
/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
After each task, a completion report (`task-N-<slug>.done.md`) is written to `implement/tasks/`.
### 6. Task Review
```
/sddw:task-review <feature-name> --task <N> [--auto]
```
A focused, task-level quality gate that runs after each `implement` and before feature-level `verify`. It reviews one task's diff — not a rewrite — and routes back to `implement` when changes are needed:
- **Assess** — load the task file, completion report, and design; identify the diff from the task's commits
- **Review** — run the task's tests and review the changes across six dimensions: criteria conformance, design conformance, convention conformance, code quality, test quality, and deviation integrity
- **Report & Decide** — classify findings (Blocker / Major / Minor) and issue a verdict: **APPROVED** or **CHANGES REQUESTED**
Output: `.sddw/<feature-name>/task-review/task-<N>-<slug>.review.md`
Steps 5 and 6 form a per-task loop: implement a task, review it, then move to the next task. When all tasks are implemented and approved, proceed to verify.
### 7. Verify
```
/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/`. These can be executed with `/sddw:implement` and then verified again.
### 8. Self-Improve
```
/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
```
### Chat
```
/sddw:chat <feature-name> [--auto]
```
Fast-track interaction with a feature that already has artifacts. Skips the full questionnaire ceremony — load context and talk.
- **Questions** — ask anything about the feature
- **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
### Help
```
/sddw:help [list | status <feature-name>]
```
- `/sddw:help` — workflow overview
- `/sddw:help list` — list all features with progress indicators
- `/sddw:help status <feature-name>` — detailed feature status
## Output Structure
All artifacts live under `.sddw/` in the project root:
```
.sddw/
<feature>/
requirements.md # Step 1 output
design/
design.md # Cross-cutting design artefact
tasks/
task-1-<slug>.md # One file per implementation task
task-2-<slug>.md
implement/
tasks/
task-1-<slug>.done.md # Completion reports
task-review/
task-1-<slug>.review.md # Per-task review reports (verdict + findings)
verify/
report.md # FR-by-FR pass/fail, test results
self-improve/
report.md # Findings, proposals, applied changes
code-analysis.md # Optional shared codebase analysis
```
## License
MIT