ideation

构思

通过对话式访谈，将零散的想法转化为实现文档，在动笔前建立共同理解。HTML 用于交互式决策（可视化、比较、任务简报契约）；Markdown 用于参考文档（规格说明、PRD）。

工作流

INTAKE → INTERVIEW LOOP → CONTRACT.HTML → PHASING → SPEC.MD GENERATION → HANDOFF
              ↓                  ↓             ↓             ↓                ↓
         Accept the mess    One question    Mission       Repeatable?      Phase track
                            at a time,      Brief with      ↓              + copy buttons
                            explore code    confidence   Template +        in contract
                            + show HTML     + scope      per-phase
                            examples        tiers        deltas

阶段 1-2：访谈

阅读并遵循 ${CLAUDE_PLUGIN_ROOT}/references/interview-engine.md，了解完整的需求收集和访谈循环流程。继续进入阶段 3 之前，先完成其中描述的所有阶段。

阅读 ${CLAUDE_PLUGIN_ROOT}/references/confidence-rubric.md，了解详细的评分标准。

阶段 3：契约（HTML）

当置信度 ≥ 95% 时，生成 HTML 格式的任务简报契约。不得提前生成。

1. 如果无法从上下文中明确项目名称，使用 AskUserQuestion 确认项目名称

2. 转换为 kebab-case，作为目录名称（即 slug）

3. 创建输出目录 ./docs/ideation/{slug}/

4. 在输出目录中编写 contract-data.json。这是一个符合 ContractData schema 的 JSON 文件，CLI 会根据它生成 HTML。该 JSON 包含所有访谈结果：

   {
     "projectName": "Human-Readable Name",
     "slug": "kebab-case-name",
     "date": "YYYY-MM-DD",
     "status": "Draft",
     "supersedes": null,
     "confidence": {
       "score": 96,
       "dimensions": [
         { "key": "scope", "score": 100, "label": "Scope", "reason": "One sentence explaining the score" },
         { "key": "risk", "score": 92, "label": "Risk", "reason": "One sentence" },
         { "key": "effort", "score": 95, "label": "Effort", "reason": "One sentence" },
         { "key": "clarity", "score": 98, "label": "Clarity", "reason": "One sentence" },
         { "key": "tests", "score": 95, "label": "Tests", "reason": "One sentence" }
       ]
     },
     "problem": ["paragraph 1", "paragraph 2"],
     "goals": ["Measurable goal 1", "Measurable goal 2"],
     "successCriteria": ["Pass/fail criterion 1", "Pass/fail criterion 2"],
     "scope": {
       "mvp": [{"item": "Core feature", "reason": "Why it's MVP"}],
       "full": [{"item": "Full feature", "reason": "Optional rationale"}],
       "stretch": [{"item": "Stretch feature"}],
       "outOfScope": [{"item": "Excluded item", "reason": "Why excluded"}],
       "future": ["Deferred idea 1"]
     },
     "execution": {
       "strategy": "Sequential",
       "phases": [
         {
           "title": "Phase name",
           "risk": "low",
           "blocking": true,
           "specPath": "docs/ideation/slug/spec-phase-1.md",
           "notes": "Brief description of what this phase covers"
         }
       ],
       "agentTeamPrompt": "only if 2+ phases parallelizable"
     }
   }
   

   **置信度维度：**每个维度都要给出一个数值评分（0-100）和一句话理由。总体 score 会显示在主视觉区域；各维度则显示评分明细。

   阶段字段：risk（high/medium/low）、blocking（布尔值）、specPath（规格说明路径）、notes（简要说明）。可选：kind（人工检查点时填写 "gate"）、prereqs（此阶段所依赖的阶段标题数组）。

5. 运行契约生成器：

   npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/contract-gen.ts \
     --input ./docs/ideation/{slug}/contract-data.json \
     --output ./docs/ideation/{slug}/contract.html
   

   CLI 会自动处理版本关系——如果 contract.html 已存在，就会将其重命名为 contract-{date}.html，并设置 supersedes 链接。

6. 在浏览器中打开：运行 open ./docs/ideation/{slug}/contract.html（macOS）或 xdg-open（Linux）

7. 使用 AskUserQuestion 获取批准——包括范围层级问题：

Question: "Does this contract capture your intent? Which scope tier should we target?"
Options:
- "Approved — Full scope (Recommended)" - Build MVP + Full tiers
- "Approved — MVP scope" - Ship the minimum viable version first
- "Approved — Stretch scope" - Include MVP + Full + Stretch tiers
- "Needs changes" - Some parts need revision before approving
- "Start over" - Fundamentally off track, re-interview

获批的范围层级决定规格说明中包含哪些内容。所选层级之外的事项会移至“未来考虑事项”。

