🐤 CoalMine

A mine's canary dies first so the miners live — these nine die first so your codebase lives.

9 Quality-Safeguard Canaries for AI Coding Agents — Detect code rot, weak rules, hallucinations, supply-chain vulnerabilities, brittle architectures, and API contract drift before they pollute your codebase.

Design Principles · Benchmark · Contributing · Changelog · Security · Privacy · Releases

Part of TheColliery — siblings: CoalTipple (model/effort routing) · CoalBoard (consensus & debate board) · CoalHearth (session warm-resume) · CoalFace (fan-out discipline) · CoalWash (memory defrag) · CoalLedger (docs health).

---

🐤 The 9 Canaries

Skill Name	Catches	Run Mode
rot-canary	Dead code, bugs, resource leaks, race conditions, silent failures, stale docs	Auto + Manual (runs on session end / manual trigger)
gold-standard	Audits project completeness against world-class exemplars	One-time (triggered once, governs the session)
source-grounding	Prevents AI hallucinations by forcing cross-source verification	Always-on (background rule for all chat sessions)
supply-chain-audit	Audits dependency vulnerabilities, licenses, phone-home code, and build/CI security	On-demand (manually run when relevant)
resilience-audit	Audits failure path handling (FMEA), rollbacks, retry limits, and idempotency	On-demand (manually run when relevant)
telemetry-canary	Audits observability, log structures, metrics, and telemetry quality	On-demand (manually run when relevant)
testability-canary	Audits testing ease, code coupling, mockability, and Dependency Injection (DI)	On-demand (manually run when relevant)
scale-canary	Audits performance scaling issues, $O(N^2)$ loops, and duplicate (N+1) database queries	On-demand (manually run when relevant)
drift-canary	Prevents contract and schema drift (API/database contract inconsistencies)	On-demand (manually run when relevant)

Run Mode Details:

• 📌 Always-on: Runs implicitly in the background to verify facts.
• 🔄 Auto + Manual: Scans affected files at session end via lifecycle hooks (auto-wired in Claude Code; manual snippets in platform-configs/hooks/ for other agents). Manual trigger via /rot-canary.
• ⚡ One-time: Governs the session by scanning and filling project-local rules.
• 🎯 On-demand: Manually run for specific tasks to conserve tokens.

Canaries follow grounding in evidence, zero grade inflation, and report before fixing. Fixes apply through a safe loop: Stash/Commit -> Apply fix -> Run build+tests -> Auto-revert if tests fail.

---

🔌 Universal Agent Support

SKILL.md is an open standard compatible with all major AI coding agents:

AI Agent	Target Skills Folder	Installation Shortcut	Choice Tool Support
Claude Code	plugin cache (recommended) or ~/.claude/skills/	/plugin install coalmine@coalmine	✅ Native: AskUserQuestion
Antigravity	.agents/skills/	node scripts/install.mjs antigravity	✅ Native: built-in question prompt
Cursor	.cursor/skills/	node scripts/install.mjs cursor	✅ Native: built-in ask-question tool
Devin Desktop (ex-Windsurf)	.windsurf/skills/	node scripts/install.mjs windsurf	✅ Native: suggested_responses
GitHub Copilot	.github/skills/	node scripts/install.mjs copilot	✅ Native: askQuestions
Cline	.claude/skills/	node scripts/install.mjs cline	✅ Native: ask_question
Gemini CLI (business-tier; individual tiers ended 2026-06-18 → Antigravity CLI)	.gemini/skills/	node scripts/install.mjs gemini	✅ Native: ask_user
Goose	.agents/skills/	node scripts/install.mjs goose	⚠️ Text Fallback: no question tool
Amp	.agents/skills/	node scripts/install.mjs amp	⚠️ Text Fallback: tool not documented
Junie	.junie/skills/	node scripts/install.mjs junie	⚠️ Text Fallback: tool not documented
Codex	.agents/skills/	node scripts/install.mjs codex	✅ Native: request_user_input
Kiro	.kiro/skills/	node scripts/install.mjs kiro	⚠️ Text Fallback: tool not documented
Augment Code	.augment/skills/	node scripts/install.mjs augment	⚠️ Text Fallback: tool not documented

