This guide walks through the complete SDD setup for a brand new project — from initializing theDocumentation 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.
openspec/ directory to completing your first feature cycle. By the end you will have steering files capturing your project’s context, a working spec-to-code pipeline, and a closed, archived change that proves the workflow end to end.
Prerequisites
- SDD Skills installed (see Installation)
- An AI coding assistant (Claude Code, Cursor, Codex, or GitHub Copilot)
- A git repository initialized (
git init)
Run /sdd-init
/sdd-init is the first command of any SDD project. It creates the openspec/ directory structure, scans your environment, runs a short questionnaire, and generates 7 steering files that every other skill reads to understand your project.| Group | Questions about |
|---|---|
| A — Project | What the system builds, who uses it, what is explicitly out of scope |
| B — Stack | Language, framework, database, testing stack |
| C — Team & rigor | Team size, quality level (MVP/production/open-source), CI/CD |
| D — Tools | Available MCPs (only asked when MCPs are detected in the environment scan) |
| E — Patterns | Architecture style, TDD approach, commit format |
If a stack is already detected (existing
package.json, pyproject.toml, go.mod, Cargo.toml, etc.), Group B is skipped automatically. Use /sdd-init --quick for minimal questions with sensible defaults — only Groups A and B are asked, and C/D/E use sensible defaults.openspec/steering/ contains these 7 files:| File | Content |
|---|---|
product.md | What the project builds and for whom |
tech.md | Stack, dependencies, dev/test commands |
structure.md | Directory layout, layers, responsibilities |
conventions.md | Rules that cause PR failures (RFC 2119: MUST/SHOULD/MAY) |
environment.md | Available MCPs, CLIs, runtimes, Docker containers |
project-skill.md | Quick-reference index pointing to the other steering files |
project-rules.md | Empty at first — 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 re-running the questionnaire.Start your first feature — /sdd-new
Once Internally, Review the proposal and give feedback or approve it before moving on.
openspec/ is initialized, start your first feature with /sdd-new. This single command combines codebase exploration and proposal writing./sdd-new runs two steps:- Explore — reads the codebase in read-only mode to find relevant patterns, affected files, and any existing specs in
openspec/INDEX.md. Writes findings tonotes.md. - Propose — reads the exploration notes, checks for gaps, asks clarifying questions if needed, and generates
proposal.md.
proposal.md follows this structure:Advance through spec, design, and tasks with /sdd-continue
With Second call → DesignThird call → TasksReview and approve the task list before moving to implementation.
proposal.md approved, run /sdd-continue three times — once for each remaining documentation phase. Continue detects which phase is pending by reading your change directory, so you never need to remember the order.First call → Spec/sdd-spec identifies the affected domain, checks whether a canonical spec already exists at openspec/specs/{domain}/spec.md, and writes a delta spec — only what changes, not a full rewrite. It uses Given/When/Then format and resolves edge cases interactively before writing./sdd-design runs as a subagent (non-interactive), reads the proposal and spec, then produces a concrete implementation plan covering files to create, files to modify, architecture decisions, and a scope assessment. Changes touching more than 20 files trigger a split recommendation before continuing./sdd-tasks reads design.md and produces an ordered task list. Tasks are sorted by dependency: interfaces first, base files before files that use them, tests interleaved or after. Each task maps to exactly one file and one commit.Implement with /sdd-apply
With Before writing any code,
tasks.md approved, run /sdd-apply to implement the change task by task./sdd-apply verifies that conventions.md exists — it refuses to start without it. Then for each pending task it launches a subagent that:- Reads similar existing code to follow established patterns
- Implements the change
- Runs tests and lint on the modified file
- Makes an atomic commit:
[user-registration] Description - Marks the task
[x]intasks.md - Reports a one-line summary back to the orchestrator
tasks.md, it gets registered as BUG01 or IMP01 before being implemented — tasks.md is always the complete record of what was done.Use /sdd-apply --auto to skip the between-task confirmation prompt on small, low-risk changes. Use /sdd-apply T03 to resume from a specific task.Verify and archive
Once all tasks are marked Runs as a subagent and checks:Closes the cycle by merging delta specs into canonical specs at
[x], verify the change and close the cycle.Verify:- Full test suite (not just changed files)
- Linter and formatter on changed files
- Self-review checklist: test coverage, input validation, method size, no hardcoded values, no duplication, type hints, spec compliance
- Convention audit against
conventions.md - Creates the PR with context pulled from
proposal.md
READY FOR PR or a list of issues to fix before merging.Archive:openspec/specs/{domain}/spec.md, updating openspec/INDEX.md, and moving the change directory to openspec/changes/archive/{date}-user-registration/. Canonical specs now reflect the current system state.Command sequence
Quick reference for the complete new-project flow:Fast-Forward Mode
Run the full propose → spec → design → tasks cycle in one command for clear-scope changes.