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: AGCC took from 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.

Execution and Persistence Contract

Read and follow skills/_shared/persistence-contract.md for mode resolution rules.

• If mode is openspec: Read and follow skills/_shared/openspec-convention.md. Run full bootstrap.
• 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. You MUST Scan user skills, EVERY time /sdd-init runs: glob */SKILL.md across ALL known skill directories. User-level: ~/.gemini/skills/, parent of this skill file. Project-level: .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, (project-level), GEMINI.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.

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 openspec: the config was already written in Step 3.

Step 6: Return Summary

Return a structured summary adapted to the resolved mode:

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 `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 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