blueprint-init

created	"2025-12-16T00:00:00.000Z"
modified	"2026-06-21T00:00:00.000Z"
reviewed	"2026-06-21T00:00:00.000Z"
description	Initialize Blueprint Development structure. Use when bootstrapping docs/blueprint/ with manifest, PRD/ADR/PRP directories, and feature tracking for the first time.
allowed-tools	Bash, Write, Read, AskUserQuestion, Glob
name	blueprint-init

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).

   # 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$'
   

   Before recommending migration, measure cross-reference density. Migrating a doc into docs/{prds,adrs,prps}/ rewrites its path, breaking every reference to it. For each candidate doc, grep the repo for references to its path from outside docs/ (README, scripts, CI, .rulesync/) and inter-doc links:

   # Count references to each candidate doc path (skip the doc itself)
   for doc in $candidate_docs; do
     base=$(basename "$doc")
     refs=$(grep -rIl --exclude-dir=.git --exclude-dir=node_modules "$base" . | grep -v "^./$doc$" | wc -l | tr -d ' ')
     ext=$(grep -rIl --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=docs  . |  -l |  -d )
      
   
   

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.

# 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: Resolve the rules output directory before writing — honour the path chosen in Step 4a (default .claude/rules/) rather than hardcoding it, so blueprint does not collide with rulesync-managed or hand-authored rules (issue #1675):

   RULES_DIR=$(jq -r '.structure.generated_rules_path // ".claude/rules/"' docs/blueprint/manifest.json)
   mkdir -p "$RULES_DIR"
   

   When the manifest is not yet written, use the Step 4a selection directly (default .claude/rules/).

   Copy document-management-rule.md template to $RULES_DIR/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 refined → prompt to create/update PRD
   • Implementation plans being formulated → prompt to create PRP

6. Create directory structure:

   Canonical document paths are at the top level of docs/, not under docs/blueprint/. docs/blueprint/ holds blueprint machinery only (manifest, feature-tracker, work-orders); docs/{adrs,prds,prps,trps}/ hold the documents themselves. Every /blueprint:derive-* skill writes to the top-level paths — keeping them consistent prevents the dual-corpus bug where init creates one layout and derive-* writes to another.

   Execute the creation explicitly so the directories exist even when no document migration happened in Step 3:

   mkdir -p docs/blueprint/work-orders/completed
   mkdir -p docs/blueprint/work-orders/archived
    -p docs/adrs
    -p docs/prds
    -p docs/prps
   

Blueprint Development initialized! (v3.3.0)

Blueprint structure created:
- docs/blueprint/manifest.json
- docs/blueprint/work-orders/
- docs/blueprint/README.md
[- docs/blueprint/feature-tracker.json (if feature tracking enabled)]

Project documentation (top-level — derive-* skills write here):
- docs/prds/           (Product Requirements Documents)
- docs/adrs/           (Architecture Decision Records)
- docs/prps/           (Product Requirement Prompts)
- docs/trps/           (Test Regression Plans — created on first /blueprint:derive-tests run)

Claude configuration:
- .claude/rules/       (modular rules, including generated)
- .claude/skills/      (custom skill overrides)

Configuration:
- Rules mode: both (CLAUDE.md + .claude/rules/)
[- Feature tracking: enabled]
[- Decision detection: enabled (Claude will prompt when discussions should become ADR/PRD/PRP)]
[- Task scheduling: {prompt|auto-run safe|fully automatic|manual only}]

[Migrated documentation:]
[- {original} → {destination} (for each migrated file)]

Architecture:
- Plugin layer: Generic commands from blueprint-plugin (auto-updated)
- Generated layer: Rules/commands regeneratable from docs/prds/
- Custom layer: Your overrides in .claude/skills/

11. Prompt for next action (use AskUserQuestion):

    question: "Blueprint initialized. What would you like to do next?"
    options:
      - label: "Derive plans from git history (Recommended)"
        description: "Analyze commit history, PRs, and issues to build PRDs, ADRs, and PRPs from existing project decisions"
      - label: "Derive rules from codebase"
        description: "Analyze commit patterns and code conventions to generate .claude/rules/"
      - label: "Update CLAUDE.md"
        description: "Generate or update CLAUDE.md with project context and blueprint integration"
      - label: "I'm done for now"
        description: "Exit - you can run /blueprint:status anytime to see options"
    

    Based on selection:

    • "Derive plans from git history" → Run /blueprint:derive-plans
    • "Derive rules from codebase" → Run /blueprint:derive-rules
    • "Update CLAUDE.md" → Run /blueprint:claude-md
    • "I'm done for now" → Show quick reference and exit

Quick Reference (show if user selects "I'm done for now"):

Management commands:
- /blueprint:status          - Check version and configuration
- /blueprint:upgrade         - Upgrade to latest format version
- /blueprint:derive-plans    - Derive PRDs, ADRs, and PRPs from git history
- /blueprint:derive-rules    - Derive rules from git commit decisions
- /blueprint:prp-create      - Create a Product Requirement Prompt
- /blueprint:generate-rules  - Generate rules from PRDs
- /blueprint:sync            - Check for stale generated content
- /blueprint:promote         - Move generated content to custom layer
- /blueprint:rules           - Manage modular rules
- /blueprint:claude-md       - Update CLAUDE.md
- /blueprint:feature-tracker-status  - View feature completion stats
- /blueprint:feature-tracker-sync    - Sync tracker with project files