/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
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
deepeshBodh
piercelamb
jsegov
rhuss
jasonkneen
tzachbon