Contributing to CoalTipple

August 31, 2026 · View on GitHub

CoalTipple is the model/effort router of the TheColliery series. We welcome issues, bug reports, and pull requests.

🤝 Proposing a Change

Open an issue first describing the problem, routing gap, or proposed feature (especially for changes to SKILL.md).
Make your code changes and ensure the verification gates remain green.
For routing or SKILL.md changes, dogfood it live on Claude Code and document the routing behavior in your PR description.

💻 Developing & Testing

CoalTipple is zero-dependency (built using Node.js built-ins only, Node 22+). No npm install is required.

Keep the verification gates green before and after making edits:

# after editing a skill, hook, or manifest, rebuild the dist FIRST — verify checks dist-sync:
node scripts/build-plugin.mjs   # re-sync the conductor from keywords.mjs (the SSoT)
node scripts/build-dist.mjs     # compile plugin/ from source
node scripts/verify.mjs         # validates config schemas, plugins, and SSoT sync
node scripts/test.mjs           # runs the zero-dependency test runner (node --test)

Development Rules

keywords.mjs is the Single Source of Truth: Edit keywords there, run node scripts/build-plugin.mjs to re-sync the conductor, then node scripts/build-dist.mjs to compile the distribution. Do not hand-edit hooks directly.
Synchronize plugin/: Rebuild the plugin distribution after modifying the core skill, hooks, or manifest.
Add Unit Tests: Every shared helper should have a corresponding *.test.mjs test file.
Keep Hooks Phoenix-Pure: Hooks must have zero dependencies, fail-silent execution (wrap in try/catch, never exit non-zero), and run 100% locally; hooks ship a hermetic spawn test (hooks-safety.md §7).
Language & Tone: Shipped source files and documentations must stay in English.

CoalTipple is Claude Code only. Routing actuates only where an agent can pick a spawned worker's model and effort — Claude Code's Agent/Task model parameter. Antigravity's invoke_subagent DOES take a per-spawn Model field (proven live 2026-08-04), but it selects a GOOGLE model regardless of the Claude parent's vendor and carries no effort knob — CT's never-down gate, qualityBar staircase, and Claude alias floor don't map onto that shape, so it is not supported. Cursor, Codex, Gemini CLI, Cline, and Windsurf are unverified and under monthly review.

Platform	Support Status
Claude Code	Validated across the 2.1.x line - Hardened across every model tier (Haiku, Sonnet, Opus); routing degrades safe on any CC version.

Note: skills/coaltipple/SKILL.md is the highest-risk file. Prompts cannot be validated via unit tests; changes must be verified through actual live agent dogfooding.

🗂️ Project Layout

Path	Purpose
`skills/coaltipple/SKILL.md`	The core routing contract (the load-bearing prompt).
`scripts/lib/`	Core logic modules: `grade`, `classify` (Lock ranking), `keywords` (SSoT), `config-schema`.
`scripts/`	Tool scripts: `install.mjs`, `configure.mjs`, `verify.mjs`, `test.mjs`.
`hooks/coaltipple-conductor.js`	Phoenix-pure conductor hook (SessionStart + UserPromptSubmit). Auto-synced by build scripts.
`plugin/`	Generated Claude Code plugin distribution.
`platform-configs/.coaltipple.json`	Commented factory default configuration.

🚀 Releasing (Maintainers)

Bump version in .claude-plugin/plugin.json ➡️ Add a changelog entry in CHANGELOG.md ➡️ Ensure verify.mjs and test.mjs pass ➡️ Commit ➡️ Create a signed git tag (vX.Y.Z) ➡️ Push --follow-tags ➡️ 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 according to SECURITY.md.