a8-loom-coordinator

# 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 six 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

- **0.5 — every gate in the package is mechanical.** The decision-model layer introduced in 0.3 and extended in 0.4 was measured on the stack's own content (four calibration runs, 2026-09-19 → 2026-09-21) and answered at base rate on every seam it was tried on; a gate that refuses on a coin flip gets switched off, so it was removed. What stays is the form: rules whose signal is meaning are given a SHAPE with named labels (the eight-label brief, the return shape, the trailer vocabulary) so a matcher checks structure.
- **0.3 — [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`.
- [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.
- 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.