sdd-auto:init

/sdd-auto:init — SDD Autopilot Initializer

You initialize a project for SDD Autopilot by creating the required configuration files and scaffolding useful templates.

What to do

1. Determine project path: Use $ARGUMENTS if provided, otherwise use the current working directory.

2. Check existing state: Call mcp__sdd-autopilot__sdd_get_state with the project path.

   • If state.json already exists: report "Project already initialized at {path}" and show current state. Do NOT overwrite.
   • If not initialized: continue to step 3.

3. Auto-detect project stack: Read files in the project root to detect:

   • package.json → Node.js/TypeScript. Extract: name, scripts (test, dev, build, lint), dependencies
   • requirements.txt / pyproject.toml → Python. Extract: project name, test framework
   • Cargo.toml → Rust. Extract: package name, test command
   • go.mod → Go. Extract: module name
   • pom.xml / build.gradle → Java/Kotlin
   • If none found: set stack to "unknown"

   Also detect:

   • Test framework: check for jest.config, vitest.config, pytest.ini, .mocharc, etc.
   • Linter: check for .eslintrc, .prettierrc, biome.json, ruff.toml, etc.
   • Directory structure: run ls on the project root to get top-level layout

4. Create .sdd/state.json:

   {
     "version": "2.0.0",
     "project": "{detected_project_name}",
     "initialized_at": "{ISO timestamp}",
     "active_feature": null,
     "features": {}
   }
   

5. Create constitution.md (at project root, NOT inside .sdd):

   # Constitution
   
   ## Project
   - **Name**: {detected_project_name}
   - **Stack**: {detected_stack}
   - **Description**: [TODO: describe what this project does]
   
   ## Principles
   <!-- Add at least 3 non-negotiable principles for this project -->
   - [TODO: e.g., "All API endpoints must be authenticated"]
   - [TODO: e.g., "No direct database queries outside the repository layer"]
   - [TODO: e.g., "Every user-facing string must be internationalized"]
   
   ## Conventions
   - **Test framework**: {detected_test_framework or "[TODO: specify]"}
   - **Linter**: {detected_linter or "[TODO: specify]"}
   - **Directory structure**: {brief auto-generated overview}
   

6. Create CLAUDE.md (at project root) — ONLY if it does NOT already exist:

   # CLAUDE.md
   
   ## Build & Test
   - Install: `{detected_install_command or "[TODO]"}`
   - Dev: `{detected_dev_command or "[TODO]"}`
   - Test: `{detected_test_command or "[TODO]"}`
   - Lint: `{detected_lint_command or "[TODO]"}`
   
   ## Architecture
   {brief auto-generated overview from directory structure listing}
   

   If CLAUDE.md already exists, do NOT modify it. Report: "CLAUDE.md already exists, skipping."

7. Migrate legacy docs — Check for project-level docs in legacy locations:

   • If specs/prd.md exists but docs/prd.md does NOT: report "ℹ️ Found PRD at specs/prd.md — moving to docs/prd.md for better project organization." Move the file (copy + delete original). Create docs/ if needed.
   • If specs/prd-template.md exists but docs/prd.md does NOT: same migration, rename to docs/prd.md.
   • If both specs/prd.md and docs/prd.md exist: keep docs/prd.md, report "ℹ️ Legacy PRD found at specs/prd.md — using docs/prd.md (remove the legacy file manually if no longer needed)."

8. Generate docs/roadmap.md — ONLY if a PRD exists (docs/prd.md with filled content, not just TODOs):

   • Read the PRD to extract product vision, core features, and priorities
   • Read constitution.md for architectural constraints that affect sequencing
   • Generate docs/roadmap.md with this structure:

   # Roadmap
   
   > [One-sentence project vision extracted from PRD]
   
   ## Now (current milestone)
   [2-4 features that should be built first — foundational, unblocks others]
   - **feature-name**: one-line description
   
   ## Next (upcoming milestone)
   [2-4 features that follow naturally once Now is done]
   - **feature-name**: one-line description
   
   ## Later (future direction)
   [2-3 directional items, less defined, more strategic]
   - **feature-name**: one-line description
   
   ---
   *Generated by auto-init from PRD. Edit this file — the pipeline reads it during triage and spec generation.*
   

   • If no PRD exists or PRD is all TODOs: skip this step, report "Roadmap skipped — fill in a PRD first."
   • If docs/roadmap.md already exists: do NOT overwrite. Report "Roadmap already exists, skipping."
   • Create docs/ directory if it doesn't exist.

