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 の決定に基づいて、研究サブエージェントを起動:

• コードベース調査: Task(subagent_type=Explore)
• ウェブ調査: Task(subagent_type=Explore) with WebSearch

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

重要: サブエージェントは調査結果を返します。直接ファイルを書き込みません。すべてのサブエージェントから結果を収集したら、それらを組み合わせて <planning_dir>/claude-research.md に書き込みます。

ステップ 4 でユーザーが調査を選択しなかった場合は、このステップ全体をスキップします。

6. 詳細なインタビュー

interview-protocol.md を参照

メインコンテキストで実行 (AskUserQuestion が必要)。インタビューは以下の情報に基づく必要があります:

• 初期仕様
• 研究結果 (ステップ 5 が実行された場合)

7. インタビュートランスクリプトを保存

Q&A を <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. Gemini via Bash
2. Codex via Bash

両方がプラン内容を受け取り、分析を返します。結果を <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 つのタスク:

1. まず、sections/index.md を解析して SECTION_MANIFEST リストを取得
2. その後、すべてのセクション タスクを 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
═══════════════════════════════════════════════════════════════