Gepetto Agent Skill

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

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

2. Validate Spec File Input

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.

3. Setup Planning Session

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.

Logging Format

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

Workflow

4. Research Decision

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

5. Execute Research

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.

6. Detailed Interview

See interview-protocol.md

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

• The initial spec
• Research findings (if any)

7. Save Interview Transcript

Write Q&A to <planning_dir>/claude-interview.md

8. Write Initial Spec (Spec Synthesis)

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.

9. Generate Implementation Plan

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.

10. External Review

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

11. Integrate External Feedback

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.

12. User Review of Integrated Plan

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.

13. Create Section Index

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.

14. Write Section Files — Parallel Subagents

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

# 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

Wait for ALL subagents to complete before proceeding.

15. Generate Execution Files — Subagent

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.

16. Final Status

Verify all files were created successfully:

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

17. Output Summary

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