9. Generate .claude/rules/ — Create SDD-specific rules for Claude Code. These rules are auto-loaded by Claude Code when working in this project, including in spawned subagents.

   ONLY create if .claude/rules/ does NOT already contain SDD rule files. If any of the three files below exist, skip this step and report "SDD rules already exist, skipping."

   Create .claude/rules/sdd-agent-defaults.md:

   ---
   description: SDD Autopilot agent defaults — telemetry and verbosity conventions
   paths:
     - "specs/**"
     - ".sdd/**"
   ---
   
   ## Output Constraints
   
   - When called with verbosity=minimal: respond with ONLY the structured output (JSON/contract markers). No explanations, no reasoning, no suggestions.
   - When called with verbosity=standard: structured output + 1-2 sentence summary.
   - When called with verbosity=full (default): full output with reasoning.
   
   ## Telemetry (mandatory for SDD pipeline agents)
   
   Your FINAL line of output — after all work and signals — MUST be:
   
   

   [TELEMETRY] tool_calls={N} estimated_output_tokens={K}

   
   Where:
   - `N` = total number of tool calls you made (count every Read, Write, Edit, Grep, Glob, Bash, MCP call, etc.)
   - `K` = estimated total output tokens you generated. Heuristic: count approximate words in all your text responses (not tool calls) and multiply by 1.3.
   
   This line is OBLIGATORY. Do not omit it. It must be the very last line of your final response.
   

   Create .claude/rules/sdd-spec-contracts.md:

   ---
   description: SDD spec contract markers — how to interpret immutable/negotiable sections in specs
   paths:
     - "specs/**"
   ---
   
   ## Spec Contract Rules
   
   - `<!-- contract: immutable -->` — non-negotiable, do NOT modify/reinterpret/skip
   - `<!-- guidance: negotiable -->` — suggestions, alternatives OK if justified
   - `<!-- contract: interface-immutable, implementation-negotiable -->` — interface fixed, internals flexible
   - `<!-- status: unresolved -->` — open questions, do NOT assume; emit SPEC_GAP signal
   

   Create .claude/rules/sdd-workflow.md:

   ---
   description: SDD pipeline workflow conventions — token optimization, external docs, context7 usage
   paths:
     - "specs/**"
     - ".sdd/**"
     - "src/**"
   ---
   
   ## Token optimization
   
   When calling `sdd_get_state` or `sdd_memory_read`, pass `verbosity: "minimal"` to reduce response size. You only need state/tasks summary, not full transitions and signals.
   
   ## External docs
   
   Use context7 MCP tools (`resolve-library-id` + `get-library-docs`) for live API docs when available.
   

10. Create docs/prd.md — ONLY if docs/prd.md does NOT already exist (including after migration in step 7-8):

# Product Requirements Document

## Vision
[What is this product and why does it exist?]

## Users
[Who uses this and what do they need?]

## Core Features
[List the main features]

## Non-Goals
[What this product explicitly does NOT do]

## Domain Vocabulary
| Term | Definition | NOT to be confused with |
|------|-----------|------------------------|
| [term] | [definition] | [confusable term] |

11. Report to user:

SDD Autopilot initialized successfully.

Files created:
✓ .sdd/state.json
✓ constitution.md
✓ CLAUDE.md (or "skipped — already exists")
✓ .claude/rules/sdd-agent-defaults.md (or "skipped — already exists")
✓ .claude/rules/sdd-spec-contracts.md (or "skipped — already exists")
✓ .claude/rules/sdd-workflow.md (or "skipped — already exists")
✓ docs/prd.md
✓ docs/roadmap.md (or "skipped — no PRD" or "skipped — already exists")

Before your first run:
1. Fill in constitution.md with your project principles
2. Review CLAUDE.md (auto-generated, adjust if needed)
3. Fill docs/prd.md with your product vision — the pipeline uses it for specs and roadmap
4. If a roadmap was generated, review docs/roadmap.md — the pipeline uses it
   as context for triage and spec generation, so the more accurate it is,
   the better the output.

Quick start: run /sdd-autopilot:auto-run "your feature description"
Your first run will use Standard mode. Express mode activates for trivial tasks.

Important notes

• Use Read, Glob, and Bash tools for auto-detection — do NOT guess
• All [TODO] placeholders should be clearly marked for the user to fill
• The constitution.md goes in the PROJECT ROOT, not in .sdd/
• The docs/ directory should be created if it doesn't exist
• The specs/ directory should be created if it doesn't exist (for per-feature specs)
• Do NOT modify any existing files except creating new ones