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
- Locate or create state file:
{project}/.ralph/state.json
- Locate or create categories file:
{project}/.ralph/categories.json
- 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:
- Write failing test first
- Implement minimal fix
- Verify test passes
- Update state
Phase 4: Category Evolution
After each iteration:
- Merge new discoveries
- Recalculate scores
- 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
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:
- Full test suite run
- TypeScript strict mode check
- Build production bundle
- Verify game loads and plays
- Generate completion report
- 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
1---2name: ralph-wiggum-v23description: Autonomous TDD development loop with parallel agent swarm, category evolution, and convergence detection. Use when running autonomous game development, quality improvement loops, or comprehensive codebase reviews.4pipeline-status:5 - new6metadata:7 source: https://skillmd.com/skills/delorenj/ralph-wiggum-v28---910# Ralph Wiggum v2 - Autonomous TDD Development Loop1112## Quick Start1314```15/ralph-wiggum-v2:ralph-loop --project "diablo-starcraft" --completion-promise "DIABLO_STARCRAFT_COMPLETE"16```1718## Overview1920Autonomous 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.2122## Workflow2324### Phase 1: Discovery & Initialization25261. **Locate or create state file**: `{project}/.ralph/state.json`272. **Locate or create categories file**: `{project}/.ralph/categories.json`283. **Bootstrap categories** from codebase structure if empty2930### Phase 2: Parallel Agent Review Swarm3132Spawn 3-5 parallel agents with:33- Random category (weighted toward lowest scores)34- Random subcategory within that category35- Random review style (never same as last 3 used)36- Unique focus area (no overlap between agents)3738### Phase 3: TDD Implementation Cycle3940For each finding:411. Write failing test first422. Implement minimal fix433. Verify test passes444. Update state4546### Phase 4: Category Evolution4748After each iteration:491. Merge new discoveries502. Recalculate scores513. Meta-review (every 5 iterations)5253### Phase 5: Convergence Detection5455Complete when:56- 10 consecutive clean iterations57- All category scores >= 95/10058- All tests passing59- Game runs without crashes6061---6263## State Schema6465```json66{67 "project": "diablo-starcraft",68 "iteration": 0,69 "consecutiveCleanIterations": 0,70 "requiredCleanIterations": 10,71 "completionPromise": "DIABLO_STARCRAFT_COMPLETE",72 "categories": {},73 "discoveryLog": [],74 "lastReviewStyles": [],75 "agentHistory": [],76 "startedAt": "<timestamp>",77 "lastUpdated": "<timestamp>"78}79```8081## Categories Schema8283```json84{85 "categories": {86 "<category_name>": {87 "score": 50,88 "maxScore": 100,89 "subcategories": {90 "<subcategory_name>": {91 "score": 50,92 "issues": [],93 "lastReviewed": null,94 "reviewCount": 095 }96 },97 "discoveredAt": 0,98 "lastUpdated": "<timestamp>"99 }100 }101}102```103104---105106## Review Styles107108### Code Quality109| Style | Focus |110|-------|-------|111| NITPICKER | Formatting, naming, tiny inconsistencies |112| REFACTORER | Duplication, abstraction opportunities |113| DRY_ENFORCER | Copy-paste code, repeated patterns |114| TYPE_ZEALOT | Type safety, any usage, casting |115| SOLID_ADHERENT | SOLID principle violations |116| API_PURIST | Interface design, contracts, signatures |117118### Reliability119| Style | Focus |120|-------|-------|121| DEBUGGER | Logic errors, off-by-one, wrong operators |122| EDGE_CASE_HUNTER | Boundary conditions, null/undefined |123| ERROR_HANDLER | Missing try/catch, unhandled promises |124| STATE_MACHINE_ANALYST | Invalid state transitions |125| CONCURRENCY_EXPERT | Race conditions, async bugs |126| MEMORY_LEAK_HUNTER | Listeners not removed, growing arrays |127128### Performance129| Style | Focus |130|-------|-------|131| PERFORMANCE_HAWK | O(n²), unnecessary renders, hot paths |132| ALLOCATION_AUDITOR | Object churn, GC pressure |133| RENDER_OPTIMIZER | DOM thrashing, layout thrashing |134135### Security136| Style | Focus |137|-------|-------|138| SECURITY_AUDITOR | XSS, injection, unsafe operations |139| INPUT_VALIDATOR | Unsanitized user input |140141### Architecture142| Style | Focus |143|-------|-------|144| ARCHITECT | Coupling, cohesion, separation of concerns |145| DEPENDENCY_AUDITOR | Circular deps, tight coupling |146| LAYER_GUARDIAN | Layer violations, wrong abstractions |147148### Testing149| Style | Focus |150|-------|-------|151| TEST_SKEPTIC | Coverage gaps, weak assertions |152| MUTATION_TESTER | Tests that always pass |153| INTEGRATION_ANALYST | Unit vs integration gaps |154155### Game-Specific156| Style | Focus |157|-------|-------|158| DIABLO_VETERAN | ARPG conventions, loot, skills, combat feel |159| STARCRAFT_FAN | Faction identity, unit feel, SC universe |160| GAME_FEEL_EXPERT | Juice, polish, responsiveness |161| BALANCE_DESIGNER | Numbers, progression, fairness |162| PLAYER_PSYCHOLOGY | Motivation, reward loops |163| SPEEDRUNNER | Exploits, sequence breaks |164| COMPLETIONIST | Missing edge cases in content |165| FIRST_TIME_USER | Onboarding, confusion points |166167### Meta168| Style | Focus |169|-------|-------|170| FRESH_EYES | What would confuse a new developer? |171| DOCUMENTATION_STICKLER | Missing/wrong comments |172| FUTURE_MAINTAINER | Technical debt accumulation |173174---175176## Agent Output Format177178```json179{180 "agentId": "<uuid>",181 "category": "<category>",182 "subcategory": "<subcategory>",183 "reviewStyle": "<style>",184 "filesReviewed": ["<paths>"],185 "findings": [186 {187 "severity": "critical|major|minor|nitpick",188 "type": "<issue_type>",189 "location": "<file:line>",190 "description": "<what's wrong>",191 "suggestedFix": "<how to fix>",192 "requiresTest": true,193 "testWritten": false,194 "fixed": false,195 "newSubcategory": null196 }197 ],198 "scoreAdjustment": 0,199 "newCategoriesDiscovered": [],200 "cleanReview": false201}202```203204---205206## Hard Requirements207208- [ ] **PLAYABLE_LOCAL** - Runs in browser, playable start-to-finish209- [ ] **TDD_ENFORCED** - No fix without failing test first210- [ ] **ZERO_CRASHES** - No unhandled exceptions in any path211- [ ] **ALL_TESTS_PASS** - 100% test suite green212- [ ] **SCORES_95_PLUS** - Every category at 95+/100213- [ ] **CLEAN_CONVERGENCE** - 10 consecutive clean iterations214215---216217## Iteration Loop218219```220LOOP:221 1. Load state from .ralph/state.json222 2. Load categories from .ralph/categories.json223 3. Increment iteration counter224 4. Select 3-5 lowest-scoring categories for review225 5. Spawn parallel review agents (use Task tool)226 6. Collect findings from all agents227 7. Sort findings by severity (critical → major → minor)228 8. TDD fix each finding:229 a. Write failing test230 b. Implement minimal fix231 c. Verify test passes232 d. Run full test suite233 9. Update scores and state234 10. Check convergence criteria:235 - All agents returned cleanReview: true?236 - No critical/major findings?237 - All tests passing?238 - No new categories discovered?239 11. IF clean: consecutiveCleanIterations++240 IF dirty: consecutiveCleanIterations = 0241 12. IF consecutiveCleanIterations >= 10 AND all scores >= 95:242 → CONVERGED: Run final verification243 ELSE: → Continue loop244```245246---247248## Final Verification249250When convergence criteria met:2511. Full test suite run2522. TypeScript strict mode check2533. Build production bundle2544. Verify game loads and plays2555. Generate completion report2566. Output: `{COMPLETION_PROMISE}` achieved257258---259260## Game-Specific Categories (Diablo-StarCraft)261262### Auto-discovered from codebase:263- **engine/** → Engine (Game, Camera)264- **mechanics/** → Mechanics (Player, Ability, Item)265- **ai/** → AI (Enemy, Pathfinding)266- **graphics/** → Graphics (Renderer, VFX)267- **audio/** → Audio (AudioManager)268- **physics/** → Physics (Collision)269- **world/** → World (Tilemap)270- **persistence/** → Persistence (SaveManager)271- **input/** → Input (InputManager)272- **utils/** → Utils (isometric)273274### Game system categories:275- **Combat** → Damage, resistance, crits, DOTs276- **Skills** → Abilities, cooldowns, scaling277- **Loot** → Drops, rarity, equipment278- **Progression** → XP, levels, stats279- **Waves** → Spawning, difficulty, bosses280- **UI/HUD** → Health bars, buffs, minimap281- **Save/Load** → Persistence, state restoration