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

gepetto

NPX Install

SKILL.md Content