blueprint-init

このプロジェクトで Blueprint Development を初期化します。

このスキルを使用するタイミング

このスキルを使用する場合	代わりに blueprint-upgrade を使用する場合
プロジェクトにまだ docs/blueprint/manifest.json がない	プロジェクトに古い形式バージョンのマニフェストがすでにある
新しいプロジェクトの PRD／ADR／PRP ディレクトリを初期設定する	v1.x→v2、v2→v3、または v3.x→v3.y に移行する
機能の追跡と意思決定の検出をゼロから有効にする	初期化後に PRD／ADR／PRP を作成するには blueprint-derive-plans を使用する
タスクのスケジューリングを初めて設定する	次のステップを自動検出するには、代わりに blueprint-execute を使用する

手順

1. 初期化済みか確認します：
   • docs/blueprint/manifest.json を探します
   • 存在する場合は、バージョンを読み取ってユーザーに確認します：

     Use AskUserQuestion:
     question: "Blueprint はすでに初期化されています（v{version}）。どうしますか？"
     options:
       - "アップグレードを確認する" → run /blueprint:upgrade
       - "再初期化する（マニフェストがリセットされます）" → ステップ 2 に進む
       - "キャンセル" → 終了
     

1a. モノレポのコンテキストを検出します（format_version 3.3.0 以降）：

• 現在のディレクトリから上位へたどり、祖先ディレクトリに docs/blueprint/manifest.json があるか確認します（リポジトリのルートまたは $HOME で終了します）。
• ルートのマニフェストが祖先にある場合、この初期化では子 ワークスペースを作成しています。子からルートへの相対パスを記録します。
• さらに、既存の docs/blueprint/manifest.json を探して、子孫ディレクトリを最大深度 4 までスキャンします（node_modules、 .git、dist、build、target、.venv は除外します）。見つかった場合、この初期化では既存の子を管理する ルートを作成しています。
• それ以外の場合はスタンドアロンの Blueprint です（workspaces ブロックは書き込まれません）。

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. 機能の追跡について確認します（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"
   

   「はい」が選択された場合： a. プロジェクト内で要件、機能、またはユーザーストーリーを含む Markdown ファイルを検索します b. 内容を分析して、最も可能性の高いソース文書を自動検出します c. 検出したソースを使用して、テンプレートから docs/blueprint/feature-tracker.json を作成します d. マニフェストで has_feature_tracker: true に設定します

3. ドキュメントの移行について確認します（AskUserQuestion を使用）： README.md、CHANGELOG.md、CONTRIBUTING.md、LICENSE.md、CODE_OF_CONDUCT.md、SECURITY.md などの標準ファイルを除き、プロジェクト全体で既存の Markdown ドキュメントファイルを検索します。

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

   移行を推奨する前に、相互参照の密度を測定します。 ドキュメントを docs/{prds,adrs,prps}/ に移行するとパスが書き換えられ、そのドキュメントへのすべての参照が 破損します。候補ドキュメントごとに、リポジトリ内でそのパスへの参照を、docs/ の外部（README、スクリプト、CI、.rulesync/）およびドキュメント間のリンクから検索します：

   # 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 "$base" . | wc -l | tr -d ' ')
     echo "$doc total=$refs outside_docs=$ext"
   done
   

   パスが**docs/ の外部**（ビルドスクリプト、CI、README、 .rulesync/）から参照されているドキュメントは、移行コストが高くなります。ビルドに不可欠なファイルを含め、すべての参照を書き換える必要があるためです。Blueprint に必要なのは、将来派生するドキュメント用の空の docs/{prds,adrs,prps}/ だけなので、移行コストが高い場合は「そのまま残す」のが安全な既定の選択です。

   ドキュメントファイルが見つかった場合（例：REQUIREMENTS.md、ARCHITECTURE.md、DESIGN.md、標準的でない場所にある docs）：

   • 候補ドキュメントが docs/ の外部から参照されていない場合に限り、移行を推奨する既定の選択肢にします（label: "はい、ドキュメントを移行する（推奨）"）。
   • 候補ドキュメントが 1 つ以上 docs/ の外部から参照されている場合は、移行オプションから「（推奨）」を削除し、参照数を示してユーザーがコストを判断できるようにします。「そのまま残す」方向に誘導することを優先します。

   Use AskUserQuestion:
   question: "Found existing documentation: {file_list}. {N} of these are referenced outside docs/ ({ref_summary}). Migrate to Blueprint-managed paths?"
   options:
     # When NO candidate is referenced outside docs/: keep "(Recommended)" on migrate.
     # When ANY candidate IS referenced outside docs/: drop "(Recommended)" and show counts.
     - label: "Yes, migrate documents"
       description: "Move docs into docs/prds/, docs/adrs/, docs/prps/ based on content type. Rewrites all {total_refs} references — including build-critical files when referenced outside docs/."
     - label: "No, leave them in place"
       description: "Blueprint creates new docs under docs/{prds,adrs,prps}/; existing docs stay where build tooling and READMEs already point. Safe default when docs are referenced outside docs/."
   

   「はい」を選択した場合： a. 各ファイルを分析して種類を判定します：

   • 要件、機能、ユーザーストーリーを含む → docs/prds/
   • アーキテクチャ上の決定やトレードオフを含む → docs/adrs/
   • 実装計画を含む → docs/prps/
   • 一般的なドキュメント → docs/ b. ファイルを適切な docs/ サブディレクトリに移動します c. 必要に応じて kebab-case に名前を変更します（REQUIREMENTS.md → requirements.md） d. 移行結果を報告します：

   ドキュメントを移行しました：
   - REQUIREMENTS.md → docs/prds/requirements.md
   - ARCHITECTURE.md → docs/adrs/0001-initial-architecture.md
   

   ドキュメントファイルが見つからない場合： この手順を通知なしでスキップします。

