Skip to main content
The sdd-init sub-agent bootstraps the Spec-Driven Development (SDD) workflow in a project by detecting the stack, understanding conventions, and initializing the persistence backend.

​
Metadata

​
name
string
sdd-init
​
version
string
2.0
​
author
string
gentleman-programming
​
license
string
MIT

​
When It’s Triggered

The orchestrator launches sdd-init when:
  • User says “sdd init”, “iniciar sdd”, or “openspec init”
  • User wants to initialize SDD in a project
  • First time using SDD in a new workspace

​
What It Does

​
Step 1: Detect Project Context

Reads the project to understand:
  • Tech stack: Checks package.json, go.mod, pyproject.toml, Cargo.toml, etc.
  • Existing conventions: Linters, formatters, test frameworks, CI configuration
  • Architecture patterns: Monorepo, microservices, MVC, etc.

​
Step 2: Resolve Persistence Mode

Follows the persistence contract to determine:
  • engram — if Engram tool is available
  • openspec — if explicitly requested by the orchestrator
  • none — fallback (ephemeral)

​
Step 3: Bootstrap Persistence Backend

​
If mode is engram:

  • Persists project context to Engram with topic_key: sdd-init/{project-name}
  • Does NOT create openspec/ directory
  • Returns observation ID

​
If mode is openspec:

Creates this structure: 
openspec/
├── config.yaml              ← Project-specific SDD config
├── specs/                   ← Source of truth (empty initially)
└── changes/                 ← Active changes
    └── archive/             ← Completed changes
Generates config.yaml based on detected context: 
schema: spec-driven

context: |
  Tech stack: React 19, TypeScript, Vite, Vitest
  Architecture: Component-based UI with hooks
  Testing: Vitest + React Testing Library
  Style: ESLint + Prettier

rules:
  proposal:
    - Include rollback plan for risky changes
    - Identify affected modules/packages
  specs:
    - Use Given/When/Then format for scenarios
    - Use RFC 2119 keywords (MUST, SHALL, SHOULD, MAY)
  design:
    - Include sequence diagrams for complex flows
    - Document architecture decisions with rationale
  tasks:
    - Group tasks by phase (infrastructure, implementation, testing)
    - Use hierarchical numbering (1.1, 1.2, etc.)
    - Keep tasks small enough to complete in one session
  apply:
    - Follow existing code patterns and conventions
    - Load relevant coding skills for the project stack
  verify:
    - Run tests if test infrastructure exists
    - Compare implementation against every spec scenario
  archive:
    - Warn before merging destructive deltas (large removals)

​
If mode is none:

  • Returns detected context inline only
  • Recommends enabling engram or openspec for persistence

​
Step 4: Return Summary

Returns a result envelope adapted to the persistence mode.

​
Result Envelope Examples

​
Engram Mode

## SDD Initialized

**Project**: my-app
**Stack**: React 19, TypeScript, Vite, Vitest
**Persistence**: engram

### Context Saved
Project context persisted to Engram.
- **Engram ID**: #obs_abc123
- **Topic key**: sdd-init/my-app

No project files created.

### Next Steps
Ready for /sdd-explore <topic> or /sdd-new <change-name>.

​
OpenSpec Mode

## SDD Initialized

**Project**: my-app
**Stack**: React 19, TypeScript, Vite, Vitest
**Persistence**: openspec

### Structure Created
- openspec/config.yaml ← Project config with detected context
- openspec/specs/      ← Ready for specifications
- openspec/changes/    ← Ready for change proposals

### Next Steps
Ready for /sdd-explore <topic> or /sdd-new <change-name>.

​
None Mode

## SDD Initialized

**Project**: my-app
**Stack**: React 19, TypeScript, Vite, Vitest
**Persistence**: none (ephemeral)

### Context Detected
- React 19 with TypeScript
- Vite build tool
- Vitest for testing
- ESLint + Prettier for code quality

### Recommendation
Enable `engram` or `openspec` for artifact persistence across sessions. Without persistence, all SDD artifacts will be lost when the conversation ends.

### Next Steps
Ready for /sdd-explore <topic> or /sdd-new <change-name>.

​
Rules

  • NEVER create placeholder spec files — specs are created via sdd-spec during a change
  • ALWAYS detect the real tech stack — don’t guess
  • If openspec/ already exists, report what’s there and ask if it should be updated
  • Keep config.yaml context CONCISE — no more than 10 lines
  • Return a structured envelope with: status, executive_summary, detailed_report, artifacts, next_recommended, and risks

Build docs developers (and LLMs) love

Get started for freeTalk to us