gepetto

Gepetto

协调多步骤规划流程：研究 → 访谈 → 规格综合 → 计划 → 外部评审 → 分节

重要：首先执行的操作

在执行任何其他操作之前，按以下顺序执行：

1. 打印简介

立即打印简介横幅：

═══════════════════════════════════════════════════════════════
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. 验证规格文件输入

检查用户在调用时是否提供了 @file，且该文件是规格文件（以 .md 结尾）。

如果没有提供 @file，或路径不以 .md 结尾，则输出以下内容并停止：

═══════════════════════════════════════════════════════════════
GEPETTO: Spec File Required
═══════════════════════════════════════════════════════════════

This skill requires a markdown spec file path (must end with .md).
The planning directory is inferred from the spec file's parent directory.

To start a NEW plan:
  1. Create a markdown spec file describing what you want to build
  2. It can be as detailed or as vague as you like
  3. Place it in a directory where gepetto can save planning files
  4. Run: /gepetto @path/to/your-spec.md

To RESUME an existing plan:
  1. Run: /gepetto @path/to/your-spec.md

Example: /gepetto @planning/my-feature-spec.md
═══════════════════════════════════════════════════════════════

不要继续。等待用户使用 .md 文件路径重新调用。

3. 设置规划会话

通过检查现有文件确定会话状态：

1. 将 planning_dir 设置为规格文件的父目录

2. 将 initial_file 设置为规格文件路径

3. 扫描是否存在以下规划文件：

   • 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/ 目录

4. 确定模式和恢复位置：

找到的文件	模式	从何处恢复
无	new	步骤 4
仅 research	resume	步骤 6（访谈）
research + interview	resume	步骤 8（规格综合）
+ spec	resume	步骤 9（计划）
+ plan	resume	步骤 10（外部评审）
+ reviews	resume	步骤 11（整合）
+ integration-notes	resume	步骤 12（用户评审）
+ sections/index.md	resume	步骤 14（编写分节）
所有分节均已完成	resume	步骤 15（执行文件）
+ claude-ralph-loop-prompt.md + claude-ralphy-prd.md	complete	完成

5. 根据当前状态，使用 TodoWrite 创建 TODO 列表

打印状态：

Planning directory: {planning_dir}
Mode: {mode}

如果正在恢复：

Resuming from step {N}
To start fresh, delete the planning directory files.

---

日志格式

═══════════════════════════════════════════════════════════════
STEP {N}/17: {STEP_NAME}
═══════════════════════════════════════════════════════════════
{details}
Step {N} complete: {summary}
───────────────────────────────────────────────────────────────

---

工作流

4. 研究决策

参见 research-protocol.md。

1. 阅读规格文件
2. 提取潜在研究主题（技术、模式、集成）
3. 询问用户是否需要研究代码库
4. 询问用户是否需要网络研究（将整理出的主题作为多选项呈现）
5. 记录要在步骤 5 中执行的研究类型

5. 执行研究

参见 research-protocol.md。

根据步骤 4 的决定，启动研究子 Agent：

• 代码库研究： Task(subagent_type=Explore)
• 网络研究： 使用 WebSearch 的 Task(subagent_type=Explore)

如果两者都需要，则并行启动两个 Task 工具（在一条消息中发出多个工具调用）。

重要： 子 Agent 会返回研究结果，但不会直接写入文件。收集所有子 Agent 的结果后，将其合并并写入 <planning_dir>/claude-research.md。

如果用户在步骤 4 中选择不进行研究，则完全跳过此步骤。

6. 详细访谈

参见 interview-protocol.md

在主上下文中运行（AskUserQuestion 需要主上下文）。访谈应参考：

• 初始规格
• 研究结果（如有）

7. 保存访谈记录

将问答写入 <planning_dir>/claude-interview.md

8. 编写初始规格（规格综合）

将以下内容整合到 <planning_dir>/claude-spec.md：

• 初始输入（规格文件）
• 研究结果（如果已执行步骤 5）
• 访谈回答（来自步骤 6）

通过综合这些内容，将用户的原始需求整理成完整规格。

9. 生成实施计划

创建详细计划 → <planning_dir>/claude-plan.md

重要： 面向不熟悉项目的读者编写。计划必须完全自包含——即使工程师或大模型没有任何背景信息，仅阅读本文档也应能理解我们要构建什么、为什么构建以及如何构建。

10. 外部评审

参见 external-review.md

并行启动两个子 Agent 来评审计划：

1. 通过 Bash 使用 Gemini
2. 通过 Bash 使用 Codex

两者都会收到计划内容并返回分析结果。将结果写入 <planning_dir>/reviews/。

