Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jorgeferrando/sdd-skills/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks through a complete SDD cycle from start to finish. You will run /sdd-init to bootstrap your project, start a change with /sdd-new, advance through each phase with /sdd-continue, and close the cycle with /sdd-verify and /sdd-archive. By the end you will have a working openspec/ directory, a full set of steering files, and a change that has been implemented, verified, and archived.
Prerequisites: SDD Skills must be installed before running any /sdd-* command. See the Installation guide for setup instructions. You will also need an AI coding assistant and a Git repository to work in.

​
Full walkthrough

1

Bootstrap your project — /sdd-init

Run /sdd-init once per project. It creates the openspec/ directory structure and runs a guided questionnaire to generate your steering files.
/sdd-init
The skill scans your environment — detecting runtimes, frameworks, Docker containers, and config files — then asks about your product, stack, team conventions, and testing strategy. If code already exists, it detects the stack automatically and asks only project-level questions.When it finishes, you will have seven steering files in openspec/steering/:
FileContent
product.mdWhat the project builds, for whom, bounded context
tech.mdStack, dependencies, dev/test commands
structure.mdDirectory layout, layers, responsibilities
conventions.mdRules that cause PR failures (RFC 2119: MUST/SHOULD/MAY)
environment.mdAvailable MCPs, CLI tools, runtimes, Docker containers
project-skill.mdQuick-reference index pointing to the other steering files
project-rules.mdEmpty initially — grows as the AI learns from your corrections
/sdd-init is safe to re-run. If steering files already exist, it shows the current state instead of regenerating from scratch. Use /sdd-init --quick for minimal questions with sensible defaults — ideal for small projects or quick evaluation.
After init, the skill will suggest two paths: /sdd-new to start your first feature, or /sdd-discover if the project already has existing code that needs specs reverse-engineered.
2

Start a new change — /sdd-new

Tell the AI what you want to build. /sdd-new is the canonical entry point for every change — feature, bugfix, or refactor.
/sdd-new "add health check endpoint"
Internally the skill runs two things in sequence:
  1. Explore — searches archived specs and past decisions for relevant context, then reads the codebase in read-only mode to understand patterns, affected files, and relevant canonical specs. Findings are saved to notes.md.
  2. Propose — reads the exploration notes and steering files. If the description leaves any gaps, it asks specific questions until all sections are covered. Then generates proposal.md.
The resulting proposal.md contains:
# Proposal: Add Health Check Endpoint

## Problem
No way to verify service health without hitting a business endpoint.

## Proposed Solution
Add a /health route that returns 200 with service status.

## Alternatives Discarded
Using an existing endpoint — couples health checks to business logic.

## Impact
Files affected: routes/, tests/. No database migrations needed.
Review the proposal and give feedback directly in the chat if anything needs adjusting. When you are satisfied, advance with /sdd-continue.
3

Spec phase — /sdd-continue or /sdd-spec

With proposal.md approved, run /sdd-continue. It detects that no spec exists yet and launches the spec phase automatically.
/sdd-continue
The spec skill identifies the affected domain and checks whether a canonical spec already exists at openspec/specs/{domain}/spec.md. If one does, it writes a delta spec — only what this change adds or modifies, not a full rewrite. Before writing, it asks clarifying questions to resolve edge cases, validation rules, and error behavior that the proposal left open.The output uses Given/When/Then format:
## Health check endpoint

### Given a running service
**When** `GET /health` is called
**Then** respond with `200 OK` and `{ "status": "ok" }`

**When** a dependency is unavailable
**Then** respond with `503 Service Unavailable` and `{ "status": "degraded" }`
Review the spec carefully — it is the behavioral contract that design and implementation will follow. Run /sdd-continue again when approved.
4

Design and Tasks — /sdd-continue twice

Run /sdd-continue to generate the technical design, then again to break it into tasks.
/sdd-continue   # detects missing design.md → runs /sdd-design
/sdd-continue   # detects missing tasks.md → runs /sdd-tasks
Design phase runs as a non-interactive subagent — it reads the proposal, spec, and existing code patterns, then produces design.md with a technical plan: which files to create or modify, the architecture approach, scope assessment (changes touching more than 20 files trigger a split recommendation), and technical decisions with discarded alternatives.Tasks phase reads design.md and produces an ordered tasks.md. Tasks follow strict dependency ordering — interfaces and contracts first, base files before dependent files, tests after or interleaved with implementation. Each task is atomic: one file, one commit.
## Implementation Tasks

- [ ] **T01** Create `src/routes/health.ts` — health check handler
  - Commit: `[add-health-check] Add health check route handler`

