SDD can be added to any existing project without rewriting anything.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.
/sdd-init detects your stack from config files and skips questions it can already answer. /sdd-discover then reverse-engineers canonical specs from your existing code so future changes have a behavioral baseline to diff against. The whole onboarding takes two commands.
Two-step onboarding overview
| Step | Command | What it does |
|---|---|---|
| 1 | /sdd-init | Creates openspec/, generates steering files, skips stack questions already known from config files |
| 2 | /sdd-discover | Scans src/, app/, lib/ and generates openspec/specs/{domain}/spec.md per domain |
/sdd-new to start your first tracked change.
Run /sdd-init on your existing code
Run What gets detected automatically:
Because Group B (stack questions) is already answered from config files, Group B is skipped automatically. Init still asks Group A (project context — what it builds, who uses it, what is out of scope), Group C (team rigor — team size, quality level, CI/CD), Group D if MCPs are detected, and Group E (architecture style, TDD approach, commit format).The same 7 steering files are generated in
Review the generated
/sdd-init from the project root just as you would for a new project. The key difference: when code already exists, init detects your stack automatically and skips the questions it can answer from config files.| Config file | Detected information |
|---|---|
package.json | Language (Node.js), framework, test runner, scripts |
pyproject.toml / setup.cfg | Python version, dependencies, test commands |
go.mod | Go version, module name |
Cargo.toml | Rust edition, crate type |
Dockerfile / docker-compose.yml | Runtime, exposed ports, services |
openspec/steering/:| 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 |
conventions.md carefully — it is inferred from your stack and general best practices, not from your actual codebase. You may want to edit it to reflect team-specific rules before running any changes.Generate specs from existing code with /sdd-discover
With steering files in place, run The skill:This is useful when you want to onboard one domain at a time, or when a specific area needs to be specced before starting a change in it.
/sdd-discover to reverse-engineer behavioral specs from your existing code. This populates openspec/specs/ so that future /sdd-spec calls can write targeted deltas against a known baseline instead of starting from scratch.- Scans
src/,app/, andlib/to detect domains by directory structure and import patterns - Shows detected domains with file counts and asks for confirmation before analyzing
- Launches one parallel subagent per domain — each reads the domain code, infers its purpose, main entities, and behavior
- Generates
openspec/specs/{domain}/spec.mdwithStatus: inferredin the frontmatter - Creates or updates
openspec/INDEX.md— a keyword index used by/sdd-exploreto find relevant specs quickly
Review and refine the generated specs
Inferred specs are a starting point, not ground truth. Before using SDD for real changes, spend a few minutes reviewing what was generated.Things to check in each spec:This compares current conventions against code, skills, and
- Domain boundaries — did the AI correctly identify what belongs in each domain?
- Business rules — are the inferred rules accurate, or did the AI over-generalize from code structure?
- Edge cases — are error paths and validation rules described, or just the happy path?
- Status field — change
Status: inferredtoStatus: reviewedonce you’ve verified a spec
openspec/specs/{domain}/spec.md. There is no special command needed — the files are the source of truth.After reviewing specs, run /sdd-steer sync to check whether your conventions file has already drifted from the actual codebase patterns:MEMORY.md, then presents proposed additions, updates, and removals for your confirmation. It does not auto-apply changes.Start using the SDD workflow for new changes
With steering and specs in place, you’re ready to use SDD for all new work. The workflow is identical to a new project from this point forward.Because
openspec/specs/payments/spec.md already exists, the spec phase will write a delta — only what changes — rather than describing the entire payments domain from scratch. This is the key benefit of running /sdd-discover first.Continue with the normal cycle:Command sequence
Inferred vs. authored specs: Specs generated by
/sdd-discover have Status: inferred and describe existing behavior — what the code does today, including any bugs or inconsistencies. Specs written by /sdd-spec during a change cycle have Status: approved and describe intended behavior — what the system should do after the change. Both types coexist in openspec/specs/. When they conflict, the authored spec (from an active or archived change) takes precedence.