11. 整合外部反馈

分析 <planning_dir>/reviews/ 中的建议。

由你决定整合哪些建议。也可以决定不整合任何建议。

步骤 1： 编写 <planning_dir>/claude-integration-notes.md，记录：

• 整合了哪些建议及原因
• 未整合哪些建议及原因

步骤 2： 将整合后的更改更新到 <planning_dir>/claude-plan.md。

12. 用户审核整合后的计划

使用 AskUserQuestion：

The plan has been updated with external feedback. You can now review and edit claude-plan.md.

If you want Claude's help editing the plan, open a separate Claude session - this session
is mid-workflow and can't assist with edits until the workflow completes.

When you're done reviewing, select "Done" to continue.

选项："审核完成"

等待用户确认后再继续。

13. 创建章节索引

参见 section-index.md

阅读 claude-plan.md。确定自然的章节边界，并创建 <planning_dir>/sections/index.md。

重要： index.md 必须以 SECTION_MANIFEST 块开头。格式要求请参见参考文档。

创建章节文件之前，先写入 index.md。

14. 编写章节文件 — 并行子 Agent

参见 section-splitting.md

启动并行子 Agent — 每个章节分配一个 Task，以提高效率：

1. 首先，解析 sections/index.md，获取 SECTION_MANIFEST 列表
2. 然后，在同一条消息中启动所有章节 Task（并行执行）：

# Launch all in ONE message for parallel execution:

Task(
  subagent_type="general-purpose",
  prompt="""
  Write section file: section-01-{name}

  Inputs:
  - <planning_dir>/claude-plan.md
  - <planning_dir>/sections/index.md

  Output: <planning_dir>/sections/section-01-{name}.md

  The section file must be COMPLETELY SELF-CONTAINED. Include:
  - Background (why this section exists)
  - Requirements (what must be true when complete)
  - Dependencies (requires/blocks)
  - Implementation details (from the plan)
  - Acceptance criteria (checkboxes)
  - Files to create/modify

  The implementer should NOT need to reference any other document.
  """
)

Task(
  subagent_type="general-purpose",
  prompt="Write section file: section-02-{name} ..."
)

Task(
  subagent_type="general-purpose",
  prompt="Write section file: section-03-{name} ..."
)

# ... one Task per section in the manifest

等待所有子 Agent 完成后再继续。

15. 生成执行文件 — 子 Agent

委派给子 Agent，以减少主上下文的令牌用量：

Task(
  subagent_type="general-purpose",
  prompt="""
  Generate two execution files for autonomous implementation.

  Input files:
  - <planning_dir>/sections/index.md (has SECTION_MANIFEST)
  - <planning_dir>/sections/section-*.md (all section files)

  OUTPUT 1: <planning_dir>/claude-ralph-loop-prompt.md
  For ralph-loop plugin. EMBED all section content inline.

  Structure:
  - Mission statement
  - Full content of sections/index.md
  - Full content of EACH section file (embedded, not referenced)
  - Execution rules (dependency order, verify acceptance criteria)
  - Completion signal: <promise>ALL-SECTIONS-COMPLETE</promise>

  OUTPUT 2: <planning_dir>/claude-ralphy-prd.md
  For Ralphy CLI. REFERENCE section files (don't embed).

  Structure:
  - PRD header
  - How to use (ralphy --prd command)
  - Context explanation
  - Checkbox task list: one "- [ ] Section NN: {name}" per section

  Write both files.
  """
)

等待子 Agent 完成后再继续。

16. 最终状态

验证所有文件均已成功创建：

• SECTION_MANIFEST 中的所有章节文件
• claude-ralph-loop-prompt.md
• claude-ralphy-prd.md

17. 输出摘要

列出生成的文件和后续步骤：

═══════════════════════════════════════════════════════════════
GEPETTO: Planning Complete
═══════════════════════════════════════════════════════════════

Generated files:
  - 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)

How to implement:

Option A - Manual (recommended for learning/control):
  1. Read sections/index.md to understand dependencies
  2. Implement each section file in order
  3. Each section is self-contained with acceptance criteria

Option B - Autonomous with ralph-loop (Claude Code plugin):
  /ralph-loop @<planning_dir>/claude-ralph-loop-prompt.md --completion-promise "COMPLETE" --max-iterations 100

Option C - Autonomous with Ralphy (external CLI):
  ralphy --prd <planning_dir>/claude-ralphy-prd.md
  # Or: cp <planning_dir>/claude-ralphy-prd.md ./PRD.md && ralphy
═══════════════════════════════════════════════════════════════