Contributing to CoalBoard
August 9, 2026 · View on GitHub
CoalBoard is the consensus & debate board of the TheColliery series. We welcome issues, bug reports, and pull requests.
🤝 Proposing a Change
- Open an issue first describing the problem, gap, or proposed feature (especially for changes to
SKILL.md— the board contract). - Make your code changes and keep the verification gates green.
- For board-behavior or
SKILL.mdchanges, dogfood it live (convene the board on a real task across at least one platform) and document the behavior in your PR.
💻 Developing & Testing
CoalBoard is zero-dependency (Node.js built-ins only, Node 22+). No npm install is required.
Keep the gates green before and after editing:
node scripts/verify.mjs # validates the config schema, the manifest, the factory config, and plugin/ dist-sync
node scripts/test.mjs # runs the zero-dependency test suite (node --test)
Development Rules
- Rebuild the dist after a source change: edit
skills/,hooks/,commands/,scripts/lib/, or the manifest, thennode scripts/build-plugin.mjsto re-syncplugin/(verify fails on a stale dist). config-schema.mjsis the single source of truth for every.coalboard.jsonkey —verify.mjsvalidates the factory config against it.- Keep the conductor Phoenix-pure: zero dependencies, fail-silent (wrap in try/catch, never exit non-zero), no network, no spawn, no NUL byte.
- Add unit tests: every shared helper gets a
*.test.mjs; the conductor change gets a hermetic spawn test. Register new files inscripts/test.mjs(the runner fails on an unlisted orphan). - Language & tone: shipped source and docs stay in English.
🖥️ Supported Platforms
CoalBoard is cross-agent — it runs on any platform with concurrent subagents (the board spawns parallel-blind lenses; diversity rides the prompts, not a vendor). Claude Code additionally lets it run cheap lenses + a premium judge (a cost bonus) and auto-activates via hooks. A platform with no concurrent fan-out degrades to a sequential pass or off — never a broken board. Verify the platform's current subagent support (it churns).
Two tiers, honestly. Any subagent platform works with CoalBoard — the degrade-safe path runs (conservatively, unverified, design-supported not run end-to-end by us) with no setup, so you can use the board there today. Claude Code + Antigravity are validated end-to-end. Validation follows access, not a request queue: if you run a platform we haven't, open an issue at Issues and we'll walk you through a one-off capability probe you run on your side, then we confirm the result and ship a tuned adapter. The probe prompts stay private, and we never mark a platform "validated" until it's actually been run there — the free degrade-safe path is always there; "validated" is earned by whoever has the platform.
🗂️ Project Layout
| Path | Purpose |
|---|---|
skills/coalboard/SKILL.md | The board contract (the load-bearing prompt). |
scripts/lib/ | Core logic: config-schema, trigger (AND-gate), rigor (preset), secrets (scrubber). |
scripts/ | Tool scripts: build-plugin.mjs, verify.mjs, test.mjs. |
hooks/coalboard-conductor.js | Phoenix-pure conductor hook (SessionStart + UserPromptSubmit). Auto-synced by the build. |
plugin/ | Generated Claude Code plugin distribution. |
platform-configs/.coalboard.json | Commented factory default configuration. |
| (benchmark) | The with-the-board-vs-without benchmark lives in the series records — TheColliery/.github/benchmarks/CoalBoard — kept out of the clone (clean-clone: a skill repo carries only the skill). |
🚀 Releasing (Maintainers)
Bump version in .claude-plugin/plugin.json ➡️ add a CHANGELOG.md entry ➡️ ensure verify.mjs and test.mjs pass ➡️ commit ➡️ create a signed git tag (vX.Y.Z) ➡️ push ➡️ create a GitHub Release (stable tags only).
📄 License & Conduct
Contributions are licensed under the Apache License 2.0. Please assume good faith and be respectful. Report security issues per SECURITY.md.