Gepetto

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:

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.

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.

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: 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

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:

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
═══════════════════════════════════════════════════════════════

/gepetto

🪵 Like Geppetto carved Pinocchio from rough wood, transform vague ideas into living implementation plans

Just as the master craftsman took rough timber and carved it into a puppet that came to life, Gepetto transforms your rough feature sketches into detailed, battle-tested specifications that spring into action.

Gepetto carves vague ideas into comprehensive, sectionized implementation plans through structured research, stakeholder interviews, and multi-LLM review.

The Craft

Geppetto doesn't rush. Neither should your specs.

• Rough Wood (Your initial spec) → Research & refinement
• Careful Carving (Interview & synthesis) → Shape emerges
• Fine Details (External review) → Master craftsmen review your work
• Final Polish (Sections) → Ready for life
• Brings to Life (Ralph-loop) → Your creation walks and talks

The Problem

You: "Claude, build me an auth system"
Claude: *starts coding immediately*
Result: Back-and-forth iterations, missed edge cases, scope creep

The Solution

You: "/gepetto @planning/auth-spec.md"
gepetto: Research → Interview → Spec → Plan → External Review → Sections
Result: Clear implementation roadmap, reviewed by multiple LLMs, ready for execution

Table of Contents

• Installation
• Workflow
• Quick Start
• When to Use
• Output Files
• External Review
• Resuming
• Best Practices
• Implementing the Plan
• Integration with ralph-loop (Optional)
• Integration with Ralphy (Optional)
• File Structure

Installation

Claude Code only - This skill is designed specifically for Claude Code.

Recommended: Plugin Installation

Step 1: Add the marketplace (first time only)

/plugin marketplace add softaworks/agent-skills

Step 2: Install gepetto

/plugin install gepetto

Alternative: Manual Installation

npx add-skill softaworks/gepetto
# or
cp -r skills/gepetto ~/.claude/skills/

For claude.ai

While not the primary use case, you can add the skill to project knowledge or paste SKILL.md contents into the conversation for basic guidance.

---

Workflow

┌─────────────────────────────────────────────────────────────────┐
│                      gepetto pipeline                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   /gepetto @spec.md                                             │
│          │                                                      │
│          ▼                                                      │
│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐    │
│   │   Research   │ ──▶ │  Interview   │ ──▶ │     Spec     │    │
│   │  (optional)  │     │  (5-10 Q&A)  │     │  Synthesis   │    │
│   └──────────────┘     └──────────────┘     └──────────────┘    │
│                                                   │             │
│                                                   ▼             │
│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐    │
│   │   Section    │ ◀── │   Integrate  │ ◀── │   External   │    │
│   │  Splitting   │     │   Feedback   │     │  LLM Review  │    │
│   └──────────────┘     └──────────────┘     └──────────────┘    │
│          │                                                      │
│          ▼                                                      │
│   ┌──────────────────────────────────────────────────────────┐  │
│   │  sections/section-01-*.md  sections/section-02-*.md ...  │  │
│   │  (Self-contained, parallel-ready implementation units)   │  │
│   └──────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Start

1. Create a spec file

mkdir -p planning
cat > planning/auth-spec.md << 'EOF'
# Authentication System

Need OAuth2 login with Google and GitHub.
Sessions stored in Redis, JWT for API auth.
EOF

Your spec can be detailed or just bullet points - the interview phase extracts the details.

2. Run gepetto

/gepetto @planning/auth-spec.md

3. Follow the prompts

Answer research and interview questions. Review the generated plan. Done.

When to Use

Use gepetto when:

• Requirements are fuzzy and need clarification
• The feature is complex enough to benefit from external review
• You want implementation sections that can be worked on in parallel
• You prefer thinking before coding

Skip gepetto when:

• Simple bug fixes or one-file changes
• Requirements are already crystal clear
• You just want to start coding

Output Files

After running gepetto, your planning directory contains:

planning/
├── your-spec.md                 # Your original input
├── claude-research.md           # Web + codebase research findings
├── claude-interview.md          # Q&A transcript
├── claude-spec.md               # Synthesized specification
├── claude-plan.md               # Implementation plan
├── claude-integration-notes.md  # Review feedback decisions
├── claude-ralph-loop-prompt.md  # Ready-to-run ralph-loop prompt
├── claude-ralphy-prd.md         # Ready-to-run Ralphy PRD
├── reviews/
│   ├── gemini-review.md         # Gemini's feedback
│   └── codex-review.md          # Codex's feedback
└── sections/
    ├── index.md                 # Section manifest & dependencies
    ├── section-01-*.md          # Implementation unit 1
    ├── section-02-*.md          # Implementation unit 2
    └── ...

