blueprint-init

What this skill does

Initialize Blueprint Development in this project.

## When to Use This Skill

| Use this skill when... | Use blueprint-upgrade instead when... |
|---|---|
| The project has no `docs/blueprint/manifest.json` yet | The project already has a manifest at an older format version |
| You're bootstrapping a new project's PRD/ADR/PRP directories | You're migrating v1.x→v2, v2→v3, or v3.x→v3.y |
| You want to enable feature tracking and decision detection from scratch | Use blueprint-derive-plans to populate PRDs/ADRs/PRPs after init |
| You're configuring task scheduling for the first time | Use blueprint-execute instead when you want auto-detection of next step |

## Steps

1. **Check if already initialized**:
   - Look for `docs/blueprint/manifest.json`
   - If exists, read version and ask user:
     ```
     Use AskUserQuestion:
     question: "Blueprint already initialized (v{version}). What would you like to do?"
     options:
       - "Check for upgrades" → run /blueprint:upgrade
       - "Reinitialize (will reset manifest)" → continue with step 2
       - "Cancel" → exit
     ```

1a. **Detect monorepo context** (format_version 3.3.0+):
   - Walk upward from the current directory looking for an ancestor
     `docs/blueprint/manifest.json` (stop at the repo root or `$HOME`).
   - If an ancestor root manifest exists, this init is creating a **child**
     workspace. Capture the relative path from the child back to the root.
   - Additionally scan descendants (max depth 4, skipping `node_modules`,
     `.git`, `dist`, `build`, `target`, `.venv`) for existing
     `docs/blueprint/manifest.json`. If any are found, this init is creating a
     **root** that will own existing children.
   - Otherwise this is a **standalone** blueprint (no `workspaces` block written).

   ```
   Use AskUserQuestion (only when ancestor root detected):
   question: "Found a parent blueprint at {parent_path}. Register this as a child workspace?"
   options:
     - label: "Yes - register as child"
       description: "Writes workspaces.role=child + root_relative_path; root picks it up on next /blueprint:workspace-scan"
     - label: "No - treat as standalone"
       description: "No workspaces block written; this project is independent"
   ```

2. **Ask about feature tracking** (use AskUserQuestion):
   ```
   question: "Would you like to enable feature tracking?"
   options:
     - label: "Yes - Track implementation against requirements"
       description: "Creates feature-tracker.json to track FR codes from a requirements document"
     - label: "No - Skip feature tracking"
       description: "Can be added later with /blueprint:feature-tracker-sync"
   ```

   **If "Yes" selected:**
   a. Search for markdown files in the project that contain requirements, features, or user stories
   b. Auto-detect the most likely source document based on content analysis
   c. Create `docs/blueprint/feature-tracker.json` from template using the detected source
   d. Set `has_feature_tracker: true` in manifest

3. **Ask about document migration** (use AskUserQuestion):
   Search for existing markdown documentation files across the project (excluding standard files like README.md, CHANGELOG.md, CONTRIBUTING.md, LICENSE.md, CODE_OF_CONDUCT.md, SECURITY.md).

   ```bash
   # Find markdown files that look like documentation (not standard repo files)
   find . -name '*.md' -not -path '*/node_modules/*' -not -path '*/.git/*' | grep -viE '(README|CHANGELOG|CONTRIBUTING|LICENSE|CODE_OF_CONDUCT|SECURITY)\.md$'
   ```

   **If documentation files found** (e.g., REQUIREMENTS.md, ARCHITECTURE.md, DESIGN.md, docs in non-standard locations):
   ```
   Use AskUserQuestion:
   question: "Found existing documentation: {file_list}. Migrate these to Blueprint-managed paths? (Strongly recommended)"
   options:
     - label: "Yes, migrate documents (Recommended)"
       description: "Move docs into docs/prds/, docs/adrs/, docs/prps/ based on content type. Prevents stale and orphaned documents."
     - label: "No, leave them in place"
       description: "Warning: unmigrated docs may become stale or duplicated as Blueprint creates its own documents"
   ```

   **If "Yes" selected:**
   a. Analyze each file to determine type:
      - Contains requirements, features, user stories → `docs/prds/`
      - Contains architecture decisions, trade-offs → `docs/adrs/`
      - Contains implementation plans → `docs/prps/`
      - General documentation → `docs/`
   b. Move files to appropriate `docs/` subdirectory
   c. Rename to kebab-case if needed (REQUIREMENTS.md → requirements.md)
   d. Report migration results:
      ```
      Migrated documentation:
      - REQUIREMENTS.md → docs/prds/requirements.md
      - ARCHITECTURE.md → docs/adrs/0001-initial-architecture.md
      ```

   **If no documentation files found:** Skip this step silently.

4. **Ask about maintenance task scheduling** (use AskUserQuestion):
   ```
   question: "How should blueprint maintenance tasks run?"
   options:
     - label: "Prompt before running (Recommended)"
       description: "Always ask before running maintenance tasks like sync, validate"
     - label: "Auto-run safe tasks"
       description: "Read-only tasks (validate, sync, status) run automatically when due"
     - label: "Fully automatic"
       description: "All tasks run automatically on schedule, including writes like rule generation"
     - label: "Manual only"
       description: "Tasks only run when you explicitly invoke them"
   ```

   Store selection for task_registry defaults:
   - **Prompt**: all `auto_run: false`, default schedules
   - **Auto-run safe**: read-only tasks (`adr-validate`, `feature-tracker-sync`, `sync-ids`) get `auto_run: true`; write tasks get `false`
   - **Fully automatic**: all tasks get `auto_run: true`, default schedules
   - **Manual only**: all `auto_run: false`, all schedules set to `on-demand`

4a. **Ask about generated-rules output path** (use AskUserQuestion):

   Only prompt when `.claude/rules/` already exists and contains files (i.e., hand-authored rules that pre-date blueprint). Skip silently in fresh repos and use the default.

   ```bash
   # Only prompt if .claude/rules/ has any content not created by blueprint
   find .claude/rules -maxdepth 1 -type f -name '*.md'
   ```

   ```
   Use AskUserQuestion (only when .claude/rules/ has existing content):
   question: "Detected existing content in .claude/rules/. Where should blueprint write generated rules?"
   options:
     - label: ".claude/rules/blueprint/ (Recommended)"
       description: "Isolated subdirectory — keeps blueprint-managed and hand-authored rules separate, prevents collisions on regenerate"
     - label: ".claude/rules/ (flat)"
       description: "Write generated rules alongside hand-authored ones; risk of overwrite when filenames collide"
   ```

   Store the chosen path in `structure.generated_rules_path` in the manifest (defaults to `.claude/rules/` when unset). This keeps `blueprint-generate-rules` and `blueprint-derive-rules` from clobbering hand-curated rule files (issue #1043).

5. **Ask about decision detection** (use AskUserQuestion):
   ```
   question: "Would you like to enable automatic decision detection?"
   options:
     - label: "Yes - Detect decisions worth documenting"
       description: "Claude will notice when conversations contain architecture decisions, feature requirements, or implementation plans that should be captured as ADR/PRD/PRP documents"
     - label: "No - Manual commands only"
       description: "Use /blueprint:derive-plans, /blueprint:prp-create explicitly when you want to create documents"
   ```

   Set `has_document_detection` in manifest based on response.

   **If enabled:**
   Copy `document-management-rule.md` template to `.claude/rules/document-management.md`.
   This rule instructs Claude to watch for:
   - Architecture decisions being made during discussion → prompt to create ADR
   - Feature requirements being discussed or