Plan Ralph

---
description: Generate Ralph-compatible execution plan with 16-hour phases, embedded agent calls, and auto-created fase directories
---

# Plan Ralph: Spec → Executable Ralph Plan + Directories

Transform a technical specification into a Ralph-executable plan with pre-created fase directories and Skill invocations per TDD phase.

## Usage

```bash
# Basic usage - SPEC in current directory
/plan-ralph SPEC-TASK-VISUAL-TOOLS.md

# With explicit target directory
/plan-ralph SPEC-TASK-VISUAL-TOOLS.md tasks/active/techlead/current/

# From tasks directory
cd tasks/active/techlead/current/
/plan-ralph SPEC-AI-CHAT.md

Purpose

1. Break feature into 16-hour fases (1 fase = RED+GREEN+REFACTOR+SECURITY)
2. Create fase-XX/ directories with tests/, implementation/, refactor/, security/ subdirs
3. Generate Skill invocations for each TDD phase (not inline templates!)
4. Include completion promises for Ralph detection
5. Enforce MEDIUM+ threshold via skills
6. Generate ready-to-execute Ralph command (~100 lines instead of ~2800!)

Why Skill-Based Architecture

Problem: Inline Templates Fail

1. "Lost in the Middle" phenomenon: 2800+ line prompts lose critical info
2. Steps get buried: Gates skipped, agents not invoked
3. TodoWrite resets: Between Ralph iterations

Solution: Skill-Per-Phase Model

• Each TDD phase is a separate skill with its own gates
• Skills are ~400 lines each (not 2800 combined)
• Ralph only needs to track: "which skill, which fase"
• Gates enforced within each skill invocation

---

Ralph TDD Skills (Auto-Available)

Skill	Purpose	Gates	Output
ralph-red	Test specification & generation	5 gates	<promise>RED_PHASE_COMPLETE</promise>
ralph-green	Minimal implementation	7 gates	<promise>GREEN_PHASE_COMPLETE</promise>
ralph-refactor	Code quality (MEDIUM+ threshold)	7 gates	<promise>REFACTOR_PHASE_COMPLETE</promise>
ralph-security	OWASP audit (MEDIUM+ threshold)	8 gates	<promise>SECURITY_PHASE_COMPLETE</promise>

Skills location: .claude/skills/ralph-*/SKILL.md

State tracking: Each skill writes to [fase-dir]/gates.json

---

Execution Workflow

┌─────────────────────────────────────────────────────────────────────┐
│ /plan-ralph: SPEC → PLAN-RALPH + DIRECTORIES                       │
└─────────────────────────────────────────────────────────────────────┘

0. INPUT VALIDATION
   → Verify SPEC file exists
   → Determine target directory (where SPEC is, or user-specified)
   → Extract feature name from SPEC filename
   → Output: Feature name, target directory confirmed

1. EXPLORE PHASE (MANDATORY)
   → Use Task tool with subagent_type='Explore' and thoroughness='very thorough'
   → Analyze SPEC structure and complexity:
     * Count operations/components to implement
     * Identify schema changes required
     * Find natural boundaries for 16-hour blocks
     * Check existing patterns in codebase
     * Identify dependencies between components
   → Output: Complexity analysis with fase boundaries

2. PLAN PHASE (MANDATORY)
   → Use Task tool with subagent_type='Plan' and model='sonnet'
   → Design fase structure:
     * Group operations into 16-hour blocks
     * Each block = RED + GREEN + REFACTOR + SECURITY
     * Sequence fases (schema changes first, dependent features later)
   → Output: Fase structure with operation assignments

3. CREATE DIRECTORIES
   → For each fase:
     mkdir -p [target]/fase-XX/{tests,implementation,refactor,security}
   → Create README.md in each fase with:
     * Fase title and operations list
     * Entities involved
     * Dependencies on prior fases
   → Output: Directory structure created

3.5 CREATE FASE TASKS (Task Tracking)
   → Update feature task with plan metadata
   → Create fase tasks with blockedBy dependencies
   → See Task Tracking section below

4. GENERATE PLAN-RALPH FILE
   → Write PLAN-RALPH-[FEATURE].md with NEW compact format:

   ┌─────────────────────────────────────────────────────────────┐
   │ NEW FORMAT: ~100 lines instead of ~2800!                   │
   │                                                             │
   │ # Ralph Plan: [FEATURE]                                    │
   │                                                             │
   │ ## Fases                                                    │
   │ - fase-01: [Title] (ops: X, Y, Z)                          │
   │ - fase-02: [Title] (ops: A, B)                             │
   │ ...                                                         │
   │                                                             │
   │ ## Execution                                                │
   │                                                             │
   │ FOR EACH fase:                                              │
   │   1. Skill('ralph-red', args='[fase-dir] [feature] ops:X,Y')│
   │      → Wait for <promise>RED_PHASE_COMPLETE</promise>      │
   │   2. Skill('ralph-green', args='[fase-dir]')               │
   │      → Wait for <promise>GREEN_PHASE_COMPLETE</promise>    │
   │   3. Skill('ralph-refactor', args='[fase-dir]')            │
   │      → Wait for <promise>REFACTOR_PHASE_COMPLETE</promise> │
   │   4. Skill('ralph-security', args='[fase-dir]')            │
   │      → Wait for <promise>SECURITY_PHASE_COMPLETE</promise> │
   │   → <promise>FASE_X_COMPLETE</promise>                     │
   │                                                             │
   │ <promise>ALL_FASES_COMPLETE</promise>                      │
   └─────────────────────────────────────────────────────────────┘

5. SUMMARY
   → Display created files
   → Display Ralph command to copy
   → Remind about MEDIUM+ thresholds

-- ```