需要为功能做详尽实施前分析时，用多步研究、访谈、多 LLM…

适用于规划需要充分前期分析、干系人访谈、外部模型评审并可交付分节执行文件的功能。

适用场景

解决思路

1. 1. BEFORE anything else，立即打印 intro banner： ═══════════════════════════════════════════════════════════════ GEPETTO: AI-Assisted Implementation Planning ═══════════════════════════════════════════════════════════════ Research → Interview → Spec Synthesis → Plan → External Review → Sections Note: GEPETTO will write many .md files to the planning directory you pass it
2. 2. 验证 Spec File 输入：检查用户调用时是否提供 @file 且该路径以 .md 结尾；若未提供 @file 或路径不以 .md 结尾，输出 Spec File Required 提示并 STOP。提示内容包含：此技能需要 markdown spec 文件路径（必须以 .md 结尾）；规划目录由 spec 文件的父目录推断；新建计划时先创建描述目标的 markdown spec 文件（可详细可模糊），放在 gepetto 可保存规划文件的目录，然后运行 /gepetto @path/to/your-spec.md；恢复已有计划也运行 /gepetto @path/to/your-spec.md；示例 /gepetto @planning/my-feature-spec.md。不要继续，等待用户重新以 .md 文件路径调用。
3. 3. Setup Planning Session：设置 planning_dir = spec 文件的父目录；设置 initial_file = spec 文件路径。
4. 4. 扫描已有规划文件：claude-research.md、claude-interview.md、claude-spec.md、claude-plan.md、claude-integration-notes.md、claude-ralph-loop-prompt.md、claude-ralphy-prd.md、reviews/ 目录、sections/ 目录。
5. 5. 根据已找到文件判断 mode 和 resume point：None -> new，从 Step 4 开始；research only -> resume，从 Step 6 interview 开始；research + interview -> resume，从 Step 8 spec synthesis 开始；+ spec -> resume，从 Step 9 plan 开始；+ plan -> resume，从 Step 10 external review 开始；+ reviews -> resume，从 Step 11 integrate 开始；+ integration-notes -> resume，从 Step 12 user review 开始；+ sections/index.md -> resume，从 Step 14 write sections 开始；all sections complete -> resume，从 Step 15 execution files 开始；+ claude-ralph-loop-prompt.md + claude-ralphy-prd.md -> complete，Done。
6. 6. 根据当前状态用 TodoWrite 创建 TODO list。
7. 7. 打印状态：Planning directory: {planning_dir}；Mode: {mode}。如果是恢复，打印：Resuming from step {N}；To start fresh, delete the planning directory files。
8. 8. 使用统一日志格式：\n═══════════════════════════════════════════════════════════════\nSTEP {N}/17: {STEP_NAME}\n═══════════════════════════════════════════════════════════════\n{details}\nStep {N} complete: {summary}\n───────────────────────────────────────────────────────────────
9. 9. Step 4 Research Decision：见 research-protocol.md；读取 spec 文件；提取潜在研究主题（technologies、patterns、integrations）；询问用户代码库研究需求；询问用户 web 研究需求（将推导出的主题作为 multi-select 展示）；记录哪些研究类型要在 Step 5 执行。
10. 10. Step 5 Execute Research：见 research-protocol.md；根据 Step 4 决策启动研究 subagents：Codebase research 用 Task(subagent_type=Explore)；Web research 用 Task(subagent_type=Explore) 配合 WebSearch；若两者都需要，在单条消息中并行启动两个 Task 工具；重要：subagents 返回他们的发现，不直接写文件；收集所有 subagents 结果后合并写入 <planning_dir>/claude-research.md；若 Step 4 选择 no research，则完全跳过此步。
11. 11. Step 6 Detailed Interview：见 interview-protocol.md；在主上下文运行（AskUserQuestion 要求如此）；访谈应参考初始 spec 和研究发现（如有）。
12. 12. Step 7 Save Interview Transcript：将 Q&A 写入 <planning_dir>/claude-interview.md。
13. 13. Step 8 Write Initial Spec (Spec Synthesis)：合并初始输入（spec 文件）、研究发现（若 Step 5 执行）、访谈答案（来自 Step 6）到 <planning_dir>/claude-spec.md；将用户原始需求综合为完整 specification。
14. 14. Step 9 Generate Implementation Plan：创建详细计划到 <planning_dir>/claude-plan.md；面向不熟悉的读者写作；计划必须完全自包含，没有先验上下文的工程师或 LLM 仅阅读文档就应理解要构建什么、为什么、以及如何做。
15. 15. Step 10 External Review：见 external-review.md；并行启动两个 subagents 审查计划：1 Gemini 通过 Bash；2 Codex 通过 Bash；两者接收计划内容并返回分析；将结果写入 <planning_dir>/reviews/。
16. 16. Step 11 Integrate External Feedback：分析 <planning_dir>/reviews/ 中的建议；你是决定整合与否的权威，决定不整合任何内容也可以；Step 1：写入 <planning_dir>/claude-integration-notes.md，记录整合哪些建议及原因、不整合哪些建议及原因；Step 2：用整合后的变更更新 <planning_dir>/claude-plan.md。
17. 17. Step 12 User Review of Integrated Plan：使用 AskUserQuestion，提示计划已根据外部反馈更新，用户现在可审查并编辑 claude-plan.md；如果想让 Claude 帮助编辑计划，另开一个 Claude session，因为当前 session 处于 workflow 中，在 workflow 完成前无法协助编辑；用户完成后选择 `Done reviewing` 继续；等待用户确认后再继续。
18. 18. Step 13 Create Section Index：见 section-index.md；读取 claude-plan.md；识别自然 section 边界并创建 <planning_dir>/sections/index.md；CRITICAL：index.md 必须以 SECTION_MANIFEST block 开头，格式要求见 reference；在继续创建 section 文件前先写 index.md。
19. 19. Step 14 Write Section Files — Parallel Subagents：见 section-splitting.md；并行启动 subagents，每个 section 一个 Task 以最大化效率；先解析 sections/index.md 获取 SECTION_MANIFEST 列表；然后在单条消息中为所有 section 启动 Task（并行执行）；每个 Task 使用 subagent_type="general-purpose"；prompt 指定写 section 文件 section-01-{name}，输入 <planning_dir>/claude-plan.md 和 <planning_dir>/sections/index.md，输出 <planning_dir>/sections/section-01-{name}.md；section 文件必须完全自包含，包括 Background（为什么存在）、Requirements（完成后必须满足什么）、Dependencies（requires/blocks）、Implementation details（来自计划）、Acceptance criteria（复选框）、Files to create/modify；实现者不应需要引用任何其他文档；所有 subagents 完成后再继续。
20. 20. Step 15 Generate Execution Files — Subagent：委派给 subagent 减少主上下文 token 使用；使用 Task subagent_type="general-purpose"，prompt 要求生成两个用于自主实现的文件；输入文件为 <planning_dir>/sections/index.md（含 SECTION_MANIFEST）和 <planning_dir>/sections/section-*.md（所有 section 文件）；OUTPUT 1：<planning_dir>/claude-ralph-loop-prompt.md，用于 ralph-loop plugin，必须内联嵌入所有 section 内容，结构包括 Mission statement、sections/index.md 的完整内容、每个 section 文件的完整内容（嵌入而非引用）、执行规则（依赖顺序、验证 acceptance criteria）、完成信号 <promise>ALL-SECTIONS-COMPLETE</promise>；OUTPUT 2：<planning_dir>/claude-ralphy-prd.md，用于 Ralphy CLI，引用 section 文件（不要嵌入），结构包括 PRD 头部、如何使用（ralphy --prd command）、上下文说明、复选框任务列表每个 section 一个 "- [ ] Section NN: {name}"；写两个文件；等待 subagent 完成后再继续。
21. 21. Step 16 Final Status：验证所有文件成功创建：SECTION_MANIFEST 中的所有 section 文件、claude-ralph-loop-prompt.md、claude-ralphy-prd.md。
22. 22. Step 17 Output Summary：打印生成文件和下一步；列出的生成文件包括 claude-research.md（research findings）、claude-interview.md（Q&A transcript）、claude-spec.md（synthesized specification）、claude-plan.md（implementation plan）、claude-integration-notes.md（feedback decisions）、reviews/（external LLM feedback）、sections/（implementation units）、claude-ralph-loop-prompt.md（for ralph-loop plugin）、claude-ralphy-prd.md（for Ralphy CLI）；实现方式：Option A 手动（推荐学习/控制）：读 sections/index.md 理解依赖，按顺序实现每个 section 文件，每个 section 自包含且有 acceptance criteria；Option B 用 ralph-loop 自主（Claude Code plugin）：/ralph-loop @<planning_dir>/claude-ralph-loop-prompt.md --completion-promise "COMPLETE" --max-iterations 100；Option C 用 Ralphy 外部 CLI：ralphy --prd <planning_dir>/claude-ralphy-prd.md，或 cp <planning_dir>/claude-ralphy-prd.md ./PRD.md && ralphy。

适用边界 · 注意事项

• 不适用于没有 Markdown spec 文件、或不想先写 spec 的场景。
• 不适用于只想要快速计划、不需要研究/访谈/外部 LLM 审查/分节执行文件的小任务。
• 不适用于无法使用 Claude Code 的 Task、AskUserQuestion、TodoWrite，或无法调用 Gemini/Codex/ralph-loop/Ralphy 的环境。