Key Files

External Review

gepetto uses Gemini CLI and Codex CLI to get independent reviews of your plan.

Requirements

Install at least one:

# Gemini CLI (Google)
# See: https://github.com/google-gemini/gemini-cli

# Codex CLI (OpenAI)
# See: https://github.com/openai/codex

What Reviewers Check

Both LLMs analyze your plan for:

• Potential footguns and edge cases
• Missing considerations
• Security vulnerabilities
• Performance issues
• Architectural problems
• Unclear requirements

No CLI Installed?

If neither CLI is available, gepetto will skip the external review step and continue with the workflow.

Resuming

If the workflow is interrupted (context limit, need a break), just re-run with the same spec:

/gepetto @planning/auth-spec.md

gepetto detects existing files and resumes from where it left off.

Resume Points

Best Practices

1. Start with something - Even a few bullet points. The interview phase extracts details.

2. Answer thoroughly - The interview is where hidden requirements surface. Don't rush it.

3. Review critically - External LLMs catch blind spots but may over-engineer. You decide what to integrate.

4. Use sections - Each section file is self-contained. Work on them in parallel or hand them off.

5. Iterate - If the plan isn't right, edit claude-plan.md and re-run section generation.

Implementing the Plan

After gepetto completes, you have self-contained section files ready for implementation. Choose your approach:

Option A: Manual Implementation (Recommended)

Best for: learning the codebase, maintaining control, reviewing as you go.

# 1. Check the dependency order
cat planning/sections/index.md

# 2. Open first section
cat planning/sections/section-01-foundation.md

# 3. Implement following the acceptance criteria

# 4. Move to next section, repeat

Each section file contains:

• Background context
• Requirements
• Implementation details
• Acceptance criteria (checklist)
• Files to create/modify

You can implement sections yourself, delegate to another Claude session, or hand off to a team member.

Option B: Autonomous with ralph-loop (Claude Code Plugin)

Best for: hands-off execution within Claude Code, large plans, overnight runs.

/ralph-loop @planning/claude-ralph-loop-prompt.md --completion-promise "COMPLETE" --max-iterations 100

See Integration with ralph-loop for details.

Option C: Autonomous with Ralphy (External CLI)

Best for: multi-engine support (Claude, Codex, Cursor, etc.), parallel execution, branch-per-task workflows.

ralphy --prd planning/claude-ralphy-prd.md

See Integration with Ralphy for details.

---

Integration with ralph-loop (Optional)

gepetto generates claude-ralph-loop-prompt.md for optional integration with ralph-loop.

What is ralph-loop?

Ralph Loop is an iterative execution technique that keeps Claude working on a task until completion. It uses a Stop hook to create a self-referential feedback loop - Claude works, checks progress, and continues until the completion criteria are met.

One-Command Execution

After gepetto completes, it generates claude-ralph-loop-prompt.md with all section content embedded. Execute the entire plan with:

/ralph-loop @planning/claude-ralph-loop-prompt.md --completion-promise "COMPLETE" --max-iterations 100

That's it. Walk away and come back to working code.

The Workflow

┌─────────────────────────────────────────────────────────────────┐
│                    gepetto + ralph-loop                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   1. /gepetto @planning/feature.md                              │
│      └── Generates sections + claude-ralph-loop-prompt.md       │
│                                                                 │
│   2. (Optional) Review sections/index.md for dependencies       │
│                                                                 │
│   3. /ralph-loop @planning/claude-ralph-loop-prompt.md \        │
│        --completion-promise "COMPLETE" --max-iterations 100     │
│                                                                 │
│   4. Walk away. Come back to working code.                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

What the Prompt Does

The generated claude-ralph-loop-prompt.md instructs ralph-loop to:

1. Parse the section index for dependencies 2. Execute each section in the correct order 3. Verify acceptance criteria for each section 4. Track progress in PROGRESS.md 5. Continue until all sections are done (or hit max iterations)

Executing Individual Sections

If you prefer to execute sections one at a time:

# Execute section 01 (usually foundation/setup)
/ralph-loop "Implement the following section. Follow all requirements exactly.

$(cat planning/sections/section-01-foundation.md)

When ALL acceptance criteria are met and tests pass:
- Output <promise>SECTION-01-COMPLETE</promise>

