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).

Topic	Use	Load when
TDD	mattpocock/skills@tdd	Red-green-refactor, vertical slices, good vs bad tests
Vitest	antfu/skills@vitest	Unit tests, Vitest API
Mutation testing	mutation-testing skill (this repo)	Stryker, survivors, setup
E2E	wshobson/agents@e2e-testing-patterns	E2E/Playwright patterns
AGENTS.md	create-agents-md skill (this repo)	Creating AGENTS.md when missing
Progress format	references/progress-format.md	Appending to .ralph/progress.md or .ralph/lessons.md (Ralph-specific)

Pre-Flight Checklist

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

#	Question	Default
1	Project name and working directory	—
2	Backlog source (Linear team, GitHub repo, local PRD file)	—
3	Tasks to skip or focus on?	Priority order
4	How many iterations?	5
5	Agent runtime — see Agent Runtimes	Codex
6	Permission mode — see Permission Modes	Full auto
7	Feedback commands: typecheck, lint, test, mutation	Auto-detect
8	Does AGENTS.md exist? If not, the Ralph script will prompt the agent to run the create-agents-md skill first.	—
9	Start fresh .ralph/progress.md or continue existing?	Fresh
10	Does .ralph/lessons.md exist? Create if not (persists across sprints).	—
11	Commit per task, or batch?	Per task
12	Branch — current or create new?	Current
13	Anything off-limits?	None

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.

Runtime	Command	Notes
Codex (default)	`codex --approval-mode full-auto -q`	OpenAI Codex CLI. `-q` for quiet/non-interactive.
Claude Code	`claude -p --dangerously-skip-permissions`	Full auto. Best for AFK.
Claude Code (semi)	`claude -p --permission-mode acceptEdits`	Allows edits, blocks shell. May stall AFK.

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

Permission Modes

Mode	Claude Code Flag	Codex Flag	Risk	Best For
Full auto	`--dangerously-skip-permissions`	`--approval-mode full-auto`	Agent can run any command	Trusted repos, overnight runs
Accept edits	`--permission-mode acceptEdits`	`--approval-mode auto-edit`	Blocks on shell commands	Semi-trusted, may stall
Default	(none)	`--approval-mode suggest`	Blocks on everything	Not suitable for AFK

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

Architectural decisions — cascade through entire codebase
Integration points — reveals incompatibilities early
Unknowns / spikes — fail fast
Features — implementation work
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.

Source	How
Linear	MCP or CLI. Mark issue in-progress → implement → mark done. Preferred when available.
GitHub Issues	`gh issue list`, `gh issue close` (or update labels/state)
PRD file	Local `prd.md` with checklist; tick off items as done

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:

Loop	Focus
Mutation Score	Kill surviving mutants across codebase
Test Coverage	Write tests for uncovered lines
Lint	Fix lint errors one at a time
Refactor	Code smells → extract, simplify