Skill paths follow the cross-vendor Agent Skills spec. Cline reads .claude/skills/, Junie reads .junie/skills/, Kiro reads .kiro/skills/, Augment reads .augment/skills/, others use .agents/skills/.

What ports where

Part	Portable?
The 9 skills (the audits)	✅ All targets natively via Agent Skills spec
Interactive choice menus (ask_question)	✅ Native question tools on most agents; text fallback on Goose/Amp/Junie
Sub-agent fan-out + tiers	✅ Supported if host has sub-agent system; inline fallback
rot-canary auto-cadence	✅ Auto-wired on Claude Code; 🔧 wired on Antigravity 2.0 via a one-time hooks.json copy (see Install) + manual snippets in platform-configs/hooks/ for other hook-capable agents; ⛔ unsupported on Cline/Junie

Manual Fallback: Copy conformed skill body from plugin/skills/<name>/SKILL.md (strip YAML frontmatter) into AGENTS.md / rules file.

---

🚀 Install

Per-platform, at a glance — every canary is a read/analyze skill, so it runs wherever a SKILL.md loads; only the rot-canary auto-cadence hook is host-dependent (Claude Code auto-wires it; a manual snippet covers other hook-capable hosts).

Platform	Tier	Install
Claude Code	validated	/plugin marketplace add HetCreep/CoalMine → /plugin install coalmine@coalmine (Option A) — auto-wires the rot-canary Stop-hook
Antigravity	validated (canaries) · wired (auto-cadence)	file-copy the skills to the global ~/.gemini/config/skills/ or per-project <workspace>/.agents/skills/ (node scripts/install.mjs antigravity); for the full auto-cadence (conductor + rot-canary) on AG 2.0's hook engine, copy platform-configs/hooks/antigravity-hooks.json to <workspace>/.agents/hooks.json or ~/.gemini/config/hooks.json and adjust the CoalMine path
Cursor · Codex · Cline · Copilot · Gemini CLI · …	works with	node scripts/install.mjs <agent> — file-copy into the agent's skills folder (targets in Universal Agent Support)
claude.ai (web / app)	works with	ZIP-upload a canary folder from skills/ as a custom skill (Option A3) — read/analyze skills only, manual invocation, no hooks

wired (the Antigravity auto-cadence tier) = built + hermetically tested against the empirically-verified AG 2.0 hook spec (pilot 2026-07-12 — which did fire CoalMine's Stop cadence live on AG; corroborated against the official docs 2026-07-13). Delivery of the injected context into the agent is emitted per spec but not yet validated end-to-end — one real AG session run flips it to validated. The 9 canaries themselves are already validated on AG.

Option A — Claude Code Plugin (No clone needed)

/plugin marketplace add HetCreep/CoalMine
/plugin install coalmine@coalmine

🔧 Maintainers: plugin/ is generated output. After edits in skills/, skills/_shared/, hooks/, or .claude-plugin/plugin.json, run node scripts/build-plugin.mjs.

Option A2 — skills.sh (One line)

npx skills add HetCreep/CoalMine

Option A3 — claude.ai (web / desktop app)

Zip any canary's folder from skills/ and upload it as a custom skill (Settings → Capabilities → Skills). Manual invocation only — no hooks there. Steps + capability notes: CLAUDE-AI-INSTALL.

Option B — Universal Installer

1. Clone the Repository

git clone https://github.com/HetCreep/CoalMine.git

2. Run the Installer

Run from your project's root folder (not inside the CoalMine clone):

cd /path/to/your-project
node /path/to/CoalMine/scripts/install.mjs <agent|all|PATH>

• Supported <agent>: antigravity, cursor, codex, cline, copilot, windsurf, amp, goose, junie, gemini, kiro, augment (for claude, prefer the plugin above) — see Universal Agent Support for target folders + choice-tool support.
• all auto-detects and installs to all configured agents in the directory.
• The installer sets up pre-commit/pre-push gates in .git/hooks, writes trigger rules, and generates .coalmine.json config.

3. Verify & Uninstall

• Verify: node /path/to/CoalMine/scripts/verify.mjs <agent|PATH>
• Uninstall: node scripts/install.mjs --uninstall <agent|PATH>

---

🔋 One button: install — the suite drives itself

Installing is the power button. The agent conducts the canaries and asks for consent before running expensive tasks:

What	When it fires	Your part
gold-standard	Offered once on new projects, and again when a rule's revalidate date passes	Run now / Queue / Skip
rot-canary	Auto-scans touched files at session end (QUICK); findings end with a fix menu	Choose a fix option
Specialists	Offered when conversation enters their domain (deps, schemas, async, loops, etc.)	Accept / Skip
source-grounding	Always-on background fact verification	—

Consent Rule: Nothing expensive runs silently. Revocable via .coalmine.json, ~/.claude/.rot-canary-off, or --uninstall.

---

⚙️ Configure (.coalmine.json)

Zero-config to start — and two config levels when you want them: a global ~/.claude/.coalmine.json overlaid per key by the project <gitroot>/.coalmine.json (project wins), so a globally-installed CoalMine can be tuned or shut off per project — a project that doesn't need it stops loading (and burning tokens) there (disabledCanaries: ["all"] is the full off-switch; enableConductor: false silences only the session-start conductor, leaving rot-canary's auto-scan running). The installer generates the per-project file; write the global layer with node scripts/configure.mjs --global <flags>. The high-impact keys:

