adaptationio/ralph-wiggum-v2

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

| Style | Focus | |-------|-------| | NITPICKER | Formatting, naming, tiny inconsistencies | | REFACTORER | Duplication, abstraction opportunities | | DRY_ENFORCER | Copy-paste code, repeated patterns | | TYPE_ZEALOT | Type safety, any usage, casting | | SOLID_ADHERENT | SOLID principle violations | | API_PURIST | Interface design, contracts, signatures |

Reliability

| Style | Focus | |-------|-------| | DEBUGGER | Logic errors, off-by-one, wrong operators | | EDGE_CASE_HUNTER | Boundary conditions, null/undefined | | ERROR_HANDLER | Missing try/catch, unhandled promises | | STATE_MACHINE_ANALYST | Invalid state transitions | | CONCURRENCY_EXPERT | Race conditions, async bugs | | MEMORY_LEAK_HUNTER | Listeners not removed, growing arrays |

Performance

| Style | Focus | |-------|-------| | PERFORMANCE_HAWK | O(n²), unnecessary renders, hot paths | | ALLOCATION_AUDITOR | Object churn, GC pressure | | RENDER_OPTIMIZER | DOM thrashing, layout thrashing |

Security

| Style | Focus | |-------|-------| | SECURITY_AUDITOR | XSS, injection, unsafe operations | | INPUT_VALIDATOR | Unsanitized user input |

Architecture

| Style | Focus | |-------|-------| | ARCHITECT | Coupling, cohesion, separation of concerns | | DEPENDENCY_AUDITOR | Circular deps, tight coupling | | LAYER_GUARDIAN | Layer violations, wrong abstractions |

Testing

| Style | Focus | |-------|-------| | TEST_SKEPTIC | Coverage gaps, weak assertions | | MUTATION_TESTER | Tests that always pass | | INTEGRATION_ANALYST | Unit vs integration gaps |

Game-Specific

| Style | Focus | |-------|-------| | DIABLO_VETERAN | ARPG conventions, loot, skills, combat feel | | STARCRAFT_FAN | Faction identity, unit feel, SC universe | | GAME_FEEL_EXPERT | Juice, polish, responsiveness | | BALANCE_DESIGNER | Numbers, progression, fairness | | PLAYER_PSYCHOLOGY | Motivation, reward loops | | SPEEDRUNNER | Exploits, sequence breaks | | COMPLETIONIST | Missing edge cases in content | | FIRST_TIME_USER | Onboarding, confusion points |

Meta

| Style | Focus | |-------|-------| | FRESH_EYES | What would confuse a new developer? | | DOCUMENTATION_STICKLER | Missing/wrong comments | | FUTURE_MAINTAINER | Technical debt accumulation |

---

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