If blocked after 10 iterations, document blockers and output <promise>SECTION-01-BLOCKED</promise>" --completion-promise "SECTION-01" --max-iterations 30

Tips

1. Set max-iterations - Always use --max-iterations as a safety net (50-100 is reasonable for full execution) 2. Review PROGRESS.md - Check progress during long executions 3. Respect dependencies - If executing manually, check sections/index.md for the dependency graph

Installing ralph-loop

# Via Claude Code plugin marketplace
/plugin marketplace add anthropics/claude-plugins-official
/plugin install ralph-loop
/plugin enable ralph-loop

---

Integration with Ralphy (Optional)

gepetto generates claude-ralphy-prd.md for optional integration with Ralphy, an autonomous AI coding loop that works with multiple AI engines.

What is Ralphy?

Ralphy is an external CLI tool that iterates through a task list (PRD.md) and executes each task using an AI CLI of your choice. Unlike ralph-loop (which runs inside Claude Code), Ralphy runs externally and supports multiple AI engines.

Key Differences: ralph-loop vs Ralphy

One-Command Execution

# Using the generated PRD directly
ralphy --prd planning/claude-ralphy-prd.md

# Or copy to project root
cp planning/claude-ralphy-prd.md ./PRD.md
ralphy

How It Works

1. Ralphy reads claude-ralphy-prd.md and finds checkbox tasks 2. For each unchecked task, it builds a prompt with project context 3. The AI (Claude by default) reads the referenced section file for detailed requirements 4. AI implements the task, runs tests, commits 5. Ralphy marks the task complete (- [ ] → - [x]) 6. Repeat until all tasks done

The Generated PRD Format

# Implementation PRD

## Tasks

- [ ] Section 01: Foundation - Read sections/section-01-foundation.md for details
- [ ] Section 02: Core libs - Read sections/section-02-core-libs.md for details
- [ ] Section 03: API layer - Read sections/section-03-api-layer.md for details

Each task references the detailed section file, so the AI gets all the context Gepetto prepared.

Advanced Usage

# Use different AI engine
ralphy --prd planning/claude-ralphy-prd.md --codex
ralphy --prd planning/claude-ralphy-prd.md --cursor

# Parallel execution (3 agents by default)
ralphy --prd planning/claude-ralphy-prd.md --parallel

# Branch per task with auto PR
ralphy --prd planning/claude-ralphy-prd.md --branch-per-task --create-pr

# Skip tests for faster iteration
ralphy --prd planning/claude-ralphy-prd.md --fast

Learn More

See the Ralphy repository for installation, configuration, and advanced features.

File Structure

~/.claude/skills/gepetto/
├── SKILL.md                    # Main skill definition
├── README.md                   # This file
└── references/
    ├── research-protocol.md    # How research works
    ├── interview-protocol.md   # Interview guidelines
    ├── external-review.md      # CLI review setup
    ├── section-index.md        # Index creation rules
    └── section-splitting.md    # Section file format

Differences from Similar Tools

---

Crafted by: Leonardo Flores License: MIT Repository: https://github.com/softaworks/gepetto

"When you wish upon a spec..." ⭐🪵

External Review Protocol

This step sends claude-plan.md to external LLMs (Gemini and Codex) for independent review using CLI subagents.

Overview

Launch TWO parallel Bash commands to get external reviews: 1. Gemini CLI - Google's Gemini 3 Pro 2. Codex CLI - OpenAI's GPT-5.2

Both reviewers receive the same plan and return their analysis.

Review Prompt

Use this prompt for both reviewers:

You are a senior software architect reviewing an implementation plan.

The plan is self-contained - it includes all background, context, and requirements.

Identify:
- Potential footguns and edge cases
- Missing considerations
- Security vulnerabilities
- Performance issues
- Architectural problems
- Unclear or ambiguous requirements
- Anything else worth adding to the plan

Be specific and actionable. Reference specific sections. Give your honest, unconstrained assessment.

Here is the plan to review:

{PLAN_CONTENT}

Execution

Step 1: Read the Plan

plan_content=$(cat "<planning_dir>/claude-plan.md")

Step 2: Launch Both Reviews in Parallel

Use TWO Bash tool calls in a single message:

Gemini Review:

gemini -m gemini-3-pro-preview --approval-mode yolo "You are a senior software architect reviewing an implementation plan.

The plan is self-contained - it includes all background, context, and requirements.

Identify:
- Potential footguns and edge cases
- Missing considerations
- Security vulnerabilities
- Performance issues
- Architectural problems
- Unclear or ambiguous requirements
- Anything else worth adding to the plan

