Creates detailed, sectionized implementation plans through research, stakeholder interviews, and multi-LLM review. Use when planning features that need thorough pre-implementation analysis.
npxskills add softaworks/agent-toolkit--skill gepettoLoading…
Orchestrates a multi-step planning process: Research → Interview → Spec Synthesis → Plan → External Review → Sections
BEFORE anything else, do these in order:
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
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.
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/ directoryDetermine 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 |
Print status:
Planning directory: {planning_dir}
Mode: {mode}
If resuming:
Resuming from step {N}
To start fresh, delete the planning directory files.
═══════════════════════════════════════════════════════════════
STEP {N}/17: {STEP_NAME}
═══════════════════════════════════════════════════════════════
{details}
Step {N} complete: {summary}
───────────────────────────────────────────────────────────────
See research-protocol.md.
See research-protocol.md.
Based on decisions from step 4, launch research subagents:
Task(subagent_type=Explore)Task(subagent_type=Explore) with WebSearchIf 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.
Run in main context (AskUserQuestion requires it). The interview should be informed by:
Write Q&A to <planning_dir>/claude-interview.md
Combine into <planning_dir>/claude-spec.md:
This synthesizes the user's raw requirements into a complete specification.
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.
Launch TWO subagents in parallel to review the plan:
Both receive the plan content and return their analysis. Write results to <planning_dir>/reviews/.
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:
Step 2: Update <planning_dir>/claude-plan.md with the integrated changes.
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.
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.
Launch parallel subagents - one Task per section for maximum efficiency:
sections/index.md to get the SECTION_MANIFEST list# 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.
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.
Verify all files were created successfully:
claude-ralph-loop-prompt.mdclaude-ralphy-prd.mdPrint 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
═══════════════════════════════════════════════════════════════
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).