plans/<spec-name>/
├── spec.md          # Copy of original spec
├── prd.json         # Tasks list for Ralph
├── progress.txt     # Learnings log (initialized)
├── prompt.md        # Instructions for each iteration
├── run.sh           # Loop execution script
└── run-once.sh      # Single iteration (for testing)

{
  "branchName": "feature-name",
  "tasks": [
    {
      "id": "T-0001",
      "title": "Short imperative title",
      "acceptanceCriteria": [
        "Explicit criterion 1",
        "Explicit criterion 2",
        "typecheck passes",
        "tests pass"
      ],
      "priority": 1,
      "passes": false,
      "notes": "",
      "tests": ["make all"],
      "dependencies": []
    }
  ]
}

❌ TOO BIG:
"Implement the router system"

✅ RIGHT SIZE:
"Create route matching algorithm for static paths"
"Add dynamic param matching (:id)"
"Add optional segment matching (:id?)"
"Add catch-all matching (*)"

❌ VAGUE:
- "Works correctly"
- "Handles errors"
- "Users can navigate"

✅ EXPLICIT:
- "Function returns `['a', 'b']` for path `/a/b` with pattern `/*`"
- "Throws `RouteNotFoundError` when no route matches"
- "Link component renders <a> tag with href attribute"
- "`make typecheck` passes"
- "`make test` passes"

{
  "id": "T-0003",
  "title": "Add Link component",
  "dependencies": ["T-0001", "T-0002"],
  "priority": 3
}

"tests": ["make all"]

❌ WRONG (Horizontal Layering):
T-0001: Create all type definitions
T-0002: Create all components
T-0003: Create all utilities
...
T-0015: Build and test everything

✅ RIGHT (Steel Wire / Vertical Slice):
T-0001: Scaffold project
T-0002: Create ONE component with ONE dependency
T-0003: Build and verify chunk exists  ← EARLY VALIDATION
T-0004: Add second component
T-0005: Verify two chunks exist  ← INCREMENTAL VALIDATION
...

[
  { "id": "T-0001", "title": "Scaffold project" },
  { "id": "T-0002", "title": "Create home component with date-fns" },
  { "id": "T-0003", "title": "Build and verify single chunk works" },  // ← TEST
  { "id": "T-0004", "title": "Add dashboard component with lodash" },
  { "id": "T-0005", "title": "Verify two separate chunks in build" },  // ← TEST
  { "id": "T-0006", "title": "Add SSR rendering" },
  { "id": "T-0007", "title": "Verify SSR outputs correct HTML" },      // ← TEST
  ...
]

1. Scaffold / setup
2. Implement ONE minimal vertical slice
3. ✓ VERIFY: Build/run and confirm it works
4. Add second task
5. ✓ VERIFY: Both tasks work together
6. Add remaining tasks...
7. ✓ VERIFY: after each major addition
8. Final integration verification

1. Create file with type stubs / interfaces
2. Implement core logic
3. ✓ VERIFY: typecheck and basic functionality
4. Add error handling
5. Wire into existing system
6. ✓ VERIFY: integration works

1. Implement base case
2. ✓ VERIFY: base case works
3. Add edge case handling
4. Add complex case handling
5. ✓ VERIFY: all cases pass

1. Create component skeleton with props/types
2. Add rendering logic
3. ✓ VERIFY: renders correctly
4. Add interactivity
5. ✓ VERIFY: interactions work

1. Add command registration + minimal implementation
2. ✓ VERIFY: command runs
3. Add options/flags
4. Add error handling
5. ✓ VERIFY: all options work

[
  {
    "id": "T-0001",
    "title": "Create route matcher for static paths",
    "acceptanceCriteria": [
      "Create `packages/pulse/js/src/router/match.ts`",
      "`matchPath('/users', '/users')` returns `{ params: {}, matched: true }`",
      "`matchPath('/users', '/posts')` returns `{ matched: false }`",
      "`make typecheck` passes"
    ],
    "priority": 1,
    "passes": false,
    "notes": "",
    "tests": ["make all"],
    "dependencies": []
  },
  {
    "id": "T-0002",
    "title": "Add dynamic param matching to router",
    "acceptanceCriteria": [
      "`matchPath('/users/:id', '/users/123')` returns `{ params: { id: '123' }, matched: true }`",
      "Multiple params work: `/users/:userId/posts/:postId`",
      "`make test` passes for router/match.test.ts"
    ],
    "priority": 2,
    "passes": false,
    "notes": "",
    "tests": ["make all"],
    "dependencies": ["T-0001"]
  },
  {
    "id": "T-0003",
    "title": "Add optional segment matching",
    "acceptanceCriteria": [
      "`matchPath('/users/:id?', '/users')` matches with `id: undefined`",
      "`matchPath('/users/:id?', '/users/123')` matches with `id: '123'`",
      "All permutations of `/a/:b?/:c?` work correctly"
    ],
    "priority": 3,
    "passes": false,
    "notes": "",
    "tests": ["make all"],
    "dependencies": ["T-0002"]
  }
]

