refactor(claude): triage always-loaded user rules into skills, hooks, and ambient

[laurigates]

Closes #353. Paired with laurigates/claude-plugins#2450, which carries the skills and hooks these stubs point at — merge that one first, or the stubs point at nothing.

Result

114,284c → 76,564c across the 38 always-loaded rules — ~9,430 est. tokens/session, 33% off the surface, in every project, on top of the ~8.2k already landed for the portfolio rules.

The issue projected ~10,400. The gap is accounted for: prefer-diy-over-heavy-dependency (7,079c in the issue's table) was already promoted before this work started, so its ~1,600 tokens were already banked. Several other rules had grown since the issue was measured on 2026-08-05 — read-issue-thread-before-contributing 3,916 → 7,431, taskwarrior-tracking 2,978 → 4,735 — so the per-rule figures below are measured now, not copied from the issue.

Bucket 2 — nine rules with a trigger recognisable in advance

Rule	Before	After	Now lives in
read-issue-thread-before-contributing	7,431	618	git-plugin:git-issue-scoping
pr-merge-hazards	7,607	2,163	git-plugin:git-merge-hazards
multi-model-delegation	6,607	756	agent-patterns-plugin:multi-model-delegation (already existed)
verify-machine-facts-before-publishing	4,945	593	documentation-plugin:docs-verify-machine-facts
taskwarrior-tracking	4,735	620	taskwarrior-plugin:task-add / task-claim
documentation-authoring	3,093	505	documentation-plugin:docs-single-source
scaffold-fix-backport	2,960	590	code-quality-plugin:code-scaffold-backport
verify-upstream-before-patching	2,710	654	git-plugin:git-upstream-fix-check
repo-deletion-safety	2,576	649	git-plugin:git-repo-delete-check + a hook

multi-model-delegation was a free win the issue didn't have: it listed the rule as already-stubbed, but on disk it was still 6,607c of full body while an agent-patterns-plugin skill of the same name had covered 100% of it since 2026-07-17 — plus four sections the rule lacked. The dotfiles copy was the stale side. Verified section-by-section before deleting rather than taken on faith.

pr-merge-hazards keeps its two load-bearing gates inline (the gh pr list --head authority order for squash-merge detection, and UNSTABLE ≠ BLOCKED), following the worktree-stale-base-merge exception. Both are read at the instant of deciding whether to delete a branch or merge over red — there is no earlier moment at which to invoke a skill, and getting it wrong deletes unmerged work. Those copies are byte-identical to the skill's, so drift is a literal string diff.

Bucket 4 — tool-use-patterns split, not moved

9,917 → 7,713. Ambient traps stay resident; only lookup material left, with pointers in its place.

Stays	Goes
Read-before-Edit; re-Read after a formatter	WebFetch failure→fallback ladder
rg -r is --replace, not a bundled short flag	agent fan-out burst-limit guidance
"a rejected flag looks exactly like no results"	usage-limit mid-run recovery
parallel-batch cancellation; Bash denials are terminal

Smaller than the issue's ~1,300-token estimate (~555 gross, ~485 net of the new skill's listing cost) because the file had shrunk since it was measured. Still worth doing — no always-on trap was made lazy.

Bucket 1 — two hooks

Both in laurigates/claude-plugins#2450: repo-deletion-safety.sh (block, 57 assertions) and branch-base-guard.sh (nudge, 59 assertions). The repo-deletion-safety stub here names the hook, its self-extinguishing property, and its opt-out, so the rule reads as skill + enforcement rather than skill alone.

Bucket 3 — deliberately left resident

Rules whose trigger is the failure they prevent: diagnose-at-the-failure-point, never-fabricate-test-identifiers (by the time you'd think to load the skill you have already fabricated the identifier), plus communication, decision-defaults, security, plan-mode, agent-and-tool-selection. And skill-and-agent-catalog-check above all — promoting rules to skills only pays off if the catalog is actually consulted at task boundaries, which makes it load-bearing for this entire plan.

Every move is verifiable

Bodies were moved by script, never retyped, then diffed against a pre-change snapshot of all 49 rules. The only edits inside a moved body are sibling-rule path requalifications (git-hazards.md → ~/.claude/rules/git-hazards.md), since the text no longer sits beside those rules. That keeps "the skill cannot have drifted from the rule it replaced" a checkable claim rather than a hope.

A false premise found in the budget test

tests/test-claude-context-budget.sh carried a 2026-08-09 comment asserting that a cleanup had landed — "multi-model-delegation went 6,607 → 493 bytes … freeing 6.1 kB". It never did; the rule was still 6,607 bytes when this work started, so a TOTAL_BUDGET_BYTES bump to 120,000 was argued on bytes that were never freed.

Corrected and kept as a lesson rather than quietly deleted (a budget bump must cite measured bytes on disk, never a cleanup believed to have landed). Remeasured from disk and ratcheted 120,000 → 86,000 — 6.4% headroom, deliberately not razor-thin, because the file's own #2324 finding is that a razor margin destroys the gate's signal and forces each new rule to adjudicate someone else's.

PASS=4 FAIL=0 STATUS=PASS
unconditional_rule_bytes+claude_md=80463  path_scoped_bytes=45435  budget=86000

Note for the maintainer

These are chezmoi sources. Before applying, run chezmoi status ~/.claude and treat every D line as a stop signal — a path-scoped chezmoi diff does not show pending deletions of unmanaged files under an exact_ tree. Then chezmoi apply -v ~/.claude. Nothing here was applied to a live target.

---

Generated by Claude Code

[laurigates]

Build (macOS) is red on main, not from this PR

/Users/runner/work/_temp/….sh: line 1: timeout: command not found
##[error]Process completed with exit code 127

timeout is GNU coreutils. macOS runners don't ship it — there is no timeout, and no gtimeout either unless coreutils is brewed. smoke.yml:139 calls it unconditionally.

Evidence this is not mine:

• The last smoke.yml run on main — fe31477b, "ci(smoke): add a macOS build job alongside Ubuntu (ci(smoke): add a macOS build job alongside Ubuntu #374)", 18:19Z — failed, 44 minutes before this PR was opened. The macOS job has never passed since it was added.
• This branch changes no workflow and no shell config. git diff --name-only origin/main..HEAD is exact_dot_claude/rules/*, exact_dot_claude/session-plugin.local.md, tests/test-claude-context-budget.sh.
• smoke.yml is byte-identical to origin/main here.

Not fixing it in this PR — it is unrelated to the rules triage and belongs in its own change. Proposed patch, whichever fits the repo's taste:

Option A — install coreutils in the macOS setup step (keeps the step identical across platforms):

- name: Install coreutils (macOS)
  if: runner.os == 'macOS'
  run: brew install coreutils

…then timeout resolves via the gnubin path, or call gtimeout explicitly.

Option B — drop the coreutils dependency (no install, works on both):

- run: |
    perl -e 'alarm 60; exec @ARGV' zsh -c '
      source ~/.zshrc
      [[ -n "$ZSH_VERSION" ]] || { echo "❌ zsh configuration failed to load"; exit 1; }
      echo "✅ zsh $ZSH_VERSION configuration loaded successfully"
    '

I'd take B — perl is preinstalled on both runners, and it keeps the "60 s is the ceiling" intent that the comment above line 139 spells out without adding a Homebrew step to every macOS run.

Happy to open that as a separate PR if you want it.

---

Generated by Claude Code