/gepetto

🪵 Like Geppetto carved Pinocchio from rough wood, transform vague ideas into living implementation plans

Just as the master craftsman took rough timber and carved it into a puppet that came to life, Gepetto transforms your rough feature sketches into detailed, battle-tested specifications that spring into action.

Gepetto carves vague ideas into comprehensive, sectionized implementation plans through structured research, stakeholder interviews, and multi-LLM review.

The Craft

Geppetto doesn't rush. Neither should your specs.

• Rough Wood (Your initial spec) → Research & refinement
• Careful Carving (Interview & synthesis) → Shape emerges
• Fine Details (External review) → Master craftsmen review your work
• Final Polish (Sections) → Ready for life
• Brings to Life (Ralph-loop) → Your creation walks and talks

The Problem

You: "Claude, build me an auth system"
Claude: *starts coding immediately*
Result: Back-and-forth iterations, missed edge cases, scope creep

The Solution

You: "/gepetto @planning/auth-spec.md"
gepetto: Research → Interview → Spec → Plan → External Review → Sections
Result: Clear implementation roadmap, reviewed by multiple LLMs, ready for execution

Table of Contents

• Installation
• Workflow
• Quick Start
• When to Use
• Output Files
• External Review
• Resuming
• Best Practices
• Implementing the Plan
• Integration with ralph-loop (Optional)
• Integration with Ralphy (Optional)
• File Structure

Installation

Claude Code only - This skill is designed specifically for Claude Code.

Recommended: Plugin Installation

Step 1: Add the marketplace (first time only)

/plugin marketplace add softaworks/agent-skills

Step 2: Install gepetto

/plugin install gepetto

Alternative: Manual Installation

npx add-skill softaworks/gepetto
# or
cp -r skills/gepetto ~/.claude/skills/

For claude.ai

While not the primary use case, you can add the skill to project knowledge or paste SKILL.md contents into the conversation for basic guidance.

---

Workflow

┌─────────────────────────────────────────────────────────────────┐
│                      gepetto pipeline                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   /gepetto @spec.md                                             │
│          │                                                      │
│          ▼                                                      │
│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐    │
│   │   Research   │ ──▶ │  Interview   │ ──▶ │     Spec     │    │
│   │  (optional)  │     │  (5-10 Q&A)  │     │  Synthesis   │    │
│   └──────────────┘     └──────────────┘     └──────────────┘    │
│                                                   │             │
│                                                   ▼             │
│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐    │
│   │   Section    │ ◀── │   Integrate  │ ◀── │   External   │    │
│   │  Splitting   │     │   Feedback   │     │  LLM Review  │    │
│   └──────────────┘     └──────────────┘     └──────────────┘    │
│          │                                                      │
│          ▼                                                      │
│   ┌──────────────────────────────────────────────────────────┐  │
│   │  sections/section-01-*.md  sections/section-02-*.md ...  │  │
│   │  (Self-contained, parallel-ready implementation units)   │  │
│   └──────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Start

1. Create a spec file

mkdir -p planning
cat > planning/auth-spec.md << 'EOF'
# Authentication System

Need OAuth2 login with Google and GitHub.
Sessions stored in Redis, JWT for API auth.
EOF

Your spec can be detailed or just bullet points - the interview phase extracts the details.

2. Run gepetto

/gepetto @planning/auth-spec.md

3. Follow the prompts

Answer research and interview questions. Review the generated plan. Done.

When to Use

Use gepetto when:

• Requirements are fuzzy and need clarification
• The feature is complex enough to benefit from external review
• You want implementation sections that can be worked on in parallel
• You prefer thinking before coding

Skip gepetto when:

• Simple bug fixes or one-file changes
• Requirements are already crystal clear
• You just want to start coding

Output Files

After running gepetto, your planning directory contains:

