blueprint-init

在此项目中初始化 Blueprint Development。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 blueprint-upgrade……
项目尚无 docs/blueprint/manifest.json	项目已有旧格式版本的清单
你要为新项目搭建 PRD/ADR/PRP 目录	你要迁移 v1.x→v2、v2→v3 或 v3.x→v3.y
你想从头启用功能跟踪和决策检测	初始化后使用 blueprint-derive-plans 填充 PRD/ADR/PRP
你要首次配置任务调度	想要自动检测下一步时，改用 blueprint-execute

步骤

1. 检查是否已初始化：
   • 查找 docs/blueprint/manifest.json
   • 如果存在，读取版本并询问用户：

     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. 检测 monorepo 上下文（format_version 3.3.0+）：

• 从当前目录向上遍历，查找祖先目录中的 docs/blueprint/manifest.json（到仓库根目录或 $HOME 为止）。
• 如果存在祖先根清单，则此次初始化会创建一个子 工作区。记录从子工作区到根目录的相对路径。
• 另外，扫描后代目录（最大深度为 4，跳过 node_modules、 .git、dist、build、target、.venv），查找现有的 docs/blueprint/manifest.json。如果找到任何文件，则此次初始化会创建一个 将管理现有子工作区的根工作区。
• 否则，这是一个独立的 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"
   

   如果选择“Yes”： a. 在项目中搜索包含需求、功能或用户故事的 Markdown 文件 b. 根据内容分析自动检测最可能的源文档 c. 使用检测到的源文档从模板创建 docs/blueprint/feature-tracker.json d. 在清单中设置 has_feature_tracker: true

3. 询问是否迁移文档（使用 AskUserQuestion）： 在整个项目中搜索现有 Markdown 文档文件（排除 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$'
   

   建议迁移前，先衡量交叉引用密度。 将文档迁移到 docs/{prds,adrs,prps}/ 会改写其路径，导致所有指向该文档的 引用失效。对于每个候选文档，使用 grep 搜索仓库中来自 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: "Yes, migrate documents (Recommended)"）。
   • 如果有一个或多个候选文档被 docs/ 以外的位置引用，请从迁移选项中移除“(Recommended)”标记，并显示引用数量，让用户判断成本。优先引导用户选择“保留原位”。

   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 默认值：

   • 提示：所有任务的 auto_run: false，使用默认计划
   • 安全自动运行：只读任务（adr-validate、feature-tracker-sync、sync-ids）的 auto_run: true；写入任务的 auto_run: false`
   • 完全自动：所有任务的 auto_run: true，使用默认计划
   • 仅手动：所有任务的 auto_run: false，所有计划均设为 on-demand

   同一选择还会设置 automation.autonomy_level（ADR-0020 的级别模型——实际执行 auto_run 契约的内容）：

   • 提示 / 仅手动 → autonomy_level: 0（无人值守时不运行任何任务）
   • 安全自动运行 → autonomy_level: 1（到期的确定性任务通过 SessionStart 探测运行；到期的 Agent 任务会显示为偏差发现）
   • 完全自动 → autonomy_level: 2（静默自动驾驶模式也会在会话中运行到期的 Agent 任务；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/ 顶层，而非 docs/blueprint/ 下。docs/blueprint/ 仅存放 Blueprint 机制相关内容（清单、feature-tracker、工作单）；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）。

   Monorepo workspaces 块（v3.3.0+），根据步骤 1a 的检测结果附加到清单中：

   • 子级（找到祖先 Blueprint 且用户选择加入）：

     "workspaces": {
       "role": "child",
       "root_relative_path": "[relative path from this dir to the root]"
     }
     

   • 根级（找到后代 Blueprint）：

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

     写入清单后，运行一次 /blueprint:workspace-scan 以填充 children[]。
   • 独立项目：完全省略 workspaces 块。

8. 在解析出的 $RULES_DIR（步骤 4a 的 generated_rules_path，默认为 .claude/rules/）下创建初始规则 — 绝不能硬编码为 .claude/rules/ — 以便与 rulesync 管理的规则或手动编写的规则并列，而不是覆盖它们（问题 #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: "Blueprint 已初始化。接下来要做什么？"
    options:
      - label: "从 git 历史推导计划（推荐）"
        description: "分析提交历史、PR 和 issue，根据现有项目决策构建 PRD、ADR 和 PRP"
      - label: "从代码库推导规则"
        description: "分析提交模式和代码规范，生成 .claude/rules/"
      - label: "更新 CLAUDE.md"
        description: "生成或更新 CLAUDE.md，加入项目背景和 Blueprint 集成信息"
      - label: "暂时到此为止"
        description: "退出 — 你可以随时运行 /blueprint:status 查看选项"
    

    根据所选项：

    • “从 git 历史推导计划” → 运行 /blueprint:derive-plans
    • “从代码库推导规则” → 运行 /blueprint:derive-rules
    • “更新 CLAUDE.md” → 运行 /blueprint:claude-md
    • “暂时到此为止” → 显示快速参考并退出

快速参考（如果用户选择“暂时到此为止”，则显示）：

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