gepetto

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gepetto

Orchestrates a multi-step planning process: Research → Interview → Spec Synthesis → Plan → External Review → Sections

编排多步骤规划流程：调研 → 访谈 → 规格合成 → 计划制定 → 外部评审 → 分章节输出

CRITICAL: First Actions

重要提示：初始操作

BEFORE anything else, do these in order:

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

1. Print Intro

1. 打印介绍横幅

Print intro banner immediately:

═══════════════════════════════════════════════════════════════
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

立即打印介绍横幅：

═══════════════════════════════════════════════════════════════
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. Validate Spec File Input

2. 验证规格文件输入

Check if user provided @file at invocation AND it's a spec file (ends with
.md
).

If NO @file was provided OR the path doesn't end with

.md

, output this and STOP:

═══════════════════════════════════════════════════════════════
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
═══════════════════════════════════════════════════════════════

Do not continue. Wait for user to re-invoke with a .md file path.

检查用户在调用时是否提供了@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. Setup Planning Session

3. 设置规划会话

Determine session state by checking existing files:

Set
```
planning_dir
```
= parent directory of the spec file
Set
```
initial_file
```
= the spec file path

Scan for existing planning files:

```
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/
```
directory
```
sections/
```
directory

Determine mode and resume point:

Files Found	Mode	Resume From
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

Create TODO list with TodoWrite based on current state

Print status:

Planning directory: {planning_dir}
Mode: {mode}

If resuming:

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

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

设置
```
planning_dir
```
= 规格文件的父目录
设置
```
initial_file
```
= 规格文件路径

扫描现有规划文件：

