ralph-tdd（拉尔夫 TDD）

Ralph TDD Loop

Naming: Skill and script are both ralph-tdd (the capability). Ralph is designed to run AFK (away-from-keyboard); the script is ralph-tdd.sh.

Ralph runs AI coding agents in an AFK loop. The agent picks tasks from a backlog, implements with TDD, verifies test quality with mutation testing, and commits. You come back to working code.

TDD: Use the mattpocock/skills/tdd skill for red-green-refactor and vertical slicing (one test → one impl). Install: npx skills add mattpocock/skills@tdd. Ralph adds the backlog loop and mutation gate on top.

Architecture

┌──────────────────────────────────────────────────────┐
│ RALPH OUTER LOOP (per task)                          │
│                                                      │
│  1. Read .ralph/progress.md + .ralph/lessons.md     │
│  2. Read backlog (Linear, GitHub Issues, PRD, etc.)  │
│  3. Pick highest-priority unfinished task             │
│  4. TDD red-green-refactor (see ref below)           │
│  5. Run feedback loops (types, lint, tests)           │
│  6. Verify: "Would a staff engineer approve this?"   │
│                                                      │
│  ┌────────────────────────────────────────────────┐  │
│  │ MUTATION QUALITY GATE (see ref below)          │  │
│  │  7. Run incremental mutation testing           │  │
│  │  8. Kill survivors on touched files            │  │
│  │  9. Repeat until score >= 95%                  │  │
│  └────────────────────────────────────────────────┘  │
│                                                      │
│  10. Mark task done, append to .ralph/progress.md    │
│      Update .ralph/lessons.md if anything learned    │
│  11. Commit                                          │
└──────────────────────────────────────────────────────┘

Outer loop = Ralph picking tasks. Inner loop = mutation quality gate. The gate prevents "green but useless" tests — a constraint the AI can't cheat its way out of.

Mutation quality gate (steps 7–9)

After tests pass: run npm run test:mutate:incremental (or project equivalent). For each surviving mutant on files you changed, write a test that would fail with the mutation, then re-run until mutation score ≥ 95% on those files. Full workflow and setup: use the mutation-testing skill (this repo; install with Ralph stack).

Reference guide

Everything except progress format comes from installed skills (install with Ralph stack). Project-specific commands: use package.json scripts and config (vitest.config, playwright.config).

Pre-Flight Checklist

Before going AFK, gather all of this. Ask the user until every item is answered.

After gathering answers, confirm back:

Ready to go AFK:
- Project: [name] on branch [branch]
- Backlog: [source] — [N] iterations, priority order
- Agent: [runtime] with [permission mode]
- Feedback: tsc → biome → vitest → stryker (incremental)
- Commit after each task

Anything to change?

Only start after user confirms.

Agent Runtimes

The Ralph TDD script supports multiple agent CLIs. Set AGENT_CMD in the script.

For true AFK, use full-auto permission modes. Semi-auto modes may prompt for approval and stall the loop.

Permission Modes

Recommendation: Use full-auto for AFK. The mutation testing quality gate and test suite act as safety nets. If tests pass and mutations are killed, the code is likely correct regardless of what commands ran.

Setup

1. Run the Ralph TDD script

See scripts/ralph-tdd.sh and run it directly from the skills repo (no copy required).

Make executable:

chmod +x /Users/jonathanmumm/src/skills/ralph-tdd/scripts/ralph-tdd.sh

Run:

/Users/jonathanmumm/src/skills/ralph-tdd/scripts/ralph-tdd.sh \
  --project /abs/path/to/your-repo \
  --iterations 5

Optional:

# Use Claude runtime instead of Codex
/Users/jonathanmumm/src/skills/ralph-tdd/scripts/ralph-tdd.sh \
  --project /abs/path/to/your-repo \
  --iterations 5 \
  --agent claude

Typically run AFK.

2. Create.ralph/progress.md

Ralph scripts write progress and lessons under .ralph/ and ensure .ralph/ is in the project’s .gitignore so these files are not committed.

# Progress

Agent working memory. Delete after sprint.

---

See references/progress-format.md for entry format and promise tags (COMPLETE, BLOCKED, DECIDE).

3. Create AGENTS.md (if missing)

The agent's onboarding doc — project description, tech stack, feedback commands, conventions, off-limits. If AGENTS.md doesn't exist, the Ralph script instructs the agent to run the create-agents-md skill (this repo) to create it from the template, then continue.

4. Create.ralph/lessons.md

# Lessons

Patterns and rules learned during development. Review at the start of each iteration.

---

The agent updates this file after any failed approach, mistake, or course correction. Unlike.ralph/progress.md (what was done),.ralph/lessons.md captures what to avoid — it persists across iterations and prevents repeating the same class of mistake.

See references/progress-format.md for entry format and promise tags (COMPLETE, BLOCKED, DECIDE).

Task Prioritization

1. Architectural decisions — cascade through entire codebase
2. Integration points — reveals incompatibilities early
3. Unknowns / spikes — fail fast
4. Features — implementation work
5. Polish — save for last

Task Sources & Work Tracking

Use Linear for tracking work when the backlog is a Linear team: mark the current task in-progress when starting, and mark it done when the task is complete (before committing). Use Linear MCP or linear CLI. Same idea for GitHub Issues or a local PRD — update status so progress is visible.

Optional: Critical work before backlog

Some setups (e.g. pro-ralph) use a STEERING.md (or similar) file that the agent must complete before picking backlog tasks: one-time env fixes, install deps, install Playwright browsers, start dev server, etc. You can add a step in your prompt: "Check.agent/STEERING.md (or PROJECT_ROOT/STEERING.md); complete items in sequence and remove when done. Only then proceed to the backlog." This avoids burning iterations on broken env.

Alternative Loop Types

Same Ralph pattern works for non-feature work: