sdd-init

Triggers: "sdd init", "iniciar sdd", initialize SDD in a project.

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 engram persistence.

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 Engram is available (default), persist disk-primary (per _shared/sdd-phase-common.md Section C): Save project context — disk FIRST, then an engram pointer:

  Write("docs/sdd/{project-name}/init-context.md", "{detected project context markdown}")
  mem_save(
    title: "sdd-init/{project-name}",
    topic_key: "sdd-init/{project-name}",
    type: "architecture",
    project: "{project-name}",
    content: "path: docs/sdd/{project-name}/init-context.md\n\n{1-3 sentence summary}"
  )
  

  topic_key enables upserts — re-running init updates the existing pointer, not duplicates. The disk file is the source of truth.

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

• If Engram is not available (none mode): Return detected context inline; the disk artifact is still written when a project context is produced.

Process

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: Build Skill Registry

Build the skill registry:

1. Scan user skills: glob */SKILL.md across skill directories. User-level: ~/.claude/skills/. Project-level: .claude/skills/, skills/. Skip sdd-* and _shared. 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 .agent-config/skill-registry.md in the project root (create .agent-config/ 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}")

The registry format: one entry per skill with name, path, triggers, and format type.

Step 3: Persist Project Context

This step is MANDATORY — do NOT skip it.

Persist disk-primary — write the disk artifact FIRST (source of truth), then the engram pointer:

Write("docs/sdd/{project-name}/init-context.md", "{your detected project context from Steps 1-2}")

If Engram is available, also save the pointer:

mem_save(
  title: "sdd-init/{project-name}",
  topic_key: "sdd-init/{project-name}",
  type: "architecture",
  project: "{project-name}",
  content: "path: docs/sdd/{project-name}/init-context.md\n\n{1-3 sentence summary}"
)

Step 4: Return Summary

Return a structured summary:

If Engram is available:

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-propose <change-name>.

If Engram is not available:

## SDD Initialized

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

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

### Recommendation
Enable `engram` 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-propose <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
• Keep config context CONCISE - no more than 10 lines
• Return a structured envelope with: status, executive_summary, detailed_report (optional), artifacts, next_recommended, and risks