Ralph Loop — Default REQ-Level Iterative Build

Core principles: isolated context per REQ, TDD-first, full regression every iteration, token efficiency (40-67% savings vs parallel).

Triggers

Keywords: ralph-loop, process one REQ, Phase 2 BUILD, iterate REQ, isolated REQ build

Use when: executing Sprint-Flow Phase 2 BUILD; reading specification.yaml to implement REQs one-by-one; needing controlled token budget per REQ; preventing context pollution between REQs; full regression needed per step.

Don't use: 1-2 simple independent REQs (use parallel); emergency hotfix; --mode parallel is explicitly set.

Architecture Overview

Ralph Loop is the default Phase 2 BUILD mode. Each REQ gets a fresh subagent context:

Sprint-Flow Phase 2 (default):
  ralph-loop → per-REQ iteration → clean context each time → full regression

Sprint-Flow Phase 2 (--mode parallel):
  dispatching-parallel-agents → parallel dispatch → context grows linearly

Full Flow

Phase 0: 准备 → 读取 specification.yaml → 构建依赖图 → 拓扑排序
    │
    ▼
Phase 1: 迭代循环 (max_iterations=15 默认)
    │
    ├── 取下一个 READY REQ（依赖已满足，优先级最高）
    │
    ├── 测试基础设施检查 (test-utils.ts)
    │     ├── 不存在或接口缺失 → dispatch 生成 subagent (retry max 2)
    │     └── 已存在 → 注入 API 摘要到 subagent context
    │
    ├── Dispatch 独立 subagent (unspecified-high + test-driven-development)
    │     Context: 当前 REQ + AC + permanent learnings + contextual learnings
    │              + AGENTS.md + git log -5 + Mock 边界策略
    │
    ├── 三层验证
    │     ├── L1: typecheck + lint → FAIL? → retry
    │     ├── L1b: 测试行占比 ≥ 40% → FAIL? → retry
    │     ├── L2: 全量测试（ALL tests）→ FAIL? → retry
    │     └── L3: coverage ≥ 80% → FAIL? → retry
    │
    ├── PASS → git commit → 标记 done
    │        → 写 learnings (permanent/contextual)
    │        → orchestrator 更新 AGENTS.md
    │        → 继续下一个 READY REQ
    │
    └── FAIL (max 3 retry) → BLOCK → 用户决策 (skip/manual/stop/rollback)
        │
        ▼
    终止条件: ALL DONE → COMPLETE | max_iterations → PARTIAL | BLOCK → WAIT_USER

输入格式 (specification.yaml)

specification:
  requirements:
    - id: REQ-001
      description: "Create User Model"
      acceptance_criteria:
        - id: AC-001-01
          criteria: "email (unique), password_hash, created_at"
      priority: 1
      status: pending
    - id: REQ-002
      description: "Password encryption"
      depends_on: [REQ-001]
      priority: 2
      status: pending

每个 REQ 自动作为迭代单元，所有 AC-XXX-XX 作为验收标准。

依赖排序

1. 拓扑排序（Kahn's algorithm，基于 depends_on）
2. 同层按 priority 升序
3. 循环依赖 → BLOCK + 报告循环链

状态机

PENDING → test_infra_check → [infra needed?] → test_infra_dispatch
                                        │                    │
                                        │ FAIL (max 2)      │ pass
                                        ▼                    ▼
                                    BLOCK/fallback      in_progress → done (commit)
                                        │                  │
                                        │  depend not met  │ all done → COMPLETE
                                        ▼                  ▼
                                     PENDING (waiting)  RETRY (n≤3, 注入错误)
                                                            │
                                                         n≥3 → BLOCKED

崩溃恢复：检查 checkpoint → 跳过已 done REQs → 从下一个 pending 继续。

Retry 策略

Mock 边界策略

Mock 密度上限：mock/spy/fn 行数 > 总测试行 30% → 必须加 // @mock-justified: <理由>。

Learnings 分类

AGENTS.md 更新机制

Orchestrator 统一执行，subagent 输出 agentmd_addition 字段，orchestrator append。>500 行触发归档到 .sprint-state/ralph-loop/agents-archive/。

Output Format

{
  "skill_name": "ralph-loop",
  "version": "2.0.0",
  "requirements": { "total": 6, "done": 4, "pending": 1, "blocked": 1, "skipped": 0 },
  "learnings": {
    "permanent": ["Auth middleware must run before validation"],
    "contextual": ["migration files must be in src/migrations/"]
  },
  "status": "running",
  "checkpoint_at": "2026-05-08T10:30:00Z"
}

Eval: done + pending + blocked + skipped == total, iteration <= max_iterations.

Scope

In Scope:

• Phase 2 BUILD 的 REQ 级迭代构建
• 从 specification.yaml 读取需求实现
• TDD + 全量回归测试
• Learnings 持久化 + 依赖排序 + 崩溃恢复

Out of Scope:

• Phase 0-1 (THINK/PLAN) / Phase 3-6 (REVIEW/SHIP/等)
• 并行模式（--mode parallel）
• 紧急热修复
• 非 spec 定义的需求

Token Savings

Anti-Patterns

References

• Components — 系统提示/状态记忆/中间件/技能调用/构建步骤分解
• Workflow Details — 详细执行步骤 + Output Contract 检查清单
• Phase 2 Integration — Sprint-Flow 集成细节
• Progress Log Template
• Design Doc: ralph-loop v3.0