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. Web リサーチが必要かどうかをユーザーに確認します（導出されたトピックを複数選択形式で提示します）
5. 実行するリサーチの種類を、ステップ5で記録します

5. リサーチの実行

research-protocol.md を参照してください。

ステップ4の判断に基づいて、リサーチ用のサブエージェントを起動します：

• コードベースのリサーチ： Task(subagent_type=Explore)
• Web リサーチ： WebSearch を使用する Task(subagent_type=Explore)

両方が必要な場合は、両方の Task ツールを並列で起動します（複数のツール呼び出しを含む単一のメッセージで実行）。

重要： サブエージェントは調査結果を返すだけで、ファイルを直接書き込みません。すべてのサブエージェントから結果を収集した後、それらを統合して <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

重要：初めて読む読者を想定して記述してください。計画は完全に自己完結している必要があります。事前の文脈がないエンジニアや LLM でも、この文書を読むだけで 何を 構築するのか、なぜ なのか、どのように 行うのかを理解できなければなりません。

10. 外部レビュー

external-review.md を参照してください

計画をレビューするために、2つのサブエージェントを並列で起動します：

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.

選択肢: "Done reviewing"

次に進む前に、ユーザーの確認を待ってください。

13. セクションインデックスの作成

section-index.md を参照してください。

claude-plan.md を読み込み、自然なセクションの区切りを特定して <planning_dir>/sections/index.md を作成してください。

重要: index.md は必ず SECTION_MANIFEST ブロックで始めてください。形式の要件はリファレンスを参照してください。

セクションファイルの作成に進む前に、index.md を書き出してください。

14. セクションファイルの作成 — 並列サブエージェント

section-splitting.md を参照してください。

並列サブエージェントを起動します — 最大限の効率を得るため、セクションごとに 1 つの Task を割り当てます:

1. まず sections/index.md を解析し、SECTION_MANIFEST のリストを取得してください。
2. 次に、すべてのセクションの Task を 1 つのメッセージでまとめて起動してください(並列実行):

# 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

すべてのサブエージェントが完了するまで待ってから次に進んでください。

15. 実行ファイルの生成 — サブエージェント

メインのコンテキストのトークン使用量を抑えるため、サブエージェントに委譲します:

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. 最終ステータス

すべてのファイルが正常に作成されたことを確認してください:

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