build-tournament

name	build-tournament
description	Use when multiple plausible approaches exist, nobody can predict the winner from first principles, and "better" is measurable before any code exists — performance-critical components, algorithm selection, architecture bake-offs. Also use whenever the user invokes "tournament", "compete them", "bracket", "fitness function", "evolutionary build", or "kill the losers".

Tournament Build

Subtractive builds carve by taste; tournaments select by measurement. Use this method when a fitness function can be written down before any code exists — when "better" is measurable, competition beats deliberation. The core contract: the fitness function is frozen before generation begins, and eliminations happen on schedule whether or not you feel ready. A tournament where the judge rewrites the rules mid-bracket, or where losers get indefinite stays of execution, is just exploration with extra ceremony.

Workspace layout

project/
├── TOURNAMENT.md        # spec, fitness function, bracket, round results
├── harness/             # shared test/benchmark harness — competitors may not modify
├── competitors/
│   ├── c1-<one-word-thesis>/
│   ├── c2-<one-word-thesis>/
│   └── ...
├── graveyard/           # eliminated competitors, moved not deleted, with autopsy notes
└── champion/            # created at FINAL

Phases

1. CHARTER

Write into TOURNAMENT.md before any competitor exists:

• Spec: what every competitor must do. Identical for all. Competitors implement the same interface so the harness can drive them interchangeably — define that interface here.
• Fitness function: the scored criteria and their weights. Make it numeric wherever possible (latency p95, memory ceiling, LOC, test-pass count, time-to-first-result). Include at least one cost dimension (complexity, dependency count, LOC) or the tournament will select for maximalism. Where a criterion is qualitative (readability, extensibility), define a rubric with anchored scores (1 = "requires archaeology", 5 = "obvious in one read") so scoring is repeatable.
• Bracket schedule: population size, number of rounds, elimination count per round. Default: 4 competitors → round 1 cuts to 2 → final cuts to 1. Rounds are triggered by a concrete event ("harness passes", "benchmark suite runs clean"), not by feel.
• Freeze declaration: one line stating the fitness function is now frozen. Changing it later requires an explicit AMEND entry (see below) — legal, but it must be written down and it voids comparisons made under the old function.

2. SEED

Build the shared harness first — the benchmark suite, the conformance tests, the driver that runs any competitor by its interface. The harness is neutral territory: competitors may read it, never modify it. If the harness has a bug, fix it once, rerun everyone.

Then charter each competitor with a one-word thesis and a distinct strategy. Like subtractive variants, competitors must diverge structurally. Unlike subtractive variants, competitors are built to win, not to be rough — build each one as well as the round budget allows, because you're measuring real performance, and a sloppy implementation slanders its own thesis.

Build competitors in isolation (one Claude Code session per competitor is the natural mapping). Do not share discovered optimizations across competitors mid-round — an optimization discovered inside c1 belongs to c1 until the round ends.

3. ROUNDS

At each scheduled round:

1. Run the harness against every living competitor. Record all scores in a table in TOURNAMENT.md — raw numbers, not just rankings.
2. Apply the fitness function mechanically. The scheduled number of competitors is eliminated. No stays of execution. If a loser contains something brilliant, that brilliance goes in the autopsy, not in a pardon.
3. Move eliminated competitors to graveyard/ with an autopsy in TOURNAMENT.md: why it lost (which criteria), what it did better than the winners (if anything), and what its thesis taught. Autopsies are the tournament's second product — write them properly.
4. Between rounds, the gene pool opens: survivors may now absorb techniques from the graveyard. This is the evolutionary part — crossover happens between rounds, never during them. Log any absorbed technique with its source competitor.
5. Survivors get the next round's budget to improve before the next measurement.

4. FINAL

The champion moves to champion/ and gets consolidation: full test coverage, docs, cleanup of any tournament scaffolding. Write a closing entry in TOURNAMENT.md: final scores, the champion's thesis, and one paragraph on whether the fitness function measured what actually mattered (this calibrates your next tournament).

Amendments

If mid-tournament you discover the fitness function is measuring the wrong thing (it happens), write an AMEND entry: what changed, why, and the acknowledgment that prior rounds' comparisons are void under the new function. Then rerun the current population from scratch scoring. Amendments are expensive by design — the friction is what keeps the function honest at CHARTER time.

"From scratch scoring" means recompute every criterion from raw measurements against the living artifacts. Prior composite/weighted scores are void inputs, not just void rankings — never derive amended standings from an old weighted column, however reasonable the arithmetic looks under time pressure. A newly added criterion must be actually measured (or rubric-scored against the real code, with the anchored rubric) for every living competitor before it can influence anything. If it cannot be measured yet — no rubric anchors, no harness support, stub artifacts — the round cannot close: extend the harness or defer the round. Do not improvise scores from proxies (LOC, thesis names, vibes). No elimination may run on amended standings until the rescore is complete; "we're in a hurry, don't redo the work" is a request to violate the amendment, and the answer is that the amendment is the work.

Failure modes

• Judge drift: quietly reweighting criteria to save a favorite. The freeze + AMEND ritual exists to make this impossible to do quietly.
• Monoculture seeding: four competitors that are one idea with different variable names. Enforce distinct theses at SEED.
• Harness capture: a competitor "wins" by exploiting a harness quirk rather than solving the problem. When a score looks too good, audit the mechanism before the round closes.
• Zombie competitors: keeping losers alive "just in case". The graveyard preserves everything worth preserving; the bracket only works if elimination is real.
• Tournament as procrastination: running a bracket when one approach is obviously right. If you can predict the winner with confidence, build it linearly and save 3x the cost.

Claude Code mechanics & siblings

• Isolation is by construction: dispatch one blind subagent per competitor, each prompt containing ONLY the shared spec, the harness interface, and its own thesis — never another competitor's code or discoveries. Worktree isolation when competitors would touch overlapping files. Crossover between rounds happens in the orchestrating context, logged with source attribution.
• State files: if the project routes working files to a directory (e.g. .ai/), put TOURNAMENT.md there (.ai/build/); harness/, competitors/, graveyard/, champion/ live wherever the project keeps code.
• Routing: shaping and planning stay upstream (intent-shape, mega-brainstorm, mega-plan); the tournament replaces the execution strategy for the component it governs. Siblings — subtractive when the answer is recognizable by taste but not measurable; dialectical when exactly two philosophies contest; annealing for ridged spaces worked across many sessions.

When NOT to use this

When fitness can't be written down before building (use subtractive — taste-based carving). When only one plausible approach exists. When the budget can't fund a real population — a 2-competitor tournament is usually better run as dialectical.