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:

1. Set planning_dir = parent directory of the spec file

2. Set initial_file = the spec file path

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

4. Determine mode and resume point:

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

1. Read the spec file
2. Extract potential research topics (technologies, patterns, integrations)
3. Ask user about codebase research needs
4. Ask user about web research needs (present derived topics as multi-select)
5. 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 eng

...