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.

All SDD artifacts live in openspec/. It is the single source of truth for what the system does and why decisions were made. Every change flows through this directory: proposals are drafted here, specs are written here, designs and task lists land here, and archived changes are stored here permanently. After every archive, the canonical specs inside openspec/specs/ reflect the exact current state of the system.

​
Directory structure

openspec/
├── config.yaml                         # Project configuration
├── INDEX.md                            # Domain index with descriptions
├── steering/                           # Project context (see Steering Files)
│   ├── product.md
│   ├── tech.md
│   ├── structure.md
│   ├── conventions.md
│   ├── environment.md
│   ├── project-skill.md
│   └── project-rules.md
├── specs/                              # Canonical specs (current system state)
│   ├── core/
│   │   └── spec.md
│   ├── auth/
│   │   └── spec.md
│   └── {domain}/
│       └── spec.md
└── changes/                            # Active and archived changes
    ├── add-user-auth/                  # Active change
    │   ├── proposal.md
    │   ├── specs/auth/spec.md          # Delta spec
    │   ├── design.md
    │   └── tasks.md
    └── archive/                        # Completed changes
        ├── 2026-03-01-bootstrap/
        ├── 2026-03-02-add-login/
        └── ...

​
Canonical specs vs delta specs

There are two types of specs in openspec/, and understanding the distinction is key to reading the directory correctly. Canonical specs (openspec/specs/{domain}/spec.md) represent the current state of the system. They are updated automatically when a change is archived. This is what the system does right now — not what it used to do or what it will do next. Delta specs (openspec/changes/{change}/specs/{domain}/spec.md) represent what changes in a specific change. Only new or modified behaviors are documented — not the full spec. When a change is archived, the delta is merged into the canonical spec. This separation means you can always see:
  • What the system does today → canonical specs in openspec/specs/
  • What a specific change introduced → delta specs in openspec/changes/archive/
  • What’s about to change → delta specs in active changes under openspec/changes/

​
config.yaml

Created by /sdd-init, config.yaml holds project-level configuration that all skills read to locate artifacts: 
project: my-app
created_at: 2026-03-01

paths:
  specs: openspec/specs
  changes: openspec/changes
  archive: openspec/changes/archive
  steering: openspec/steering

steering:
  project_skill: openspec/steering/project-skill.md

environment:
  mcps: [context7, github]
  tools: [git, gh, docker, uv]
FieldPurpose
projectHuman-readable project name used in artifact headers
created_atInitialization date
paths.*Where each artifact type lives — skills read these rather than hardcoding paths
steering.project_skillEntry point steering file loaded first by all skills
environment.mcpsAvailable MCP tools (used by /sdd-init and /sdd-steer)
environment.toolsCLI tools available in the environment

​
INDEX.md

openspec/INDEX.md is a domain index created by /sdd-discover and kept up to date by /sdd-archive. It gives skills a fast lookup of what domains exist and what each one contains: 
# Domain Index

| Domain | Description | Key Entities | Keywords |
|--------|-------------|-------------|----------|
| core | Core business logic | User, Account | auth, registration |
| api | REST API endpoints | Request, Response | http, routes |
| tui | Terminal interface | Screen, Widget | textual, ui |
Skills use the Keywords column to find relevant domains during explore and recall phases, avoiding a full scan of every spec file.

​
Git and openspec

By default, /sdd-init excludes openspec/ from git via .git/info/exclude. This keeps the directory local — useful when you don’t want to commit AI-generated artifacts or when you’re the only contributor. If your team wants to share the openspec/ directory (recommended when working with others), you can opt in explicitly: 
# Remove the local exclusion
sed -i '/openspec\//d' .git/info/exclude

# Commit the directory
git add openspec/
git commit -m "Add openspec directory"
From that point on, openspec/ is tracked like any other source directory. Skills continue to work the same way — they don’t care whether the directory is committed or not.
Committing openspec/ is recommended for teams of more than one. It lets teammates see active changes, review proposals and specs before implementation begins, and access the full history of design decisions in the archive.

Build docs developers (and LLMs) love

Get started for freeTalk to us