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 <files you touched>. 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 <remote sha> --head <local sha> 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 <remote> 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).