> For the complete documentation index, see [llms.txt](https://docs.thecolliery.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thecolliery.org/readme.md).

# TheColliery

<div align="center"><picture><source srcset="https://2433472734-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgQ42szc9W8zGLqkQR2f4%2Fuploads%2Fgit-blob-dbc0868f66c8c6d0143c2578e9a9594bdf1bb685%2Fcolliery-banner-d3-dark.svg?alt=media" media="(prefers-color-scheme: dark)"><img src="https://2433472734-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgQ42szc9W8zGLqkQR2f4%2Fuploads%2Fgit-blob-27b475f38b22b109a664b35639edb49de3b4dd9e%2Fcolliery-banner-d3-light.svg?alt=media" alt="" width="100%"></picture></div>

<p align="center"><strong>Quality tooling for AI coding agents—mined, sorted, and shipped.</strong></p>

<div align="center"><img src="https://img.shields.io/badge/Suite-TheColliery-blueviolet?style=for-the-badge" alt="Suite"> <img src="https://img.shields.io/badge/Downloads-8.7k%2B%20%2F%2014d-orange?style=for-the-badge" alt="Downloads"> <img src="https://img.shields.io/badge/Developers-1.5k%2B%20%2F%2014d-brightgreen?style=for-the-badge" alt="Developers"> <img src="https://img.shields.io/badge/Works_With-Mostly_Cross--Agent-cyan?style=for-the-badge" alt="Mostly Cross-Agent"> <img src="https://img.shields.io/badge/License-Per_Zone-lightgrey?style=for-the-badge" alt="Licence: per zone, see below"></div>

<p align="center">📖 <a href="https://thecolliery.org/docs">Full documentation</a></p>

<p align="center"><sub>The documentation is hosted on</sub> <a href="https://www.gitbook.com"><sub>GitBook</sub></a><sub>, under its Community plan for open-source projects.</sub></p>

***

## 🏗️ What is TheColliery?

A *colliery* is the complete coal mining operation: the mine, the tipple, and the workspace that turns a raw underground seam into clean, burning fuel.

**TheColliery** is a series of small, sharp, offline-first tools designed to keep AI coding agents honest, secure, and blazing fast. We build the infrastructure that helps agents execute safely, coordinate concurrently, and optimize their token budgets without sacrificing quality.

***

## ⛏️ The Series Suite

The Colliery structures its tools by the processing stages of raw digital coal:

| Project                                                     | Stage             | Status                                                                                                                                                | Concept                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**CoalMine**](https://github.com/TheColliery/CoalMine)     | *Extraction*      | **Live** ![ver](https://img.shields.io/github/v/tag/TheColliery/CoalMine?sort=semver\&label=\&color=success\&style=flat-square)                       | Nine quality-**canary** skills (code-health, grounding, supply-chain, resilience, observability, testability, scaling, drift, completeness) plus the auto-cadence hooks that run them unprompted at session start and session end, equipping agents for raw, safe code extraction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [**CoalTipple**](https://github.com/TheColliery/CoalTipple) | *Sorting*         | **Live** ![ver](https://img.shields.io/github/v/tag/TheColliery/CoalTipple?sort=semver\&label=\&color=success\&style=flat-square)                     | A model/effort **router**: **delegation** (down, to save tokens) and **escalation** (up, for quality), a `qualityBar` staircase, and a fail-safe model-ranking **Lock**. **Claude Code only**—routing actuates only where an agent can pick a spawned worker's model + effort (built and validated across the 2.1.x line).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [**CoalBoard**](https://github.com/TheColliery/CoalBoard)   | *Governance*      | **Live** ![ver](https://img.shields.io/github/v/tag/TheColliery/CoalBoard?sort=semver\&label=\&color=success\&style=flat-square)                      | A **consensus & debate board**: on an error-not-allowed task—or any hard problem worth several lenses—with consent, diverse epistemic lenses (empirical/source-grounded · formal · a show-me skeptic) debate in parallel—either verifying new work before it ships (**Generate**) or reporting on existing work (**Audit/Review**)—a judge synthesizes on VERIFIED inputs, an independent solver breaks ties, and the human signs off. Bounded cost + zero-breakage. **Cross-agent**—validated on Claude Code + Antigravity; other concurrent-subagent platforms design-supported.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [**CoalHearth**](https://github.com/TheColliery/CoalHearth) | *Session Storage* | **Live** ![ver](https://img.shields.io/github/v/tag/TheColliery/CoalHearth?sort=semver\&label=\&color=success\&style=flat-square)                     | A session **warm-resume** engine: a hook journals session state every step, so an interrupted session resumes from a recovery block instead of a manual rebuild. **Reduces** the work lost to a session limit (it does not prevent one). Claude Code (validated) + 6 wired ports (Antigravity, Gemini CLI, Copilot CLI, Devin CLI, Kiro, Augment)—Phoenix-13 hooks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [**CoalFace**](https://github.com/TheColliery/CoalFace)     | *Active Front*    | **Live** ![ver](https://img.shields.io/github/v/tag/TheColliery/CoalFace?sort=semver\&label=\&color=success\&style=flat-square)                       | The **fan-out discipline**: a mandatory scout sizes the swarm, workers return anchor-edit orders as text, one writer applies behind a snapshot + QC + domain gate, and the run's **dollar** cost fits the estimated solo cost **only when worker tiers are cheaper than main**—with the default main-equivalent workers it **can exceed it, and no budget stop exists** (raw tokens always run higher; bandwidth dial with TCP-style backoff). Disciplines the fan-outs an agent would already do—it does not make models smarter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [**CoalWash**](https://github.com/TheColliery/CoalWash)     | *Washing*         | **Live** ![ver](https://img.shields.io/github/v/tag/TheColliery/CoalWash?sort=semver\&label=\&color=success\&style=flat-square)                       | A **memory washer/defragmenter** with **two lanes and two different contracts**. **Class-B—the context you load every session** (memory + governance files): cleans the FAT, never the MEAT, under a **code-enforced fidelity gate proving zero structured-token loss by diff**, with **plan-sourced deletes made safe by UNDO** (verified snapshot + WAL + whole-run rollback, not pre-approval; pinned files untouchable), and a session-start gauge whose FULL band **force-runs** the free mechanical pass on a **deterministic break-even proof with the numbers shown**. **Class-A—the at-rest estate on disk** (transcripts and tool results): **never semantic-edited at all**—they are vendor-owned and machine-parsed, so the guarantee is **byte-identity**, copy-verify-then-delete with a round-trip restore. The estate lane runs **only when you choose it in the wizard**—never on a band, never ambient, because disk is not context. Cross-agent design (Claude Code validated). |
| [**CoalLedger**](https://github.com/TheColliery/CoalLedger) | *Records*         | **Beta** ![ver](https://img.shields.io/github/v/tag/TheColliery/CoalLedger?include_prereleases\&sort=semver\&label=\&color=orange\&style=flat-square) | A **docs-health canary suite**—CoalMine for documentation: 6+1 canaries (wrong · incomplete · stale · contradictory · broken · unreadable · + config-gated leaked), with `doc-structure` detecting through a vendored zero-dep **CommonMark+GFM AST engine** (things that render fine are never flagged). Severity judged by context, never a fixed map; fixes choice-gated, never auto-applied; correctness escalates to CoalBoard. Plus a quiet docs memory-drift reminder—not a canary—when docs change but `MEMORY.md` does not. Cross-agent + **multilingual**.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [**CoalGob**](https://github.com/TheColliery/CoalGob)       | *Backfill*        | **Beta** ![ver](https://img.shields.io/github/v/tag/TheColliery/CoalGob?include_prereleases\&sort=semver\&label=\&color=orange\&style=flat-square)    | An agent's `rm` goes **straight past the Recycle Bin**; yours does not. CoalGob is designed to check each destructive command an agent runs for whether it already lands somewhere recoverable — the OS's own trash, or a destroyer that already snapshotted it — and to block it only when it would not. **Beta: the command-classifier engine ships; the delete guard does not — yet.** CoalGob's parser and tokenizer, with their test suite, are here and working. There is no interception hook, skill, command, or agent, so nothing installs, blocks, or reroutes anything today, and `NO_MATCH` is never a safety claim. A lite form of the idea already ships inside CoalWash.                                                                                                                                                                                                                                                                                                            |
| **CoalAssay**                                               | *Assay*           | 🌱 **Seed**                                                                                                                                           | The web's own **standards, as a skeleton for any project**: accessibility (WCAG 2.2), internationalisation, security and privacy headers, mail and DNS authentication, page weight, crawler signals. The house built 184 checks from a verified net-cast of the standards bodies, each carrying its source and a label: a standard's own requirement ships with the standard's own number, and the house's own choices are stripped and replaced by a live reading of the page in hand. A third pole beside CoalMine (code) and CoalLedger (docs): what a project actually ships. **A blueprint and this row; no repository, nothing to install.**                                                                                                                                                                                                                                                                                                                                                 |
| **CoalSeam**                                                | *The Seam*        | ⚪ **Capture**                                                                                                                                         | The **org system itself**, being captured as a skill. Claude Code persists the *main* agent's memory automatically; a spawned worker gets nothing and re-learns its domain every time. CoalSeam gives each **role** that same persistence—a code / docs / review worker becomes one continuous identity across spawns—and, the sharper half, gives the rings **below** the main a **split load**: the constitution binds the main every turn, but a doc worker never needs the containment rules and a code worker never needs the doc manual. The platform offers all-or-nothing there; the middle is where every worker lives. **No new platform, no extra vendors, one model—the org is the runtime's own primitives, so it cannot drift from them.** Honest state: a captured skeleton plus a design record. **Not a plugin, not yet a repository, nothing to install.** Start method, activation and per-user generalization are all deliberately unsettled.                                  |
| **CoalPortal**                                              | *Gateway*         | ⚫ **Reserve**                                                                                                                                         | A **remote web-to-CLI gateway** (an idea held on the shelf): drive a local session from a phone. **Superseded by first-party Claude Code Remote Control** (`/rc`) and cut before build—kept as a reserve concept for a narrow air-gapped / zero-trust niche `/rc` may not serve. Whether it revives is undecided—a plan on record, not an active build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

***

## 📦 Install—pick your DLC

Each tool installs on its own, or grab them together—like choosing DLC on a store page: take the whole pack, or just the pieces you want.

**One-step selector** (needs `node` + `git` on PATH; the `claude` CLI for the plugins):

```bash
curl -fsSL https://raw.githubusercontent.com/TheColliery/.github/main/install.mjs -o colliery-install.mjs
node colliery-install.mjs all       # the seven tools in the table below (CoalGob has nothing to install yet)
node colliery-install.mjs 3         # just CoalBoard
node colliery-install.mjs 1 2 3     # CoalMine + CoalTipple + CoalBoard
node colliery-install.mjs 6 7      # CoalWash + CoalLedger (beta)
node colliery-install.mjs coalmine  # by name, too
```

**Or install each tool directly**—each repo's README has the authoritative, always-current steps:

| # | Tool                                                        | How                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| - | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | [**CoalMine**](https://github.com/TheColliery/CoalMine)     | a Claude Code **plugin**—`claude plugin marketplace add TheColliery/CoalMine` then `claude plugin install coalmine@coalmine` (auto-wires the `rot-canary` Stop hook); **other agents**—`node scripts/install.mjs <agent>` (Antigravity/Cursor/Codex/…; a file copy into the agent's skills folder). Auto-cadence hooks: auto-wired on Claude Code, **primed** on Antigravity 2.0 (built and tested against the AG 2.0 hook spec; whether they fire is unresolved)—see the [README](https://github.com/TheColliery/CoalMine#-install)                                                                                                                                                                                          |
| 2 | [**CoalTipple**](https://github.com/TheColliery/CoalTipple) | a Claude Code **plugin**—`claude plugin marketplace add TheColliery/CoalTipple` then `claude plugin install coaltipple@coaltipple` (restart Claude Code to load the /coaltipple commands)—**Claude Code only**: routing actuates only where an agent can pick a spawned worker's model + effort, and Claude Code's `Agent`/`Task` tool is the one that takes a `model` parameter. No file-copy or `install.mjs` path for other agents.                                                                                                                                                                                                                                                                                        |
| 3 | [**CoalBoard**](https://github.com/TheColliery/CoalBoard)   | a Claude Code **plugin**—`claude plugin marketplace add TheColliery/CoalBoard` then `claude plugin install coalboard@coalboard`; **Antigravity** (validated end-to-end 2026-06-22, self-run, not third-party-audited)—copy `skills/coalboard` into `~/.gemini/config/skills` (all workspaces) or `<your-repo>/.agents/skills` (per project); **other concurrent-subagent platforms**—point your agent at `skills/coalboard/SKILL.md` (design-supported, not run by us) (see the [README](https://github.com/TheColliery/CoalBoard#-install))                                                                                                                                                                                  |
| 4 | [**CoalHearth**](https://github.com/TheColliery/CoalHearth) | a Claude Code **plugin** (validated): `claude plugin marketplace add TheColliery/CoalHearth` then `claude plugin install coalhearth@coalhearth`; **works with 6 more platforms** (Antigravity 2.0, Gemini CLI, GitHub Copilot CLI, Devin CLI, Kiro, Augment Code), each by copying the plugin dir and wiring the matching template in `platform-configs/` (see the [README](https://github.com/TheColliery/CoalHearth#install) for the per-platform file)                                                                                                                                                                                                                                                                     |
| 5 | [**CoalFace**](https://github.com/TheColliery/CoalFace)     | a Claude Code **plugin**—`claude plugin marketplace add TheColliery/CoalFace` then `claude plugin install coalface@coalface`; **Antigravity**—copy `skills/coalface` into `~/.gemini/config/skills/coalface` (global) or `<repo>/.agents/skills/coalface`; **other agents**—point the agent at `skills/coalface/SKILL.md` (cross-agent contract; the auto-conductor hook is Claude Code + Antigravity 2.0 (wired), commands are Claude-Code-only)                                                                                                                                                                                                                                                                             |
| 6 | [**CoalWash**](https://github.com/TheColliery/CoalWash)     | a Claude Code **plugin**: `claude plugin marketplace add TheColliery/CoalWash` then `claude plugin install coalwash@coalwash` (also wires the session-start gauge); **other agents** (Antigravity · Cursor · Codex · Gemini CLI · Cline · Copilot): file-copy, copy `skills/coalwash/` (skill + references) and `scripts/lib/` (the engine) into the platform's skill directory, keeping the relative layout (`skills/coalwash/SKILL.md` resolves the engine at `../../scripts/lib`); on Antigravity that directory is `~/.gemini/config/skills/` (global) or `<workspace>/.agents/skills/` (per-project). The gauge hook is Claude-Code-only; elsewhere run `/coalwash` manually. No API keys, no network, no `npm install`. |
| 7 | [**CoalLedger**](https://github.com/TheColliery/CoalLedger) | a Claude Code **plugin** (beta)—`claude plugin marketplace add TheColliery/CoalLedger` then `claude plugin install coalledger@coalledger`; **other agents**—copy the built skill folders from `plugin/skills/` into the agent's skills root (each folder is self-contained; `doc-structure` carries its engine in its own `lib/`)                                                                                                                                                                                                                                                                                                                                                                                             |

**CoalGob** (beta) has no row above because there is nothing to install yet: its README says "nothing installs, blocks, or reroutes anything today", and the repository ships the command-classifier engine only ([status](https://github.com/TheColliery/CoalGob#status)).

Per-tool docs: [thecolliery.org/docs](https://thecolliery.org/docs).

***

## 📊 Benchmarks

Headline results—small, dated samples curated here, each stamped with the date + tested version it was measured on; the full tables, method, and caveats live in each tool's benchmark record (the single source of truth):

| Tool                 | Result                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **CoalMine**         | 7 canaries × 4 engines, 3-5 repeated runs each: 100% recall on 5/7 suites for every engine · 0 decoy false alarms batch-wide · the 2 suites that separate engines are drift-canary (88% median) and rot-canary (92% median on opus/haiku/AG)—measured 2026-07-03 · skill v3.8.4, [see the record](https://github.com/TheColliery/.github/blob/main/benchmarks/CoalMine/RESULTS.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **CoalTipple**       | ON-vs-OFF paired (4 tasks × 3 tiers × K=3, 2026-07-03, v1.0.23): routing ON = 4/4 task quality on both baselines, OFF = 3/4 on both (each failing a different task) · ON is \~23% cheaper from an Opus main, cost-neutral from a Sonnet main · never-delegate-sensitive-down re-confirmed on the new lineup—[see the record](https://github.com/TheColliery/.github/blob/main/benchmarks/CoalTipple/RESULTS.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **CoalBoard**        | solo-vs-board (2026-07-03, v1.5.5): **Opus 4.8** solo 4/5 · board 5/5 (strong solo catches the reasoning traps unaided; board's edge = the version-sensitive FACT T3). **Cross-vendor mirror**—Gemini 3.5 Flash solo \~4/15 · board 5/5 (weak solo → board recovers ALL traps). Board margin scales inversely with solo strength; T3 (run-the-check) is the win at both ends. Board = solo + ground-truth execution. **Third-party comparison (2026-09-16, CoalBoard v2.4.2 vs `cloudflare/security-audit-skill` commit `c1c8a8c`, n=3, model ids in the record, disclosure: we build one of the three arms)**—CoalBoard's audit mode vs the skill's quick profile vs a solo control on one seeded target: skill recall matched the solo control (0.467 median) at ≈14.5× its median cost; CoalBoard reached 0.867 median recall at ≈3.9× less median cost than the skill. **Addendum 1 (the judge chair, measured 2026-09-16):** judge seat at the weakest model tier over strong-tier lenses (two research-only levers, not shipped) held on retention—38 of 39 lens-union seeds kept, 0.867 recall at ≈0.947 strict precision that is largely the strong lenses' own; whether a weak judge rejects a look-alike stays untested, and the whole-weak-tier board read "in between"—[see the record](https://github.com/TheColliery/.github/blob/main/benchmarks/CoalBoard/RESULTS.md)                                                                 |
| **CoalHearth**       | interruption damage (2026-07-03, v1.0.0): on a 10-file mid-refactor, warm resume and cold restart BOTH finished correctly with a **<1% token delta**—at small scale a strong model rebuilds state from the tree, so CH's token saving is a large-session effect; its irreducible value is state **fidelity**—the in-flight sub-agent record (CH 1, cold 0) a cold restart cannot reconstruct—[see the record](https://github.com/TheColliery/.github/blob/main/benchmarks/CoalHearth/RESULTS.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **CoalFace**         | fan-out cost (2026-07-03, beta.2): fanning out costs **more raw tokens** than solo (ad-hoc 4.2×, CF 5.3×); in **dollars**, cheap-tier fan-out CAN beat solo—but that win belongs to the **ad-hoc** arm alone (6× Haiku, no scout: **−15%**). **CoalFace's own total, scout included, ran MORE than solo on this small job** (+51% Sonnet scout, +7% Haiku scout)—its wallet claim is a **$-via-cheap-tier** bound that depends on the scout amortizing above a shared-context threshold this synthetic 6-spot job does not reach; never a guaranteed win, never a token saving. (Measured at beta.2; CoalFace graduated stable on its first real 15-spot run 2026-07-09—the receipt matched this honest frame, not a win.)—[see the record](https://github.com/TheColliery/.github/blob/main/benchmarks/CoalFace/RESULTS.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **CoalWash**         | first dated run (2026-07-09, v0.1.0-beta.5, fable tier): consecutive-run ceiling **≥ 2** (tested to round 2, 0 muscle loss—never extrapolated) · post-fat-exhaustion loop rounds **100% no-op, 0% fact-loss/round** (the structural target) · fidelity gate PASS on every round · a **controlled equal-size fidelity** test (2026-07-12): at a \~54% cut, CoalWash lost **0/448** structured tokens (100% recoverable) vs a fair naive compress's **218.8** lost (0% recoverable)—safe saving, not a smaller file · the headline sawtooth-vs-bloat saving is still unmeasured (protocol ready)—[see the record](https://github.com/TheColliery/.github/blob/main/benchmarks/CoalWash/RESULTS.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **CoalLedger**       | not yet measured—launched unbenchmarked rather than with an invented number; the engine's mechanical layer is fixture-gated in-repo (planted defects found, clean decoys silent), and the first published benchmark will follow the flock shape—[pending digest](https://github.com/TheColliery/.github/blob/main/benchmarks/CoalLedger/RESULTS.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **Governance**       | the series' OWN always-injected rule pile—the first non-tool benchmark (2026-07-27, byte-pinned snapshot; the target has no version): pile ≈ 198k chars / \~79.3k calibrated tokens, all 7 plugins' always-on = 7.2% of it · the "keep CLAUDE.md under 200 lines" tip is the WRONG UNIT here (AGENTS.md passes at 188 lines while carrying 7.0× a conventional 200-line file's content—gate on tokens) · adherence to 10 pile-dictated behaviours at ceiling across 3 conditions × 3 rounds (90/90, spread 0 pp)—a ceiling proves the LEVEL, never the SLOPE, so "volume degrades adherence" stays unanswered · under 5 planted contradictions, workers detected + disclosed them 3/3 rather than silently degrading—[see the record](https://github.com/TheColliery/.github/blob/main/benchmarks/Governance/RESULTS.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **SkillDeterminism** | the second non-tool benchmark (2026-07-31 to 2026-10-18, last updated 2026-10-22; Claude Code, haiku/sonnet/opus tier aliases, exact model ids not recorded): do independent readers extract the SAME directives from the SAME shipped `SKILL.md` prose, repeated reads across weak/mid/strong tiers · two high-index skills (CoalBoard \~83, an un-indexed hook-injected cue) FAILED—one hit 67% divergence on its enumeration rail with the top tier split against itself, another reached 0% variance while unanimously WRONG (agreement ≠ correctness, always scored separately) · the one low-index skill walked (CoalMine `rot-canary`, index 12.0) PASSED its 4 pre-registered rails at 0% variance, with one small un-predicted 33.3% wobble traced to a single un-enumerated conditional · 24 further runs on five rooms' skill bodies (2026-08 to 2026-10) found that a numbered ledger took its target rail to 0% in one or two waves in most carves but not all, that a stable count can hide unstable membership, and that one null control gave a noise floor of 2 walkers of 9 (22.2 points) for one instrument on one skill · **most walked bodies have been edited since their last walk** (CoalTipple 14 commits, CoalBoard 23, CoalFace 22, CoalWash 12), so these are snapshots of named blobs, not of the skills today—[see the record](https://github.com/TheColliery/.github/blob/main/benchmarks/SkillDeterminism/RESULTS.md) |

See [**the benchmark records**](https://github.com/TheColliery/.github/tree/main/benchmarks/README.md).

***

## 📜 The 5 Doctrine Layers

Every tool inside **TheColliery** is governed by our core constitution—the [**full doctrine**](https://github.com/TheColliery/.github/blob/main/DESIGN-PRINCIPLES.md) spells out every Phoenix-13 and Quantum-11 point. The lines below are one-line digests:

1. 🌐 **Works in Every Mine (Cross-Agent):** Vendor-agnostic by design, and each tool says exactly how far it has been taken—no blanket claim covers them all.

   | Tool           | Beyond Claude Code (all are validated on Claude Code)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
   | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | **CoalMine**   | **Validated on Antigravity** (the 9 canaries). Auto-cadence hooks *primed* there: built and tested against the AG 2.0 hook spec, firing unresolved (one 2026-07-12 pilot fired, one 2026-08-04 re-test recorded zero fires). **Works with** Cursor, Codex, Cline, Copilot, Gemini CLI and the other file-copy targets. Reads + analyzes anywhere.                                                                                                                                                                                                                                                                |
   | **CoalBoard**  | Antigravity: partial. The skill installs and starts, but Antigravity loads only the first 24,000 bytes of a SKILL.md, and CoalBoard's SKILL.md body is more than twice that (51,244 bytes at 2.8.10, 51,554 at 2.8.11; measured 2026-10-27 with agy 1.4.8), so the instructions for steps 1 to 4 never reach it. The end-to-end validation of 2026-06-22 predates that growth and no longer holds. Needs a concurrent-subagent platform; every other named platform (Cursor, Codex, Gemini CLI, Cline, Copilot, Amp, Goose) is design-supported only. The conductor hook and cost-tiering stay Claude-Code-only. |
   | **CoalHearth** | **Validated on Claude Code. Antigravity 2.0: validated** on the native plugin path (headless `agy -p`, 2026-10-08; the global and project `hooks.json` paths stay unproven). **Works with** Gemini CLI, GitHub Copilot CLI, Devin CLI, Kiro and Augment Code: built and hermetically tested against each platform's primary docs, not yet validated by a real run. Runs wherever a platform has both a session-start-class event and a per-tool event.                                                                                                                                                           |
   | **CoalWash**   | **Validated end-to-end on Claude Code only**; every other platform **works with** CoalWash via the file-copy install: designed-degrade-safe, not yet validated.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
   | **CoalLedger** | **Validated on Claude Code** (live plugin). **Works with** Antigravity, Cursor, Codex, Gemini CLI, Cline and Copilot—built for them, not yet run end-to-end there. **claude.ai: works with**—upload confirmed 2026-10-09 (`doc-rot.zip`, two accounts); the Release carries the seven ZIPs and a `SHA256SUMS.txt`. Reads + analyzes anywhere; `doc-structure` additionally runs its bundled zero-dep engine (Node only—no install, no network).                                                                                                                                                                  |
   | **CoalFace**   | **Works with** every concurrent-subagent platform (Antigravity, Cursor, Codex, Gemini CLI, Cline, Copilot)—the swarm is e2e-proven only on Claude Code; re-verify on yours.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
   | **CoalTipple** | **Claude Code only** (validated live across the 2.1.x line), by product judgement: routing needs an agent that picks a spawned worker's model AND effort. Antigravity's `invoke_subagent` does pick a per-spawn tier, but a cross-vendor Google tier with no effort knob -- a different, unbuilt product. Cowork: not verified here. claude.ai (chat): no Agent/Task tool, nothing to actuate through. Cursor, Zed, OpenCode, Devin, Kiro, Copilot CLI: candidates under monthly review, not supported.                                                                                                          |

   Headline tiers are exactly two words, per [DOC-PATTERN.md](https://github.com/TheColliery/.github/blob/main/DOC-PATTERN.md#platform-tiers-row-4-locked-2026-08-01): **validated** = we built it, test it, run it here daily · **works with** = it installs and runs, documented, not yet run by us. Neither is a promise; a `works with` row becomes `validated` only after a real run. CoalTipple carries no `works with` row because it does not run on any other platform at all—the cell states why, not a tier.
2. 🦅 **Phoenix 13 Compliance:** Immortal hooks, all **13** commandments—fail-silent · zero-dependency · zero-latency · zero-garbage · zero-side-effects · stateless · offline · deterministic · portable · sandboxed · future-proof · self-healing · zero-noise.
3. 🔬 **Quantum 11 Performance:** All **11** principles—maximum output · zero visible errors · single brand · minimum power + consent · essential accessories · error correction · determinism · isolation · measurement · trust · entanglement.
4. 🛡️ **Antivirus/ESET Heuristics:** Heuristic detection plus definition-freshness stamps (revalidate dates) and consent-gated updates—never a silent one.
5. 🔌 **Single Power Button:** Absolute minimal setup—a single command installs and runs the conductor.

> 🔑 **Least-power, in one place:** the [**Permission Matrix**](https://github.com/TheColliery/.github/blob/main/PERMISSION-MATRIX.md) lists the minimum capability each tool requests—and the rights it deliberately never asks for, proven absent rather than merely unused.

***

## 🧩 The 5 Standard Systems

Beyond the doctrine, each tool is built like a proper program—it ships the same five standard systems, so any tool feels familiar the moment you open it (the [**full doctrine**](https://github.com/TheColliery/.github/blob/main/DESIGN-PRINCIPLES.md#the-5-standard-systems) has the detail):

1. ⚙️ **Config**—**two levels**: a global `~/.claude/.<tool>.json` plus a per-project `.<tool>.json` override (project wins). Install a tool globally, then re-tune—**or shut it off entirely**—per project: a skill you don't need in a given project stops loading (and burning tokens) there. Schema-validated, range-clamped; nothing load-bearing is hard-coded out of reach.
2. 🌍 **Language**—output auto-detects the conversation's language (English is the always-safe fallback—zero setup) and can be locked via config. Prose is translated; technical terms—commands, paths, identifiers, config keys, model/tier/severity names—are kept **verbatim** (a translated command is a broken command).
3. 🔄 **Self-Update**—a tool checks for and applies its own updates (consent-gated, offline-graceful), and every version transition leaves **no old-version leftover**—stale caches and renamed files are swept, never abandoned.
4. 🐛 **Problem-Report**—one command offers to file an issue upstream, with any memory content scrubbed first; nothing is ever submitted without your say-so.
5. 📊 **Measurement**—a `/stats` command shows what the tool actually did and what it was worth—tokens saved, issues caught, or fidelity preserved; a quality tool should prove its own impact.

***

## 📜 License—per zone, not one blanket

TheColliery is a portfolio, not one licence. The Coal\* skill suite above ships **Apache-2.0**—see each repo's own `LICENSE`. Other zones of the series (a code product, a spec, an article, a model's weights) ship whatever licence fits what THAT artifact protects, stated in that artifact's own `LICENSE`/`README`. Never assume Apache-2.0 outside the Coal\* suite; check the repo you're looking at.

***

<p align="center"><em>More tools and skills are still deep underground. 🔦</em></p>

<p align="center">📮 Contact: <a href="mailto:info@thecolliery.org">info@thecolliery.org</a></p>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thecolliery.org/readme.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
