llms.txt git:20260919.aeae257A

Immutable. This exact content never changes and is served at /api/v1/blob/38f1a5b932ce9680.

# a8-loom-coordinator

> A config-driven governance, skills, and hooks stack for running an LLM (Claude,
> Codex, Gemini, or any capable coordinator) as the autonomous senior engineer on a
> software project — any language, any framework, frontend or backend. Its enforced
> idea: **discover-then-reuse** — retrieve what the codebase already provides and
> reuse it, never hand-roll a fresh version. That is how you make LLM building
> deterministic against an existing codebase. Distilled from three months of daily
> production sessions by [exiledsurfer](https://github.com/exiledsurfer) (operator)
> and the Loom coordinator seat (Claude). MIT licensed. A reusable seat — the first
> of the `a8-loom-*` line.

## Start here

- **NEW in 0.3 (A) — [spec-catalog](https://github.com/LoomA8osAgent/a8-loom-coordinator/blob/master/integrations/spec-catalog.md): constraint BEFORE, not refusal after.** The code registry is projected into a catalog plus a byte-capped catalog prompt the builder preloads instead of the raw ruleset; the builder emits a `{helper, props, children}` spec that can only name catalog entries; validation runs a lossless-only autofix, compilation emits the real helper calls plus an HMAC'd receipt, and `hooks/spec-gate.js` refuses a freehand new surface no receipt covers. json-render (core + codegen) and `zod` are vendored node-side only, so the package keeps zero runtime dependencies. Opt-in (`specCatalog.enabled`); generator `tools/gen-catalog.js`.
- **NEW in 0.3 (B) — [judgment](https://github.com/LoomA8osAgent/a8-loom-coordinator/blob/master/integrations/judgment.md): a decision model as a fourth executor class.** A rule that lived in prose because no matcher reads MEANING becomes a gate. `hooks/judgment-gate.js` — a hook like any other, registered at the edit / commit / spawn matchers — asks **Jev (TypeSafe AI)** or **an open decision model on your own machine (Laya 421M served by von)** over one loopback `/v1/systemone` wire, with a fixture provider for every test. It fails closed, is additive to the matcher that owns the moment, ships advisory, and arms a band only from a measured coverage curve on labeled data. ON by default: the executor class is always on, the provider is what may be absent. Practice: `skills/judgment-SKILL.md`; providers + measured costs: `governance/LOCAL-MODELS.md`. The one seam between the two layers: `specCatalog.autofixSelector: "judgment"` picks among candidates code already enumerated, and can never widen what a spec may name.
- [README](https://github.com/LoomA8osAgent/a8-loom-coordinator/blob/master/README.md): what it is, why it exists, how to install (plugin / npx / manual).
- [AGENTS.md](https://github.com/LoomA8osAgent/a8-loom-coordinator/blob/master/AGENTS.md): the cross-model agent guide (Codex / Claude Code / Gemini / Cursor / Cline / Devin).
- [stack.config.README.md](https://github.com/LoomA8osAgent/a8-loom-coordinator/blob/master/stack.config.README.md): the annotated config schema — every gate is a config key.

## Governance

- [FAILURE-PATTERNS.md](https://github.com/LoomA8osAgent/a8-loom-coordinator/blob/master/governance/FAILURE-PATTERNS.md): the enforced catalogue of failure modes + their mechanical prevention, each row naming its executor — hook, generator, or judgment (universal core + opt-in frontend appendix).
- [WORK.template.md](https://github.com/LoomA8osAgent/a8-loom-coordinator/blob/master/governance/WORK.template.md): the work list + the rails — ONE flat `WORK.tsv` (`tools/work.js`), no tree, no status column, order is the only priority, and a row leaves only against a real non-checkpoint commit.
- Templates: CLAUDE / OPERATOR / ROUTING / WORK / SESSION / HANDOFF (in `governance/`). The invariant set is deliberately NOT always-on — it is delivered by subject, inside the gate's refusal.

## Skills (the practice)

- [coordinator-SKILL.md](https://github.com/LoomA8osAgent/a8-loom-coordinator/blob/master/skills/coordinator-SKILL.md): the cost/competency model grid + the brief contract (BUDGET in tokens + PROOF tier + paths-not-prose) + delegation + audit contract + the git work method.
- [model-succession-SKILL.md](https://github.com/LoomA8osAgent/a8-loom-coordinator/blob/master/skills/model-succession-SKILL.md): the seat-handoff letter — how the coordinator seat survives a model change.
- [judgment-SKILL.md](https://github.com/LoomA8osAgent/a8-loom-coordinator/blob/master/skills/judgment-SKILL.md): the judgment seam — the fourth executor class, for standing rules whose signal is MEANING and which therefore have no matcher. The seam shape, how to write a closed Noul / Choice / Score question, provider classes and which may refuse, grading + coverage-curve bands, fail-closed engagement, and the red proof. Opt-in (`judgment.enabled`), advisory by default, additive to the matcher that already owns the moment.
- Also: doc-sync, dev-infrastructure, init-interview, skill-creator.

## Hooks (the enforcement floor — all config-driven, language-agnostic)

- canon-before-edit, anti-hand-roll (discover-then-reuse consent), doc-sync + state-persistence commit gates, verification-first, session regenerators, service recovery.
- verification-first also carries the INSTRUMENT ROSTER: anything allowed to vouch for a run — a browser driver, a desktop driver against the built app bundle — is DECLARED in `verification.instruments[]` (id / kind / driver / launch / receipt / enabled); every instrument writes ONE receipt shape, and a receipt naming an undeclared or disabled instrument is refused (fail closed). Example desktop driver, with its install audit: `hooks/native-instrument.example.sh`.
- [ENFORCEMENT.md](https://github.com/LoomA8osAgent/a8-loom-coordinator/blob/master/ENFORCEMENT.md): the architecture of the floor — the four moments a gate fires (edit / spawn / commit / turn-boundary), the gates on the INSTRUMENTS you verify with (scripted-API-only, the synthetic-input ban, the route ban), the spawn-time economy (budget line, model pin, proof tier, and the body check that refuses a heavy body under a light label), the commit-time receipts (a machine-written watched-run receipt, not a claim), the meta-gates that keep the gates honest (self-test / coverage / drift), and the graduation rule (every prose rule that can be mechanical becomes a hook).

## Install

- Claude Code plugin: `/plugin marketplace add LoomA8osAgent/a8-loom-coordinator`
- npx: `npx a8-loom-coordinator init`
- Examples: `stack.config.example.backend.json`, `stack.config.example.frontend.json`

## Optional

- [frontend/](https://github.com/LoomA8osAgent/a8-loom-coordinator/blob/master/frontend/README.md): opt-in CSS/DOM module — the design-system-export / satellite-product method (host-first, generated extraction, measured parity). Backend projects ignore it.
- [integrations/spec-catalog.md](https://github.com/LoomA8osAgent/a8-loom-coordinator/blob/master/integrations/spec-catalog.md): opt-in constraint layer — constraint BEFORE replaces refusal AFTER. The code registry is projected into a catalog plus a byte-capped prompt the builder preloads instead of a raw ruleset; the builder emits a `{helper, props, children}` spec that can only name catalog entries; a compiler emits the real calls and an HMAC'd receipt; a gate refuses any new surface no receipt covers. Vendored (json-render + zod), so the package keeps zero runtime dependencies.
- [governance/LOCAL-MODELS.md](https://github.com/LoomA8osAgent/a8-loom-coordinator/blob/master/governance/LOCAL-MODELS.md): the judgment layer's provider side — what a decision model is, the three provider classes and why only a TRAINED one may arm a refusal, the named picks (Jev 1.13.0 by TypeSafe AI as the commercial reference at $0.042/M input tokens; Laya 421M, Apache-2.0, served by von on loopback as the open primary; Verdict/OpenJev 151M, Apache-2.0, in-browser and Choice-only for now), the measured on-device costs (an Apple M4, 16 GB, 2026-09-19: ~115 ms per question warm; bundling is super-linear, so state length is the only latency lever and model size is not), the telemetry findings measured in both directions, and the calibration gate a band must pass — instrument `AbdelStark/jev-benchmarks`, Apache-2.0, vendored not written. Watch <https://huggingface.co/spaces/multimodalart/jev-reproductions-tracker> for new open candidates. The package ships no model, no weights and no inference dependency — only the loopback `/v1/systemone` wire.