**如果未获批准：**根据反馈进行修订。如果反馈表明存在根本性误解，请返回访谈循环。否则，重写 HTML 文件并在浏览器中重新打开。反复迭代，直到获得批准。

在契约明确获批之前，不得继续。

阶段 4：阶段规划与规格说明

契约获批后，确定实施阶段并生成 Markdown 规格说明。PRD 为可选项。

4.1 选择工作流

使用 AskUserQuestion 提问：

Question: "How should we proceed from the contract?"
Options:
- "Straight to specs (Recommended)" — Contract defines what, specs define how. Faster.
- "PRDs then specs" — Adds a requirements layer for stakeholder alignment.

4.2 确定阶段

分析契约，并将范围拆分为逻辑清晰的实施阶段。

**小型项目捷径：**如果范围足够小，可以在单个阶段中实现（1-3 个组件，涉及的文件少于约 10 个），则完全跳过阶段规划。生成单个 spec.md（无需阶段编号），然后直接移交。简单问题不必强行增加结构。

阶段划分标准（适用于多阶段项目）：

• 依赖关系（必须先构建什么？）
• 风险（优先处理高风险事项）
• 价值交付（用户能否在每个阶段完成后受益？）
• 复杂度（平衡各阶段的工作量）

典型阶段划分：

• 阶段 1：核心功能／基础设施
• 阶段 2+：功能、增强项、其他集成
• 阶段 N：未来考虑事项

**检测可重复模式：**如果有 3 个或更多阶段遵循相同结构，只是输入不同（例如“为 {language} 添加 SDK 支持”），请注明这一点——这会影响规格说明的生成方式（见 4.4）。

### 4.3 生成 PRD（仅当用户选择“先生成 PRD，再生成规格说明”时）

对于每个阶段，使用 Read 工具读取 references/prd-template.md，然后生成 prd-phase-{n}.md。

包括：

• 阶段概述和理由
• 本阶段的用户故事
• 功能需求（分组列出）
• 非功能需求
• 依赖项（前置条件和输出）
• 验收标准

通过 AskUserQuestion 提交所有 PRD 供审阅：

Question: "Do these PRD phases look correct?"
Options:
- "Approved" - Phases and requirements look good, proceed to specs
- "Adjust phases" - Need to move features between phases
- "Missing requirements" - Some requirements are missing or unclear
- "Start over" - Need to revisit the contract

反复迭代，直到用户明确批准。

4.4 生成实现规格说明

使用 Read 工具读取 references/spec-template.md，然后生成 spec-phase-{n}.md。按需创建规格说明文件——仅在某个阶段的细节确定后才创建。

标准阶段（各阶段各不相同）

对于每个阶段，生成完整的 spec-phase-{n}.md，包括：

• 技术方案 — 高层策略
• 反馈策略 — 内循环命令、试验环境、理由
• 文件变更 — 包含新建／修改／删除标记的表格
• 实现细节 — 按组件分节，每节都包含一个反馈循环（试验环境 → 实验 → 检查命令）
• 测试要求 — 包含测试文件和覆盖范围的表格
• 故障模式 — 包含组件、故障、触发条件、影响、缓解措施列的表格
• 验证命令 — 代码块

参考现有代码： 如果在访谈期间的代码库探索中发现了相关模式，请在规格说明的实现细节中加入“遵循此模式：path/to/similar/file.ts”。

设计反馈循环： 对于每个迭代组件，都要定义一个试验环境（交互环境）、实验（参数化检查）和检查命令（最快的单项验证）。反馈机制应与组件类型匹配——数据层使用测试，UI 使用开发服务器，API 使用 curl 脚本，配置／类型则完全跳过循环。组件类型对应关系和设计标准详见 ${CLAUDE_PLUGIN_ROOT}/references/feedback-loop-guide.md。

命名故障模式： 对于每个非简单组件，都要思考：“它会如何故障？”在规格说明的故障模式表格中，填写明确命名的故障、数据失效路径（nil、空数据、过期数据）和边缘情况（并发访问、超大输入、缺少权限）。简单组件（配置、类型、常量）无需枚举故障模式。

可重复阶段（3 个或更多阶段遵循相同模式）

如果多个阶段结构相同（例如“添加对 {SDK} 的支持”），请避免生成 N 份几乎相同的完整规格说明。请改为：

1. 生成一份完整的模板规格说明 — spec-template-{pattern-name}.md — 使用占位符表示可变部分，并提供详细的实现步骤。

