claude-code-toolkit

Template repo for bootstrapping projects with Claude Code config. It ships no application code — the deliverable is the config itself.

Layout

• templates/<variant>/ — six variants: general, dotnet, dotnet-maui, rust-tauri, java, python. Each carries CLAUDE.md, AGENT_TEAM.md, PROJECT_CONTEXT.md, PROJECT_STATE.md, gitignore, .claude/{settings.json,agents/,rules/}.
• user-level-reference/ — the copyable source for ~/.claude/ (CLAUDE.md, settings.json). Since v5.0 the agents, skills, output style and hooks ship in the cct plugin, whose root is the repo root: agents/, skills/, output-styles/, hooks/hooks.json.
• hooks/ — the canonical enforcement hooks, referenced by both template settings and agent frontmatter.
• scripts/ — verification and propagation tooling. setup-project.sh / .ps1 bootstrap a project.
• docs/plans/ — plans are committed markdown here, not ephemeral plan-mode files.

Gate

bash scripts/verify-template-consistency.sh, bash scripts/test-hooks.sh, and bash scripts/test-server.sh are the gate. All three must be green before a commit is claimed done. The gate command list is three since v4.0: scripts/test-setup-project.sh (bootstrap fixtures) is still invoked from verify-template-consistency.sh as check 27, and scripts/test-server.sh — the template-sync server's pytest suite in server/tests, run with the venv bash server/install.sh creates — is the third command, run at merge time by run-gate.sh and not on the per-commit **Test** path, which would double it. A missing venv fails that command loudly (bash server/install.sh once per checkout); it never skips. scripts/verify-user-level-drift.sh checks the live ~/.claude/ against a release: the rendered CLAUDE.md equal, cct@dagonet installed and enabled at that release's VERSION, no path from scripts/lib/v4-user-leftovers.txt present, autoMode.environment in settings.json equal to the reference, and hooks/verify-hooks.sh --report clean against the live HOME (no stale v4 registration); the reference leads, the live copy follows per the CHANGELOG's downstream-migration section. A release is not done until that script reports 0 drift — it is the delivery probe, replacing "remember to re-copy SKILL.md" with something that executes.

scripts/test-hooks-parser-matrix.sh runs test-hooks.sh in all three parser configurations (node, python3-only, jq-only) and asserts the restricted runs skip a non-zero, in-band number of assertions — a restricted configuration reporting zero skips is proof the restriction did not apply, not proof of improvement. Run it before a release, and after anything touching hooks/lib/json.sh or a hook that embeds a node program. It is deliberately NOT in the three-command gate list: three full suite runs is ~90 minutes (the jq configuration alone is ~70), which would make every merge unaffordable. Never re-derive the procedure by hand — the hand-run version was performed wrongly and the wrong result looked right.

Since v2.2.6 this repo gates ITSELF for real: v2.2.5 added the root PROJECT_CONTEXT.md the gates read, and v2.2.6 added the root .claude/settings.json that registers them — without both, pre-commit-test.sh and gate-before-merge.sh are registered nowhere and run on no commit, with every consistency assertion green — a census over config cannot see whether the config is REGISTERED. Do not reach for a clock to check this: a PreToolUse hook completes before the Bash tool runs the command, so a timer started inside the command cannot observe it. Read the registration, or observe a side effect that outlives the hook. .claude/settings.json is the one tracked file under /.claude/; the root .gitignore re-includes it with /.claude/* + !/.claude/settings.json, because git never descends into an excluded directory. The split: **Test** (the consistency script alone, 58-117s measured) runs on every commit via hooks/pre-commit-test.sh, and **Gate** (consistency + test-hooks.sh + test-server.sh; 512-619s measured for the first two) is what hooks/run-gate.sh runs to write the gate artifact — since v4.0.1, <common git dir>/gate/last-pass.<sha>.json (inside .git, shared by every worktree, never a working-tree object; see gc_gate_dir in hooks/lib/git-cmd.sh) — for hooks/gate-before-merge.sh. The split is deliberate — one command for both would put ten minutes on every commit. One consequence to keep in mind when touching the suite: test-hooks.sh now runs as a CHILD of run-gate.sh, which exports RUN_GATE_ACTIVE=1, so the suite unsets it — left inherited, it trips the recursion guard in every fixture that nests run-gate.sh, and those fixtures skip instead of running. The suite must not answer differently depending on who invoked it. (The CHANGELOG holds the assertion and skip counts; this file deliberately names none, so there is only one place for them to drift out of.)

Self-reference risk, and the escape hatch. The gates now enforce against the repository that defines them, so a bug in hooks/pre-commit-test.sh can block the very commit that fixes hooks/pre-commit-test.sh, and the same holds for hooks/lib/json.sh, hooks/lib/git-cmd.sh and scripts/verify-template-consistency.sh. Read the block message first — it is far more often a real red gate than a broken hook. When it genuinely is the hook, the documented escape is the pre-existing kill switch: create .claude/git-guard-off under the process cwd, make the one fix, delete it again. Never leave it in place, and never commit it.

Invariants

• AGENT_TEAM.md and .claude/settings.json are byte-identical across all six variants. verify-template-consistency.sh asserts this — edit templates/general/ first, then cp to the other variants.
• .claude-plugin/plugin.json version equals VERSION (check 72); without the bump, machines receive no update.
• The plugin root is the repo root, so a root .mcp.json, settings.json, commands/ or .lsp.json would load machine-wide in every project; none is tracked.
• Plugin agents/*.md must not carry project-only frontmatter hooks: (check 75) — they would fail closed in repos without a hooks/ directory.
• Every file is LF. scripts/template_propagate_to_variants can emit CRLF — normalize afterwards.
• Never rewrite a file containing non-ASCII through PowerShell Get-Content/WriteAllText (PS 5.1 mojibakes UTF-8). Use Bash or the Edit tool.
• Every release adds a measured column to the always-loaded context table in docs/architecture.md (Context Budget) only; the README's former copy (The trim pass, measured) is frozen at v5.1.0 in docs/history.md: wc -c on the shipped files at that release, in two subtotals — harness-injected at session start (variant CLAUDE.md + unscoped .claude/rules/project.md + the .claude/project-instructions.md seed + the user-level CLAUDE.md + the pm-report style; the file set check 35 caps) and at the end of bootstrap (+ PROJECT_CONTEXT.md, which the model reads on instruction as a tool result, not an injection) — per variant in architecture.md; AGENT_TEAM.md, VERIFICATION_PLAYBOOK.md, scoped rules and skills are the on-demand rows. Never carry a figure forward arithmetically, and never present an older column as the current state — the audit of 2026-09-19 found both tables frozen at v3.1 three releases later, counting a retired file and missing one that loads.
• This file carries the literal context-mode deliberately — in this bullet. That plugin's MCP launcher (start.mjs) appends its 63-line routing block to <project>/CLAUDE.md on every server spawn unless the file already contains that substring, and the substring is its only idempotency guard. Check 37 asserts the sentinel in all six variants and here, and re-measures the guard predicate in the installed plugin so a change there goes red rather than silent. Removing the word re-arms the injection.