Key	Default	What it does
language	auto	Language for prompts and nudges (auto | en | th | ja | zh | es)
enableConductor	true	Master switch for rules injection at session start
rotCanaryMode	auto	rot-canary session-end auto-scan (auto | manual | off)
defaultTier	auto	Force an execution tier (Light | Standard | Heavy | auto)
disabledCanaries	[]	Canaries to disable (e.g. ["rot-canary"] or ["all"])

Full key reference: every key + default lives in scripts/lib/config-schema.mjs and the commented template platform-configs/.coalmine.json — or run node scripts/configure.mjs --help.

---

📝 Ultra-Short Summary Format

Canaries report in a lean shape (one-line verdict + severity table of confirmed findings) to save tokens:

| # | path:line | category | severity | finding | evidence |

Severity levels: CRITICAL · HIGH · MEDIUM · LOW. Clean scan outputs a single line.

---

⚡ Escalation Tiers

Tier	Trigger	Orchestration	Token Cost
Light	Small scope / targeted review	Primary agent, quick	Very Low 🟢
Standard	Moderate scope / module review	Multi-threaded routing, detailed	Moderate 🟡
Heavy	Large scope / release prep	Sub-agent fan-out, deep paths	High 🔴

---

📊 Benchmark

Headline (measured 2026-07-03, skill v3.8.4): 7 canaries measured over 82 planted-defect fixtures × 4 engines (Claude Fable 5 / Opus 4.8 / Sonnet 5 / Haiku 4.5 + Gemini 3.5 Flash), K=3-5 repeated runs per arm — recall at 100% on 6 of 7 suites for every engine · zero decoy false alarms across the entire batch (~200 clean-file opportunities) · drift-canary is the discriminating suite (88% median — engines find every planted disagreement but split on which side is authoritative).

Each canary is measured AV-Comparatives-style — recall, precision, decoy false-positives, and severity accuracy over fixed fixture corpora, scored mechanically, cross-engine, with repeated runs (flips extend K per the locked methodology). Honest scope: small, dated samples authored in-project — a regression floor, not an independent benchmark; re-run on model/skill changes.

Full method, per-category scoring, and the cross-engine comparison live in the series records: TheColliery/.github/benchmarks/CoalMine.

---

🧭 Design Principles

Bound by the 11 principles of the Quantum Computer Spec: maximum performance, zero visible errors, single-brand, minimum power, essential accessories, error correction, determinism, isolation, measurement, trustworthiness, and entanglement.

---

🏭 Part of TheColliery

CoalMine shares its engineering doctrine with CoalTipple (model/effort routing), CoalBoard (consensus & debate board), CoalHearth (session warm-resume), CoalFace (fan-out discipline), CoalWash (memory defrag), and CoalLedger (docs health): Phoenix-13 hooks (zero-dependency, no network, fail-silent, no child processes, deterministic), single-source-of-truth config schemas, and a strict no-overkill discipline. Install one and it stands alone; install all and they compose without conflict.

---

📄 License

Apache License 2.0. See LICENSE for details.