XS

ExtremeSpecification

People specify. Agents build, verify and integrate.

An open-source method for autonomous programming with coding agents.

One page per outcome

The spec is the main input people write: the outcome, the requirements and the invariants. “Extreme” refers to rigor, not length.

Minimal
One page per outcome.
Verifiable
Every requirement has an id. Every invariant has a test.
Current
The lead logs decisions and discoveries in the spec as the work goes on.
project/specs/S04-invoice-csv-export.mdready

Edit the spec to rerun the readiness gate.

Write the spec

Readiness gate, S047 of 7 hold
  1. holdsThe outcome states a result an observer can verify.
  2. holdsEach requirement is verifiable by someone who did not write it.
  3. holdsEach invariant names a test.
  4. holdsNo [ASSUMPTION] remains unconfirmed.
  5. holdsEach open item is routed to tasks; none awaits the owner.
  6. holdsEach shared decision is an accepted ADR.
  7. holdsEach approver has approved, recorded as a Log line with name and date.
status: ready. The lead derives four tasks in two chains. Agents build, verify and land without further approval, except for irreversible actions.

This page checks the text of the spec. The lead judges conditions 1 and 2 by reading the outcome and the requirements.

Check the gate

Six practices

People reason, decide and approve. Agents research, build, verify, triage and land.

Pair specification
Reason about the idea with the partner, in your session. It challenges the idea, retrieves prior work across projects, documentation and papers, and drafts the spec with you.
One-page spec
Approve a one-page spec with the outcome, boundaries, requirements and tested invariants. The readiness gate checks that it is complete.
The factory
The lead splits the spec into chains of tasks and runs each chain in its own worktree, where agents implement, review and fix.
Risk triage
Agents file the work they discover. A triager admits each task with no routing signal and sends the others to their owner.
Autonomous gate
A change lands when five conditions hold. You approve the spec and each irreversible action; the merge needs no approval.
Improvement loop
Turn repeated corrections into rules, then into checks. Track three metrics to see whether the method improves.

From spec to main

First, the lead splits the spec into tasks.

Each task delivers one change and cites the requirements and invariants it satisfies.

Tasks that touch the same files form a chain. Chains run in parallel, each in its own worktree and branch.

Tasks derived from S042 chains
TaskTitleCitesChain
T41 p1Test: export totals match the ledger, cents preserved, organization scopedI1 I2 I3export-core
T42 p2Export endpoint streams the CSV for a date rangeR2 R3 R5 R6 I1 I2 I3export-core
T43 p2Background export above 50,000 rows with an email linkR4export-core
T44 p2“Export CSV” button on the invoice listR1export-ui
T41 comes first: it writes the invariant tests that every later task must keep green.

Then agents build and review each task.

An implementer builds one task with its tests. A reviewer that did not write the code reads the diff.

The lead logs each decision, discovery and deviation as a dated line in the spec. The next agent reads the Log first.

S04-invoice-csv-export.md## Log, chain export-core
- 2026-11-19 T41 landed: three invariant tests, red as expected before T42.
- 2026-11-19 T42 discovery: billing/totals.py rounds per line; the ledger rounds per invoice. I1 fails by 0.01 on 3 of 400 invoices.
- 2026-11-19 decision by Ada: export per-invoice totals, as the ledger does. R2 unchanged.
- 2026-11-19 T42 review round 1: must-fix, the organization filter is applied after the stream starts (I3). Fixed with test `export excludes other organizations`.
- 2026-11-19 T42 review round 2: approve. Finding "use pandas" dismissed: adds a dependency for a 30-line writer.
- 2026-11-19 T42 landed.
- 2026-11-20 T43 landed. Breaker: an export of 120,000 rows completed in 94 seconds.

Then the change passes the merge gate.

A change reaches main when five conditions hold. You approve the spec, not the merge.

Under every gate setting, a person approves each irreversible action: migrating or deleting live data, releasing, rewriting history, changing a public contract, spending money.

