# gauntlet-kit

**A ready-to-use Gauntlet Loop for any coding agent.** Point your harness at this repo, say what
you want built, and it builds → gets judged by an independent critic against a real quality bar →
rebuilds, until it wins.

Works in Claude Code, Codex, Cursor, Copilot, Gemini CLI, or anything that reads `AGENTS.md`.

```
Run the Gauntlet Loop from this repo.

Goal: build me a Linear-quality issue tracker.
```

That's the whole interface. → [`START.md`](START.md)

---

## The idea

[Matt Shumer](https://twitter.com/mattshumer_) built a 55,000-line, AAA-looking FPS from a single
prompt by having agents compare their work against **real Call of Duty screenshots** and keep
going until they won. [Ben Tossell wrote up the method](https://somethingbig.ai/gauntlet-loop) as
the *Gauntlet Loop*. The original prompt was one paragraph:

> Build a modern, AAA-quality first-person shooter in Three.js. Break the work among subagents.
> Put every important piece through its own loop with a separate, harsh visual critic. Compare
> our output side by side with real Call of Duty. If ours loses, keep improving it.

Four ideas do the work:

1. **A concrete bar.** Not "make it great" — an artifact you can open, run, or measure. Adjectives
   let an agent declare victory on round one.
2. **Builder ≠ critic.** A builder remembers why it made each choice and will defend it. Verdicts
   come from a fresh context that never saw the reasoning.
3. **Blind A/B.** Strip the labels and randomize the order, or the critic scores "ours" generously
   and the loop ends early.
4. **No round limit.** The bar decides when you're done, not a schedule.

## What this repo adds

The article gives you a prompt. This gives you a **runnable protocol**:

| | Prompt alone | gauntlet-kit |
|---|---|---|
| Bar selection | you write it each time | auto-proposed from a domain library ([`bars/`](bars/README.md)) |
| Loop state | in the agent's context | on disk, survives compaction and resume |
| Blind A/B | "do a blind comparison" | randomized pair on disk, mapping hidden from the judge |
| "Done" | the agent's say-so | `gate` fails without a verdict + evidence artifact |
| Ties | judge's discretion | counted as a loss, by design |
| Progress | ask the agent | self-contained live HTML page |
| Harnesses | copy-paste per tool | entrypoints for Claude Code, Codex, Cursor, Copilot, Gemini |

Zero dependencies. Node 18+. Playwright only if you want automatic screenshots.

## How it runs

```
Phase 0  lock a bar        →  concrete, inspectable, external, above your level
Phase 1  decompose         →  4–12 independently judgeable pieces
Phase 2  the gauntlet      →  per piece: builder → capture → blind A/B → fresh critic → gap → repeat
Phase 3  smoothing         →  make many agents' work feel like one product
Phase 4  stop              →  won, diminishing returns, or budget. Never "it looks good now"
```

The full protocol is [`gauntlet/LOOP.md`](gauntlet/LOOP.md); the hard constraints are
[`gauntlet/RULES.md`](gauntlet/RULES.md). Both are written for an agent to execute, not for you
to read — though they're short.

## Layout

```
AGENTS.md CLAUDE.md GEMINI.md    entrypoints — put any harness into the loop
gauntlet/LOOP.md                 the protocol, phase by phase
gauntlet/RULES.md                the 10 rules that override an agent's instincts
gauntlet/state/                  the ledger: pieces, rounds, verdicts, evidence
agents/                          prompt cards: decomposer, builder, critic, blind judge, smoother
bars/                            how to choose a bar, per domain (+ your reference files)
scripts/gauntlet.mjs             the runner — ledger, blind pairs, gate, progress
scripts/capture.mjs              turn a piece's output into an inspectable artifact
scripts/smoke.mjs                20 checks on the runner's invariants (`npm run smoke`)
progress/                        self-contained live progress page
templates/                       prefab goals: web app, game, CLI, redesign
.claude/                         /gauntlet command + builder & critic subagent types
```

## Watching a run

```bash
node scripts/gauntlet.mjs status     # every piece, round, current gap
node scripts/gauntlet.mjs progress   # writes progress/live.html
node scripts/gauntlet.mjs gate       # exits 1 unless every piece has evidence
```

Watch from a distance. Interrupting a builder mid-round costs you the round.

## Honest limits

- **A bad bar produces a confident bad result.** The bar is the one thing worth your attention.
- **It's expensive.** Many agents, many rounds, real tokens. That's the trade: compute for quality.
- **Some things can't be barred.** If the output can't be inspected, compared, or measured, this
  method has nothing to grip.
- **Critics can still be wrong.** They're calibrated to be harsh and to default to the reference,
  which costs extra rounds — deliberately, since the opposite failure ends the loop early.
- **`done` ≠ won.** A piece that stalls at diminishing returns is reported as stalled, with its
  residual gap. Read the status output before you believe a win.

## Credit

Method: [Matt Shumer](https://twitter.com/mattshumer_/status/2081054356405731740) — original prompt
in [mshumer/Claude-of-Duty](https://github.com/mshumer/Claude-of-Duty/blob/main/prompt.md).
Write-up: [somethingbig.ai/gauntlet-loop](https://somethingbig.ai/gauntlet-loop).
This repo is an independent, unaffiliated packaging of that method.

MIT.