Be specific and actionable. Reference specific sections. Give your honest, unconstrained assessment.

Here is the plan to review:

$(cat '<planning_dir>/claude-plan.md')"

Codex Review:

echo "You are a senior software architect reviewing an implementation plan.

The plan is self-contained - it includes all background, context, and requirements.

Identify:
- Potential footguns and edge cases
- Missing considerations
- Security vulnerabilities
- Performance issues
- Architectural problems
- Unclear or ambiguous requirements
- Anything else worth adding to the plan

Be specific and actionable. Reference specific sections. Give your honest, unconstrained assessment.

Here is the plan to review:

$(cat '<planning_dir>/claude-plan.md')" | codex exec -m gpt-5.2 --sandbox read-only --skip-git-repo-check --full-auto 2>/dev/null

Step 3: Write Review Files

Create <planning_dir>/reviews/ directory and write:

• gemini-review.md - Gemini's analysis
• codex-review.md - Codex's analysis

Format each file:

# {Provider} Review

**Model:** {model_name}
**Generated:** {timestamp}

---

{review_content}

Handling Failures

Notes

• Gemini: Uses --approval-mode yolo for non-interactive execution
• Codex: Uses --full-auto and 2>/dev/null to suppress thinking tokens
• Both CLIs must be installed and configured separately by the user
• If a CLI is not available, skip that reviewer and continue with the other

Interview Protocol

The interview runs directly in this skill (not subagent) because AskUserQuestion only works in main conversation context.

Context

The interview should be informed by:

• Initial spec (always available)
• Research findings (if step 5 produced claude-research.md)

If research was done, use it to:

• Skip questions already answered by research
• Ask clarifying questions about trade-offs or patterns discovered
• Dig deeper into areas where research revealed complexity

Philosophy

• You are a senior architect accountable for this implementation
• Surface everything the user knows but hasn't mentioned
• Assume the initial spec is incomplete
• Extract context from user's head

Technique

• Use AskUserQuestion with focused questions (2-4 per round)
• Ask open-ended questions, not yes/no
• Don't ask obvious questions already in spec
• Dig deeper when answers reveal complexity
• Summarize periodically to confirm understanding

Example Questions

Good questions:

• "What happens when X fails? Should we retry, log, or surface to user?"
• "Are there existing patterns in the codebase for Y that we should follow?"
• "What's the expected scale - dozens, thousands, or millions of Z?"

Bad questions (too vague):

• "Anything else?"
• "Is that all?"
• "Do you have any other requirements?"

When to Stop

Stop interviewing when you are confident you can: 1. Write a detailed implementation plan 2. Make no assumptions about requirements 3. Handle all edge cases the user cares about

If uncertain, ask one more round. Better to over-clarify than make wrong assumptions.

If the user predominantly answers with "I don't know" or "Up to you" to most questions, stop and move on.

Saving the Transcript

After the interview, save the full Q&A to <planning_dir>/claude-interview.md:

• Format each question as a markdown heading
• Include the user's full answer below
• Number questions for reference (Q1, Q2, etc.)

Research Protocol

This document defines the research decision and execution flow.

Overview

┌─────────────────────────────────────────────────────────────┐
│  RESEARCH FLOW                                              │
│                                                             │
│  Step 4: Decide what to research                            │
│    - Codebase research? (existing patterns/conventions)     │
│    - Web research? (best practices, SOTA approaches)        │
│                                                             │
│  Step 5: Execute research (parallel if both selected)       │
│    - Subagents return results                               │
│    - Main Claude combines and writes claude-research.md     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

Step 4: Research Decision

4.1 Read and Analyze the Spec File

Read the spec file and extract potential research topics by identifying:

• Technologies mentioned (React, Python, PostgreSQL, Redis, etc.)
• Feature types (authentication, file upload, real-time sync, caching, etc.)
• Architecture patterns (microservices, event-driven, serverless, etc.)
• Integration points (third-party APIs, OAuth providers, payment gateways, etc.)

Generate 3-5 research topic suggestions based on what you find. Format them as searchable queries with year for recency:

• "React authentication patterns 2025"
• "PostgreSQL full-text search best practices"
• "Redis session storage patterns"

If the spec is vague, fall back to generic options:

• "General best practices for {detected_language/framework}"
• "Security considerations for {feature_type}"

4.2 Ask About Codebase Research

Use AskUserQuestion:

