Reorganize: Move all skills to skills/ folder

- Created skills/ directory - Moved 272 skills to skills/ subfolder - Kept agents/ at root level - Kept installation scripts and docs at root level Repository structure: - skills/ - All 272 skills from skills.sh - agents/ - Agent definitions - *.sh, *.ps1 - Installation scripts - README.md, etc. - Documentation Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-23 18:05:17 +00:00
parent 2b4e974878
commit b723e2bd7d
4083 changed files with 1056 additions and 1098063 deletions
--- a/skills/gepetto/skill.md
+++ b/skills/gepetto/skill.md
@@ -0,0 +1,345 @@
+---
+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.
+---
+
+# 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(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](references/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](references/external-review.md)
+
+Launch TWO subagents in parallel to review the plan:
+1. **Gemini** via Bash
+2. **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](references/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](references/section-splitting.md)
+
+**Launch parallel subagents** - one Task per section for maximum efficiency:
+
+1. First, parse `sections/index.md` to get the SECTION_MANIFEST list
+2. 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
+═══════════════════════════════════════════════════════════════
+```