4. メンテナンスタスクのスケジュール設定について確認する（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"
   

   選択内容を task_registry のデフォルト値として保存します：

   • Prompt：すべて auto_run: false、スケジュールはデフォルト
   • 安全な自動実行：読み取り専用タスク（adr-validate、feature-tracker-sync、sync-ids）は auto_run: true、書き込みタスクは false
   • 完全自動：すべてのタスクを auto_run: true にし、スケジュールはデフォルト
   • 手動のみ：すべて auto_run: false、すべてのスケジュールを on-demand に設定

   同じ選択内容で automation.autonomy_level も設定します（ADR-0020 のレベル モデル — auto_run の契約を実際に実行するものです）：

   • Prompt / 手動のみ → autonomy_level: 0（無人では何も実行されません）
   • 安全な自動実行 → autonomy_level: 1（決定論的な期限到来タスクは SessionStart プローブ経由で実行され、期限到来したエージェントタスクはドリフト検出結果として提示されます）
   • 完全自動 → autonomy_level: 2（静かな自動操縦により、セッション内で期限到来した エージェントタスクも実行されます。interaction_mode のデフォルトは quiet です）

4a. 生成ルールの出力パスについて確認する（AskUserQuestion を使用）：

.claude/rules/ がすでに存在し、ファイルを含んでいる場合（つまり、blueprint より前に手動で作成されたルールがある場合）にのみ確認します。新規リポジトリでは通知なしでスキップし、デフォルトを使用します。

# 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"

選択したパスをマニフェストの structure.generated_rules_path に保存します（未設定の場合のデフォルトは .claude/rules/）。これにより、blueprint-generate-rules と blueprint-derive-rules が手動で管理されたルールファイルを上書きするのを防ぎます（issue #1043）。

5. 決定事項の検出について確認する（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"
   

   回答に基づいて、マニフェストの has_document_detection を設定します。

   有効にした場合： 書き込み前にルールの出力ディレクトリを解決します。ハードコードされたパスではなく、ステップ 4a で選択したパス（デフォルトは .claude/rules/）を優先し、blueprint が rulesync 管理のルールや手動作成されたルールと競合しないようにします（issue #1675）。

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

   マニフェストがまだ書き込まれていない場合は、ステップ 4a の選択内容を直接使用します（デフォルトは .claude/rules/）。

   document-management-rule.md テンプレートを $RULES_DIR/document-management.md にコピーします。 このルールは Claude に、次の状況を監視するよう指示します：

   • ディスカッション中にアーキテクチャ上の決定がなされた場合 → ADR の作成を促します
   • 機能要件について議論または詳細化された場合 → PRD の作成または更新を促します
   • 実装計画が策定された場合 → PRP の作成を促します

