{"id":50666684,"url":"https://github.com/hetcreep/coalmine","last_synced_at":"2026-07-02T10:01:03.664Z","repository":{"id":362587818,"uuid":"1259836955","full_name":"HetCreep/CoalMine","owner":"HetCreep","description":"9 quality-canary skills for AI coding agents - code health, gold-standard rules, anti-hallucination grounding, supply chain, resilience, observability, testability, scaling, contract drift. Consent-gated, token-lean, one-button install, works across all major AI coding agents.","archived":false,"fork":false,"pushed_at":"2026-06-15T08:19:04.000Z","size":456,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T08:21:35.173Z","etag":null,"topics":["agent-skills","ai-agents","ai-coding","claude","claude-code","code-health","code-quality","code-review","developer-tools","skills"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HetCreep.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-04T23:02:22.000Z","updated_at":"2026-06-15T08:19:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/HetCreep/CoalMine","commit_stats":null,"previous_names":["hetcreep/coalmine"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/HetCreep/CoalMine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HetCreep%2FCoalMine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HetCreep%2FCoalMine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HetCreep%2FCoalMine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HetCreep%2FCoalMine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HetCreep","download_url":"https://codeload.github.com/HetCreep/CoalMine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HetCreep%2FCoalMine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35041999,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agents","ai-coding","claude","claude-code","code-health","code-quality","code-review","developer-tools","skills"],"created_at":"2026-06-08T07:03:55.914Z","updated_at":"2026-07-02T10:01:03.651Z","avatar_url":"https://github.com/HetCreep.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🐤 CoalMine\n\n\u003e *A mine's canary dies first so the miners live — these nine die first so your codebase lives.*\n\n**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.\n\n![version](https://img.shields.io/github/v/tag/HetCreep/CoalMine?label=version\u0026color=blue)\n![license](https://img.shields.io/badge/license-MIT-blue)\n![status](https://img.shields.io/badge/status-live-brightgreen)\n![SKILL.md](https://img.shields.io/badge/SKILL.md-open_standard_·_major_agents-success)\n![skills](https://img.shields.io/badge/skills-9-success)\n![Claude Code](https://img.shields.io/badge/Claude_Code-validated-success)\n![agents](https://img.shields.io/badge/works_with-Claude_·_Antigravity_·_Cursor_·_Windsurf-informational)\n\n[Design Principles](https://github.com/TheColliery/.github/blob/main/DESIGN-PRINCIPLES.md) · [Benchmark](https://github.com/TheColliery/.github/tree/main/benchmarks/CoalMine) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md) · [Privacy](PRIVACY.md) · [Releases](https://github.com/HetCreep/CoalMine/releases)\n\n**Part of [TheColliery](https://github.com/TheColliery)** — siblings: **[CoalTipple](https://github.com/TheColliery/CoalTipple)** (model/effort routing) · **[CoalBoard](https://github.com/TheColliery/CoalBoard)** (consensus \u0026 debate board).\n\n\u003c/div\u003e\n\n---\n\n## 🐤 The 9 Canaries\n\n| Skill Name | Catches | Run Mode |\n|---|---|---|\n| **`rot-canary`** | Dead code, bugs, resource leaks, race conditions, silent failures, stale docs | **Auto + Manual** (runs on session end / manual trigger) |\n| **`gold-standard`** | Audits project completeness against world-class exemplars | **One-time** (triggered once, governs the session) |\n| **`source-grounding`** | Prevents AI hallucinations by forcing cross-source verification | **Always-on** (background rule for all chat sessions) |\n| **`supply-chain-audit`** | Audits dependency vulnerabilities, licenses, phone-home code, and build/CI security | **On-demand** (manually run when relevant) |\n| **`resilience-audit`** | Audits failure path handling (FMEA), rollbacks, retry limits, and idempotency | **On-demand** (manually run when relevant) |\n| **`telemetry-canary`** | Audits observability, log structures, metrics, and telemetry quality | **On-demand** (manually run when relevant) |\n| **`testability-canary`** | Audits testing ease, code coupling, mockability, and Dependency Injection (DI) | **On-demand** (manually run when relevant) |\n| **`scale-canary`** | Audits performance scaling issues, $O(N^2)$ loops, and duplicate (N+1) database queries | **On-demand** (manually run when relevant) |\n| **`drift-canary`** | Prevents contract and schema drift (API/database contract inconsistencies) | **On-demand** (manually run when relevant) |\n\n*Run Mode Details:*\n* 📌 **Always-on:** Runs implicitly in the background to verify facts.\n* 🔄 **Auto + Manual:** Scans affected files at session end via lifecycle hooks (auto-wired in Claude Code; manual snippets in [`platform-configs/hooks/`](platform-configs/hooks/) for other agents). Manual trigger via `/rot-canary`.\n* ⚡ **One-time:** Governs the session by scanning and filling project-local rules.\n* 🎯 **On-demand:** Manually run for specific tasks to conserve tokens.\n\n*Canaries follow **grounding in evidence, zero grade inflation, and report before fixing**. Fixes apply through a safe loop: `Stash/Commit -\u003e Apply fix -\u003e Run build+tests -\u003e Auto-revert if tests fail`.*\n\n---\n\n## 🔌 Universal Agent Support\n\n`SKILL.md` is an **open standard** compatible with all major AI coding agents:\n\n| AI Agent | Target Skills Folder | Installation Shortcut | Choice Tool Support |\n|---|---|---|---|\n| **Claude Code** | plugin cache (recommended) or `~/.claude/skills/` | `/plugin install coalmine@coalmine` | ✅ **Native:** `AskUserQuestion` |\n| **Antigravity** | `.agents/skills/` | `node scripts/install.mjs antigravity` | ✅ **Native:** built-in question prompt |\n| **Cursor** | `.cursor/skills/` | `node scripts/install.mjs cursor` | ✅ **Native:** built-in ask-question tool |\n| **Windsurf** | `.windsurf/skills/` | `node scripts/install.mjs windsurf` | ✅ **Native:** `suggested_responses` |\n| **GitHub Copilot** | `.github/skills/` | `node scripts/install.mjs copilot` | ✅ **Native:** `askQuestions` |\n| **Cline** | `.claude/skills/` | `node scripts/install.mjs cline` | ✅ **Native:** `ask_question` |\n| **Gemini CLI** | `.gemini/skills/` | `node scripts/install.mjs gemini` | ✅ **Native:** `ask_user` |\n| **Goose** | `.agents/skills/` | `node scripts/install.mjs goose` | ⚠️ **Text Fallback:** no question tool |\n| **Amp** | `.agents/skills/` | `node scripts/install.mjs amp` | ⚠️ **Text Fallback:** tool not documented |\n| **Junie** | `.junie/skills/` | `node scripts/install.mjs junie` | ⚠️ **Text Fallback:** tool not documented |\n| **Codex** | `.agents/skills/` | `node scripts/install.mjs codex` | ✅ **Native:** `request_user_input` |\n\n*Skill paths follow the cross-vendor [Agent Skills spec](https://agentskills.io/specification). Cline reads `.claude/skills/`, Junie reads `.junie/skills/`, others use `.agents/skills/`.*\n\n### What ports where\n\n| Part | Portable? |\n|---|---|\n| The 9 skills (the audits) | ✅ All targets natively via Agent Skills spec |\n| Interactive choice menus (`ask_question`) | ✅ Native question tools on most agents; text fallback on Goose/Amp/Junie |\n| Sub-agent fan-out + tiers | ✅ Supported if host has sub-agent system; inline fallback |\n| rot-canary **auto-cadence** | ✅ Auto-wired on Claude Code; 🔧 manual snippets in [`platform-configs/hooks/`](platform-configs/hooks/) for other major agents; ⛔ unsupported on Cline/Junie |\n\n**Manual Fallback:** Copy conformed skill body from [`plugin/skills/\u003cname\u003e/SKILL.md`](plugin/skills/) (strip YAML frontmatter) into `AGENTS.md` / rules file.\n\n---\n\n## 🚀 Install\n\n### Option A — Claude Code Plugin (No clone needed)\n```text\n/plugin marketplace add HetCreep/CoalMine\n/plugin install coalmine@coalmine\n```\n\n\u003e 🔧 **Maintainers:** `plugin/` is generated output. After edits in `skills/`, `skills/_shared/`, `hooks/`, or `.claude-plugin/plugin.json`, run `node scripts/build-plugin.mjs`.\n\n### Option A2 — skills.sh (One line)\n```bash\nnpx skills add HetCreep/CoalMine\n```\n\n### Option B — Universal Installer\n\n#### 1. Clone the Repository\n```bash\ngit clone https://github.com/HetCreep/CoalMine.git\n```\n\n#### 2. Run the Installer\nRun from **your project's root folder** (not inside the CoalMine clone):\n```bash\ncd /path/to/your-project\nnode /path/to/CoalMine/scripts/install.mjs \u003cagent|all|PATH\u003e\n```\n* `all` auto-detects and installs to all configured agents in the directory.\n* The installer sets up pre-commit/pre-push gates in `.git/hooks`, writes trigger rules, and generates `.coalmine.json` config.\n\n#### 3. Verify \u0026 Uninstall\n* **Verify:** `node /path/to/CoalMine/scripts/verify.mjs \u003cagent|PATH\u003e`\n* **Uninstall:** `node scripts/install.mjs --uninstall \u003cagent|PATH\u003e`\n\n---\n\n## 🔋 One button: install — the suite drives itself\n\nInstalling is the power button. The agent conducts the canaries and asks for consent before running expensive tasks:\n\n| What | When it fires | Your part |\n|---|---|---|\n| **gold-standard** | Offered once on new projects, and again when a rule's `revalidate` date passes | Run now / Queue / Skip |\n| **rot-canary** | Auto-scans touched files at session end (QUICK); findings end with a fix menu | Choose a fix option |\n| **Specialists** | Offered when conversation enters their domain (deps, schemas, async, loops, etc.) | Accept / Skip |\n| **source-grounding** | Always-on background fact verification | — |\n\n*Consent Rule:* Nothing expensive runs silently. Revocable via `.coalmine.json`, `~/.claude/.rot-canary-off`, or `--uninstall`.\n\n---\n\n## 🛡️ Work Execution Gate \u0026 Haldane Safety\n\n1. **Work Execution Gate:** Before starting a task, the agent presents a confirm menu:\n   * **ทำทันที / Do now** — Assess scope, recommend tier, and execute.\n   * **เก็บเข้าแผนงาน / Add to plan** — Queue in `task.md`.\n   * **ดูแผนงานทั้งหมด / View full plan** — View queued tasks, adjust tiers, and run.\n2. **Haldane Safety Protocol (for sub-agents):**\n   * Active files edited by sub-agents are marked `[/] in-flight` in `task.md` to prevent collisions.\n   * If conversation shifts to topics affecting in-flight files, the agent warns you first.\n3. **Proactive Suggestions:** The agent automatically offers canary runs via `ask_question` when relevant changes (e.g., adding a package) are detected.\n\n---\n\n## ⚙️ Configure (.coalmine.json)\n\n* **General Users (Zero-Config):** Automatically generated `.coalmine.json` pre-configured with safe, token-optimal defaults.\n* **Programmers (Overrides):** Inline comments document every key. Run the configurator tool or edit manually.\n\n### Configuration Schema\n\nThe full key set (the source of truth is `scripts/lib/config-schema.mjs`; the shipped `platform-configs/.coalmine.json` template documents every key inline):\n\n| Key | Type | Default | Description |\n|---|---|---|---|\n| `language` | String | `auto` | Override language detection (`auto` \\| `en` \\| `th` \\| `ja` \\| `zh` \\| `es`) |\n| `enableConductor` | Boolean | `true` | Set false to disable rules injection on Session Start |\n| `skipOnboarding` | Boolean | `false` | Skip the gold-standard onboarding offer at session start |\n| `defaultTier` | String | `auto` | Force execution tier (`Light` \\| `Standard` \\| `Heavy` \\| `auto`) |\n| `rotCanaryMode` | String | `auto` | rot-canary auto-scan mode (`auto` \\| `manual` \\| `off`) |\n| `autoScanFileCap` | Number | `10` | Maximum touched files to scan at session end |\n| `autoScanFileCapSlice` | Number | `5` | Most-recently-modified files kept when `autoScanFileCap` is exceeded (a count, not a fraction) |\n| `tripwireMaxFileSizeKb` | Number | `100` | Size limit in KB for the tripwire scan |\n| `tripwireMaxLines` | Number | `800` | Line count that flags a file as a smell |\n| `tempSweepStaleDays` | Number | `7` | Age in days before session temp files are swept |\n| `watchedExtensions` | Array | `[]` | File extensions the touch hook watches (empty = defaults) |\n| `updateMode` | String | `ask` | Self-update behavior at session start (`ask` \\| `auto` \\| `remind` \\| `off`) |\n| `updateCheckDays` | Number | `14` | Days between self-update checks/reminders |\n| `ruleRevalidateDays` | Number | `90` | Days before general rules need re-validation |\n| `platformRuleRevalidateDays` | Number | `30` | Days before platform/model rules need re-validation |\n| `definitionRevalidateDays` | Number | `90` | Days before general reference definitions are stale |\n| `platformDefinitionRevalidateDays` | Number | `30` | Days before platform definitions are stale |\n| `disabledCanaries` | Array | `[]` | Canaries to disable (e.g. `[\"rot-canary\"]` or `[\"all\"]`) |\n| `autoFixMode` | String | `interactive` | Default fix-mode behavior (`interactive` \\| `safe` \\| `off`) |\n| `schemaPaths` | Array | `[]` | Glob paths to schemas / API specs |\n| `migrationDirs` | Array | `[]` | Database migration directories |\n| `packageManifests` | Array | `[]` | Package manifest / lockfile paths |\n| `trustedDomains` | Array | `[]` | Extra trusted domains for source grounding |\n\n### Configurator Utility\n```bash\n# Set language and cap limit\nnode scripts/configure.mjs --language th --file-cap 15\n\n# Disable specific canaries (mechanically enforced for rot-canary/conductor; advisory for skill-canaries)\nnode scripts/configure.mjs --disable rot-canary\n```\n\n---\n\n## 📝 Ultra-Short Summary Format\n\nCanaries report in a lean shape (one-line verdict + severity table of confirmed findings) to save tokens:\n```text\n| # | path:line | category | severity | finding | evidence |\n```\n*Severity levels:* CRITICAL · HIGH · MEDIUM · LOW. Clean scan outputs a single line.\n\n---\n\n## ⚡ Escalation Tiers\n\n| Tier | Trigger | Orchestration | Token Cost |\n|---|---|---|---|\n| **Light** | Small scope / targeted review | Primary agent, quick | Very Low 🟢 |\n| **Standard** | Moderate scope / module review | Multi-threaded routing, detailed | Moderate 🟡 |\n| **Heavy** | Large scope / release prep | Sub-agent fan-out, deep paths | High 🔴 |\n\n---\n\n## 📊 Benchmark\n\n**Headline:** `rot-canary` scored **100% recall · 100% precision · 0/4 decoy false-positives** over the 16-fixture corpus, scored mechanically (skill v3.4.0, 2026-06-13).\n\n`rot-canary` is measured AV-Comparatives-style — recall, precision, decoy false-positives, and severity accuracy over a fixed fixture corpus, scored mechanically, cross-engine. **Honest scope:** small, dated samples authored in-project — a regression floor, not an independent benchmark; re-run on model/skill changes.\n\nFull method, per-category scoring, and the cross-engine comparison live in the series records: [`TheColliery/.github/benchmarks/CoalMine`](https://github.com/TheColliery/.github/tree/main/benchmarks/CoalMine).\n\n---\n\n## 🧭 Design Principles\n\nBound by the 11 principles of the [Quantum Computer Spec](https://github.com/TheColliery/.github/blob/main/DESIGN-PRINCIPLES.md): maximum performance, zero visible errors, single-brand, minimum power, essential accessories, error correction, determinism, isolation, measurement, trustworthiness, and entanglement.\n\n---\n\n## 🏭 Part of TheColliery\n\nCoalMine shares its engineering doctrine with [CoalTipple](https://github.com/TheColliery/CoalTipple) (model/effort routing) and [CoalBoard](https://github.com/TheColliery/CoalBoard) (consensus \u0026 debate board): 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.\n\n---\n\n## 📄 License\n\nMIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhetcreep%2Fcoalmine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhetcreep%2Fcoalmine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhetcreep%2Fcoalmine/lists"}