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

• **PLAY

...