/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

| File | Purpose | |------|---------| | claude-plan.md | The main deliverable - complete implementation plan | | sections/*.md | Self-contained units ready for implementation | | reviews/*.md | External perspectives on your plan | | claude-ralph-loop-prompt.md | One-command execution with ralph-loop (Claude Code plugin) | | claude-ralphy-prd.md | One-command execution with Ralphy (external CLI) |

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

| Files Found | Resumes At | |-------------|------------| | claude-research.md | Interview | | + claude-interview.md | Spec synthesis | | + claude-spec.md | Plan generation | | + claude-plan.md | External review | | + reviews/ | Feedback integration | | + sections/index.md | Section writing | | + all sections | Execution files generation | | + claude-ralph-loop-prompt.md + claude-ralphy-prd.md | Done |

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 a