geoffmilleraz/fathom

Activate fathom's advanced features in a wired repo — guards, layer packs (kit-shipped or repo-local), module bindings, skills, loud gates — each proven by demonstration, never by assertion. Use after fathom-rewire/onboard, when adopting a kit's fathom-pack, or when a repo has the index but none of the delivered-configuration features.

Register falsifiable concerns about a repo's agent configuration (CLAUDE.md / AGENTS.md) and act on fathom config audit violations — the "instructed means true" loop, where fathom is the instrument and THIS session is the hand. Use when config feels stale, after a doctor concerns failure or a session-start config attention line, when asked to "keep CLAUDE.md honest", or to set up config contracts in a newly wired repo.

Run and interpret fathom doctor, the deterministic wiring-diagnosis checklist for a fathom-adopting repo — MCP registration, daemon reachability, binary freshness, the hook stack (installed AND firing), the AGENTS.md stanza and whether Claude Code loads it, shipped skills, config validity, obligations serving, and surface traffic. Use when asked "is fathom actually wired here", when troubleshooting missing or silent fathom behavior, right after fathom init, or before trusting a fresh session's tool access.

File friction with a fathom tool the moment you hit it — a wrong answer, a missing recall case, a confusing contract, a slow or flaky response. Use immediately after any fathom MCP tool or CLI command behaves worse than expected, even (especially) mid-task; never let the observation die unrecorded once the task moves on.

Work with fathom's findings loop — an external review kit's own findings, imported and served at the edit alongside governing rules (docs/vision/30-findings-loop.md, ADR-040). Use to import a review-kit outbox, inspect open findings (findings status/findings near/ findings candidates), refute or corroborate one with fathom claim, read an import receipt honestly, or explain what fathom does and does not do with an imported finding's authority.

Narrate fathom's measured impact in this repo, honestly — run fathom instrument --adoption (the flywheel's gauge) plus fathom plans status and the open-observation backlog, and report exactly what those instruments measured, no more. Use when asked "is fathom actually helping here", "what has fathom caught", for a periodic adoption check-in, or before claiming any fathom-driven win in a summary, standup update, or PR description.

Wire a repo end-to-end into fathom's coding-agent story: build/install the binary, stand up (or point at) a serve-http daemon, ingest the repo, register the MCP surface with Claude Code and/or Codex, wire the Claude Code hook stack, scaffold .fathom/ (config.toml, layers, rules), and confirm the whole loop is live with a verification checklist. Use when asked to "set up fathom", "wire fathom into this repo", "onboard fathom", or "get the fathom MCP tools working here".

Scaffold a gate-ready fathom plan (grammar v2) in any repo fathom indexes. Use when asked to write, draft, or start a new plan/checklist under docs/plans/, turn a design doc into a work order, or convert a rough task list into something fathom verify can gate. Produces docs/plans/<slug>.md with stable IDs, {symbol, package} contracts grounded via the fathom MCP index, typed dispositions for skipped work, and the verify command to run before any box is checked — so the plan is born gate-ready instead of needing a rewrite pass after the fact.

Reconcile this repo's fathom wiring in place — hooks vs the current template, stale binary paths repointed to the PATH shim, stanza regenerated, index refreshed with a canonical root, then proven by demonstration. Use when doctor or the session line reports wiring drift, after a fathom upgrade, when hooks feel silent, or whenever a repo was wired by hand at an unknown vintage. Knows doctor's known false signals so you don't chase wrong-repo readings.

Run and interpret fathom's "done means proven" gate for any fathom-indexed repo. Use before checking off a docs/plans/*.md box, before a git push, when asked whether a plan's claims actually hold, or to see computed SDD progress (fathom plans status/next). Explains exit codes 0/1/2, --strict vs the default, --require-all, and the fail-open convention for an unreachable daemon or an empty index.