- [ ] **T02** Register route in `src/app.ts`
  - Commit: `[add-health-check] Register /health route`
  - Depends on: T01

- [ ] **T03** Add `tests/routes/health.test.ts` — unit tests
  - Commit: `[add-health-check] Add health check tests`
  - Depends on: T01

## Quality Gate

- [ ] **QG** Run full test suite and linter
Verify the task order and completeness before advancing. Run /sdd-continue once more when approved.
5

Implement — /sdd-apply

With an approved tasks.md, run apply to implement the change.
/sdd-apply
Before touching any code, apply verifies that conventions.md exists — it refuses to start without it. Then it loads all steering files silently.For each pending task, it launches a subagent that:
  1. Reads existing code to follow established patterns
  2. Implements the change
  3. Runs tests and lint on the modified file
  4. Makes an atomic commit: [add-health-check] Description
  5. Marks the task [x] in tasks.md
The main conversation only sees summaries — not the code-reading noise from each subagent. Apply pauses between tasks and asks for confirmation before continuing (use /sdd-apply --auto to skip confirmations for small changes).
If something unexpected comes up during implementation — a dependency conflict, an ambiguous convention, an undocumented pattern — apply stops and asks you. It does not make unilateral decisions. Any unplanned work gets registered as BUG01 or IMP01 in tasks.md before being implemented, so nothing is done without being tracked.
6

Verify — /sdd-verify

When all tasks are marked [x], run verify to perform final quality checks.
/sdd-verify
Verify runs as a non-interactive subagent and performs these checks in sequence:
  1. Full test suite — the entire project’s tests, not just the changed files
  2. Linter/formatter — on changed files, with auto-fix and commit if issues are found
  3. Self-review checklist — tests exist for new code, input validated at boundaries, methods under 50 lines, no hardcoded values, no duplication, type hints complete, spec compliance confirmed
  4. Smoke test — if the project is a UI, runs the app and verifies the golden path
  5. Convention audit — runs /sdd-audit on branch files against conventions.md
  6. PR creation — pushes the branch and creates a pull request using context from proposal.md
The output is a VERIFY REPORT with status READY FOR PR or a list of issues to fix before continuing.
7

Archive — /sdd-archive

Once the PR is reviewed and approved, close the cycle.
/sdd-archive
Archive does three things:
  1. Merges delta specs into canonical — the change specs in openspec/changes/{change-name}/specs/ are integrated into openspec/specs/{domain}/spec.md. If no canonical spec existed for the domain, one is created. Canonical specs now reflect the current system state.
  2. Updates openspec/INDEX.md — adds new entities and keywords introduced by this change so future explores find them.
  3. Moves to archive — the change directory moves to openspec/changes/archive/{date}-add-health-check/. It is no longer active but serves as historical context for future changes in the same domain.
Without archive, canonical specs grow stale. Running it ensures the next developer who explores the codebase sees specs that actually match what the code does.

​
Fast-forward shortcut

When the scope is clear and you do not need to review each phase separately, use /sdd-ff to generate all four planning documents in a single pass. 
/sdd-ff "add health check endpoint"   # proposal + spec + design + tasks in one pass
/sdd-apply                             # implement task by task
/sdd-verify                            # final checks + PR
/sdd-archive                           # close the cycle
/sdd-ff runs propose → spec → design → tasks without pausing between phases. If it finds an ambiguity it cannot resolve on its own, it pauses to ask, then continues. Use it for straightforward changes with clear scope. For large or uncertain changes — those touching multiple domains or requiring architectural decisions — the standard /sdd-new + /sdd-continue path gives you review checkpoints at each phase.
Clear your conversation context between phases. Every SDD phase produces an artifact that captures all decisions made. Once proposal.md exists, the conversation context that produced it is redundant — /sdd-continue reads the files, not the conversation history. Clearing context before /sdd-apply in particular saves significant tokens across the longest phase.

​
Quick reference

Common command flows for different scenarios:
ScenarioCommands
New project from scratch/sdd-init → /sdd-new "..." → /sdd-continue ×4 → /sdd-verify → /sdd-archive
Existing project, first SDD change/sdd-init → /sdd-discover → /sdd-new "..." → /sdd-continue
Quick change, clear scope/sdd-ff "..." → /sdd-apply → /sdd-verify → /sdd-archive
Audit code against conventions/sdd-audit or /sdd-audit src/api/
Update conventions after refactor/sdd-steer sync
Resume interrupted change/sdd-continue (detects the next pending phase automatically)

Understand the full workflow

Read a deeper explanation of why each phase exists, how artifacts chain together, and when to clear context between sessions.

Build docs developers (and LLMs) love

Get started for freeTalk to us