Gepetto
Turn a rough feature spec into a researched, interviewed, externally reviewed, sectionized implementation plan before any coding starts.
Overview
Gepetto is an agent skill most often used in Validate (also Build, Idea) that produces sectionized implementation plans via research, interviews, synthesis, external review, and structured sections.
Install
npx skills add https://github.com/softaworks/agent-toolkit --skill gepettoWhat is this skill?
- Six-phase orchestration: Research → Interview → Spec Synthesis → Plan → External Review → Sections
- Hard-gate: requires an @-referenced markdown spec path or stops with Spec File Required
- Writes many planning .md artifacts into the spec’s parent directory
- Multi-LLM external review step before sectionized output
- Intro banner prints before any other action for predictable agent behavior
- Six-step pipeline: Research → Interview → Spec Synthesis → Plan → External Review → Sections
Adoption & trust: 1.3k installs on skills.sh; 2k GitHub stars; 1/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have a feature idea in a spec file but no rigorous, reviewed implementation plan with clear sections for your agent or team to execute.
Who is it for?
Solo builders starting a non-trivial feature from a `.md` spec who want structured discovery, interviews, and external LLM review before coding.
Skip if: Quick one-file tweaks, tasks with an already approved sectional plan, or invocations without a markdown spec path—the skill stops by design.
When should I use this skill?
Planning features that need thorough pre-implementation analysis, with a markdown spec file provided at invocation.
What do I get? / Deliverables
You get a multi-step-reviewed, sectionized plan and supporting markdown artifacts in your planning directory, ready to drive implementation without restarting discovery.
- Sectionized implementation plan markdown
- Supporting research, interview, and review artifacts under the planning directory
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Gepetto sits where you still define what to build—after an idea exists but before implementation commitments harden. Scope validation needs stakeholder alignment, spec synthesis, and phased sections—the skill’s Research → Interview → Plan pipeline maps directly to scoping work.
Where it fits
Expand a vague product note into researched constraints before choosing stack or timeline.
Interview-style clarification and spec synthesis to lock scope from an initial FEATURE.md.
Emit sectional plans your coding agent can execute as ordered implementation chunks.
How it compares
Use instead of ad-hoc “write me a plan” prompts when you need on-disk artifacts, gated inputs, and a fixed Research→Sections pipeline.
Common Questions / FAQ
Who is gepetto for?
Indie builders and small teams who plan features in markdown and want an agent-driven planning ritual with research, interviews, and multi-LLM review.
When should I use gepetto?
In Validate when scoping a feature from a spec; in Build when breaking PM work into sectional plans; in Idea when researching requirements before you commit to architecture.
Is gepetto safe to install?
Check the Security Audits panel on this Prism page; external review steps may call other models—review what your agent toolkit sends and where planning files are written.
SKILL.md
READMESKILL.md - Gepetto
# 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: | 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 | 5. 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](references/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](references/research-protocol.md). Based on decisions from step 4, launch research subagents: - **Codebase research:** `Task(su