Ralph Wiggum v2 - Autonomous TDD Development Loop

Quick Start

/ralph-wiggum-v2:ralph-loop --project "diablo-starcraft" --completion-promise "DIABLO_STARCRAFT_COMPLETE"

Overview

Autonomous TDD development loop that uses parallel agent swarms to review code, discover issues, and fix them with test-first methodology until convergence criteria are met.

Workflow

Phase 1: Discovery & Initialization

1. Locate or create state file: {project}/.ralph/state.json
2. Locate or create categories file: {project}/.ralph/categories.json
3. Bootstrap categories from codebase structure if empty

Phase 2: Parallel Agent Review Swarm

Spawn 3-5 parallel agents with:

• Random category (weighted toward lowest scores)
• Random subcategory within that category
• Random review style (never same as last 3 used)
• Unique focus area (no overlap between agents)

Phase 3: TDD Implementation Cycle

For each finding:

1. Write failing test first
2. Implement minimal fix
3. Verify test passes
4. Update state

Phase 4: Category Evolution

After each iteration:

1. Merge new discoveries
2. Recalculate scores
3. Meta-review (every 5 iterations)

Phase 5: Convergence Detection

Complete when:

• 10 consecutive clean iterations
• All category scores >= 95/100
• All tests passing
• Game runs without crashes

State Schema

{
  "project": "diablo-starcraft",
  "iteration": 0,
  "consecutiveCleanIterations": 0,
  "requiredCleanIterations": 10,
  "completionPromise": "DIABLO_STARCRAFT_COMPLETE",
  "categories": {},
  "discoveryLog": [],
  "lastReviewStyles": [],
  "agentHistory": [],
  "startedAt": "<timestamp>",
  "lastUpdated": "<timestamp>"
}

Categories Schema

{
  "categories": {
    "<category_name>": {
      "score": 50,
      "maxScore": 100,
      "subcategories": {
        "<subcategory_name>": {
          "score": 50,
          "issues": [],
          "lastReviewed": null,
          "reviewCount": 0
        }
      },
      "discoveredAt": 0,
      "lastUpdated": "<timestamp>"
    }
  }
}

Review Styles

Code Quality

Reliability

Performance

Security

Architecture

Testing

Game-Specific

Meta

Agent Output Format

{
  "agentId": "<uuid>",
  "category": "<category>",
  "subcategory": "<subcategory>",
  "reviewStyle": "<style>",
  "filesReviewed": ["<paths>"],
  "findings": [
    {
      "severity": "critical|major|minor|nitpick",
      "type": "<issue_type>",
      "location": "<file:line>",
      "description": "<what's wrong>",
      "suggestedFix": "<how to fix>",
      "requiresTest": true,
      "testWritten": false,
      "fixed": false,
      "newSubcategory": null
    }
  ],
  "scoreAdjustment": 0,
  "newCategoriesDiscovered": [],
  "cleanReview": false
}

Hard Requirements

• PLAYABLE_LOCAL - Runs in browser, playable start-to-finish
• TDD_ENFORCED - No fix without failing test first
• ZERO_CRASHES - No unhandled exceptions in any path
• ALL_TESTS_PASS - 100% test suite green
• SCORES_95_PLUS - Every category at 95+/100
• CLEAN_CONVERGENCE - 10 consecutive clean iterations

Iteration Loop

LOOP:
  1. Load state from .ralph/state.json
  2. Load categories from .ralph/categories.json
  3. Increment iteration counter
  4. Select 3-5 lowest-scoring categories for review
  5. Spawn parallel review agents (use Task tool)
  6. Collect findings from all agents
  7. Sort findings by severity (critical → major → minor)
  8. TDD fix each finding:
     a. Write failing test
     b. Implement minimal fix
     c. Verify test passes
     d. Run full test suite
  9. Update scores and state
  10. Check convergence criteria:
      - All agents returned cleanReview: true?
      - No critical/major findings?
      - All tests passing?
      - No new categories discovered?
  11. IF clean: consecutiveCleanIterations++
      IF dirty: consecutiveCleanIterations = 0
  12. IF consecutiveCleanIterations >= 10 AND all scores >= 95:
      → CONVERGED: Run final verification
      ELSE: → Continue loop

Final Verification

When convergence criteria met:

1. Full test suite run
2. TypeScript strict mode check
3. Build production bundle
4. Verify game loads and plays
5. Generate completion report
6. Output: {COMPLETION_PROMISE} achieved

Game-Specific Categories (Diablo-StarCraft)

Auto-discovered from codebase:

• engine/ → Engine (Game, Camera)
• mechanics/ → Mechanics (Player, Ability, Item)
• ai/ → AI (Enemy, Pathfinding)
• graphics/ → Graphics (Renderer, VFX)
• audio/ → Audio (AudioManager)
• physics/ → Physics (Collision)
• world/ → World (Tilemap)
• persistence/ → Persistence (SaveManager)
• input/ → Input (InputManager)
• utils/ → Utils (isometric)

Game system categories:

• Combat → Damage, resistance, crits, DOTs
• Skills → Abilities, cooldowns, scaling
• Loot → Drops, rarity, equipment
• Progression → XP, levels, stats
• Waves → Spawning, difficulty, bosses
• UI/HUD → Health bars, buffs, minimap
• Save/Load → Persistence, state restoration