planning/
├── your-spec.md                 # Your original input
├── claude-research.md           # Web + codebase research findings
├── claude-interview.md          # Q&A transcript
├── claude-spec.md               # Synthesized specification
├── claude-plan.md               # Implementation plan
├── claude-integration-notes.md  # Review feedback decisions
├── claude-ralph-loop-prompt.md  # Ready-to-run ralph-loop prompt
├── claude-ralphy-prd.md         # Ready-to-run Ralphy PRD
├── reviews/
│   ├── gemini-review.md         # Gemini's feedback
│   └── codex-review.md          # Codex's feedback
└── sections/
    ├── index.md                 # Section manifest & dependencies
    ├── section-01-*.md          # Implementation unit 1
    ├── section-02-*.md          # Implementation unit 2
    └── ...

Key Files

External Review

gepetto uses Gemini CLI and Codex CLI to get independent reviews of your plan.

Requirements

Install at least one:

# Gemini CLI (Google)
# See: https://github.com/google-gemini/gemini-cli

# Codex CLI (OpenAI)
# See: https://github.com/openai/codex

What Reviewers Check

Both LLMs analyze your plan for:

• Potential footguns and edge cases
• Missing considerations
• Security vulnerabilities
• Performance issues
• Architectural problems
• Unclear requirements

No CLI Installed?

If neither CLI is available, gepetto will skip the external review step and continue with the workflow.

Resuming

If the workflow is interrupted (context limit, need a break), just re-run with the same spec:

/gepetto @planning/auth-spec.md

gepetto detects existing files and resumes from where it left off.

Resume Points

Best Practices

1. Start with something - Even a few bullet points. The interview phase extracts details.

2. Answer thoroughly - The interview is where hidden requirements surface. Don't rush it.

3. Review critically - External LLMs catch blind spots but may over-engineer. You decide what to integrate.

4. Use sections - Each section file is self-contained. Work on them in parallel or hand them off.

5. Iterate - If the plan isn't right, edit claude-plan.md and re-run section generation.

Implementing the Plan

After gepetto completes, you have self-contained section files ready for implementation. Choose your approach:

Option A: Manual Implementation (Recommended)

Best for: learning the codebase, maintaining control, reviewing as you go.

# 1. Check the dependency order
cat planning/sections/index.md

# 2. Open first section
cat planning/sections/section-01-foundation.md

# 3. Implement following the acceptance criteria

# 4. Move to next section, repeat

Each section file contains:

• Background context
• Requirements
• Implementation details
• Acceptance criteria (checklist)
• Files to create/modify

You can implement sections yourself, delegate to another Claude session, or hand off to a team member.

Option B: Autonomous with ralph-loop (Claude Code Plugin)

Best for: hands-off execution within Claude Code, large plans, overnight runs.

/ralph-loop @planning/claude-ralph-loop-prompt.md --completion-promise "COMPLETE" --max-iterations 100

See Integration with ralph-loop for details.

Option C: Autonomous with Ralphy (External CLI)

Best for: multi-engine support (Claude, Codex, Cursor, etc.), parallel execution, branch-per-task workflows.

ralphy --prd planning/claude-ralphy-prd.md

See Integration with Ralphy for details.

---

Integration with ralph-loop (Optional)

gepetto generates claude-ralph-loop-prompt.md for optional integration with ralph-loop.

What is ralph-loop?

Ralph Loop is an iterative execution technique that keeps Claude working on a task until completion. It uses a Stop hook to create a self-referential feedback loop - Claude works, checks progress, and continues until the completion criteria are met.

One-Command Execution

After gepetto completes, it generates claude-ralph-loop-prompt.md with all section content embedded. Execute the entire plan with:

/ralph-loop @planning/claude-ralph-loop-prompt.md --completion-promise "COMPLETE" --max-iterations 100

That's it. Walk away and come back to working code.

The Workflow

┌─────────────────────────────────────────────────────────────────┐
│                    gepetto + ralph-loop                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   1. /gepetto @planning/feature.md                              │
│      └── Generates sections + claude-ralph-loop-prompt.md       │
│                                                                 │
│   2. (Optional) Review sections/index.md for dependencies       │
│                                                                 │
│   3. /ralph-loop @planning/claude-ralph-loop-prompt.md \        │
│        --completion-promise "COMPLETE" --max-iterations 100     │
│                                                                 │
│   4. Walk away. Come back to working code.                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

