gepetto
Skill237 starsChanged 3 months agoApache-2.0View on GitHub
Creates detailed, sectionized implementation plans through research, stakeholder interviews, and multi-LLM review. Use when planning features that need thorough pre-implementation analysis.
6 other projects use a version of this, 3 of them edited.
Adopted by
Most recently taken up by
- Ivan-propio/claude-skillsword for word, first seen Nov 16, 2026
- imMamdouhaboammar/kaku-chatgpt-harnessword for word, first seen Oct 25, 2026
- rohinipachanta/claude-code-quickstartedited, first seen Oct 13, 2026
- Samueladewole/claude-skillsedited, first seen Oct 13, 2026
- meshery/mesheryword for word, first seen Oct 8, 2026
- nbirkner/digital-brainedited, first seen Apr 12, 2026
Other versions6 projects use a version of this.
Word for word · 3
- meshery/meshery★ 12k100% same
- imMamdouhaboammar/kaku-chatgpt-harness★ 0100% same
- Ivan-propio/claude-skills★ 0100% same
Edited · 3
- rohinipachanta/claude-code-quickstart★ 118% same
- nbirkner/digital-brain★ 096% same
- Samueladewole/claude-skills★ 068% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository15 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- chrome-devtools-axiSkill
- gh-axiSkill
- iterate-prSkill
- lavishSkill
- quota-axiSkill
- agent-md-refactorSkill
- command-creatorSkill
- cut-releaseSkill
- database-schema-designerSkill
- find-skillsSkill
- iterate-prSkill
- qa-test-plannerSkill
- reducing-entropySkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
19 rules. 9 are common, 2 are distinctive, and 8 are very specific to this project.
9
Common
Most of the 3 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 30
If NO @file was provided OR the path doesn't end with .md, output this and STOP:
- Common: line 85
Create TODO list with TodoWrite based on current state
- Common: line 120
Read the spec file
- Common: line 122
Ask user about codebase research needs
- Common: line 123
Ask user about web research needs (present derived topics as multi-select)
- Common: line 134
If both are needed, launch both Task tools in parallel (single message with multiple tool calls).
- Common: line 144
Run in main context (AskUserQuestion requires it).
- Very specific: line 150
Write Q&A to <planning_dir>/claude-interview.md
- Very specific: line 163
Create detailed plan → <planning_dir>/claude-plan.md
- Common: line 165
IMPORTANT: Write for an unfamiliar reader.
- Very specific: line 183
Step 1: Write <planning_dir>/claude-integration-notes.md documenting:
- Very specific: line 187
Step 2: Update <planning_dir>/claude-plan.md with the integrated changes.
- Common: line 203
Wait for user confirmation before proceeding.
- Very specific: line 209
Read claude-plan.md. Identify natural section boundaries and create <planning_dir>/sections/index.md.
- Very specific: line 213
Write index.md before proceeding to section file creation.
- Distinctive: line 263
Wait for ALL subagents to complete before proceeding.
- Distinctive: line 303
Wait for subagent completion before proceeding.
- Common: line 307
Verify all files were created successfully:
- Very specific: line 308
All section files from SECTION_MANIFEST
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 it2. 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:
- Set
planning_dir= parent directory of the spec file - Set
initial_file= the spec file path - Scan for existing planning files:
claude-research.mdclaude-interview.mdclaude-spec.mdclaude-plan.mdclaude-integration-notes.mdclaude-ralph-loop-prompt.mdclaude-ralphy-prd.mdreviews/directorysections/directory
- 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 |
- 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.
- Read the spec file
- Extract potential research topics (technologies, patterns, integrations)
- Ask user about codebase research needs
- Ask user about web research needs (present derived topics as multi-select)
- 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 engineer or LLM with no prior context should understand what we're building, why, and how just from reading this document.
10. External Review
See external-review.md
Launch TWO subagents in parallel to review the plan:
- Gemini via Bash
- Codex via Bash
Both receive the plan content and return their analysis. Write results to <planning_dir>/reviews/.
11. Integrate External Feedback
Analyze the suggestions in <planning_dir>/reviews/.
You are the authority on what to integrate or not. It's OK if you decide to not integrate anything.
Step 1: Write <planning_dir>/claude-integration-notes.md documenting:
- What suggestions you're integrating and why
- What suggestions you're NOT integrating and why
Step 2: Update <planning_dir>/claude-plan.md with the integrated changes.
12. User Review of Integrated Plan
Use AskUserQuestion:
The plan has been updated with external feedback. You can now review and edit claude-plan.md.
If you want Claude's help editing the plan, open a separate Claude session - this session
is mid-workflow and can't assist with edits until the workflow completes.
When you're done reviewing, select "Done" to continue.Options: "Done reviewing"
Wait for user confirmation before proceeding.
13. Create Section Index
See section-index.md
Read claude-plan.md. Identify natural section boundaries and create <planning_dir>/sections/index.md.
CRITICAL: index.md MUST start with a SECTION_MANIFEST block. See the reference for format requirements.
Write index.md before proceeding to section file creation.
14. Write Section Files — Parallel Subagents
See section-splitting.md
Launch parallel subagents - one Task per section for maximum efficiency:
- First, parse
sections/index.mdto get the SECTION_MANIFEST list - Then launch ALL section Tasks in a single message (parallel execution):
# Launch all in ONE message for parallel execution:
Task(
subagent_type="general-purpose",
prompt="""
Write section file: section-01-{name}
Inputs:
- <planning_dir>/claude-plan.md
- <planning_dir>/sections/index.md
Output: <planning_dir>/sections/section-01-{name}.md
The section file must be COMPLETELY SELF-CONTAINED. Include:
- Background (why this section exists)
- Requirements (what must be true when complete)
- Dependencies (requires/blocks)
- Implementation details (from the plan)
- Acceptance criteria (checkboxes)
- Files to create/modify
The implementer should NOT need to reference any other document.
"""
)
Task(
subagent_type="general-purpose",
prompt="Write section file: section-02-{name} ..."
)
Task(
subagent_type="general-purpose",
prompt="Write section file: section-03-{name} ..."
)
# ... one Task per section in the manifestWait for ALL subagents to complete before proceeding.
15. Generate Execution Files — Subagent
Delegate to subagent to reduce main context token usage:
Task(
subagent_type="general-purpose",
prompt="""
Generate two execution files for autonomous implementation.
Input files:
- <planning_dir>/sections/index.md (has SECTION_MANIFEST)
- <planning_dir>/sections/section-*.md (all section files)
OUTPUT 1: <planning_dir>/claude-ralph-loop-prompt.md
For ralph-loop plugin. EMBED all section content inline.
Structure:
- Mission statement
- Full content of sections/index.md
- Full content of EACH section file (embedded, not referenced)
- Execution rules (dependency order, verify acceptance criteria)
- Completion signal: <promise>ALL-SECTIONS-COMPLETE</promise>
OUTPUT 2: <planning_dir>/claude-ralphy-prd.md
For Ralphy CLI. REFERENCE section files (don't embed).
Structure:
- PRD header
- How to use (ralphy --prd command)
- Context explanation
- Checkbox task list: one "- [ ] Section NN: {name}" per section
Write both files.
"""
)Wait for subagent completion before proceeding.
16. Final Status
Verify all files were created successfully:
- All section files from SECTION_MANIFEST
claude-ralph-loop-prompt.mdclaude-ralphy-prd.md
17. Output Summary
Print generated files and next steps:
═══════════════════════════════════════════════════════════════
GEPETTO: Planning Complete
═══════════════════════════════════════════════════════════════
Generated files:
- claude-research.md (research findings)
- claude-interview.md (Q&A transcript)
- claude-spec.md (synthesized specification)
- claude-plan.md (implementation plan)
- claude-integration-notes.md (feedback decisions)
- reviews/ (external LLM feedback)
- sections/ (implementation units)
- claude-ralph-loop-prompt.md (for ralph-loop plugin)
- claude-ralphy-prd.md (for Ralphy CLI)
How to implement:
Option A - Manual (recommended for learning/control):
1. Read sections/index.md to understand dependencies
2. Implement each section file in order
3. Each section is self-contained with acceptance criteria
Option B - Autonomous with ralph-loop (Claude Code plugin):
/ralph-loop @<planning_dir>/claude-ralph-loop-prompt.md --completion-promise "COMPLETE" --max-iterations 100
Option C - Autonomous with Ralphy (external CLI):
ralphy --prd <planning_dir>/claude-ralphy-prd.md
# Or: cp <planning_dir>/claude-ralphy-prd.md ./PRD.md && ralphy
═══════════════════════════════════════════════════════════════Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

