A template for coordinating AI agent teams with Claude Code. Combines Agent Teams (parallel Claude instances with a shared task board) and the Ralph Wiggum Loop (autonomous iteration until tests pass) into a hybrid workflow for building features.
Read the blog post: When Agent Teams Meet the Ralph Wiggum Loop — the story behind this template, what broke, and the 13 lessons that shaped it.
Feature Plan ──> team-planner ──> Team Brief ──> Human Approval
|
┌─────────────────┴─────────────────┐
│ │
Docs Track Code Track
(single-shot) (Ralph loops)
│ │
flows-writer ┌─────┬───────┤
│ │ │ │
test-writer wt-A wt-B wt-C
│ │
└─────────────────┬─────────────────┘
│
build-validator
│
Human Review
Docs track runs as single-shot agents with human review — documentation and tests need judgment.
Code track runs as Ralph loops in git worktrees — mechanical work that iterates until build + test passes.
Both tracks run in parallel. A build-validator agent verifies the integrated result.
Click "Use this template" on GitHub, or copy the folders manually:
cp -r .claude/ /path/to/your-project/.claude/
cp -r .ralph/ /path/to/your-project/.ralph/.ralph/AGENTS.md — Replace the build/test commands with yours:
## Validation Commands
- `cargo build` # your build command
- `cargo test` # your test command.ralph/loop.sh — Update the --allowedTools section (~line 100) with your commands:
"Bash(cargo build)" "Bash(cargo test)" \.claude/agents/team-planner.md — Fill in the "Key Context" section at the bottom with your tech stack, test conventions, and project structure.
Create a markdown document describing what you want to build. See examples/planned-feature-example.md for the format.
/build-feature path/to/your/planned-feature.md
The skill will:
- Run the team-planner to decompose the work
- Show you the plan for approval
- Spawn teammates (single-shot or Ralph loops)
- Validate the integrated result
- Report what was built
.claude/
├── skills/build-feature/SKILL.md # Orchestration skill (the /build-feature command)
└── agents/
├── team-planner.md # Decomposes features into team briefs
└── build-validator.md # Validates build + tests + shared contracts
.ralph/
├── loop.sh # Ralph Wiggum iteration loop
├── launch.sh # Create worktree + start loop in tmux
├── cleanup.sh # Merge branch + remove worktree
├── AGENTS.md # Template agent instructions (customize this)
└── plans/
└── example-feature.md # Example PLAN.md showing the format
docs/
├── architecture.md # How the pieces fit together
├── ralph-loop-guide.md # Deep dive on the Ralph loop pattern
├── shared-contracts-guide.md # Why contracts matter + how to define them
└── lessons-learned.md # 13 lessons from production
examples/
├── planned-feature-example.md # Example input: a feature plan
└── team-brief-example.md # Example output: what team-planner produces
| Mode | Used For | How It Works |
|---|---|---|
| Single-shot | Creative work (docs, tests, API design) | Spawn once, plan approval, human reviews output |
| Ralph loop | Mechanical work (bug fixes, boilerplate) | Iterate in git worktree until build + tests pass |
Choose Ralph when ALL of these apply:
- Output is machine-verifiable (tests pass, build succeeds)
- Scope is tightly bounded (specific files)
- Does NOT require judgment (no UX, no API design)
- Could take multiple attempts
When in doubt, default to single-shot.
The #1 cause of integration failures is two agents inventing different identifiers for the same thing. Shared contracts solve this — the team-planner defines exact values (test IDs, interfaces, function signatures) and embeds them in each relevant agent's prompt.
See docs/shared-contracts-guide.md for details and examples.
In production, agents commit their own changes about 1 in 9 times. loop.sh includes a safety net that auto-commits staged changes after each iteration. This is essential, not optional.
- Claude Code — The CLI tool
- Agent Teams — Enable with
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1(experimental feature) - tmux — Required for Ralph loops (
brew install tmuxon macOS) - git — For worktree isolation
| What | Where | Default |
|---|---|---|
| Build command | .ralph/AGENTS.md |
npm run build |
| Test command | .ralph/AGENTS.md |
npm test |
| E2E test command | SKILL.md quality gates |
npm run test:e2e |
| Install command | .ralph/loop.sh |
npm ci |
| Test ID convention | team-planner.md Key Context |
data-testid |
| Project tech stack | team-planner.md Key Context |
(blank — fill in) |
Approximate per-feature cost with Claude Sonnet:
| Component | Cost |
|---|---|
| Ralph iteration (one task) | ~$1-2 |
| Single-shot teammate | ~$3-8 |
| team-planner | ~$2-4 |
| build-validator | ~$1-3 |
| Typical feature (3-4 teammates) | $15-30 |
Set max_iterations on Ralph teammates to cap cost.
- Architecture — System diagram and component overview
- Ralph Loop Guide — PLAN.md format, AGENTS.md, worktree setup, parallel execution
- Shared Contracts Guide — Why contracts matter, types, rules, common mistakes
- Lessons Learned — 13 lessons from production (each cost at least one failed iteration)
- Feature Plan — Input: what you give to
/build-feature - Team Brief — Output: what the team-planner produces (teammates, contracts, file ownership, spawn prompts)
- PLAN.md — What a Ralph loop agent reads each iteration
The Ralph Wiggum Loop pattern was created by Geoffrey Huntley. Key references:
- The Ralph Wiggum Playbook (paddo.dev)
- 11 Tips for AI Coding with Ralph Wiggum (aihero.dev)
- snarktank/ralph — reference implementation
Agent Teams is an experimental feature in Claude Code.
MIT