question: "Is there existing code I should research first?"
header: "Codebase"
options:
  - label: "Yes, research the codebase"
    description: "Analyze existing patterns, conventions, dependencies"
  - label: "No existing code"
    description: "This is a new project or standalone feature"

4.3 Ask About Web Research

Present the derived topics as multi-select options:

question: "Should I research current best practices for any of these topics?"
header: "Web Research"
multiSelect: true
options:
  - label: "{derived_topic_1}"
    description: "Based on spec mention of {X}"
  - label: "{derived_topic_2}"
    description: "Based on spec mention of {Y}"
  - label: "{derived_topic_3}"
    description: "Based on spec mention of {Z}"

If user selects "Other", follow up to get custom topics.

4.4 Handle "No Research" Case

If user selects no codebase AND no web research, skip step 5 entirely.

---

Step 5: Execute Research

Critical Pattern: Subagents Return Results, Parent Writes Files

DO NOT have subagents write to files directly. This avoids race conditions and keeps control with the main context.

┌─────────────────────────────────────────────────────────────┐
│  PARALLEL RESEARCH EXECUTION                                │
│                                                             │
│  Task 1: Explore ──────────┐                                │
│    (returns codebase       │                                │
│     findings as markdown)  ├──→ Main Claude combines       │
│                            │    and writes single          │
│  Task 2: Explore ──────────┘    claude-research.md         │
│    (returns best practices                                  │
│     findings as markdown)                                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

5.1 Codebase Research (if selected)

Launch Task tool with subagent_type=Explore:

Task tool:
  subagent_type: Explore
  description: "Research codebase patterns"
  prompt: |
    Research this codebase to understand:
    - Project structure and architecture
    - Existing patterns and conventions
    - Dependencies and how they're used
    - Testing setup (framework, patterns, how tests are run)

    Focus areas from user: {user_specified_areas_if_any}

    Return your findings as markdown.
    DO NOT write to any files. Return findings in your response.

5.2 Web Research (if topics selected)

Launch Task tool with subagent_type=Explore:

Task tool:
  subagent_type: Explore
  description: "Research best practices"
  prompt: |
    Research current best practices for the following topics:
    {selected_topics_list}

    For each topic:
    1. Use WebSearch to find authoritative sources
    2. Use WebFetch on promising results to extract recommendations
    3. Cross-validate information across sources
    4. Synthesize findings with clear recommendations

    Return your findings as markdown. Always cite sources with URLs.
    DO NOT write to any files. Return findings in your response.

5.3 Parallel Execution

If both codebase and web research are needed, launch both Task tools in a single message.

# Single message with multiple tool calls:
[Task tool call 1: Explore subagent for codebase]
[Task tool call 2: Explore subagent for web research]

Wait for both to complete, then combine results.

5.4 Combine Results and Write File

After collecting results from all subagents, combine them into <planning_dir>/claude-research.md.

Structure the file however makes sense for the findings.

---

Edge Cases

Section Index Creation

Create <planning_dir>/sections/index.md to define implementation sections.

Input Files

• <planning_dir>/claude-plan.md - implementation plan

Output

<planning_dir>/sections/
└── index.md

SECTION_MANIFEST Block

index.md MUST start with a SECTION_MANIFEST block:

<!-- SECTION_MANIFEST
section-01-foundation
section-02-config
section-03-parser
section-04-api
END_MANIFEST -->

# Implementation Sections Index

... rest of human-readable content ...

SECTION_MANIFEST Rules

• Must be at the TOP of index.md (before any other content)
• One section per line, format: section-NN-name (e.g., section-01-foundation)
• Section numbers must be two digits with leading zero (01, 02, ... 12)
• Section names use lowercase with hyphens (no spaces or underscores)
• Numbers should be sequential (01, 02, 03...)
• This block is parsed to track progress - the rest of index.md is for humans

Human-Readable Content

After the manifest block, include:

Dependency Graph

Table showing what blocks what:

| Section | Depends On | Blocks | Parallelizable |
|---------|------------|--------|----------------|
| section-01-foundation | - | section-02, section-03 | Yes |
| section-02-config | section-01 | section-04 | No |
| section-03-parser | section-01 | section-04 | Yes |
| section-04-api | section-02, section-03 | - | No |

Execution Order

Which sections can run in parallel:

1. section-01-foundation (no dependencies)
2. section-02-config, section-03-parser (parallel after section-01)
3. section-04-api (requires section-02 AND section-03)

Section Summaries

Brief description of each section:

### section-01-foundation
Initial project setup and configuration.

### section-02-config
Configuration loading and validation.

