Back to Details

ralph-wiggum-v2

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ralph Wiggum v2 - Autonomous TDD Development Loop

Ralph Wiggum v2 - 自动化TDD开发循环

Quick Start

快速开始

/ralph-wiggum-v2:ralph-loop --project "diablo-starcraft" --completion-promise "DIABLO_STARCRAFT_COMPLETE"
/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.
这是一个自动化TDD开发循环，利用并行Agent集群评审代码、发现问题，并采用测试优先的方法论修复问题，直到满足收敛标准。

Workflow

工作流程

Phase 1: Discovery & Initialization

阶段1：发现与初始化

  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
  1. 定位或创建状态文件：
    {project}/.ralph/state.json
  2. 定位或创建分类文件：
    {project}/.ralph/categories.json
  3. 若分类文件为空，则从代码库结构引导生成分类

Phase 2: Parallel Agent Review Swarm

阶段2：并行Agent评审集群

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)
生成3-5个并行Agent，每个Agent具备：
  • 随机分配分类（权重倾向于得分最低的分类）
  • 该分类下的随机子分类
  • 随机评审风格（与最近3次使用的风格不同）
  • 唯一的聚焦领域（Agent之间无重叠）

Phase 3: TDD Implementation Cycle

阶段3：TDD实施周期

For each finding:
  1. Write failing test first
  2. Implement minimal fix
  3. Verify test passes
  4. Update state
针对每个发现的问题：
  1. 先编写失败的测试用例
  2. 实现最小化修复
  3. 验证测试通过
  4. 更新状态

Phase 4: Category Evolution

阶段4：分类演进

After each iteration:
  1. Merge new discoveries
  2. Recalculate scores
  3. Meta-review (every 5 iterations)
每次迭代后：
  1. 合并新发现的内容
  2. 重新计算得分
  3. 元评审（每5次迭代进行一次）

Phase 5: Convergence Detection

阶段5：收敛检测

Complete when:
  • 10 consecutive clean iterations
  • All category scores >= 95/100
  • All tests passing
  • Game runs without crashes
满足以下条件时完成循环：
  • 连续10次清洁迭代
  • 所有分类得分≥95/100
  • 所有测试通过
  • 游戏运行无崩溃

State Schema

状态 Schema

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

Categories Schema

分类 Schema

