back
loading skill details...
gepetto — an installable skill for AI agents, published by softaworks/agent-toolkit.
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:
Set planning_dir = parent directory of the spec file
Set initial_file = the spec file path
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
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.md to 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 manifest
Wait 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.md
claude-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
═══════════════════════════════════════════════════════════════don't have the plugin yet? install it then click "run inline in claude" again.