--- name: maintain-claude-md description: How CLAUDE.md and the .claude/agents and skills it references are kept true (check:claude, check:rules, agent maintenance). when_to_use: When editing CLAUDE.md, a .claude/agents definition, or a load-bearing script CLAUDE.md names. --- # Specialized agents and keeping CLAUDE.md true Three subagents live in `.claude/agents/` and encode checklists you would otherwise rebuild from scratch. Use them; they exist because each of these failures happened more than once: - **`completionist`** audits changed files against these operating rules at the end of a feature task. It reports violations, it does not fix them. One exception, and it is absolute: when the user asks to commit or push, that IS the approval. Do not run the completionist (or tests, audits, or diff reviews) first. Ship it. - **`deploy-preflight`** verifies a production deploy is safe BEFORE `gcloud builds submit`: build order, worktree artifacts, service-account pins, changelog wiring. Run it before any deploy, or when a deploy died mid-build. It does not deploy; deploys stay owner-gated. - **`x402-economy-triage`** diagnoses x402 outages against the known failure map. Run it before concluding "the wallets are dry", which is usually wrong: settle-floor starvation and capital dispersion look identical from the outside and have completely different fixes. **Evolve** (`npm run evolve:start`, `scripts/evolve.mjs`, runbook `docs/ops/evolve.md`), the unattended development loop and not the product's trading Autopilot, runs headless Claude Code sessions around the clock in its own worktree beside the repo, on branch `evolve`: it works the `prompts/finish/` queue, writes new scouted orders into the `400` band, and sweeps production, then fast-forwards finished commits into local `main`. Its sessions are denied every owner-gated action. If you are hand-running an order, evolve leaves it alone for 6 hours after you last touched it; `npm run evolve:pause` frees the subscription for interactive work. `.claude/workflows/` holds two workflow scripts: `docs-drift.js` sweeps documentation drift across the repo, and `docs-freshness.js` re-verifies the docs the freshness report marks stale. **Maintaining these agents.** An agent definition is executed verbatim, exactly like this file, so it is held to the same standard and `npm run check:claude` enforces it: every `npm run` script and repo path it names must exist, it must never send the agent to a per-machine memory file (auto-memory under `~/.claude` is invisible to a fresh clone or a cloud session; put the knowledge in `docs/` and link it), and it must read changeable facts (build chains, artifact lists, env-var locations) from their source of truth instead of restating them. When the same multi-step diagnosis has been rebuilt from scratch twice, that is the signal to add an agent for it. Subagents launched with `isolation: "worktree"` leave a tree under `.claude/worktrees/`; `npm run clean:worktrees` reclaims each one once its branch is merged and it holds no uncommitted work. ## Keeping this file true This file is the operating brain for every agent here, and agents execute what it says verbatim. A stale line in it does not read as stale, it reads as an instruction, and the cost is a wasted session per drift. Treat it as load-bearing code: - **`npm run check:rules` enforces the hard rules on the lines you changed** (`scripts/check-rules.mjs`). It reads added lines only, so your change is held to the rules while the legacy around it is left alone: em-dashes, TODO/FIXME comments, not-implemented throws, commented-out code, and `sampleFoo = [...]` fallback arrays all fail it. Because concurrent agents share this worktree, scope it to your own work: `npm run check:rules -- --paths `. It also reads brand-new untracked files, which a bare `git diff` cannot see. Generated output is excluded, including the compiled Marketplace Action under `satellites/glb-quality-gate/dist/`; its authored source remains scanned. It is also enforced mechanically at push time: the pre-push hook (installed into `.git/hooks` by `scripts/setup-git-hooks.mjs`, which `postinstall` runs on every `npm install`) runs it with `--base --head ` per pushed ref, so it judges exactly the commits leaving the machine and never the shared working tree. In that push-scoped mode it also lints every pushed commit's subject line against the "Commit messages" rules in the Git section, so a `chore: sync working tree` never lands again. A pre-commit hook runs the same check on the staged lines (`--staged`), so violations are stopped before they become a commit; plumbing commits (`git commit-tree` + `update-ref`) skip hooks, so run `node scripts/check-rules.mjs --staged` against the private index before `commit-tree`. Emergency bypass: `SKIP_PUSH_CHECKS=1 git push` (or `git commit`). The hook deliberately runs ONLY this diff-scoped check and its sibling secrets scan (`scripts/check-secrets.mjs`, same push-scoped mode, so no credential material leaves the machine), never `npm run gate` or other worktree-state audits, because those would block a requested push on other agents' in-flight work. - **`npm run check:claude` guards it** (`scripts/check-claude-md.mjs`, wired into `npm run gate`). It re-derives the checkable claims from their source of truth on every run: every npm script and repo path named here or in `.claude/agents/` must exist, the cron count must match `vercel.json`, the deploy runbook must list the real `build:gcp` chain in the real order, the `db:migrate` warning must match what the script actually does, the README-coverage standard must hold, the remotes documented below must be the ones actually configured (a `git push main` instruction that does not resolve fails exactly when the owner asked to ship), and the em-dash ban must be honored by this file itself. Run it after editing this file. - **If you change a load-bearing script, update this file in the same change.** Renaming a script, reordering `build:gcp`, adding a cron, or flipping a default is a documentation change too. The guard will catch most of it; do not make it do your job. - **Never add a claim here you have not verified.** Numbers, dates, and "X is automatic" statements are the ones that rot. If a claim cannot be checked mechanically, prefer wording that stays true (name the source of truth instead of quoting a number from it). ---