task-queue

Tidy-as-you-touch: when you edit a file, format it and surface linter findings — fixing what's safe — flag it for decomposition when it grows past a size budget, and hold a subtractive posture (reuse before create, delete what a change makes redundant) so an actively-worked project trends down in complexity over time, scoped to the file you touched. The standard goes quiet (one-line re-anchor) once it's recorded in the project's CLAUDE.md. Edit-time linting targets Go (goimports/gofumpt + golangci-lint), web (eslint incl. jsx-a11y, stylelint), Python (ruff) and shell (shellcheck) — findings-only, the project's own tool, fast file-scoped tools only (slow whole-project linters stay with the verification floor). It surfaces an approximate blast-radius of the touched file (Go via the toolchain's exact go list importer graph, cached per session, falling back to git grep; else git grep) so a change's affected surface gets test coverage. A Stop hook is the verification floor: after Claude finishes, if the working tree changed and the project has a discoverable test command, it runs the tests and blocks until they pass (bounded) — the safety net a non-technical owner can't produce. After a change verifies clean, the same Stop hook surfaces the deliberate whole-project prune when debt crosses a threshold (over-budget files past CLAUDE_TIDY_PRUNE_THRESHOLD, default 3) — a weight report recommending a subtractive pass (dead code, duplication, doc gaps), throttled to once per debt episode, with any cuts routed through the task-queue review loop; no manual command. Coverage ratchet: when a touched source file has no test, nudge to characterize it before changing; opt-in strict mode (CLAUDE_TIDY_COVERAGE_RATCHET=1) blocks the stop until changed source is characterized. Regression gate (always-on, narrow): the same Stop hook blocks when a changed file is BOTH a scar-tissue hotspot (one git history shows has been repeatedly FIXED — mirrors charter's outcome-memory detector, drift-guarded) AND still has no test — a fix to a proven debt-magnet can silently regress, so it must be pinned by a regression test before finishing. Safe to keep on by default because it only fires on files that have earned it and goes quiet the moment a test lands (closing the loop charter's scar-tissue detection opens); bounded like the test floor (can't loop), disable with CLAUDE_TIDY_REGRESSION_GATE=0, and stands down when the broad coverage ratchet is already forcing. Quality floor: before the tests, the same Stop hook enforces the project's OWN declared quality gates beyond its test command — typecheck, a11y/perf, and architecture/dependency rules, discovered as package.json scripts (npm/pnpm/yarn) — running detect-and-run (installs/invents nothing; heavy Lighthouse/CWV audits stay in CI) and blocking until they pass, bounded like the test floor; disable with CLAUDE_TIDY_QUALITY_FLOOR=0. Clean-architecture check (zero owner config): after a clean verify it also surfaces any import CYCLE that involves a file changed this turn — detect-and-run the project's own madge (no bespoke resolver; silent without it; Go/Rust cycles are compiler errors the floor already catches), non-blocking and content-deduped per session, disable with CLAUDE_TIDY_CYCLE_CHECK=0. Coupling-density trend: the same post-green surface nudges when import-edges-per-file (a size-normalized coupling proxy, so healthy growth doesn't false-alarm) climbs past a threshold vs the last check — turning 'watch total coupling' into a measured signal; per-repo baseline, non-blocking, disable with CLAUDE_TIDY_COUPLING_TREND=0.

Know the project + own the owner relationship. At SessionStart, a compact proportional brief that gates substantive work on the project's Claude-facing docs: quality attributes (Lighthouse-aligned for web), a project map (file→responsibility index, for blast radius), recorded decisions/ADRs (the alignment anchor — don't reverse without consulting), a roadmap/backlog, stack notes, and the project's established conventions (reuse before create) — generating them from code/git when missing and going quiet once they're summarised in CLAUDE.md (claude-companion marker). Surfaces outcome memory — "scar tissue": files this project has REPEATEDLY had to FIX, derived from git history by the rework ratio (fix/revert commits over total touching a file), not raw churn — so the review loop treats debt magnets as high-risk (understand why they churn, cover them, prefer the smallest change, or simplify an over-built abstraction) before extending them; surfaced even in quiet mode (it's state, not policy), silent on a clean/new repo. Owns the non-technical owner loop: confirm intent in plain language → demonstrate the result back → recap. Adds an alignment floor — a bounded Stop hook (the outcome-time complement to the review loop's intent-time alignment): when a finished change plausibly bears on a recorded decision (a dependency manifest / config / migration changed, or a backtick-fenced decision token appears in the diff), it blocks once and puts the recorded decisions in front of the model — honor them, or, if the change reverses/contradicts one, surface that to the owner in plain language and confirm before it lands. Silent on routine edits and on projects with no recorded decisions; bounded (≤ CLAUDE_CHARTER_ALIGN_MAX blocks/session, never twice for the same tree) so it can't loop; disable with CLAUDE_CHARTER_ALIGN_GATE=0. /charter:align reconciles open/proposed work against recorded decisions + roadmap on demand (clean ≠ correct). Action-time consent for consequential/irreversible operations is enforced natively (settings.json auto mode + deny/ask rules), not a charter hook. MCP reachability probe: a second SessionStart hook checks that the MCP servers DECLARED for this project (merged read-only from ~/.claude.json, .mcp.json, and .claude/settings*.json) actually respond — briefly spawning each stdio server for the MCP initialize handshake and POSTing it to each http/sse endpoint, every probe hard-bounded by a per-server timeout and run in parallel — so the silent failure mode (a mis-installed/unreachable server whose tools just never appear) is surfaced to a non-technical owner in plain language; an HTTP auth challenge counts as reachable (not down), only a fresh start probes (not compact/resume), self-disables when no servers are declared, never blocks, and disables with CLAUDE_CHARTER_MCP_PROBE=0. Read-only over the project except for cache-only throttle state — it detects and the model authors the docs.

Durable, project-scoped task queue for Claude Code with Haiku triage, pause-resumable autopilot, and a status-bar reader.

A consolidated status line for the companion plugins, scoped to the signals a status line is the best surface for: a static health beacon (green/yellow/red), paused state, agent-mode, the verification floor’s ✓/✗ tests result, the count of unanswered open questions (❓N) you still owe an answer on, a coupling-rising indicator (🔗↑, shown only when tidy's last verify saw import density climbing — a cached read, never computed on render), context-window fill % (how close to a compaction, color-ramped), running session cost ($, from the payload, hidden at zero), git branch + uncommitted-file count + unpushed/unpulled commit counts (↑ahead ↓behind vs the branch's upstream — the committed-but-not-pushed companion to the dirty count), and model — rendered read-only from existing plugin state and the statusLine payload. Deliberately doesn't re-render signals already shown elsewhere (the task list Claude Code renders natively; docs-health charter nudges at session start; last tidy action) — that was duplication, and the docs mirror was the heaviest cross-plugin maintenance burden. Sets no refreshInterval: the beacon is static, so event-driven updates keep it fresh without waking jq+git on an idle timer (battery-friendly). Run /hud:setup once to wire it into settings.json with a version-resilient command (survives updates). No hooks, no scanning, zero model-token cost.