python .claude/skills/prd-gen/check_topo.py plans/<spec-name>/prd.json

python .claude/skills/prd-gen/available_tasks.py plans/<spec-name>/prd.json

# Ralph Agent Instructions

## Your Task

1. Read `{{PLAN_DIR}}/progress.txt`
2. Check you're on the correct branch: `{{BRANCH_NAME}}`
3. **Check for in-progress work** (see Task Selection below)
4. Implement that ONE task
5. Run typecheck and tests: `make all`
6. Update AGENTS.md files with learnings (if discovered reusable patterns)
7. Commit: `feat: [ID] - [Title]`
8. Update prd.json: `passes: true`
9. Append learnings to progress.txt (clear "In Progress" section if completing it)
10. Stop after implementing this single task

## Task Selection

Check `progress.txt` for an `## In Progress` section:

**If in-progress work exists:**
- You MUST continue that task (don't start something new)
- Exception: If you discover a missing dependency that must be done first, document this in progress.txt and work on the dependency instead
- Read the in-progress notes carefully - they contain context from the previous iteration

**If no in-progress work:**
- Run: `python .claude/skills/prd-gen/available_tasks.py {{PLAN_DIR}}/prd.json`
- Pick any task from the available list

## Context Window Management

After each tool call, the hook reports current context usage as feedback.

**At ~60% context**: Start planning to stop soon.

**At ~80% context**: STOP IMMEDIATELY. Make NO more tool calls. Save your work:

1. **Read progress.txt** to see the format
2. **Write `## In Progress` section** with:
   - What you completed
   - Current working state
   - Exact next steps to try
   - Key learnings
3. **Do NOT mark task as passed** in prd.json
4. **Commit**: `wip: [ID] - partial progress`
5. **Stop the session** - next agent will continue with fresh context

Example `## In Progress` section:

## Progress Format

When completing a task, APPEND to progress.txt:

---
## [Date] - [Task ID]
- What was implemented
- Files changed
- **Learnings:**
  - Patterns discovered
  - Gotchas encountered
---

If you completed in-progress work, clear the `## In Progress` section.

## Codebase Patterns

Add reusable patterns to the TOP of progress.txt under "## Codebase Patterns":

## AGENTS.md Updates

Update AGENTS.md in directories with edited files if you discover:
- "When modifying X, also update Y"
- "This module uses pattern Z"
- "Tests require dev server running"

Do NOT add task-specific details or temporary notes.

## Stop Condition

If ALL tasks pass, reply:
<promise>COMPLETE</promise>

Otherwise end normally.

# Ralph Progress Log
Started: {{DATE}}

## Codebase Patterns
<!-- Add discovered patterns here -->

## Key Files
<!-- Add important files discovered during implementation -->

## In Progress
<!-- Partial work from interrupted sessions. Next iteration MUST continue this. -->

---

#!/bin/bash
set -e

MAX_ITERATIONS=${1:-25}
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

echo "🚀 Starting Ralph Loop"
echo "Plan: $SCRIPT_DIR"
echo "Max iterations: $MAX_ITERATIONS"

for i in $(seq 1 $MAX_ITERATIONS); do
  echo ""
  echo "═══════════════════════════════════════"
  echo "  Iteration $i of $MAX_ITERATIONS"
  echo "═══════════════════════════════════════"

  OUTPUT=$(claude -p --dangerously-skip-permissions --verbose < "$SCRIPT_DIR/prompt.md" 2>&1 | tee /dev/stderr) || true

  if echo "$OUTPUT" | grep -q "<promise>COMPLETE</promise>"; then
    echo ""
    echo "✅ All tasks complete!"
    exit 0
  fi

  sleep 2
done

echo ""
echo "⚠️ Max iterations reached ($MAX_ITERATIONS)"
echo "Check progress: cat $SCRIPT_DIR/progress.txt"
exit 1

#!/bin/bash
set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

echo "🔍 Running single iteration (for testing PRD quality)"
echo "Plan: $SCRIPT_DIR"
echo ""

claude -p --dangerously-skip-permissions --verbose < "$SCRIPT_DIR/prompt.md"

echo ""
echo "Single iteration complete."
echo "Check: $SCRIPT_DIR/prd.json and $SCRIPT_DIR/progress.txt"