export-core into main, T425 of 5 hold
  1. holdsIts spec is ready or building.S04, status: building
  2. holdsThe checks are green on the branch rebased on main.make check, invariant tests of I1, I2 and I3 included
  3. holdsAn independent review reports no open must-fix.Round 2: approve
  4. holdsEach closed task has a Done section with a proof command.pytest -k "export totals match ledger"
  5. holdsThe change contains no irreversible action.No migration, no release, no contract change
Landed. Commit 3f9c2e1 on main. Merge gate: autonomous.

Last, the lead reports in four lines.

The report lists what landed, what is running, what waits for you and the new tasks, with five to ten words per id.

where lists the worktrees, branches and uncommitted files not yet on main.

Status from the leadS04
Landed: invoice CSV export endpoint, invariants green (T42); background export above 50,000 rows (T43)
Running: Export CSV button, in review (T44)
Waiting for you: none
New tasks: T45 per-line rounding in billing/totals.py differs from the ledger (p2)
$ where
~/code/billing, on main, compared with main

worktrees:
  ~/code/billing   main
  ~/code/billing/.claude/worktrees/export-ui   export-ui   2 commit(s) not on main, last 12 minutes ago

disk: 212 GB free

When to write a spec

Write a spec when a request triggers any of four signals. Select a request to see its signals and the route, or switch a signal to test another case.

Three signals. Write a spec first.

    Eight principles

    1. P1

      Human attention is the scarce resource. Spend it on intent, taste and decisions; record all three in the spec.

    2. P2

      State lives in the ledger. Keep each fact in one place, with one writer.

    3. P3

      A claim is not a proof. Accept a result only with the command that reproduces it.

    4. P4

      Specify what is costly to change. Decide it before building it.

    5. P5

      Isolate parallel work. Give each chain its own worktree, branch and id range.

    6. P6

      Work counts only when landed. Work lands when it passes the gate and reaches main.

    7. P7

      Proportion the process to the risk. Skip the spec when no signal holds, and stop for a person before each irreversible action.

    8. P8

      A repeated correction becomes a rule, then a check. Write the rule first; when agents still break it, enforce it with a lint rule, a test or a hook.

    Install

    Requires git, bash and python3. The method works with any coding agent; the skills and the hook require Claude Code.

    The repository is not yet public. Replace <repository> with its address.

    git clone <repository> ~/xs
    export PATH="$HOME/xs/scripts:$PATH"   # where, land, next-id
    
    # in a repo
    cp -R ~/xs/template/. .
    echo '.claude/worktrees/' >> .gitignore
    
    # skills, for every project
    ln -s ~/xs/skills/lead ~/.claude/skills/lead
    ln -s ~/xs/skills/distill ~/.claude/skills/distill

    Then state the request: Define a spec for the invoice CSV export. Use the lead skill.

    Four values and eight principles, on one page.

    Values

    People specify. Agents build, verify and integrate.

    Agents write code faster than people read it. Human attention is the scarce resource. We spend it on the specification. Four trade-offs:

    Four values

    The items on the right matter, but the items on the left keep agents moving when no person answers.

    Eight principles

    1. P1

      Human attention is the scarce resource. Spend it on intent, taste and decisions; record all three in the spec.

    2. P2

      State lives in the ledger. Keep each fact in one place, with one writer.

    3. P3

      A claim is not a proof. Accept a result only with the command that reproduces it.

    4. P4

      Specify what is costly to change. Decide it before building it.

    5. P5

      Isolate parallel work.

    6. P6

      Work counts only when landed.

    7. P7

      Proportion the process to the risk.

    8. P8

      A repeated correction becomes a rule, then a check.

    After Extreme Programming

    Extreme Programming turned each practice that worked up to the maximum, because writing code was the bottleneck. With agents, code is cheap and attention is scarce, so XS turns up the spec: one page per outcome, an id per requirement, a test per invariant. XP preferred conversation to written specs; XS reverses that on purpose, because agents do not attend the conversation.

    Method
    8 principles, 6 practices
    Evidence
    EVIDENCE.md, in the repository
    Teams and organizations
    Not yet measured
    License
    MIT