You bring the idea.
The method builds the rest.

Uscha rejects the usual assumption that you already know what to build. The expensive failure is a confident build of the wrong shape — so the first move is always to find the shape, and every later move advances on captured evidence, stopping short of merge.

Run /uscha-discovery when you have an idea but not a shape; run /uscha-adr-refine when the shape is known and only the edges need drawing. Neither writes code — they run on Read, Write, Glob, Grep (discovery adds WebFetch).

As decisions settle, write them straight into the repo — don't hoard for the end. The build reads files, not chat.

Ask: what can this break, and what does the break cost? The answer sizes the apparatus. Don't drag the full machine behind a config tweak. Profiles are a process heuristic — no profile concept exists in the kit's code or config, and no profile selects gates automatically; you pick them.

Three documents, three levels of force.

• SPEC — observable behavior. What must happen.
• ADR — a choice between alternatives. Why this shape.
• CONSTITUTION — what's never acceptable, whatever the trade-off.

Write an ADR only if all three are true

• Hard to reverse.
• Surprising without context.
• The result of a real trade-off.

Miss one → it's a SPEC line. The Implementation Plan makes an ADR executable; code links back with // ADR: <slug>.

The orchestrator takes the ADRs + ACCEPTANCE.md, builds, and runs a severity-gated review loop that stops. Three laws: converge, don't chase zero · tests are a guardrail, not the finale · generating tests ≠ running them.

1. Setup + Phase 0. qa_ledger.py init; ADRs + acceptance in. No acceptance → run /uscha-adr-refine first.
2. Phase 1 — coverage gate. Above threshold, existing suite guards. Below → write characterization tests at the edge; human reviews them.
3. Phase 2 — build. One commit per logical step. Stop and propose an ADR on a new dep/pattern/contradiction.
4. Phase 3 — QA loop. code-review → judgment-day → improve. Apply fixes ≥ gate; defer the rest. Log, ingest, persist each fact-gate verdict via log-gate, check converged/oscillation.
5. Phase 4–5 — integration + verify. Cross-repo contract tests; then the deferred fine-grained coverage.
6. Phase 6 — PR, then STOP. Converged + gates clean, open PR, stop at the merge gate — human reviews, then ship.
7. Phase 7–8 — smoke + docs. Manual smoke list; retrospective from the ledger. /uscha-sysdoc is optional reporting on request, not a mandatory phase.

If the maker writes its own report card, it can log exit_code: 0 having run nothing. So the ledger parses real files — it doesn't transcribe claims.

# qa_ledger.py reads files, not the agent
coverage  ← coverage report (e.g. jacoco.xml / lcov)
tests     ← test result XML (e.g. JUnit / surefire)
static    ← linters · type-checker · security scanner
LOC       ← its own count (stdlib)

A gate that reads a fact may block the work. A gate that guesses over prose may only whisper. Break this and false positives kill the gate — the dev turns it off, and a dead gate is worse than none.

Everything else is agent-authored. The golden is the one thing it can't author — and that's the point. Capture what the old code actually does by running it, freeze it as human-approved .approved, then diff the migrated code against it.

• Never let the agent generate or edit .approved — a PreToolUse hook blocks the write.
• Never capture by reasoning about output; capture by executing against real corpus.

• Pin the target locale, freeze clocks, normalize GUIDs/map-order before serializing.
• Add *.approved.* binary to .gitattributes — line endings will lie otherwise.

The outer loop is a heartbeat that fires the inner one on a cadence. Don't build it until all four are true.

• Repeats (weekly+) — else one prompt is cheaper.
• Automated verification — a test/build/linter that fails the work without you.
• Budget absorbs waste — it re-reads and retries; it burns tokens either way.
• Senior tools — logs, repro env, runs what it writes.

# heartbeat wrapping /uscha-devloop
> /loop 0 3 * * *              # nightly cadence
  /goal readiness ≥ 80 AND tests green
        AND 0 CRITICAL         # fresh checker: other agent family, or at least
                               # another profile — process, not enforced by code
  > run /uscha-devloop over <machine-checkable scope>
    stop    = /goal met (fresh checker) OR budget out
    on-done = draft PR · escalate CONSTITUTION touches
    human   = merge/deploy ALWAYS with approval

• Spike / exploration. No SPEC. Keep a note of what you learned; specify only what survives.
• Throwaway prototype. Mark it, isolate it, give it a death date.

Claude Code + Python + git/gh + skills run the method. Stack-specific bits (build tool, database driver, linters) are the per-repo adapter in each CLAUDE.md — not the workbench.

# native installer — no Node, self-updating
curl -fsSL https://claude.ai/install.sh | bash   # mac/linux/wsl
irm https://claude.ai/install.ps1 | iex          # windows
cp -r uscha-kit/.claude/skills/* ~/.claude/skills/
scoop bucket add gentleman https://github.com/Gentleman-Programming/scoop-bucket
scoop install gentle-ai                          # author's toolchain — optional, not required by the kit
claude --version && claude doctor

Cloning to a teammate isn't one file — it's 7 layers: config, plugins, skills, agents+commands, hooks, the external CLI, and MCP servers (author's setup — not shipped in the kit; the kit itself needs only Claude Code, Python 3.8+, git, optional gh, and the skills copied to ~/.claude/skills).

• Gotcha: settings.json hardcodes C:\Users\…. The author's bootstrap tooling tokenizes the path on export and rewrites it on import (not shipped in the kit).

• Memory is NOT shared. engram + MEMORY.md are per-machine and build themselves. Behavior is replicated; memory is earned.