```
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
仅research	恢复	步骤6（访谈）
research + interview	恢复	步骤8（规格合成）
+ spec	恢复	步骤9（计划制定）
+ plan	恢复	步骤10（外部评审）
+ reviews	恢复	步骤11（整合反馈）
+ integration-notes	恢复	步骤12（用户评审）
+ sections/index.md	恢复	步骤14（编写章节文件）
所有章节完成	恢复	步骤15（生成执行文件）
+ claude-ralph-loop-prompt.md + claude-ralphy-prd.md	完成	已结束

根据当前状态，使用TodoWrite创建待办事项列表

打印状态信息：

Planning directory: {planning_dir}
Mode: {mode}

如果是恢复模式：

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

Logging Format

日志格式

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

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

Workflow

工作流程

4. Research Decision

4. 调研决策

See research-protocol.md.

Read the spec file
Extract potential research topics (technologies, patterns, integrations)
Ask user about codebase research needs
Ask user about web research needs (present derived topics as multi-select)
Record which research types to perform in step 5

参考 research-protocol.md。

读取规格文件
提取潜在调研主题（技术、模式、集成方案）
询问用户关于代码库调研的需求
询问用户关于网络调研的需求（将推导的主题以多选形式呈现）
记录步骤5中需要执行的调研类型

5. Execute Research

5. 执行调研

See research-protocol.md.

Based on decisions from step 4, launch research subagents:

Codebase research:
```
Task(subagent_type=Explore)
```
Web research:
```
Task(subagent_type=Explore)
```
with WebSearch

If both are needed, launch both Task tools in parallel (single message with multiple tool calls).

Important: Subagents return their findings - they do NOT write files directly. After collecting results from all subagents, combine them and write to

<planning_dir>/claude-research.md

Skip this step entirely if user chose no research in step 4.

参考 research-protocol.md。

根据步骤4的决策，启动调研子代理：

代码库调研：
```
Task(subagent_type=Explore)
```
网络调研：
```
Task(subagent_type=Explore)
```
并启用WebSearch

如果两者都需要，并行启动两个Task工具（在单条消息中包含多个工具调用）。

重要提示：子代理仅返回调研结果，不会直接写入文件。收集所有子代理的结果后，将其合并并写入

<planning_dir>/claude-research.md

。

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

6. Detailed Interview

6. 详细访谈

See interview-protocol.md

Run in main context (AskUserQuestion requires it). The interview should be informed by:

The initial spec
Research findings (if any)

参考 interview-protocol.md

在主上下文环境中运行（AskUserQuestion需要此环境）。访谈内容应基于：

初始规格文件
调研结果（如果有）

7. Save Interview Transcript

7. 保存访谈记录

Write Q&A to

<planning_dir>/claude-interview.md

将问答内容写入

<planning_dir>/claude-interview.md

8. Write Initial Spec (Spec Synthesis)

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

Combine into

<planning_dir>/claude-spec.md

Initial input (the spec file)
Research findings (if step 5 was done)
Interview answers (from step 6)

This synthesizes the user's raw requirements into a complete specification.

将以下内容合并到

<planning_dir>/claude-spec.md

：

初始输入（规格文件）
调研结果（如果执行了步骤5）
访谈答案（来自步骤6）

此步骤将用户的原始需求合成为完整的规格说明。

9. Generate Implementation Plan

9. 生成实施计划

Create detailed plan →

<planning_dir>/claude-plan.md

IMPORTANT: Write for an unfamiliar reader. The plan must be fully self-contained - an engineer or LLM with no prior context should understand what we're building, why, and how just from reading this document.

创建详细计划并写入

<planning_dir>/claude-plan.md

重要提示：计划需面向不了解背景的读者编写。计划必须完全自包含——即使是没有任何前置背景的工程师或LLM，仅通过阅读此文档也应理解我们要构建什么、为什么构建以及如何构建。

10. External Review

10. 外部评审

See external-review.md

Launch TWO subagents in parallel to review the plan:

Gemini via Bash
Codex via Bash

Both receive the plan content and return their analysis. Write results to

<planning_dir>/reviews/

参考 external-review.md

并行启动两个子代理对计划进行评审：

Gemini 通过Bash调用
Codex 通过Bash调用

两者都会接收计划内容并返回分析结果。将结果写入

<planning_dir>/reviews/

目录。

11. Integrate External Feedback

11. 整合外部反馈

Analyze the suggestions in

<planning_dir>/reviews/

You are the authority on what to integrate or not. It's OK if you decide to not integrate anything.

Step 1: Write

<planning_dir>/claude-integration-notes.md

documenting:

What suggestions you're integrating and why
What suggestions you're NOT integrating and why

Step 2: Update

<planning_dir>/claude-plan.md

with the integrated changes.

分析

<planning_dir>/reviews/

中的建议。

你拥有是否整合建议的决定权，完全可以选择不整合任何建议。

步骤1：编写

<planning_dir>/claude-integration-notes.md

，记录：

决定整合哪些建议及原因
决定不整合哪些建议及原因

步骤2：根据整合的修改更新

<planning_dir>/claude-plan.md

。

12. User Review of Integrated Plan

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

Use 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.

Options: "Done reviewing"

Wait for user confirmation before proceeding.

使用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.

选项："Done reviewing"

等待用户确认后再继续操作。

13. Create Section Index

13. 创建章节索引

See section-index.md

Read

claude-plan.md

. Identify natural section boundaries and create

<planning_dir>/sections/index.md

CRITICAL: index.md MUST start with a SECTION_MANIFEST block. See the reference for format requirements.

Write

index.md

before proceeding to section file creation.

参考 section-index.md

读取

claude-plan.md

，识别自然章节边界并创建

<planning_dir>/sections/index.md

。

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

在开始创建章节文件前，先完成index.md的编写。

14. Write Section Files — Parallel Subagents

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

See section-splitting.md

Launch parallel subagents - one Task per section for maximum efficiency:

First, parse
```
sections/index.md
```
to get the SECTION_MANIFEST list
Then launch ALL section Tasks in a single message (parallel execution):

undefined

参考 section-splitting.md

启动并行子代理 - 为每个章节分配一个Task以最大化效率：

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

undefined

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} ..." )

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


Wait for ALL subagents to complete before proceeding.


等待所有子代理完成后再继续操作。

15. Generate Execution Files — Subagent

15. 生成执行文件 — 子代理

Delegate to subagent to reduce main context token usage:

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.
  """
)

Wait for subagent completion before proceeding.

委托给子代理 以减少主上下文的token使用量：

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.
  """
)

等待子代理完成后再继续操作。

16. Final Status

16. 最终状态验证

Verify all files were created successfully:

All section files from SECTION_MANIFEST
```
claude-ralph-loop-prompt.md
```
```
claude-ralphy-prd.md
```

验证所有文件是否成功创建：

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

17. Output Summary

17. 输出总结

Print generated files and next steps:

═══════════════════════════════════════════════════════════════
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
═══════════════════════════════════════════════════════════════

打印生成的文件和后续步骤：

═══════════════════════════════════════════════════════════════
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
═══════════════════════════════════════════════════════════════