sdd-design
Skill256 starsChanged 2 months agoMITView on GitHub
Create the architecture and technical specification for a defined feature — Phase 2 of the SDD workflow. Transforms a validated DEFINE document into a DESIGN document: architecture diagram, components, inline architecture decision records, an agent-matched file manifest, KB-grounded code patterns, and a testing strategy — then updates the DEFINE status and hands off to /build. Use when requirements are captured and technical design is needed — "design the architecture", "technical design", "Phase 2", or /design pointed at a DEFINE_*.md file. Not for capturing or clarifying requirements (that is sdd-define, Phase 1) and not for implementing code (that is sdd-build, Phase 3).
8 other projects use a version of this.
Adopted by
Most recently taken up by
- GabrielaStark/starktheir own version, first seen Nov 1, 2026
- svg153/skillstheir own version, first seen Nov 1, 2026
- PedroMosquera/squadaitheir own version, first seen Oct 13, 2026
- pchemguy/Skill-SDD-Managertheir own version, first seen Oct 6, 2026
- duviolin/sdd-kittheir own version, first seen Sep 19, 2026
- GabrielaStark/SDDtheir own version, first seen May 25, 2026
Used with
Projects with it also use sdd-requirements.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
GabrielaStarkSkillsdd-requirements
Use this skill whenever generating, validating, or editing a requirements.md file for Spec-Driven Development. Defines the canonical structure (Kiro-strict format), EARS notation rules in English, mandatory validation checklist, and good/bad examples. Trigger whenever the task involves transforming raw input (interviews, transcripts, legacy code analysis) into a formal requirements.md, or when reviewing an existing requirements.md for compliance.
Also in 3 projects that use this
Other versions8 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 8
- PedroMosquera/squadai★ 10same name
- GabrielaStark/SDD★ 1same name
- GabrielaStark/stark★ 1same name
- Maicololiveras/praxisgenai-agent-orchestrator★ 1same name
- svg153/skills★ 1same name
- callingcard1973/claude-skills★ 0same name
- duviolin/sdd-kit★ 0same name
- pchemguy/Skill-SDD-Manager★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository20 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- agent-routerSkill
- component-modelSkill
- create-agentSkill
- create-skillSkill
- excalidraw-diagramSkill
- github-cr-adrSkill
- github-cr-issueSkill
- github-post-issueSkill
- github-review-prSkill
- kb-buildSkill
- meeting-analysisSkill
- sdd-brainstormSkill
- sdd-buildSkill
- sdd-defineSkill
- sdd-iterateSkill
- sdd-shipSkill
- sdd-workflowSkill
- standup-reportSkill
- visual-explainerSkill
The file
We split this skill into the rules it gives an agent
6 rules. 0 are common, 2 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 6 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
No DEFINE, no design. If requirements are missing or incomplete, stop and route to sdd-define first.
- Very specific: line 154
Every file gets an agent or an explicit (general) fallback.
- Very specific: line 186
Run the quality gate below, then write .claude/sdd/features/DESIGN_{FEATURE_NAME}.md following the template.
- Distinctive: line 199
When the DEFINE contains data engineering context — sources, volumes, freshness SLAs, schema contracts — the DESIGN must also include …
- Distinctive: line 209
Every item must pass before the phase is declared complete:
- Very specific: line 227
Before handing off to /build, validate the document just written against this phase's contract — artifact DESIGN_{FEATURE_NAME}.md, phase …
“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
SDD Design — Architecture and Technical Specification (Phase 2)
Transform a validated DEFINE document into a comprehensive DESIGN document: system architecture with diagrams, key decisions with rationale (inline ADRs), an agent-matched file manifest, KB-grounded code patterns, and a testing strategy.
This skill owns the Phase 2 methodology. The design-agent is the executor (identity, tools, boundaries); the /design command is the entrypoint (argument surface and command-only flags). Contract-grade facts — inputs, outputs, status transitions — are canonical in .claude/sdd/architecture/WORKFLOW_CONTRACTS.yaml.
Inputs and Outputs
| Contract | Value |
| Input | .claude/sdd/features/DEFINE_{FEATURE}.md — required sections: problem statement, success criteria, acceptance tests |
| Output | .claude/sdd/features/DESIGN_{FEATURE}.md |
| Artifact shape | .claude/sdd/templates/DESIGN_TEMPLATE.md — the authoritative section structure; follow it, do not invent sections |
| DESIGN status values | Draft → In Progress → Ready for Build (later phases advance it to ✅ Complete (Built), then ✅ Shipped) |
| On completion | DEFINE status → ✅ Complete (Designed) and hand off to /build (Step 7) |
No DEFINE, no design. If requirements are missing or incomplete, stop and route to sdd-define first.
Knowledge Architecture
KB-FIRST RESOLUTION IS MANDATORY, NOT OPTIONAL.
┌─────────────────────────────────────────────────────────────────────┐
│ KNOWLEDGE RESOLUTION ORDER │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 1. KB PATTERN LOADING (from DEFINE's KB domains) │
│ └─ Read: .claude/kb/{domain}/patterns/*.md → Code patterns │
│ └─ Read: .claude/kb/{domain}/concepts/*.md → Best practices │
│ └─ Read: .claude/kb/{domain}/quick-reference.md → Quick lookup │
│ │
│ 2. AGENT DISCOVERY (for file manifest) │
│ └─ Glob: .claude/agents/**/*.md → Available agents │
│ └─ Extract: Role, capabilities, keywords from each │
│ └─ Match: Files to agents based on purpose │
│ │
│ 3. CONFIDENCE ASSIGNMENT │
│ ├─ KB patterns + agent match found → 0.95 → Design with KB │
│ ├─ KB patterns only → 0.85 → Design, note gaps│
│ ├─ Agent match only → 0.80 → Design, validate │
│ └─ No KB, no agent match → 0.70 → Research first │
│ │
│ 4. MCP VALIDATION (for novel patterns) │
│ └─ MCP docs tool (e.g., context7, ref) → Official docs │
│ └─ MCP search tool (e.g., exa, tavily) → Production examples │
│ │
└─────────────────────────────────────────────────────────────────────┘Design Confidence Matrix
| KB Patterns | Agent Match | Confidence | Action |
| Found | Found | 0.95 | Full design with KB patterns |
| Found | Not found | 0.85 | Design with KB, general agent |
| Not found | Found | 0.80 | Design, validate patterns with MCP |
| Not found | Not found | 0.70 | Research before design |
Process
Step 1: Load Context
Read(.claude/sdd/features/DEFINE_{FEATURE}.md) # problem, users, success criteria, acceptance tests
Read(.claude/sdd/templates/DESIGN_TEMPLATE.md) # artifact shape
Read(CLAUDE.md) # project conventions
# Explore codebase for patterns:
Glob(**/*.py) | head -20
Grep("class |def ") | sampleThen load KB patterns from the domains named in the DEFINE (resolution order above) and assign a confidence score from the matrix. Validate novel patterns via MCP before relying on them; at 0.70, research before designing.
Step 2: Create Architecture
Design the solution:
| Component | Content |
| Overview | ASCII diagram of the system |
| Components | Modules/services with purpose and technology |
| Data Flow | How data moves through the system |
| Integration Points | External dependencies |
┌─────────────────────────────────────────────────────────┐
│ SYSTEM OVERVIEW │
├─────────────────────────────────────────────────────────┤
│ [Input] → [Component A] → [Component B] → [Output] │
│ ↓ ↓ │
│ [Storage] [External API] │
└─────────────────────────────────────────────────────────┘Step 3: Document Decisions (Inline ADRs)
For each significant choice:
### Decision: {Name}
| Attribute | Value |
|-----------|-------|
| **Status** | Accepted |
| **Date** | YYYY-MM-DD |
**Context:** Why this decision was needed
**Choice:** What we're doing
**Rationale:** Why this approach
**Alternatives Rejected:**
1. Option A - rejected because X
2. Option B - rejected because Y
**Consequences:**
- Trade-off we accept
- Benefit we gainAt least one decision must carry full rationale. Decisions are permanent — record the "why", not just the "what".
Step 4: Create the File Manifest (Agent Matching)
Discover specialists, then list every file the build will create or modify:
- Glob
.claude/agents/**/*.mdto discover available agents - Extract role, capabilities, and keywords from each
- Match files to agents:
| Match Criteria | Weight | Example |
| File type | High | .tf → infrastructure agent |
| Purpose keywords | High | "parsing" → domain specialist |
| Path patterns | Medium | src/ → core developer |
| KB domain | Medium | {domain} KB → matching specialist |
| Fallback | Low | Any .py → general purpose |
| # | File | Action | Purpose | Agent | Dependencies |
| 1 | main.py | Create | Entry point | @{specialist-agent} | None |
| 2 | config.yaml | Create | Configuration | (general) | None |
| 3 | handler.py | Create | Request handler | @{specialist-agent} | 1, 2 |
Every file gets an agent or an explicit (general) fallback. Record the reasoning in the template's Agent Assignment Rationale section.
Step 5: Define Code Patterns
- Load patterns from the KB domains
- Adapt to the project's existing conventions (grep the codebase)
- Provide copy-paste ready snippets for each key pattern
# Pattern: Handler structure (from .claude/kb/{domain}/patterns/{pattern}.md)
from config import load_config
def handler(request):
"""Entry point following KB pattern."""
config = load_config()
result = process(request, config)
return {"status": "ok"}Step 6: Plan the Testing Strategy
| Test Type | Scope | Tools |
| Unit | Functions | pytest |
| Integration | API | pytest + requests |
| E2E | Full flow | Manual/automated |
The strategy must cover every acceptance test in the DEFINE.
Step 7: Save, Update Statuses, Hand Off
- Run the quality gate below, then write
.claude/sdd/features/DESIGN_{FEATURE_NAME}.mdfollowing the template. Update the DEFINE document — mandatory. Per the status transitions in
WORKFLOW_CONTRACTS.yaml, when the design phase completes:File Field Value DEFINE_{FEATURE}.mdStatus ✅ Complete (Designed)DEFINE_{FEATURE}.mdNext Step /buildSkipping this leaves a stale "Ready for Design" status behind.
- Hand off: suggest
/build .claude/sdd/features/DESIGN_{FEATURE_NAME}.mdas the next step.
Pipeline Architecture (Data Engineering Context)
When the DEFINE contains data engineering context — sources, volumes, freshness SLAs, schema contracts — the DESIGN must also include pipeline-specific sections:
- Detect the DE context in the DEFINE
- Load KB patterns from the
airflow,streaming,data-modeling, anddbtdomains - Fill the template's "Pipeline Architecture (if applicable)" sections: DAG diagram, partition strategy, incremental strategy, schema evolution plan, data quality gates
The section shapes (tables and diagram formats) are defined in DESIGN_TEMPLATE.md — follow them, do not invent variants.
Quality Gate
Every item must pass before the phase is declared complete:
PRE-FLIGHT CHECK
├─ [ ] KB patterns loaded from DEFINE's domains
├─ [ ] ASCII architecture diagram created and clear
├─ [ ] At least one decision with full rationale (inline ADR)
├─ [ ] Complete file manifest (all files listed)
├─ [ ] Agent assigned to each file (or marked general)
├─ [ ] Code patterns are syntactically correct and copy-paste ready
├─ [ ] Testing strategy covers acceptance tests
├─ [ ] No shared dependencies across deployable units
├─ [ ] No circular dependencies in the architecture
└─ [ ] DEFINE status updated to "✅ Complete (Designed)"Contract Gate
Before handing off to /build, validate the document just written against this phase's contract — artifact DESIGN_{FEATURE_NAME}.md, phase design:
tools/spec-linter/spec-lint .claude/sdd/features/DESIGN_{FEATURE_NAME}.md --phase design \
--contracts-file .claude/sdd/architecture/WORKFLOW_CONTRACTS.yamlRun it as tools/spec-linter/USAGE.md documents, and act on the verdict exactly as defined there. The exit-code contract and verdict semantics are owned by that document and by the contract_enforcement block (exit_code_contract, verdict_semantics) of .claude/sdd/architecture/WORKFLOW_CONTRACTS.yaml — which is also where this phase's binding is declared. Read them there rather than assuming: a contract assigns the severity of its own rules, so never reinterpret a verdict, and never assume one the linter did not return.
Anti-Patterns
| Never Do | Why | Instead |
| Skip KB pattern loading | Inconsistent code | Always load KB first |
| Hardcode config values | Hard to change | Use YAML config files |
| Shared code across deployable units | Breaks deployments | Self-contained units |
| Circular dependencies | A depends on B depends on A | Layer the architecture, break the cycle |
| Skip agent matching | Lose specialization | Always match agents |
| Skip the testing strategy | Build has nothing to verify against | Plan tests for every requirement |
| Design without DEFINE | No requirements | Require DEFINE first |
Design Principles
| Principle | Application |
| Diagram First | ASCII art clarifies thinking before prose |
| Self-Contained | Each function/service works independently |
| Config Over Code | Use YAML for tunables |
| KB Patterns | Use project KB patterns, not generic |
| Agent Specialization | Match specialists to files |
| Testable | Every component can be unit tested |
| Decisions Are Permanent | Document the "why", not just the "what" |
Remember
"Design from patterns, not from scratch. Match specialists to tasks."
Mission: Transform validated requirements into comprehensive technical designs with KB-grounded patterns and agent-matched file manifests.
Core Principle: KB first. Confidence always. Ask when uncertain.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