6. ディレクトリ構造を作成する：

   標準ドキュメントパスは docs/blueprint/ 配下ではなく、docs/ の最上位にあります。docs/blueprint/ は blueprint の仕組み（マニフェスト、feature-tracker、work-orders）のみを格納し、docs/{adrs,prds,prps,trps}/ はドキュメント本体を格納します。すべての /blueprint:derive-* スキルは最上位のパスに書き込みます。これらの場所を統一することで、init が一方の構成を作成し、derive-* が別の構成に書き込むという二重コーパスのバグを防ぎます。

   ステップ 3 でドキュメントの移行が行われなかった場合でもディレクトリが存在するよう、明示的に作成します：

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

   注：docs/trps/ は /blueprint:derive-tests によって必要に応じて作成されます。init では事前に作成しません。

   作成されるツリー：

   docs/
   ├── blueprint/
   │   ├── manifest.json            # Version tracking and configuration
   │   ├── feature-tracker.json     # Progress tracking (if enabled)
   │   ├── work-orders/             # Task packages for subagents
   │   │   ├── completed/
   │   │   └── archived/
   │   └── README.md                # Blueprint documentation
   ├── prds/                        # Product Requirements Documents (canonical)
   ├── adrs/                        # Architecture Decision Records (canonical)
   ├── prps/                        # Product Requirement Prompts (canonical)
   └── trps/                        # Test Regression Plans (created on-demand by /blueprint:derive-tests)
   

   Claude の設定（.claude/ 内）： — 初期ルールは structure.generated_rules_path（デフォルトは .claude/rules/。ステップ 4a で既存の内容が検出された場合は、.claude/rules/blueprint/ のような分離されたサブディレクトリ）に記述します。ここではデフォルトの場所を示します。

   .claude/
   ├── rules/                       # $RULES_DIR — generated_rules_path (default .claude/rules/)
   │   ├── development.md           # Development workflow rules
   │   ├── testing.md               # Testing requirements
   │   └── document-management.md   # Document organization rules (if detection enabled)
   └── skills/                      # Custom skill overrides (optional)
   

