Skip to main content

​
Quick start

Get started with the SDD plugin by running a complete pipeline from requirements to code.

​
Before you begin

Make sure you’ve installed the plugin and run /sdd:setup in your project directory.
The SDD plugin supports both greenfield (new) and brownfield (existing) projects. Choose the path that matches your situation.

​
New project (greenfield)

Start from zero and build a complete system with full traceability.
1

Initialize the pipeline

Set up pipeline tracking:
/sdd:setup
This creates pipeline-state.json and verifies all components are ready.
2

Gather requirements

Begin interactive requirements elicitation:
/sdd:requirements-engineer
The skill will guide you through:
  • Stakeholder identification
  • Elicitation techniques (interviews, prototypes, observation)
  • Requirements writing in EARS syntax
  • Quality validation
Output: requirements/REQUIREMENTS.mdExample requirement format:
### REQ-F-001: User authentication
- **Statement:** WHEN a user submits login credentials THE system SHALL validate them within 2 seconds
- **Category:** Functional
- **Priority:** Must have
- **Acceptance criteria:**
  - GIVEN valid credentials WHEN user logs in THEN system grants access
  - GIVEN invalid credentials WHEN user logs in THEN system shows error message
3

Generate specifications

Transform requirements into formal technical specs:
/sdd:specifications-engineer
This generates:
  • Domain model with entities and relationships
  • Use cases (UC) with structured workflows
  • API contracts with input/output schemas
  • Behavior-driven development scenarios (BDD)
  • System invariants (INV)
  • Architecture decision records (ADR)
  • Non-functional requirements (NFR)
Output: spec/ directory with multiple files
4

Audit specifications

Automated quality review of all specs:
/sdd:spec-auditor
Detects defects like:
  • Ambiguous language
  • Missing preconditions
  • Untestable assertions
  • Inconsistent workflows
  • Security gaps
The skill then fixes detected issues automatically.Output: audits/AUDIT-BASELINE.md
5

Plan testing

Generate comprehensive test strategy:
/sdd:test-planner
Creates:
  • Test plan with scope and approach
  • Traceability matrix (REQ → UC → BDD → Test)
  • Performance scenarios with load profiles
  • Edge case coverage analysis
Output: test/ directory
6

Design architecture

Create architecture with C4 diagrams:
/sdd:plan-architect
Generates:
  • C4 Context, Container, and Component diagrams
  • FASE files (Functional Architecture Specification Episodes)
  • Implementation plan with phases
  • Technology stack decisions
Output: plan/ directory
7

Generate tasks

Decompose architecture into atomic tasks:
/sdd:task-generator
Each task:
  • Maps to exactly one commit
  • References source artifacts (FASE, UC, ADR)
  • Includes acceptance criteria
  • Specifies files to modify
Output: task/ directory with TASK-F0-001.md, TASK-F0-002.md, etc.
8

Implement code

Write code and tests with TDD:
/sdd:task-implementer
For each task:
  1. Writes tests first (BDD scenarios)
  2. Implements code to pass tests
  3. Commits with Refs: and Task: trailers for traceability
Output:
  • src/ with source code
  • tests/ with test files
  • Git commits with full traceability
After completing the pipeline, generate a visual dashboard to see all connections:
/sdd:dashboard

​
Existing project (brownfield)

Adopt SDD in a project that already has code.
1

Diagnose your project

Get an adoption plan tailored to your codebase:
/sdd:onboarding
The skill analyzes your project and classifies it into one of 8 scenarios:
  • Code-only (no docs)
  • Code + informal docs
  • Code + formal specs but stale
  • And 5 more scenarios
Output: onboarding/ONBOARDING-REPORT.md with:
  • Health score (0-100)
  • Detection signals (what was found)
  • Recommended action plan
  • Estimated effort per step
2

Import existing docs (optional)

Convert external documentation to SDD format:
/sdd:import docs/api.yaml
Supported formats:
  • OpenAPI / Swagger (YAML, JSON)
  • Jira exports (CSV, JSON)
  • Markdown documents
  • Notion pages
  • Excel/CSV spreadsheets
Output: requirements/REQUIREMENTS.md and spec/ files
3

Reverse engineer from code

Extract specs from existing codebase:
/sdd:reverse-engineer
Analyzes code to generate:
  • Requirements (inferred from behavior)
  • Use cases (from API endpoints and functions)
  • Domain model (from classes and types)
  • Invariants (from validation logic)
  • Architecture decisions (from patterns used)
Also produces a findings report with:
  • Dead code
  • Technical debt
  • Workarounds and infrastructure issues
Output:
  • requirements/REQUIREMENTS.md
  • spec/ directory
  • findings/FINDINGS-REPORT.md
4

Reconcile specs with code

Detect and fix drift between specs and implementation:
/sdd:reconcile
Finds divergences classified as:
  • New functionality (in code, not in specs)
  • Removed features (in specs, not in code)
  • Behavioral changes
  • Refactorings
  • Bugs or defects
Then helps you align specs with reality.Output: reconciliation/RECONCILIATION-REPORT.md with alignment percentage

​
Monitor and maintain

Once the pipeline is running, use these utilities:

​
Check pipeline status

See where you are and what’s next: 
/sdd:pipeline-status
Shows:
  • Current stage
  • Completed stages
  • Pending stages
  • Staleness warnings (if upstream artifacts changed)

​
View traceability

Generate an interactive HTML dashboard: 
/sdd:dashboard
Opens in your browser with 5 views:
  1. Pipeline — Progress through 7 stages
  2. Requirements — All REQs with coverage indicators
  3. Graph — Interactive network visualization
  4. Coverage — Gap analysis by domain/layer
  5. Search — Find any artifact by ID or text
The dashboard includes code and commit traceability if you have src/ and .git/ in your project.

​
Verify traceability chain

Check for broken links and orphans: 
/sdd:traceability-check
Reports:
  • Orphaned artifacts (nothing references them)
  • Broken references (reference non-existent IDs)
  • Coverage gaps (REQs without UCs, UCs without TASKs, etc.)

​
Change a requirement

Update requirements with cascading changes: 
/sdd:req-change --cascade=auto
When you modify a requirement, this skill:
  1. Identifies all downstream artifacts affected
  2. Updates specs, tests, tasks, and code
  3. Maintains full traceability
  4. Creates an audit trail
This is a powerful operation. Use --cascade=manual to review changes before applying them.

​
Real-world example

Here’s what a complete trace looks like: 
REQ-F-001 (Validate PDF size limit)
  ↓ implements
UC-001 (Upload PDF document)
  ↓ orchestrates
WF-001-STEP-2 (Validate file)
  ↓ enforces
INV-EXT-005 (PDF size ≤ 50MB)
  ↓ tests
BDD-UC-001-02 (Rejects oversized PDF)
  ↓ informs
TASK-F1-003 (Implement PDF validator)
  ↓ implemented-by
commit abc1234 (feat: add PDF size validation)
  ↓ contains
src/extraction/validators/pdf-validator.ts:validateSize
  ↓ tested-by
tests/unit/extraction/pdf-validator.test.ts:validateSize
You can explore this chain visually in the dashboard or query it with MCP tools: 
# In Claude Code, if MCP server is running:
Use the sdd_trace tool to show the full chain for REQ-F-001

​
Next steps

Pipeline skills

Deep dive into each of the 7 pipeline steps

Utility skills

Learn about security auditor and requirements change management

Traceability

Understand how artifacts connect from requirements to code

MCP tools

Use the traceability API for queries and impact analysis

Build docs developers (and LLMs) love

Get started for freeTalk to us