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:
- 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
- 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.
- 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
Skip this step entirely if user chose no research in step 4.
- 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
- Write Initial Spec (Spec Synthesis)
Combine into
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.
- Generate Implementation Plan
Create detailed plan →
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.
- 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
- Integrate External Feedback
Analyze the suggestions in
You are the authority on what to integrate or not. It's OK if you decide to not integrate anything.
Step 1: Write
What suggestions you're integrating and why What suggestions you're NOT integrating and why
Step 2: Update
- 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.
- Create Section Index
See section-index.md
Read claude-plan.md. Identify natural section boundaries and create
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.
- 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:
-
Output:
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.
- 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:
-
OUTPUT 1:
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:
OUTPUT 2:
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.
- 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 @
Option C - Autonomous with Ralphy (external CLI):
ralphy --prd