You bring the idea.
The method builds the rest.
Uscha is a spec-driven, tool-agnostic methodology for developing with coding agents. No ceremony where it isn't earned — rigor where the stakes justify it. Its central mechanism: a deterministic ledger that separates what was measured from what was narrated.
The agent executes · the method governs · evidence decides · the human approves.
$ npx --yes @andresmassello/uscha@latest install --target claude
The agent says it's done. Who contradicts it?
Open loop vs. measured graph
There are two ways to put an agent to work on code. In the open loop, the agent decides the path and asks itself whether it is done — nothing outside it can contradict it. In the measured graph, the human defines the possible paths and every gate is answered by measured evidence, not the agent.
- investigate
- modify code
- run tests
- review the result
- solved?
- done — or try again
- reproduce the bug
- does it reproduce?
- find root cause · attempt fix
- do the tests pass?
- review
- approved by a human?
Uscha is that measured graph, with two twists of its own: every gate is answered by a deterministic, auditable artifact — the ledger, the gates, coverage, the golden suite — and the loop does not vanish: it is caged inside a bounded convergence node that either converges or escalates to a human.
Read the full essay: why uscha exists →
Gates that read FACTS block; those that GUESS over prose advise.
Five rules. Nothing more — and nothing less.
No code without SPEC + ACCEPTANCE
Before anything is built, what is being built exists — and so does how you'll know it's right.
The truth lives in versioned files
Not in the chat. SPEC.md, ADR, ACCEPTANCE.md, QA-LEDGER.json — all in the repo.
The human always approves the merge
The pipeline stops at the merge gate. Always. No exceptions.
Tests must assert
The gate is never weakened to make it pass. A test that doesn't assert is not a test.
Migrations anchored with a golden
Old behavior is captured mechanically before touching it. The agent never authors the .approved.
From idea to production, with gates along the way
Nine skills covering the full cycle
From the opening interrogation to the status dashboard. Each skill does one thing; the ledger ties them together.
From a bare idea to a spec package: the skill interrogates until a shared shape of the system exists, writing the documents as it goes.
Interview, then distill: the same interview applied to a feature you already know. Not a generator — an interrogator.
The build + QA orchestrator: a disciplined cycle, every step in the ledger, and a hard stop at the human merge gate.
Freeze current behavior as field truth: the golden suite — the one artifact the agent must not author.
The inverse of discovery, for brownfield: nothing is invented — facts are extracted from the existing system, as a map + golden.
The ACCEPTANCE of the non-testable: grades the change against a versioned RUBRIC.md. Advisory by default.
Real status at a glance: readiness, sub-scores, phases, invariants and QA loops. The skill wires — it never computes.
The system deck in two tracks — commercial and technical — with real metrics from the ledger. An optional report, on request.
The statusline on demand: a one-line progress readout, for surfaces where the statusline isn't visible.
Go deeper: the full documentation
Everything below is generated from the same repo the kit ships from — the docs and the code travel together.
Why uscha exists
Open loop vs. measured graph: who answers the gates, and why the loop gets caged instead of removed.
course html2-day developer course
From zero to production: day 1 builds a greenfield feature, day 2 migrates an existing system — discovery, characterize, reverse-discovery.
reference htmlComplete documentation
The whole method in one place: the rules, the phases, every skill, the gates and the ledger — the big doc.
paper html · pdfThe paper
The formal treatment: a fact-gated, tool-agnostic methodology for specification-driven development with LLM coding agents.
Measured beats narrated — here too
The engine is qa_ledger.py: pure Python, no pip installs. It ingests evidence from
maven, gradle, ant, python, node, go, rust, dotnet, cpp, swift and flutter, and records it in
QA-LEDGER.json — a deterministic ledger that records what was measured, never what was claimed.
"Check" is a question. The agent answered with a commit.
A human asked the agent to "check" some remote QA errors. The agent diagnosed them well — and in the same turn, without showing the diagnosis or waiting for a reply, it announced "design closed", edited tests and production code, and ran the build. Between the question and the modified code: zero human decision points. The execution was competent; the failure was governance. That is exactly the hole Uscha exists to close.