Sdd Spec
Write delta specifications with functional requirements and Given/When/Then scenarios so behavior is agreed before implementation and verification.
Overview
Sdd-spec is an agent skill most often used in Validate (also Build PM, Ship testing) that writes delta specifications with requirements and Given/When/Then scenarios for SDD changes.
Install
npx skills add https://github.com/fearovex/claude-config --skill sdd-specWhat is this skill?
- Writes delta specs with ADDED, MODIFIED, and REMOVED sections instead of replacing entire documents
- Captures functional requirements and Given/When/Then scenarios as verification-ready behavior
- Resolves SKILL.md from project-local .claude/skills then global ~/.claude/skills per SDD resolution order
- Loads project context via shared sdd-phase-common Section F and optional domain preload before authoring
- Triggered by /sdd-spec <change-name> as the specification phase of spec-driven development (metadata v3.0)
- Delta spec surface: ADDED, MODIFIED, and REMOVED sections
- Skill metadata version 3.0
- Two-tier SKILL.md resolution paths: project-local then global catalog
Adoption & trust: 1 installs on skills.sh; 1 GitHub stars; 3/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
You have a change idea but no behavioral contract—implementation and tests will drift because nobody wrote verifiable requirements.
Who is it for?
Solo builders running fearovex-style SDD who want specs as deltas with explicit scenarios before any build sub-agent runs.
Skip if: Quick one-off tweaks where a ticket comment is enough, or teams that skip spec-driven gates and code directly from chat.
When should I use this skill?
Triggers include /sdd-spec <change-name>, write specs, specifications, functional requirements, or sdd spec.
What do I get? / Deliverables
You get a delta spec file with requirements and scenarios that define WHAT must hold, ready for implementation and verification agents in the SDD orchestrator.
- Delta specification with requirements
- Given/When/Then scenario blocks
- Verification-oriented behavior contract
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is validate/scope because specs nail observable behavior and change boundaries before full build work commits. Scope subphase is where requirements and acceptance scenarios shrink ambiguity on what ships in a named change.
Where it fits
Author ADDED/MODIFIED requirements for a billing change before any code agent opens the repo.
Refresh scenario lists when PM discovers edge cases mid-sprint without rewriting the whole spec tree.
Align QA checks to Given/When/Then blocks so verification matches the delta spec source of truth.
How it compares
Specification-phase workflow in a spec-driven stack—not a code generator or a linter.
Common Questions / FAQ
Who is sdd-spec for?
Indie developers and small teams using Claude SDD orchestration who need formal, testable requirements written as deltas per change name.
When should I use sdd-spec?
In validate when scoping a change, in build when updating behavior docs alongside features, or in ship when aligning tests to refreshed Given/When/Then scenarios.
Is sdd-spec safe to install?
Review the Security Audits panel on this Prism page; the skill reads project context files—keep secrets out of specs and restrict repo access as usual.
SKILL.md
READMESKILL.md - Sdd Spec
# sdd-spec > Writes delta specifications with requirements and Given/When/Then scenarios. **Triggers**: `/sdd-spec <change-name>`, write specs, specifications, functional requirements, sdd spec --- ## Purpose Specs define **WHAT the system must do** from the perspective of observable behavior. They do not say how to implement it. They are the source of truth for verification. **Key concept — Delta Specs:** Specs are deltas (changes) on top of what already exists, not full replacements. - If there is no existing spec: I write a complete spec - If a spec already exists: I write ADDED/MODIFIED/REMOVED sections --- ## Process ### Skill Resolution When the orchestrator launches this sub-agent, it resolves the skill path using: ``` 1. .claude/skills/sdd-spec/SKILL.md (project-local — highest priority) 2. ~/.claude/skills/sdd-spec/SKILL.md (global catalog — fallback) ``` Project-local skills override the global catalog. See `docs/SKILL-RESOLUTION.md` for the full algorithm. --- ### Step 0a — Load project context Follow `skills/_shared/sdd-phase-common.md` **Section F** (Project Context Load). Non-blocking. ### Step 0b — Domain context preload After loading project context and before identifying affected domains, I perform an optional, non-blocking domain context preload: 1. **List candidates**: List all `.md` files in `ai-context/features/`, excluding `_template.md` and any file whose name begins with an underscore. If the directory is absent, skip this step silently. 2. **Apply the filename-stem matching heuristic**: - Split the change slug on hyphens to produce stems; discard any single-character stems. - For each candidate file, compute its domain slug (filename without `.md` extension). - A match occurs when: the domain slug appears in the change name, OR any change-name stem appears in the domain slug (case-insensitive comparison). 3. **Load matches**: If one or more files match, read each file and inject its content as enrichment context before writing the spec. If no file matches, skip silently — do NOT produce an error or warning. 4. **Multiple matches**: If more than one file matches, load all matching files. 5. **Non-blocking contract**: This step MUST NEVER produce `status: blocked` or `status: failed`. Any file read error is treated as a miss (skip silently). 6. **Enrichment note**: Feature file content is treated as enrichment context — it surfaces business rules, invariants, and known gotchas that should inform the spec's requirements and THEN clauses. Both feature files and any existing domain specs MUST be read when both are present. 7. **Orchestrator reporting**: When one or more feature files are loaded, the `summary` field MUST note that domain context was preloaded (e.g., "domain context loaded from ai-context/features/auth.md"). Each loaded file path MUST appear in the `artifacts` list (read, not written). ### Step 0c — Spec context preload Follow `skills/_shared/sdd-phase-common.md` **Section G** (Spec Context Preload). Non-blocking. --- ### Step 1 — Read prior artifacts I must read: - The proposal artifact (the WHAT and WHY): - `mem_search(query: "sdd/{change-name}/proposal")` → `mem_get_observation(id)` for full content. - If not found and Engram not reachable: proposal content passed inline from orchestrator. - `ai-context/architecture.md` if it exists (to understand the current system) #### Step 1 extended — Validate against Supersedes section After reading the proposal, I perform a Supersedes cross-check before writing any spec: 1. **Check for Supersedes section**: look for `## Supersedes` in the proposal. - **If absent** (older archived change): log `WARNING: proposal has no S