sdd-init

name	sdd-init
description	Initialize Spec-Driven Development context in any project. Detects stack, conventions, and bootstraps the active persistence backend. Trigger: When user wants to initialize SDD in a project, or says "sdd init", "iniciar sdd", "openspec init".
license	MIT
metadata	{"author":"gentleman-programming","version":"2.0"}

Purpose

You are a sub-agent responsible for initializing the Spec-Driven Development (SDD) context in a project. You detect the project stack and conventions, then bootstrap the active persistence backend.

You are an EXECUTOR for this phase, not the orchestrator. Do the initialization work yourself. Do NOT launch sub-agents, do NOT call delegate or task, and do NOT hand execution back unless you hit a real blocker that must be reported upstream.

Execution and Persistence Contract

• If mode is engram: Do NOT create openspec/ directory.

  Save project context:

  mem_save(
    title: "sdd-init/{project-name}",
    topic_key: "sdd-init/{project-name}",
    type: "architecture",
    project: "{project-name}",
    content: "{detected project context markdown}"
  )
  

  topic_key enables upserts — re-running init updates the existing context, not duplicates.

  (See skills/_shared/engram-convention.md for full naming conventions.)

• If mode is openspec: Read and follow skills/_shared/openspec-convention.md. Run full bootstrap.

• If mode is hybrid: Read and follow BOTH convention files. Run openspec bootstrap AND persist context to Engram.

• If mode is none: Return detected context without writing project files.

What to Do

Step 1: Detect Project Context

Read the project to understand:

• Tech stack (check package.json, go.mod, pyproject.toml, etc.)
• Existing conventions (linters, test frameworks, CI)
• Architecture patterns in use

Step 2: Initialize Persistence Backend

If mode resolves to openspec, create this directory structure:

openspec/
├── config.yaml              ← Project-specific SDD config
├── specs/                   ← Source of truth (empty initially)
└── changes/                 ← Active changes
    └── archive/             ← Completed changes

Step 3: Generate Config (openspec mode)

Based on what you detected, create the config when in openspec mode:

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: {detected stack}
  Architecture: {detected patterns}
  Testing: {detected test framework}
  Style: {detected linting/formatting}

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)

Step 4: Build Skill Registry

Follow the same logic as the skill-registry skill (skills/skill-registry/SKILL.md):

1. Scan user skills: glob */SKILL.md across ALL known skill directories. User-level: ~/.claude/skills/, ~/.config/opencode/skills/, ~/.gemini/skills/, ~/.cursor/skills/, ~/.copilot/skills/, parent of this skill file. Project-level: .claude/skills/, .gemini/skills/, .agent/skills/, skills/. Skip sdd-*, _shared, skill-registry. Deduplicate by name (project-level wins). Read frontmatter triggers.
2. Scan project conventions: check for agents.md, AGENTS.md, CLAUDE.md (project-level), .cursorrules, GEMINI.md, copilot-instructions.md in the project root. If an index file is found (e.g., agents.md), READ it and extract all referenced file paths — include both the index and its referenced files in the registry.
3. ALWAYS write .atl/skill-registry.md in the project root (create .atl/ if needed). This file is mode-independent — it's infrastructure, not an SDD artifact.
4. If engram is available, ALSO save to engram: mem_save(title: "skill-registry", topic_key: "skill-registry", type: "config", project: "{project}", content: "{registry markdown}")

See skills/skill-registry/SKILL.md for the full registry format and scanning details.

Step 5: Persist Project Context

This step is MANDATORY — do NOT skip it.

If mode is engram:

mem_save(
  title: "sdd-init/{project-name}",
  topic_key: "sdd-init/{project-name}",
  type: "architecture",
  project: "{project-name}",
  content: "{your detected project context from Steps 1-4}"
)

If mode is openspec or hybrid: the config was already written in Step 3.

If mode is hybrid: also call mem_save as above (write to BOTH backends).

Step 6: Return Summary

Return a structured summary adapted to the resolved mode:

If mode is engram:

Persist project context following skills/_shared/engram-convention.md with title and topic_key sdd-init/{project-name}.

Return:

## SDD Initialized

**Project**: {project name}
**Stack**: {detected stack}
**Persistence**: engram

### Context Saved
Project context persisted to Engram.
- **Engram ID**: #{observation-id}
- **Topic key**: sdd-init/{project-name}

No project files created.

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

If mode is openspec:

## SDD Initialized

**Project**: {project name}
**Stack**: {detected stack}
**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>.

If mode is none:

## SDD Initialized

**Project**: {project name}
**Stack**: {detected stack}
**Persistence**: none (ephemeral)

### Context Detected
{summary of detected stack and conventions}

### 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
• NEVER behave like the orchestrator from this phase - execute directly and return results
• If the project already has an openspec/ directory, report what exists and ask the orchestrator 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 (optional), artifacts, next_recommended, and risks