7. manifest.json を作成します（v3.4.0 スキーマ — 正式なファイル名は docs/blueprint/manifest.json で、ドットから始まりません）。

   {
     "format_version": "3.4.0",
     "created_at": "[ISO timestamp]",
     "updated_at": "[ISO timestamp]",
     "created_by": {
       "blueprint_plugin": "3.3.0"
     },
     "project": {
       "name": "[detected from package.json/pyproject.toml or directory name]",
       "detected_stack": []
     },
     "structure": {
       "has_prds": true,
       "has_adrs": true,
       "has_prps": true,
       "has_work_orders": true,
       "has_modular_rules": true,
       "has_feature_tracker": "[based on user choice]",
       "has_document_detection": "[based on user choice]",
       "claude_md_mode": "both",
       "generated_rules_path": "[based on Step 4a; defaults to .claude/rules/ when prompt skipped]"
     },
     "feature_tracker": {
       "file": "feature-tracker.json",
       "source_document": "[auto-detected]",
       "sync_targets": ["TODO.md"]
     },
     "generated": {
       "rules": {},
       "commands": {}
     },
     "custom_overrides": {
       "skills": [],
       "commands": []
     },
     "automation": {
       "autonomy_level": "[based on maintenance task choice: 0 for Prompt/Manual, 1 for Auto-run safe, 2 for Fully automatic]",
       "interaction_mode": "normal",
       "work_orders": {
         "auto_draft": false,
         "auto_execute": false
       }
     },
     "task_registry": {
       "derive-plans": {
         "enabled": true,
         "auto_run": false,
         "last_completed_at": null,
         "last_result": null,
         "schedule": "weekly",
         "stats": {},
         "context": {}
       },
       "derive-rules": {
         "enabled": true,
         "auto_run": false,
         "last_completed_at": null,
         "last_result": null,
         "schedule": "weekly",
         "stats": {},
         "context": {}
       },
       "generate-rules": {
         "enabled": true,
         "auto_run": false,
         "last_completed_at": null,
         "last_result": null,
         "schedule": "on-change",
         "stats": {},
         "context": {}
       },
       "adr-validate": {
         "enabled": true,
         "auto_run": "[based on maintenance task choice: true if auto-run safe, false otherwise]",
         "last_completed_at": null,
         "last_result": null,
         "schedule": "weekly",
         "stats": {},
         "context": {}
       },
       "feature-tracker-sync": {
         "enabled": true,
         "auto_run": "[based on maintenance task choice: true if auto-run safe, false otherwise]",
         "last_completed_at": null,
         "last_result": null,
         "schedule": "daily",
         "stats": {},
         "context": {}
       },
       "sync-ids": {
         "enabled": true,
         "auto_run": "[based on maintenance task choice: true if auto-run safe, false otherwise]",
         "last_completed_at": null,
         "last_result": null,
         "schedule": "on-change",
         "stats": {},
         "context": {}
       },
       "claude-md": {
         "enabled": true,
         "auto_run": false,
         "last_completed_at": null,
         "last_result": null,
         "schedule": "on-change",
         "stats": {},
         "context": {}
       },
       "curate-docs": {
         "enabled": false,
         "auto_run": false,
         "last_completed_at": null,
         "last_result": null,
         "schedule": "on-demand",
         "stats": {},
         "context": {}
       }
     }
   }
   

   注：機能トラッキングが有効な場合にのみ、feature_tracker セクションを含めます。 注：v3.2.0 以降、進捗トラッキングは feature-tracker.json に統合されています（work-overview.md は削除されました）。

   モノレポの workspaces ブロック（v3.3.0 以降）。ステップ 1a での検出結果に基づいて、マニフェストに追加します。

   • 子（親のブループリントが見つかり、ユーザーが参加を選択した場合）：

     "workspaces": {
       "role": "child",
       "root_relative_path": "[このディレクトリからルートまでの相対パス]"
     }
     

   • ルート（子孫のブループリントが見つかった場合）：

     "workspaces": {
       "role": "root",
       "discovery_strategy": "auto-cache",
       "last_scanned_at": null,
       "children": []
     }
     

     マニフェストの書き込み後、children[] を設定するために /blueprint:workspace-scan を一度実行します。
   • スタンドアロン：workspaces ブロック全体を省略します。

8. 解決済みの $RULES_DIR（ステップ 4a の generated_rules_path。デフォルトは .claude/rules/）の下に初期ルールを作成します。ハードコードされた .claude/rules/ は使用しないでください。これにより、rulesync が管理するルールや手書きのルールの上書きではなく、それらと並存させます（issue #1675）。

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

   • $RULES_DIR/development.md：TDD ワークフロー、コミット規約
   • $RULES_DIR/testing.md：テスト要件、カバレッジの期待値
   • $RULES_DIR/document-management.md：ドキュメント整理ルール（判断の検出が有効な場合）

9. .gitignore を処理します：

   • CLAUDE.md と .claude/rules/（プロジェクト共通の指示）は常にコミットします
   • docs/blueprint/work-orders/ を .gitignore に追加します（タスク固有で、機密情報が含まれる場合があります）
   • .claude/ 内でシークレットが検出された場合は、ユーザーに警告し、.gitignore への追加を提案します

10. 結果を報告します：

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. 次のアクションを確認します（AskUserQuestion を使用）：

    question: "ブループリントを初期化しました。次に何をしますか？"
    options:
      - label: "git 履歴から計画を導出する（推奨）"
        description: "コミット履歴、PR、issue を分析し、既存のプロジェクト上の意思決定から PRD、ADR、PRP を作成します"
      - label: "コードベースからルールを導出する"
        description: "コミットのパターンとコード規約を分析して .claude/rules/ を生成します"
      - label: "CLAUDE.md を更新する"
        description: "プロジェクトのコンテキストとブループリントの統合情報を含む CLAUDE.md を生成または更新します"
      - label: "今回は終了する"
        description: "終了します。いつでも /blueprint:status を実行して選択肢を確認できます"
    

    選択内容に応じて実行します：

    • "Derive plans from git history" → /blueprint:derive-plans を実行します
    • "Derive rules from codebase" → /blueprint:derive-rules を実行します
    • "Update CLAUDE.md" → /blueprint:claude-md を実行します
    • "I'm done for now" → クイックリファレンスを表示して終了します

クイックリファレンス（ユーザーが "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