Guidelines

• Natural boundaries: Split by component, layer, feature, or phase
• Focused sections: One logical unit of work each
• Parallelization: Consider which sections can run independently
• Dependency direction: Earlier sections should not depend on later sections

Example index.md

<!-- SECTION_MANIFEST
section-01-foundation
section-02-core-libs
section-03-api-layer
section-04-frontend
section-05-integration
END_MANIFEST -->

# Implementation Sections Index

## Dependency Graph

| Section | Depends On | Blocks | Parallelizable |
|---------|------------|--------|----------------|
| section-01-foundation | - | all | Yes |
| section-02-core-libs | 01 | 03, 04 | No |
| section-03-api-layer | 02 | 05 | Yes |
| section-04-frontend | 02 | 05 | Yes |
| section-05-integration | 03, 04 | - | No |

## Execution Order

1. section-01-foundation (no dependencies)
2. section-02-core-libs (after 01)
3. section-03-api-layer, section-04-frontend (parallel after 02)
4. section-05-integration (final)

## Section Summaries

### section-01-foundation
Directory structure, config files, base setup.

### section-02-core-libs
Shared utilities and core libraries.

### section-03-api-layer
REST API endpoints and middleware.

### section-04-frontend
UI components and pages.

### section-05-integration
End-to-end integration and final wiring.

Section File Writing

Write individual section files from the plan using parallel subagents for efficiency.

This step assumes sections/index.md already exists.

Input Files

• <planning_dir>/claude-plan.md - implementation details
• <planning_dir>/sections/index.md - section definitions and dependencies

Output

<planning_dir>/sections/
├── index.md (already exists)
├── section-01-<name>.md
├── section-02-<name>.md
└── ...

Parallel Execution Strategy

Launch one subagent per section in a single message for maximum parallelization:

┌─────────────────────────────────────────────────────┐
│  PARALLEL SUBAGENT APPROACH                         │
│                                                     │
│  1. Parse index.md to get SECTION_MANIFEST list     │
│  2. Check which sections already exist              │
│  3. Launch ALL missing sections as parallel Tasks:  │
│                                                     │
│     Task(prompt="Write section-01-...")             │
│     Task(prompt="Write section-02-...")             │
│     Task(prompt="Write section-03-...")             │
│     ... (all in ONE message)                        │
│                                                     │
│  4. Wait for all subagents to complete              │
│                                                     │
└─────────────────────────────────────────────────────┘

Parse SECTION_MANIFEST

Extract section list from index.md:

<!-- SECTION_MANIFEST
section-01-foundation
section-02-config
section-03-api
END_MANIFEST -->

Launch Parallel Tasks

For each section in the manifest, include a Task in a single message:

Task(
  subagent_type="general-purpose",
  prompt="""
  Write section file: section-01-foundation

  Inputs:
  - <planning_dir>/claude-plan.md
  - <planning_dir>/sections/index.md

  Output: <planning_dir>/sections/section-01-foundation.md

  Requirements: [see Section File Template below]
  """
)

Task(
  subagent_type="general-purpose",
  prompt="Write section file: section-02-config ..."
)

# ... one Task per section

Why parallel? Each section is independent - they all read from the same source files (claude-plan.md, index.md) but write to different output files.

Resume Handling

If some sections already exist: 1. Only launch Tasks for MISSING sections 2. Skip sections that have corresponding section-*.md files

Section File Requirements

CRITICAL: Each section file must be completely self-contained.

The implementer reading a section file should NOT need to reference claude-plan.md or any other document. They should be able to: 1. Read the single section file 2. Create a TODO list 3. Start implementing immediately

Include all necessary background, requirements, and implementation details within each section.

Section File Template

# Section NN: {Section Name}

## Background

{Why this section exists, what problem it solves}

## Requirements

{What must be true when this section is complete}

## Dependencies

- Requires: {list of prior sections that must be complete}
- Blocks: {list of sections that depend on this one}

## Implementation Details

{Detailed implementation guidance}

### {Subsection 1}

{Details}

### {Subsection 2}

{Details}

## Acceptance Criteria

- [ ] {Criterion 1}
- [ ] {Criterion 2}
- [ ] {Criterion 3}

## Files to Create/Modify

- `path/to/file1.ts` - {description}
- `path/to/file2.ts` - {description}

Completion

All sections are complete when every section in the SECTION_MANIFEST has a corresponding section-NN-name.md file.

After all parallel Tasks complete, update the main TODO list to mark section writing as done.