What the Prompt Does

The generated claude-ralph-loop-prompt.md instructs ralph-loop to:

1. Parse the section index for dependencies
2. Execute each section in the correct order
3. Verify acceptance criteria for each section
4. Track progress in PROGRESS.md
5. Continue until all sections are done (or hit max iterations)

Executing Individual Sections

If you prefer to execute sections one at a time:

# Execute section 01 (usually foundation/setup)
/ralph-loop "Implement the following section. Follow all requirements exactly.

$(cat planning/sections/section-01-foundation.md)

When ALL acceptance criteria are met and tests pass:
- Output <promise>SECTION-01-COMPLETE</promise>

If blocked after 10 iterations, document blockers and output <promise>SECTION-01-BLOCKED</promise>" --completion-promise "SECTION-01" --max-iterations 30

Tips

1. Set max-iterations - Always use --max-iterations as a safety net (50-100 is reasonable for full execution)
2. Review PROGRESS.md - Check progress during long executions
3. Respect dependencies - If executing manually, check sections/index.md for the dependency graph

Installing ralph-loop

# Via Claude Code plugin marketplace
/plugin marketplace add anthropics/claude-plugins-official
/plugin install ralph-loop
/plugin enable ralph-loop

---

Integration with Ralphy (Optional)

gepetto generates claude-ralphy-prd.md for optional integration with Ralphy, an autonomous AI coding loop that works with multiple AI engines.

What is Ralphy?

Ralphy is an external CLI tool that iterates through a task list (PRD.md) and executes each task using an AI CLI of your choice. Unlike ralph-loop (which runs inside Claude Code), Ralphy runs externally and supports multiple AI engines.

Key Differences: ralph-loop vs Ralphy

One-Command Execution

# Using the generated PRD directly
ralphy --prd planning/claude-ralphy-prd.md

# Or copy to project root
cp planning/claude-ralphy-prd.md ./PRD.md
ralphy

How It Works

1. Ralphy reads claude-ralphy-prd.md and finds checkbox tasks
2. For each unchecked task, it builds a prompt with project context
3. The AI (Claude by default) reads the referenced section file for detailed requirements
4. AI implements the task, runs tests, commits
5. Ralphy marks the task complete (- [ ] → - [x])
6. Repeat until all tasks done

The Generated PRD Format

# Implementation PRD

## Tasks

- [ ] Section 01: Foundation - Read sections/section-01-foundation.md for details
- [ ] Section 02: Core libs - Read sections/section-02-core-libs.md for details
- [ ] Section 03: API layer - Read sections/section-03-api-layer.md for details

Each task references the detailed section file, so the AI gets all the context Gepetto prepared.

Advanced Usage

# Use different AI engine
ralphy --prd planning/claude-ralphy-prd.md --codex
ralphy --prd planning/claude-ralphy-prd.md --cursor

# Parallel execution (3 agents by default)
ralphy --prd planning/claude-ralphy-prd.md --parallel

# Branch per task with auto PR
ralphy --prd planning/claude-ralphy-prd.md --branch-per-task --create-pr

# Skip tests for faster iteration
ralphy --prd planning/claude-ralphy-prd.md --fast

Learn More

See the Ralphy repository for installation, configuration, and advanced features.

File Structure

~/.claude/skills/gepetto/
├── SKILL.md                    # Main skill definition
├── README.md                   # This file
└── references/
    ├── research-protocol.md    # How research works
    ├── interview-protocol.md   # Interview guidelines
    ├── external-review.md      # CLI review setup
    ├── section-index.md        # Index creation rules
    └── section-splitting.md    # Section file format

Differences from Similar Tools

---

Crafted by: Leonardo Flores License: MIT Repository: https://github.com/softaworks/gepetto

"When you wish upon a spec..." ⭐🪵