OpenSpec Convention

Directory structure and file paths for SDD artifacts on the filesystem

The OpenSpec Convention defines how SDD artifacts are organized on the filesystem when using openspec persistence mode.

Directory Structure

openspec/
├── config.yaml              ← Project-specific SDD config
├── specs/                   ← Source of truth (main specs)
│   └── {domain}/
│       └── spec.md
└── changes/                 ← Active changes
    ├── archive/             ← Completed changes (YYYY-MM-DD-{change-name}/)
    └── {change-name}/       ← Active change folder
        ├── exploration.md   ← (optional) from sdd-explore
        ├── proposal.md      ← from sdd-propose
        ├── specs/           ← from sdd-spec
        │   └── {domain}/
        │       └── spec.md  ← Delta spec
        ├── design.md        ← from sdd-design
        ├── tasks.md         ← from sdd-tasks (updated by sdd-apply)
        └── verify-report.md ← from sdd-verify

Artifact File Paths

Skill	Creates / Reads	Path
sdd-init	Creates	openspec/config.yaml, openspec/specs/, openspec/changes/, openspec/changes/archive/
sdd-explore	Creates (optional)	openspec/changes/{change-name}/exploration.md
sdd-propose	Creates	openspec/changes/{change-name}/proposal.md
sdd-spec	Creates	openspec/changes/{change-name}/specs/{domain}/spec.md
sdd-design	Creates	openspec/changes/{change-name}/design.md
sdd-tasks	Creates	openspec/changes/{change-name}/tasks.md
sdd-apply	Updates	openspec/changes/{change-name}/tasks.md (marks [x])
sdd-verify	Creates	openspec/changes/{change-name}/verify-report.md
sdd-archive	Moves	openspec/changes/{change-name}/ → openspec/changes/archive/YYYY-MM-DD-{change-name}/
sdd-archive	Updates	openspec/specs/{domain}/spec.md (merges deltas into main specs)

Reading Artifacts

Each skill reads its dependencies from the filesystem:

Proposal:   openspec/changes/{change-name}/proposal.md
Specs:      openspec/changes/{change-name}/specs/  (all domain subdirectories)
Design:     openspec/changes/{change-name}/design.md
Tasks:      openspec/changes/{change-name}/tasks.md
Verify:     openspec/changes/{change-name}/verify-report.md
Config:     openspec/config.yaml
Main specs: openspec/specs/{domain}/spec.md

Writing Rules

• ALWAYS create the change directory (openspec/changes/{change-name}/) before writing artifacts
• If a file already exists, READ it first and UPDATE it (don’t overwrite blindly)
• If the change directory already exists with artifacts, the change is being CONTINUED
• Use the openspec/config.yaml rules section to apply project-specific constraints per phase

Config File Reference

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: {detected}
  Architecture: {detected}
  Testing: {detected}
  Style: {detected}

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then for scenarios
    - Use RFC 2119 keywords (MUST, SHALL, SHOULD, MAY)
  design:
    - Include sequence diagrams for complex flows
    - Document architecture decisions with rationale
  tasks:
    - Group by phase, use hierarchical numbering
    - Keep tasks completable in one session
  apply:
    - Follow existing code patterns
    tdd: false           # Set to true to enable RED-GREEN-REFACTOR
    test_command: ""     # e.g., "npm test", "pytest"
  verify:
    test_command: ""     # Override for verification
    build_command: ""    # Override for build check
    coverage_threshold: 0  # Set > 0 to enable coverage check
  archive:
    - Warn before merging destructive deltas

Config Fields

schema · string · required

Must be spec-driven

context · string · required

Project context detected by sdd-init. Includes tech stack, architecture, testing framework, and style conventions.

rules.proposal · array

Rules for the proposal phase (applied by sdd-propose)

rules.specs · array

Rules for the specs phase (applied by sdd-spec)

rules.design · array

Rules for the design phase (applied by sdd-design)

rules.tasks · array

Rules for the task planning phase (applied by sdd-tasks)

rules.apply.tdd · boolean

Enable TDD workflow in sdd-apply. When true, every task follows RED → GREEN → REFACTOR cycle.

rules.apply.test_command · string

Override test command for running tests during implementation (e.g., npm test, pytest, go test)

rules.verify.test_command · string