json
{
  "categories": {
    "<category_name>": {
      "score": 50,
      "maxScore": 100,
      "subcategories": {
        "<subcategory_name>": {
          "score": 50,
          "issues": [],
          "lastReviewed": null,
          "reviewCount": 0
        }
      },
      "discoveredAt": 0,
      "lastUpdated": "<timestamp>"
    }
  }
}
json
{
  "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

代码质量

StyleFocus
NITPICKERFormatting, naming, tiny inconsistencies
REFACTORERDuplication, abstraction opportunities
DRY_ENFORCERCopy-paste code, repeated patterns
TYPE_ZEALOTType safety, any usage, casting
SOLID_ADHERENTSOLID principle violations
API_PURISTInterface design, contracts, signatures
风格聚焦点
NITPICKER格式、命名、细微不一致性
REFACTORER代码重复、抽象优化机会
DRY_ENFORCER复制粘贴代码、重复模式
TYPE_ZEALOT类型安全、any使用、类型转换
SOLID_ADHERENTSOLID原则违反
API_PURIST接口设计、契约、签名

Reliability

可靠性

StyleFocus
DEBUGGERLogic errors, off-by-one, wrong operators
EDGE_CASE_HUNTERBoundary conditions, null/undefined
ERROR_HANDLERMissing try/catch, unhandled promises
STATE_MACHINE_ANALYSTInvalid state transitions
CONCURRENCY_EXPERTRace conditions, async bugs
MEMORY_LEAK_HUNTERListeners not removed, growing arrays
风格聚焦点
DEBUGGER逻辑错误、差一错误、运算符误用
EDGE_CASE_HUNTER边界条件、null/undefined处理
ERROR_HANDLER缺失try/catch、未处理的Promise
STATE_MACHINE_ANALYST无效状态转换
CONCURRENCY_EXPERT竞态条件、异步Bug
MEMORY_LEAK_HUNTER未移除的监听器、持续增长的数组

Performance

性能

StyleFocus
PERFORMANCE_HAWKO(n²), unnecessary renders, hot paths
ALLOCATION_AUDITORObject churn, GC pressure
RENDER_OPTIMIZERDOM thrashing, layout thrashing
风格聚焦点
PERFORMANCE_HAWKO(n²)复杂度、不必要的渲染、热点路径
ALLOCATION_AUDITOR对象频繁创建、GC压力
RENDER_OPTIMIZERDOM频繁操作、布局抖动

Security

安全性

StyleFocus
SECURITY_AUDITORXSS, injection, unsafe operations
INPUT_VALIDATORUnsanitized user input
风格聚焦点
SECURITY_AUDITORXSS、注入、不安全操作
INPUT_VALIDATOR未 sanitize 的用户输入

Architecture

架构

StyleFocus
ARCHITECTCoupling, cohesion, separation of concerns
DEPENDENCY_AUDITORCircular deps, tight coupling
LAYER_GUARDIANLayer violations, wrong abstractions
风格聚焦点
ARCHITECT耦合度、内聚性、关注点分离
DEPENDENCY_AUDITOR循环依赖、紧耦合
LAYER_GUARDIAN层级违规、错误抽象

Testing

测试

StyleFocus
TEST_SKEPTICCoverage gaps, weak assertions
MUTATION_TESTERTests that always pass
INTEGRATION_ANALYSTUnit vs integration gaps
风格聚焦点
TEST_SKEPTIC覆盖缺口、弱断言
MUTATION_TESTER始终通过的测试用例
INTEGRATION_ANALYST单元测试与集成测试的缺口

Game-Specific

游戏特定

StyleFocus
DIABLO_VETERANARPG conventions, loot, skills, combat feel
STARCRAFT_FANFaction identity, unit feel, SC universe
GAME_FEEL_EXPERTJuice, polish, responsiveness
BALANCE_DESIGNERNumbers, progression, fairness
PLAYER_PSYCHOLOGYMotivation, reward loops
SPEEDRUNNERExploits, sequence breaks
COMPLETIONISTMissing edge cases in content
FIRST_TIME_USEROnboarding, confusion points
风格聚焦点
DIABLO_VETERANARPG惯例、战利品、技能、战斗手感
STARCRAFT_FAN派系特性、单位手感、星际争霸世界观
GAME_FEEL_EXPERT游戏反馈、打磨、响应性
BALANCE_DESIGNER数值、成长、公平性
PLAYER_PSYCHOLOGY玩家动机、奖励循环
SPEEDRUNNER游戏漏洞、序列跳过
COMPLETIONIST内容中的缺失边缘场景
FIRST_TIME_USER新手引导、易混淆点

Meta

元评审

StyleFocus
FRESH_EYESWhat would confuse a new developer?
DOCUMENTATION_STICKLERMissing/wrong comments
FUTURE_MAINTAINERTechnical debt accumulation
风格聚焦点
FRESH_EYES新开发者会困惑的点
DOCUMENTATION_STICKLER缺失/错误的注释
FUTURE_MAINTAINER技术债务累积

Agent Output Format

Agent 输出格式

json
{
  "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
}
json
{
  "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
  • PLAYABLE_LOCAL - 可在浏览器中运行，从头至尾可玩
  • TDD_ENFORCED - 无失败测试用例则不进行修复
  • ZERO_CRASHES - 任何路径下均无未处理异常
  • ALL_TESTS_PASS - 测试套件100%通过
  • SCORES_95_PLUS - 所有分类得分≥95/100
  • CLEAN_CONVERGENCE - 连续10次清洁迭代

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
LOOP:
  1. 从 .ralph/state.json 加载状态
  2. 从 .ralph/categories.json 加载分类
  3. 增加迭代计数器
  4. 选择3-5个得分最低的分类进行评审
  5. 生成并行评审Agent（使用Task工具）
  6. 收集所有Agent的发现结果
  7. 按严重性排序发现结果（严重→主要→次要）
  8. 对每个发现结果执行TDD修复：
     a. 编写失败的测试用例
     b. 实现最小化修复
     c. 验证测试通过
     d. 运行完整测试套件
  9. 更新得分与状态
  10. 检查收敛标准：
      - 所有Agent均返回 cleanReview: true？
      - 无严重/主要发现结果？
      - 所有测试通过？
      - 无新分类被发现？
  11. 若清洁迭代：consecutiveCleanIterations++
      若非清洁迭代：consecutiveCleanIterations = 0
  12. 若 consecutiveCleanIterations ≥10 且所有得分≥95：
      → 已收敛：运行最终验证
      否则：→ 继续循环

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
当满足收敛标准时：
  1. 运行完整测试套件
  2. TypeScript严格模式检查
  3. 构建生产包
  4. 验证游戏可加载并正常运行
  5. 生成完成报告
  6. 输出：
    {COMPLETION_PROMISE}
    已达成

Game-Specific Categories (Diablo-StarCraft)

游戏特定分类（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)
  • engine/ → 引擎（游戏、相机）
  • mechanics/ → 机制（玩家、技能、物品）
  • ai/ → AI（敌人、寻路）
  • graphics/ → 图形（渲染器、视觉特效）
  • audio/ → 音频（音频管理器）
  • physics/ → 物理（碰撞）
  • world/ → 世界（瓦片地图）
  • persistence/ → 持久化（存档管理器）
  • input/ → 输入（输入管理器）
  • utils/ → 工具（等距投影）

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
  • Combat → 伤害、抗性、暴击、持续伤害
  • Skills → 技能、冷却、成长
  • Loot → 掉落、稀有度、装备
  • Progression → 经验值、等级、属性
  • Waves → 生成、难度、Boss
  • UI/HUD → 血条、增益效果、小地图
  • Save/Load → 持久化、状态恢复