2. 生成轻量级的各阶段差异文件 — spec-phase-{n}.md — 仅包含：

   • 阶段特定输入（例如，语言名称、包管理器、框架）
   • 与模板的差异（本阶段有哪些不同）
   • 阶段特定的注意事项或边缘情况
   • 对模板的引用：“使用以下输入，遵循 spec-template-{pattern-name}.md”

4.5 提交规格说明供审阅

继续交接前，提交阶段划分和规格说明供用户批准。

提交规格说明前，使用《规格说明反馈质量》检查清单评估反馈循环质量，该清单位于 ${CLAUDE_PLUGIN_ROOT}/references/confidence-rubric.md。对每份规格说明进行自我审查：

• 良好：所有迭代组件都有反馈循环，已定义内循环命令，且正确跳过简单组件 → 按原样提交规格说明
• 合格：大多数组件都有反馈循环，但仍存在一些缺漏 → 提交规格说明并说明缺少的内容
• 较弱：没有“反馈策略”一节，或复杂组件完全缺少反馈循环 → 提交前修订规格说明

如果质量较弱，先补齐缺漏。不要提交缺少迭代组件反馈循环的规格说明。

使用 AskUserQuestion：

Question: "Do these specs look correct? (Review them in your browser)"
Options:
- "Approved" - Specs look good, proceed to execution handoff
- "Adjust approach" - Implementation strategy needs changes
- "Missing components" - Some files or steps are missing
- "Revisit phases" - Phase breakdown needs restructuring

如果用户未批准，请根据反馈修订相关规格说明，然后重新提交。反复迭代，直到获得批准。

第 5 阶段：执行交接

规格获批后，使用执行计划更新契约 HTML，并自动生成供 /ideation:execute-spec 使用的 Markdown 规格。

5.1 分析编排策略

在构思交接期间不要创建任务——这些任务是临时的，用户开始新会话时就会丢失。每个 /ideation:execute-spec 会话都会创建自己的细粒度实现任务。

分析阶段依赖关系图，确定最佳执行策略。

检测可并行执行的阶段：

• 检查各阶段受哪些因素阻塞
• 如果 2 个或更多阶段只有同一个阻塞项（例如，所有阶段都只受第 1 阶段阻塞），则这些阶段可并行执行
• 如果各阶段构成线性链（第 2 阶段 → 第 3 阶段 → 第 4 阶段），则这些阶段应按顺序执行
• 混合关系图同时包含并行和顺序执行的部分

确定推荐策略：

模式	建议
所有阶段均按顺序执行（链式）	顺序执行 — 每次运行一个会话
2 个或更多独立阶段	Agent 团队 — 由负责人并行协调团队成员
依赖关系混合	混合模式 — 依赖链按顺序执行，独立阶段组由 Agent 团队执行

5.2 使用执行计划更新契约数据

使用最终执行计划更新 contract-data.json，然后重新运行 contract-gen.ts。这样契约就完全自包含，接手者无需背景信息也能准确了解如何执行。

1. 阶段轨道 — 在 execution.phases 中填写阶段标题、风险、阻塞项、规格路径、备注和人工关卡。CLI 会根据风险着色并渲染水平阶段轨道。

2. 执行命令 — CLI 会为 /ideation:autopilot 和每条 /ideation:execute-spec 命令渲染复制按钮。

3. Agent 团队提示词 — 仅当有 2 个或更多可并行执行的阶段时设置 execution.agentTeamPrompt，这样 CLI 会在可折叠区域中渲染该提示词，并附带复制按钮。对于完全按顺序执行的项目，请完全省略此字段。

检测共享文件： 编写 Agent 团队提示词前，扫描规格文件中的“Modified Files”部分。如果多个规格会修改同一文件，请加入协调说明：

Coordinate on shared files ({list}) to avoid merge conflicts —
only one teammate should modify a shared file at a time.

批次处理： 如果有超过 5 个可并行执行的阶段，请在执行步骤中注明先从优先级最高的批次开始。

更新后，在浏览器中重新打开生成的契约。

5.3 生成契约 Markdown

使用 references/contract-template.md 生成 contract.md，内容须与 contract.html 相同——这是 execute-spec 进行谱系检测所必需的。请包含“执行计划”部分。

规格和 PRD 已在第 4 阶段生成为 Markdown，无需转换。

5.4 呈现交接摘要

更新契约并生成 MD 规格后，以简短、自然的对话方式呈现摘要。

始终包含：

Ideation complete. Artifacts written to `./docs/ideation/{project-name}/`.

Open contract.html in your browser to review the full plan — phase track,
execution commands, and scope are all in the Mission Brief.

Specs (spec-phase-*.md) are ready. To execute all phases:
  /ideation:autopilot

Or run individual phases manually:
  /ideation:execute-spec docs/ideation/{project-name}/spec-phase-1.md