Override test command for verification phase. If not set, uses rules.apply.test_command or auto-detects.

rules.verify.build_command · string

Override build command for verification phase (e.g., npm run build, go build, python -m build)

rules.verify.coverage_threshold · number

Minimum coverage percentage required. If set to 0 (default), coverage check is skipped. Set to e.g. 80 to enforce 80% coverage.

rules.archive · array

Rules for the archive phase (applied by sdd-archive)

Archive Structure

When archiving, the change folder moves to:

openspec/changes/archive/YYYY-MM-DD-{change-name}/

Use today’s date in ISO format. The archive is an AUDIT TRAIL — never delete or modify archived changes.

Example Archive

openspec/changes/archive/
├── 2026-02-15-add-dark-mode/
│   ├── proposal.md
│   ├── specs/
│   │   └── ui/
│   │       └── theme/
│   │           └── spec.md
│   ├── design.md
│   ├── tasks.md
│   └── verify-report.md
├── 2026-02-20-add-auth/
│   ├── exploration.md
│   ├── proposal.md
│   ├── specs/
│   ├── design.md
│   ├── tasks.md
│   └── verify-report.md
└── 2026-03-04-refactor-api/
    ├── proposal.md
    ├── specs/
    ├── design.md
    ├── tasks.md
    └── verify-report.md

Main Specs (Source of Truth)

The openspec/specs/ directory contains the current state of all specifications. These are updated by sdd-archive when a change is completed.

openspec/specs/
├── auth/
│   └── spec.md          ← Full spec for authentication domain
├── payments/
│   └── spec.md          ← Full spec for payments domain
└── ui/
    ├── theme/
    │   └── spec.md      ← Full spec for theming
    └── navigation/
        └── spec.md      ← Full spec for navigation

Delta Specs vs Main Specs

• Delta specs (openspec/changes/{change-name}/specs/) describe what’s changing
• Main specs (openspec/specs/) describe current behavior

When a change is archived, delta specs are merged into main specs by sdd-archive.

Example: Change Lifecycle

1. Initialize

/sdd-init
# Creates:
# - openspec/config.yaml
# - openspec/specs/
# - openspec/changes/
# - openspec/changes/archive/

2. Create Change

/sdd-new add-dark-mode
# Creates:
# - openspec/changes/add-dark-mode/

3. Explore

# (part of /sdd-new)
# Creates:
# - openspec/changes/add-dark-mode/exploration.md

4. Propose

# (part of /sdd-new)
# Creates:
# - openspec/changes/add-dark-mode/proposal.md

5. Spec

# (part of /sdd-new)
# Creates:
# - openspec/changes/add-dark-mode/specs/ui/theme/spec.md

6. Design

# (part of /sdd-new)
# Creates:
# - openspec/changes/add-dark-mode/design.md

7. Tasks

# (part of /sdd-new)
# Creates:
# - openspec/changes/add-dark-mode/tasks.md

8. Apply

/sdd-apply
# Updates:
# - openspec/changes/add-dark-mode/tasks.md (marks tasks [x])

9. Verify

/sdd-verify
# Creates:
# - openspec/changes/add-dark-mode/verify-report.md

10. Archive

/sdd-archive add-dark-mode
# 1. Merges delta spec into main spec:
#    openspec/changes/add-dark-mode/specs/ui/theme/spec.md
#    → openspec/specs/ui/theme/spec.md
#
# 2. Moves change to archive:
#    openspec/changes/add-dark-mode/
#    → openspec/changes/archive/2026-03-04-add-dark-mode/

Git Integration

The openspec/ directory is designed to be committed to git:

# Commit a new change proposal
git add openspec/changes/add-dark-mode/
git commit -m "Propose: Add dark mode support"

# Commit after implementation
git add openspec/changes/add-dark-mode/
git add src/  # implementation
git commit -m "Implement: Add dark mode"

# Commit after archiving
git add openspec/specs/ui/theme/spec.md
git add openspec/changes/archive/2026-03-04-add-dark-mode/
git rm -r openspec/changes/add-dark-mode/
git commit -m "Archive: Add dark mode"

Related

• Persistence Contract — Mode resolution rules
• Engram Convention — Memory-based alternative
• Init Sub-Agent — Bootstraps the directory structure