{"id":"b3acdd22-0125-43f4-aabd-19d53f5108a3","shortId":"Qzw3FZ","kind":"skill","title":"gepetto","tagline":"Creates detailed, sectionized implementation plans through research, stakeholder interviews, and multi-LLM review. Use when planning features that need thorough pre-implementation analysis.","description":"# Gepetto\n\nOrchestrates a multi-step planning process: Research → Interview → Spec Synthesis → Plan → External Review → Sections\n\n## CRITICAL: First Actions\n\n**BEFORE anything else**, do these in order:\n\n### 1. Print Intro\n\nPrint intro banner immediately:\n```\n═══════════════════════════════════════════════════════════════\nGEPETTO: AI-Assisted Implementation Planning\n═══════════════════════════════════════════════════════════════\nResearch → Interview → Spec Synthesis → Plan → External Review → Sections\n\nNote: GEPETTO will write many .md files to the planning directory you pass it\n```\n\n### 2. Validate Spec File Input\n\n**Check if user provided @file at invocation AND it's a spec file (ends with `.md`).**\n\nIf NO @file was provided OR the path doesn't end with `.md`, output this and STOP:\n```\n═══════════════════════════════════════════════════════════════\nGEPETTO: Spec File Required\n═══════════════════════════════════════════════════════════════\n\nThis skill requires a markdown spec file path (must end with .md).\nThe planning directory is inferred from the spec file's parent directory.\n\nTo start a NEW plan:\n  1. Create a markdown spec file describing what you want to build\n  2. It can be as detailed or as vague as you like\n  3. Place it in a directory where gepetto can save planning files\n  4. Run: /gepetto @path/to/your-spec.md\n\nTo RESUME an existing plan:\n  1. Run: /gepetto @path/to/your-spec.md\n\nExample: /gepetto @planning/my-feature-spec.md\n═══════════════════════════════════════════════════════════════\n```\n**Do not continue. Wait for user to re-invoke with a .md file path.**\n\n### 3. Setup Planning Session\n\nDetermine session state by checking existing files:\n\n1. Set `planning_dir` = parent directory of the spec file\n2. Set `initial_file` = the spec file path\n3. Scan for existing planning files:\n   - `claude-research.md`\n   - `claude-interview.md`\n   - `claude-spec.md`\n   - `claude-plan.md`\n   - `claude-integration-notes.md`\n   - `claude-ralph-loop-prompt.md`\n   - `claude-ralphy-prd.md`\n   - `reviews/` directory\n   - `sections/` directory\n\n4. Determine mode and resume point:\n\n| Files Found | Mode | Resume From |\n|-------------|------|-------------|\n| None | new | Step 4 |\n| research only | resume | Step 6 (interview) |\n| research + interview | resume | Step 8 (spec synthesis) |\n| + spec | resume | Step 9 (plan) |\n| + plan | resume | Step 10 (external review) |\n| + reviews | resume | Step 11 (integrate) |\n| + integration-notes | resume | Step 12 (user review) |\n| + sections/index.md | resume | Step 14 (write sections) |\n| all sections complete | resume | Step 15 (execution files) |\n| + claude-ralph-loop-prompt.md + claude-ralphy-prd.md | complete | Done |\n\n5. Create TODO list with TodoWrite based on current state\n\nPrint status:\n```\nPlanning directory: {planning_dir}\nMode: {mode}\n```\n\nIf resuming:\n```\nResuming from step {N}\nTo start fresh, delete the planning directory files.\n```\n\n---\n\n## Logging Format\n\n```\n═══════════════════════════════════════════════════════════════\nSTEP {N}/17: {STEP_NAME}\n═══════════════════════════════════════════════════════════════\n{details}\nStep {N} complete: {summary}\n───────────────────────────────────────────────────────────────\n```\n\n---\n\n## Workflow\n\n### 4. Research Decision\n\nSee [research-protocol.md](references/research-protocol.md).\n\n1. Read the spec file\n2. Extract potential research topics (technologies, patterns, integrations)\n3. Ask user about codebase research needs\n4. Ask user about web research needs (present derived topics as multi-select)\n5. Record which research types to perform in step 5\n\n### 5. Execute Research\n\nSee [research-protocol.md](references/research-protocol.md).\n\nBased on decisions from step 4, launch research subagents:\n- **Codebase research:** `Task(subagent_type=Explore)`\n- **Web research:** `Task(subagent_type=Explore)` with WebSearch\n\nIf both are needed, launch both Task tools in parallel (single message with multiple tool calls).\n\n**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`.\n\nSkip this step entirely if user chose no research in step 4.\n\n### 6. Detailed Interview\n\nSee [interview-protocol.md](references/interview-protocol.md)\n\nRun in main context (AskUserQuestion requires it). The interview should be informed by:\n- The initial spec\n- Research findings (if any)\n\n### 7. Save Interview Transcript\n\nWrite Q&A to `<planning_dir>/claude-interview.md`\n\n### 8. Write Initial Spec (Spec Synthesis)\n\nCombine into `<planning_dir>/claude-spec.md`:\n- **Initial input** (the spec file)\n- **Research findings** (if step 5 was done)\n- **Interview answers** (from step 6)\n\nThis synthesizes the user's raw requirements into a complete specification.\n\n### 9. Generate Implementation Plan\n\nCreate detailed plan → `<planning_dir>/claude-plan.md`\n\n**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.\n\n### 10. External Review\n\nSee [external-review.md](references/external-review.md)\n\nLaunch TWO subagents in parallel to review the plan:\n1. **Gemini** via Bash\n2. **Codex** via Bash\n\nBoth receive the plan content and return their analysis. Write results to `<planning_dir>/reviews/`.\n\n### 11. Integrate External Feedback\n\nAnalyze the suggestions in `<planning_dir>/reviews/`.\n\nYou are the authority on what to integrate or not. It's OK if you decide to not integrate anything.\n\n**Step 1:** Write `<planning_dir>/claude-integration-notes.md` documenting:\n- What suggestions you're integrating and why\n- What suggestions you're NOT integrating and why\n\n**Step 2:** Update `<planning_dir>/claude-plan.md` with the integrated changes.\n\n### 12. User Review of Integrated Plan\n\nUse AskUserQuestion:\n```\nThe plan has been updated with external feedback. You can now review and edit claude-plan.md.\n\nIf you want Claude's help editing the plan, open a separate Claude session - this session\nis mid-workflow and can't assist with edits until the workflow completes.\n\nWhen you're done reviewing, select \"Done\" to continue.\n```\n\nOptions: \"Done reviewing\"\n\nWait for user confirmation before proceeding.\n\n### 13. Create Section Index\n\nSee [section-index.md](references/section-index.md)\n\nRead `claude-plan.md`. Identify natural section boundaries and create `<planning_dir>/sections/index.md`.\n\n**CRITICAL:** index.md MUST start with a SECTION_MANIFEST block. See the reference for format requirements.\n\nWrite `index.md` before proceeding to section file creation.\n\n### 14. Write Section Files — Parallel Subagents\n\nSee [section-splitting.md](references/section-splitting.md)\n\n**Launch parallel subagents** - one Task per section for maximum efficiency:\n\n1. First, parse `sections/index.md` to get the SECTION_MANIFEST list\n2. Then launch ALL section Tasks in a single message (parallel execution):\n\n```\n# Launch all in ONE message for parallel execution:\n\nTask(\n  subagent_type=\"general-purpose\",\n  prompt=\"\"\"\n  Write section file: section-01-{name}\n\n  Inputs:\n  - <planning_dir>/claude-plan.md\n  - <planning_dir>/sections/index.md\n\n  Output: <planning_dir>/sections/section-01-{name}.md\n\n  The section file must be COMPLETELY SELF-CONTAINED. Include:\n  - Background (why this section exists)\n  - Requirements (what must be true when complete)\n  - Dependencies (requires/blocks)\n  - Implementation details (from the plan)\n  - Acceptance criteria (checkboxes)\n  - Files to create/modify\n\n  The implementer should NOT need to reference any other document.\n  \"\"\"\n)\n\nTask(\n  subagent_type=\"general-purpose\",\n  prompt=\"Write section file: section-02-{name} ...\"\n)\n\nTask(\n  subagent_type=\"general-purpose\",\n  prompt=\"Write section file: section-03-{name} ...\"\n)\n\n# ... one Task per section in the manifest\n```\n\nWait for ALL subagents to complete before proceeding.\n\n### 15. Generate Execution Files — Subagent\n\n**Delegate to subagent** to reduce main context token usage:\n\n```\nTask(\n  subagent_type=\"general-purpose\",\n  prompt=\"\"\"\n  Generate two execution files for autonomous implementation.\n\n  Input files:\n  - <planning_dir>/sections/index.md (has SECTION_MANIFEST)\n  - <planning_dir>/sections/section-*.md (all section files)\n\n  OUTPUT 1: <planning_dir>/claude-ralph-loop-prompt.md\n  For ralph-loop plugin. EMBED all section content inline.\n\n  Structure:\n  - Mission statement\n  - Full content of sections/index.md\n  - Full content of EACH section file (embedded, not referenced)\n  - Execution rules (dependency order, verify acceptance criteria)\n  - Completion signal: <promise>ALL-SECTIONS-COMPLETE</promise>\n\n  OUTPUT 2: <planning_dir>/claude-ralphy-prd.md\n  For Ralphy CLI. REFERENCE section files (don't embed).\n\n  Structure:\n  - PRD header\n  - How to use (ralphy --prd command)\n  - Context explanation\n  - Checkbox task list: one \"- [ ] Section NN: {name}\" per section\n\n  Write both files.\n  \"\"\"\n)\n```\n\nWait for subagent completion before proceeding.\n\n### 16. Final Status\n\nVerify all files were created successfully:\n- All section files from SECTION_MANIFEST\n- `claude-ralph-loop-prompt.md`\n- `claude-ralphy-prd.md`\n\n### 17. Output Summary\n\nPrint generated files and next steps:\n```\n═══════════════════════════════════════════════════════════════\nGEPETTO: Planning Complete\n═══════════════════════════════════════════════════════════════\n\nGenerated files:\n  - claude-research.md (research findings)\n  - claude-interview.md (Q&A transcript)\n  - claude-spec.md (synthesized specification)\n  - claude-plan.md (implementation plan)\n  - claude-integration-notes.md (feedback decisions)\n  - reviews/ (external LLM feedback)\n  - sections/ (implementation units)\n  - claude-ralph-loop-prompt.md (for ralph-loop plugin)\n  - claude-ralphy-prd.md (for Ralphy CLI)\n\nHow to implement:\n\nOption A - Manual (recommended for learning/control):\n  1. Read sections/index.md to understand dependencies\n  2. Implement each section file in order\n  3. Each section is self-contained with acceptance criteria\n\nOption B - Autonomous with ralph-loop (Claude Code plugin):\n  /ralph-loop @<planning_dir>/claude-ralph-loop-prompt.md --completion-promise \"COMPLETE\" --max-iterations 100\n\nOption C - Autonomous with Ralphy (external CLI):\n  ralphy --prd <planning_dir>/claude-ralphy-prd.md\n  # Or: cp <planning_dir>/claude-ralphy-prd.md ./PRD.md && ralphy\n═══════════════════════════════════════════════════════════════\n```","tags":["gepetto","agent","toolkit","softaworks","agent-skills","automation","claude","claude-code","coding-agent","development"],"capabilities":["skill","source-softaworks","skill-gepetto","topic-agent-skills","topic-automation","topic-claude","topic-claude-code","topic-coding-agent","topic-development"],"categories":["agent-toolkit"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/softaworks/agent-toolkit/gepetto","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add softaworks/agent-toolkit","source_repo":"https://github.com/softaworks/agent-toolkit","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 1847 github stars · SKILL.md body (10,509 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:52:57.686Z","embedding":null,"createdAt":"2026-04-18T20:32:18.954Z","updatedAt":"2026-05-18T18:52:57.686Z","lastSeenAt":"2026-05-18T18:52:57.686Z","tsv":"'-01':896 '-02':961 '-03':974 '/17':378 '/claude-integration-notes.md':701 '/claude-interview.md':551 '/claude-plan.md':596,721,899 '/claude-ralph-loop-prompt.md':1032,1220 '/claude-ralphy-prd.md':1074,1238,1241 '/claude-research.md':504 '/claude-spec.md':560 '/gepetto':197,206,209 '/prd.md':1242 '/ralph-loop':1219 '/reviews':668,677 '/sections/index.md':812,900,1021 '/sections/section-':1025 '/sections/section-01-':902 '1':53,159,204,237,393,648,699,855,1031,1186 '10':308,633 '100':1228 '11':314,669 '12':321,726 '13':797 '14':327,836 '15':335,991 '16':1113 '17':1130 '2':88,171,247,398,652,719,865,1073,1192 '3':183,226,255,406,1199 '4':195,272,286,387,413,448,516 '5':342,427,436,437,570 '6':291,517,577 '7':543 '8':297,552 '9':303,589 'accept':934,1064,1207 'action':45 'ai':62 'ai-assist':61 'all-sections-complet':1068 'analysi':26,664 'analyz':673 'answer':574 'anyth':47,697 'ask':407,414 'askuserquest':527,733 'assist':63,772 'author':681 'autonom':1017,1211,1231 'b':1210 'background':915 'banner':58 'base':348,443 'bash':651,655 'block':821 'boundari':809 'build':170,624 'c':1230 'call':481 'chang':725 'check':93,234 'checkbox':936,1095 'chose':511 'claud':752,761,1216 'claude-integration-notes.md':265,1157 'claude-interview.md':262,1147 'claude-plan.md':264,748,805,1154 'claude-ralph-loop-prompt.md':266,338,1128,1167 'claude-ralphy-prd.md':267,339,1129,1173 'claude-research.md':261,1144 'claude-spec.md':263,1151 'cli':1077,1176,1235 'code':1217 'codebas':410,452 'codex':653 'collect':494 'combin':499,558 'command':1092 'complet':332,340,384,587,778,910,926,988,1066,1071,1110,1141,1222,1224 'completion-promis':1221 'confirm':794 'contain':610,913,1205 'content':660,1041,1047,1051 'context':526,618,1002,1093 'continu':213,787 'cp':1240 'creat':2,160,343,593,798,811,1120 'create/modify':939 'creation':835 'criteria':935,1065,1208 'critic':43,813 'current':350 'decid':693 'decis':389,445,1159 'deleg':996 'delet':369 'depend':927,1061,1191 'deriv':421 'describ':165 'detail':3,176,381,518,594,930 'determin':230,273 'dir':240,357 'direct':492 'directori':84,144,153,188,242,269,271,355,372 'document':632,702,949 'doesn':117 'done':341,572,782,785,789 'edit':747,755,774 'effici':854 'els':48 'emb':1038,1083 'embed':1056 'end':106,119,139 'engin':612 'entir':508 'exampl':208 'execut':336,438,876,884,993,1014,1059 'exist':202,235,258,919 'explan':1094 'explor':457,463 'extern':40,71,309,634,671,740,1161,1234 'external-review.md':637 'extract':399 'featur':19 'feedback':672,741,1158,1163 'file':80,91,97,105,111,128,136,150,164,194,224,236,246,250,253,260,278,337,373,397,491,565,834,839,894,907,937,959,972,994,1015,1020,1029,1055,1080,1106,1118,1124,1135,1143,1196 'final':1114 'find':486,540,567,1146 'first':44,856 'format':375,826 'found':279 'fresh':368 'full':1046,1050 'fulli':607 'gemini':649 'general':889,954,967,1009 'general-purpos':888,953,966,1008 'generat':590,992,1012,1134,1142 'gepetto':1,27,60,75,126,190,1139 'get':860 'header':1086 'help':754 'identifi':806 'immedi':59 'implement':5,25,64,591,929,941,1018,1155,1165,1179,1193 'import':482,597 'includ':914 'index':800 'index.md':814,829 'infer':146 'inform':534 'initi':249,537,554,561 'inlin':1042 'input':92,562,898,1019 'integr':315,317,405,670,685,696,707,715,724,730 'integration-not':316 'interview':10,36,67,292,294,519,531,545,573 'interview-protocol.md':521 'intro':55,57 'invoc':99 'invok':220 'iter':1227 'launch':449,470,639,845,867,877 'learning/control':1185 'like':182 'list':345,864,1097 'llm':14,614,1162 'log':374 'loop':1036,1171,1215 'main':525,1001 'mani':78 'manifest':820,863,982,1024,1127 'manual':1182 'markdown':134,162 'max':1226 'max-iter':1225 'maximum':853 'md':79,108,121,141,223,904,1026 'messag':477,874,881 'mid':767 'mid-workflow':766 'mission':1044 'mode':274,280,358,359 'multi':13,31,425 'multi-llm':12 'multi-select':424 'multi-step':30 'multipl':479 'must':138,605,815,908,922 'n':365,377,383 'name':380,897,903,962,975,1101 'natur':807 'need':21,412,419,469,944 'new':157,284 'next':1137 'nn':1100 'none':283 'note':74,318 'ok':690 'one':848,880,976,1098 'open':758 'option':788,1180,1209,1229 'orchestr':28 'order':52,1062,1198 'output':122,901,1030,1072,1131 'parallel':475,643,840,846,875,883 'parent':152,241 'pars':857 'pass':86 'path':116,137,225,254 'path/to/your-spec.md':198,207 'pattern':404 'per':850,978,1102 'perform':433 'place':184 'plan':6,18,33,39,65,70,83,143,158,193,203,228,239,259,304,305,354,356,371,592,595,604,647,659,731,735,757,933,1140,1156 'planning/my-feature-spec.md':210 'plugin':1037,1172,1218 'point':277 'potenti':400 'prd':1085,1091,1237 'pre':24 'pre-implement':23 'present':420 'print':54,56,352,1133 'prior':617 'proceed':796,831,990,1112 'process':34 'promis':1223 'prompt':891,956,969,1011 'provid':96,113 'purpos':890,955,968,1010 'q':548,1148 'ralph':1035,1170,1214 'ralph-loop':1034,1169,1213 'ralphi':1076,1090,1175,1233,1236,1243 'raw':583 're':219,623,706,713,781 're-invok':218 'read':394,630,804,1187 'reader':602 'receiv':657 'recommend':1183 'record':428 'reduc':1000 'refer':824,946,1078 'referenc':1058 'references/external-review.md':638 'references/interview-protocol.md':522 'references/research-protocol.md':392,442 'references/section-index.md':803 'references/section-splitting.md':844 'requir':129,132,528,584,827,920 'requires/blocks':928 'research':8,35,66,287,293,388,401,411,418,430,439,450,453,459,513,539,566,1145 'research-protocol.md':391,441 'result':495,666 'resum':200,276,281,289,295,301,306,312,319,325,333,361,362 'return':484,662 'review':15,41,72,268,310,311,323,635,645,728,745,783,790,1160 'rule':1060 'run':196,205,523 'save':192,544 'scan':256 'section':4,42,73,270,329,331,799,808,819,833,838,851,862,869,893,895,906,918,958,960,971,973,979,1023,1028,1040,1054,1070,1079,1099,1103,1123,1126,1164,1195,1201 'section-index.md':802 'section-splitting.md':843 'sections/index.md':324,858,1049,1188 'see':390,440,520,636,801,822,842 'select':426,784 'self':609,912,1204 'self-contain':608,911,1203 'separ':760 'session':229,231,762,764 'set':238,248 'setup':227 'signal':1067 'singl':476,873 'skill':131 'skill-gepetto' 'skip':505 'source-softaworks' 'spec':37,68,90,104,127,135,149,163,245,252,298,300,396,538,555,556,564 'specif':588,1153 'stakehold':9 'start':155,367,816 'state':232,351 'statement':1045 'status':353,1115 'step':32,285,290,296,302,307,313,320,326,334,364,376,379,382,435,447,507,515,569,576,698,718,1138 'stop':125 'structur':1043,1084 'subag':451,455,461,483,498,641,841,847,886,951,964,986,995,998,1006,1109 'success':1121 'suggest':675,704,711 'summari':385,1132 'synthes':579,1152 'synthesi':38,69,299,557 'task':454,460,472,849,870,885,950,963,977,1005,1096 'technolog':403 'thorough':22 'todo':344 'todowrit':347 'token':1003 'tool':473,480 'topic':402,422 'topic-agent-skills' 'topic-automation' 'topic-claude' 'topic-claude-code' 'topic-coding-agent' 'topic-development' 'transcript':546,1150 'true':924 'two':640,1013 'type':431,456,462,887,952,965,1007 'understand':620,1190 'unfamiliar':601 'unit':1166 'updat':720,738 'usag':1004 'use':16,732,1089 'user':95,216,322,408,415,510,581,727,793 'vagu':179 'valid':89 'verifi':1063,1116 'via':650,654 'wait':214,791,983,1107 'want':168,751 'web':417,458 'websearch':465 'workflow':386,768,777 'write':77,328,490,502,547,553,598,665,700,828,837,892,957,970,1104","prices":[{"id":"de1194b7-0c3a-4923-9541-6e009e34c711","listingId":"b3acdd22-0125-43f4-aabd-19d53f5108a3","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"softaworks","category":"agent-toolkit","install_from":"skills.sh"},"createdAt":"2026-04-18T20:32:18.954Z"}],"sources":[{"listingId":"b3acdd22-0125-43f4-aabd-19d53f5108a3","source":"github","sourceId":"softaworks/agent-toolkit/gepetto","sourceUrl":"https://github.com/softaworks/agent-toolkit/tree/main/skills/gepetto","isPrimary":false,"firstSeenAt":"2026-04-18T21:54:34.081Z","lastSeenAt":"2026-05-18T18:52:57.686Z"},{"listingId":"b3acdd22-0125-43f4-aabd-19d53f5108a3","source":"skills_sh","sourceId":"softaworks/agent-toolkit/gepetto","sourceUrl":"https://skills.sh/softaworks/agent-toolkit/gepetto","isPrimary":true,"firstSeenAt":"2026-04-18T20:32:18.954Z","lastSeenAt":"2026-05-07T22:41:27.152Z"}],"details":{"listingId":"b3acdd22-0125-43f4-aabd-19d53f5108a3","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"softaworks","slug":"gepetto","github":{"repo":"softaworks/agent-toolkit","stars":1847,"topics":["agent-skills","ai","automation","claude","claude-code","coding-agent","development"],"license":"mit","html_url":"https://github.com/softaworks/agent-toolkit","pushed_at":"2026-03-05T16:46:24Z","description":"A curated collection of skills for AI coding agents. Skills are packaged instructions and scripts that extend agent capabilities across development, documentation, planning, and professional workflows.","skill_md_sha":"cc7d3063a8d915cc4361b8743b4d0d04693fb167","skill_md_path":"skills/gepetto/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/softaworks/agent-toolkit/tree/main/skills/gepetto"},"layout":"multi","source":"github","category":"agent-toolkit","frontmatter":{"name":"gepetto","description":"Creates detailed, sectionized implementation plans through research, stakeholder interviews, and multi-LLM review. Use when planning features that need thorough pre-implementation analysis."},"skills_sh_url":"https://skills.sh/softaworks/agent-toolkit/gepetto"},"updatedAt":"2026-05-18T18:52:57.686Z"}}