/sdd-init: Bootstrap and onboard a new project for SDD

/sdd-init is the entry point for the entire SDD workflow. Run it once in a new project — or in an existing codebase — to create the openspec/ directory structure and generate the steering files that encode your project’s conventions, stack decisions, and team practices. Every other SDD skill reads from what /sdd-init produces.

Usage

/sdd-init          # Full or reduced questionnaire (auto-detected)
/sdd-init --quick  # Minimal questions, sensible defaults

Prerequisites

None. /sdd-init has no prerequisites and is the first skill you run on any project.

What it does

Step 1 — Skills check

Verifies that the core SDD skill files are accessible in the current environment. If any are missing, it prints installation instructions but does not block — the rest of init proceeds regardless.

⚠️  SDD skills not installed.

To install, run one of:
  bash install-skills.sh --global   # from the sdd-skills repo
  curl -fsSL https://raw.githubusercontent.com/jorgeferrando/sdd-skills/main/install-skills.sh | bash

Continuing with openspec/ setup — you can install skills afterwards.

Step 2 — Create openspec/ structure

Creates the canonical directory layout and excludes it from git by default:

mkdir -p openspec/specs
mkdir -p openspec/changes/archive
mkdir -p openspec/steering

# Exclude from git (unless your project intentionally commits openspec/)
grep -q "openspec/" .git/info/exclude 2>/dev/null || echo "openspec/" >> .git/info/exclude

Step 3 — Detect project state

Runs the sdd-env-scan.sh script (or performs a manual fallback scan) to determine:

Stack detected — which runtimes and config files are present (package.json, pyproject.toml, go.mod, Cargo.toml, etc.)

Has code — whether src/, lib/, or app/ directories exist

Steering exists — whether openspec/steering/conventions.md is already present

MCPs available — Docker containers prefixed with mcp-*

If openspec/steering/ already contains content, /sdd-init shows the current state and exits — no questionnaire is run.

SDD INIT — Project already bootstrapped
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Steering found: openspec/steering/
  ✓ conventions.md
  ✓ project-rules.md
  ✓ tech.md
  ...

To update conventions: /sdd-steer sync
To start a new feature: /sdd-new "description"

Step 4 — Questionnaire

Asks structured questions one group at a time. Three modes determine which groups are shown:

ModeWhenGroups askedQuick--quick flag or fewer than 5 source filesA, B onlyReducedStack detected from config filesA, C, D, E (B skipped)FullNo code detected, no --quick flagA, B, C, D, E

Each question shows trade-offs in plain language. The user can always answer “you decide” and the AI will choose with a one-line justification.

Group A — Project

Always asked. Defines what the project is and what it explicitly does not do.

#	Question	Notes
A1	What does this project build?	Free text, 1-3 sentences
A2	Who uses it?	End users, internal team, other APIs, etc.
A3	What does it NOT do?	Define boundaries

Group B — Stack

Skipped when the stack is already detected from config files.

#	Question	Guidance
B1	Project type?	Web frontend / API / CLI / Mobile / Library / Full-stack
B2	Language?	Frontend → TS, API → TS or Python, CLI → Python or Go, Library → match ecosystem
B3	Framework?	Shows top 2-3 options with one-line trade-offs
B4	Database?	None / PostgreSQL (default) / SQLite / MongoDB / Redis
B5	Testing stack?	Usually determined by framework — confirms if ambiguous

Group C — Team & rigor

Always asked. Shapes quality expectations, CI setup, and team conventions.

#	Question	Options
C1	Team size?	Solo / Small (2-5) / Large (6+)
C2	Quality level?	MVP (shortcuts OK) / Production (tests + review) / Open source (strict)
C3	CI/CD?	None / GitHub Actions / GitLab CI / Other

Group D — Available tools

Only shown when MCPs are detected in the scan. Lists detected MCP containers and asks which to enable for this project.

Group E — Patterns

Optional. Recommends sensible defaults based on the stack.

#	Question	Default recommendation
E1	Architecture?	Solo/MVP → layered, Team/Prod → hexagonal, Large/API → CQRS
E2	TDD?	AI decides per task (TDD for critical logic, tests-after for UI)
E3	Commit format?	`[change-name] Description` (SDD default) or Conventional Commits

Step 5 — Generate openspec/steering/

With all answers collected, generates 7 files in parallel:

FileContentproduct.mdWhat the project builds, for whom, and its bounded context (what it does NOT do)tech.mdLanguage, runtime, framework, key dependencies, dev/test commands, Context7 IDs if availablestructure.mdDirectory layout, layers and responsibilities, standard request flowconventions.mdRules in RFC 2119 format (MUST / MUST NOT / SHOULD / MAY) derived from the chosen stackenvironment.mdAvailable MCPs, CLI tools, runtimes, Docker containersproject-skill.mdQuick-reference index; keep under 100 lines — details live in the files it referencesproject-rules.mdEmpty at init — grows as the AI learns from user corrections during implementation

Step 6 — Write openspec/config.yaml

Creates the project configuration file:

# openspec/config.yaml
project: {name}
created_at: {date}

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

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

environment:
  mcps: {list from scan}
  tools: {list from scan}

Step 7 — Show completion state

Prints a summary of what was generated and what to do next:

SDD INIT COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Project:  {name}
Stack:    {language} + {framework}

openspec/steering/ generated:
  ✓ product.md
  ✓ tech.md
  ✓ structure.md
  ✓ conventions.md  ({N} rules)
  ✓ environment.md
  ✓ project-skill.md
  ✓ project-rules.md  (empty — grows with the project)

Next steps:
  /sdd-new "description"   → start your first feature
  /sdd-audit               → check existing code against conventions

Output

Artifact	Path
Project configuration	`openspec/config.yaml`
Product definition	`openspec/steering/product.md`
Tech stack reference	`openspec/steering/tech.md`
Directory layout	`openspec/steering/structure.md`
Coding conventions	`openspec/steering/conventions.md`
Environment inventory	`openspec/steering/environment.md`
Project skill index	`openspec/steering/project-skill.md`
Accumulated rules	`openspec/steering/project-rules.md`

Skill metadata

Field	Value
`name`	`sdd-init`
`model_hint`	`sonnet`
`requires`	(none)
`produces`	`openspec/config.yaml`, `openspec/steering/product.md`, `openspec/steering/tech.md`, `openspec/steering/structure.md`, `openspec/steering/conventions.md`, `openspec/steering/environment.md`, `openspec/steering/project-skill.md`, `openspec/steering/project-rules.md`

Safe to re-run

If openspec/steering/conventions.md already exists, /sdd-init shows the current steering state and exits without re-running the questionnaire. To update conventions after the initial bootstrap, use /sdd-steer sync.

If code already exists in the project, /sdd-init detects the stack from config files (package.json, pyproject.toml, go.mod, etc.) and skips Group B. This means fewer questions and faster onboarding for projects that are already underway.

Next steps

/sdd-discover — if the project has existing code, generate canonical specs for each domain
/sdd-new "description" — start your first change
/sdd-audit — check existing code against the generated conventions

Setup & Context

Change Lifecycle

Shortcuts & Utilities

/sdd-init: Bootstrap and onboard a new project for SDD

Usage

Prerequisites

What it does

Output

Skill metadata

Safe to re-run

Next steps

Build docs developers (and LLMs) love

Setup & Context

Change Lifecycle

Shortcuts & Utilities

Documentation Index

​Usage

​Prerequisites

​What it does

​Output

​Skill metadata

​Safe to re-run

​Next steps

Build docs developers (and LLMs) love

Usage

Prerequisites

What it does

Output

Skill metadata

Safe to re-run

Next steps