建议默认使用 /ideation:autopilot。它会读取契约、梳理依赖关系图、按阶段派发子 Agent（条件允许时并行执行），且仅在出现故障时停止。也可以手动使用 /ideation:execute-spec，以获得更精细的控制。

输出文件

所有文件均写入 ./docs/ideation/{project-name}/：

_comparison.html                   # Ephemeral decision aid (deleted after choice is made)
contract.html                      # Mission Brief contract (for review)
contract.md                        # Plain contract (for execute-spec lineage)
prd-phase-1.md                     # Phase 1 requirements (only if PRDs chosen)
...
spec-phase-1.md                    # Implementation spec (for execute-spec)
spec-template-{pattern}.md         # Shared template for repeatable phases (if applicable)
spec-phase-{n}.md                  # Per-phase delta or full spec
...

捆绑资源

共享参考资料（插件根目录）

• ${CLAUDE_PLUGIN_ROOT}/references/interview-engine.md - 访谈引擎（第 1–2 阶段）
• ${CLAUDE_PLUGIN_ROOT}/references/confidence-rubric.md - 信心评估的评分标准和规格反馈质量标准
• ${CLAUDE_PLUGIN_ROOT}/references/feedback-loop-guide.md - 规格反馈循环的组件类型映射和设计标准
• ${CLAUDE_PLUGIN_ROOT}/references/workflow-example.md - 端到端工作流演练

技能参考

HTML（交互式产物 — 合同、探索、访谈可视化内容）：

• references/html-guide.md - HTML 组件库、设计令牌和限制
• references/contract-template.html - 交互式 HTML 合同模板

Markdown（规格说明、PRD、用于 execute-spec 的合同文案）：

• references/contract-template.md - 纯文本合同模板
• references/prd-template.md - 纯文本 PRD 模板
• references/spec-template.md - 纯文本规格说明模板

示例

生成输出时可供参考的已完成产物示例：

• examples/contract-example.md - 为书签功能填写完成的 MD 合同
• examples/prd-example.md - 为同一功能填写完成的 MD PRD（第 1 阶段）
• examples/spec-example.md - 为同一功能填写完成的 MD 规格说明

生成产物时，请参考这些示例的语气、结构和详略程度。

用于决策的 HTML 可视化内容

在访谈和分阶段过程中，如果视觉上下文能帮助用户更好地做出决策，请生成临时 HTML 页面。这些页面是一次性辅助材料 — 创建、审阅，然后删除。

适用场景：

• 访谈示例 — 展示用户正在选择的 UI 模拟图、布局选项或组件结构
• 架构对比 — 并排展示 2-3 种有效方案及其显著不同的权衡
• 分阶段策略 — 通过可视化依赖关系流程展示“核心优先 vs. 风险优先 vs. 价值优先”
• 编排策略 — 通过时间线可视化展示顺序、并行或混合方案
• 任何适合通过视觉布局比文字更清晰地说明权衡的决策

工作方式：

1. 使用 references/html-guide.md 中的组件，在项目的构思目录下编写 _comparison.html（或 _examples.html、_mockup.html — 添加 _ 前缀以标记为临时文件）
2. 将每个选项显示为卡片或列，并在适当时包含名称、描述、权衡和可视化内容
3. 在浏览器中打开：open ./docs/ideation/{project-name}/_comparison.html
4. 通过 AskUserQuestion 提问 — 在问题文字中引用浏览器中的视图
5. 用户选择后，删除临时文件 — 它已完成用途

不适用场景： 简单的是/否决策、推荐选项显然最佳的选择，或通过文字说明更快的任何决策。不要用不必要的可视化辅助拖慢流程。

重要说明

• HTML 仅用于交互式产物 — 合同和临时决策可视化内容。规格说明和 PRD 使用 Markdown。
• 写入前使用 Read 工具加载模板。 第 3 阶段前必须阅读 references/html-guide.md，生成合同前必须阅读 references/contract-template.html。生成规格说明前必须阅读 references/spec-template.md。
• 所有问题和审批都使用 AskUserQuestion。 一次只问一个问题，并给出推荐答案。
• 保守评估信心度。 不确定时，给出较低分数。问题数量不设上限。
• 写入后在浏览器中打开 HTML 产物。 使用 open（macOS）或 xdg-open（Linux）。
• 按需创建文件。 仅在决策确定后创建，不要提前臆测。
• 在规格说明中引用现有代码模式 — 使用“应遵循的模式”并提供真实文件路径。
• 小型项目无需分阶段。 1-3 个组件 → 单份规格说明。可对可重复的阶段使用模板 + 差异项。
• 规格说明必须独立完整 — 详细程度应足以支持实现，无需重新阅读 PRD 或合同。