Operating model (all projects)

A project’s own CLAUDE.md / AGENTS.md and direct user instructions override everything here.

Read the repo’s own model first

Read AGENTS.md / CLAUDE.md at the repo root before applying this file, and follow any pointer it gives. Where a repo defines its own campaign model, domain contract or settled decisions, that is authoritative.
A tracker directory such as backlog/ means open work is a query, not a file to infer: backlog task list --plain for the queue, backlog doc list for durable docs. Read the operating-model and standing-decisions docs before running a campaign or re-opening a settled question. Never hand-edit a tracker’s markdown; drive it through its CLI.
~/repos/backlogconfig.md is the reproducible setup for that arrangement.
m7kni/agent-docs is canonical for the fan-out campaign model — the source is sources/fan-out-protocol.md, checked out at ~/repos/agent-docs. Read its Appendix B for Claude Code’s structural traps, and treat this file as winning on model routing. The document is rendered into ~35 repositories’ Backlog boards, so an edit anywhere else — including the ~/repos/agent-fanout-generic.md pointer stub — reaches one board and silently leaves the rest behind. Edit the source, run bin/sync, and bin/doctor proves nothing is stale.
Do not fold a repo’s specifics back into this file.

Planning is opt-in

Reserve brainstorming for work with a real, unresolved design fork.
Substantial multi-step work: go straight to an implementation plan, then review it for scope, assumptions, dependencies and stopping conditions before writing code. Reserve adversarial plan review for security, authentication, permissions, migrations, data loss, public interfaces and deployment changes.
Small, well-scoped changes: skip planning and do the work.
If it is unclear whether something warrants a plan or a brainstorm, ask.

Specs and plans are scratch, never deliverables

Never commit superpowers plans or specs. docs/superpowers/ must be gitignored; confirm that before writing any plan and add it first if missing.

Planning artifacts remain repository-owned. No Claude profile mirrors them into a Codex home or a cross-tool synchronization repository. Repository files are the only supported handoff surface between tools.

chat-personal and chat-work deliberately TRACK their docs/superpowers/. Those two are backup repos that commit secrets on purpose. Do not re-add the ignore line.

Parallel build (larger features)

Freeze the shared seams first in the plan — exact names, signatures, config keys and defaults, types — so every lane codes against a stable interface.
One file has one owner. Integration and wiring files (composition root, registries, shared config structs) are edited by a single lane or a dedicated wiring pass, never in parallel.
Transient red mid-wave is expected. Green is mandatory at the wiring checkpoint and before completion: one wiring pass stitches seams, fixes call-sites, regenerates artifacts and runs a proportionate integration gate.

Model routing for sub-agents

Pass model: on every dispatch. It defaults to the parent’s model, so an Opus session runs every sub-agent, plugin agents included, on Opus.
The routing test: can you state the acceptance check now? Yes → Sonnet. No — the agent must decide what “done” means, or the deliverable is a judgement → Opus, or don’t delegate. Cross-check on blast radius: wrong-and-cheap-to-detect → Sonnet; wrong-and-silently-propagating (a frozen seam, a data model, a cardinality or PII call) → Opus.
The second test: how much output does the lane discard? A subagent runs in a fresh context, so it re-reads what the main session already had and pays for its own turns. Delegate when the job produces a lot of output you do not need to keep — a log, a broad sweep, CI reduction, mass file reads. For a small job whose answer is a line or two, doing it inline is cheaper than a fresh context.
Sonnet: call-site and inventory sweeps against a named target; mechanical transforms against a frozen spec; first-pass table-driven tests from an existing spec; fixtures; doc regeneration and diff checks; running the gate and reporting failures verbatim; condensing a large read into a brief; any parallel-build lane whose seams are frozen.
Haiku (200k context, 8k output): checks whose answer is self-evidently right or wrong. Never where you would have to trust it finished — it drops steps in long tool loops, so a partial sweep returns looking complete. Completeness matters → Sonnet.
Opus keeps: the plan, freezing the seams, the wiring pass, cross-cutting integration, unknown-cause debugging, the final review.
Tell every Sonnet lane: if you hit a decision the brief does not cover, stop and return the question — do not invent an answer.
Scope every lane or they duplicate each other: objective, output format, tools and paths in scope, what NOT to touch, and when it is done. Fact-lookup 1 agent; comparison 2–4; more only for genuinely broad discovery.
effort is not a parameter on the Agent tool — only agent-definition frontmatter and Workflow’s agent() opts. Passing it in a brief is a silent no-op.
Since Claude Code v2.1.251, model precedence is per-invocation model, agent frontmatter, CLAUDE_CODE_SUBAGENT_MODEL, then the main model; only CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 overrides dispatch choices (available since v2.1.257; vendor reference).
Sub-agents doing grunt work must never commit. Only the main thread commits.
git add -- <paths> bounds what you add, never what you commit. A bare git commit takes the whole index, including what another session staged before you arrived. Use git commit -- <paths>; a merge, cherry-pick or revert commit is the exception and takes none.
The deliverable IS the agent’s final message — instruct every dispatched agent to make its last message the complete self-contained brief. Read subagent-dispatch before dispatching anything whose output you need back.

Review cadence

Review the final diff once, with a proportionate spec-conformance and code-quality review. Reserve comprehensive or adversarial review for security, authentication, permissions, migrations, data loss, public interfaces and deployment changes.
Gate mid-build only high-blast-radius seams: a shared interface being frozen before fan-out, a breaking change, a cardinality/PII/data-model decision.

Testing and verification

TDD is a tool for a specific job, not a ritual. Choose tests using the criteria below, then write the failing case before the implementation.

Test-first when the test earns its keep:

Bug fixes — almost always. Write the failing test first and watch it fail for the right reason.
Logic with real room to be wrong: parsing, arithmetic, state machines, retry/backoff, permission checks, edge cases you cannot hold in your head.
A contract other code depends on — a public interface, a shared seam being frozen before fan-out.

Skip it, and say you skipped it:

Documentation, comments, declarative config, CI YAML, dependency bumps — validate instead (parse, lint, render, --dry-run). Do not manufacture a unit test for a config file.
Wiring and glue with no branching: a new field passed through, a registry entry, a re-export.
Anything where writing the test costs more than the bug would. Say so in one line rather than silently doing the expensive thing.

Over-testing is a defect. Do not write: a test per permutation where three cases pin the contract; tests asserting on implementation details that break on any refactor; tests for behaviour a type checker or the framework already guarantees; snapshot tests that only record current output; a test per trivial accessor. Do not retro-fit tests onto code this change did not touch — mention a coverage gap outside the diff, don’t fill it.

Verification:

Verify against the exact tested SHA and CI run identity, never a moving HEAD.
A green run, HTTP 200 or exit 0 is not outcome proof; check the requested behavior directly.
Skipped or cancelled is never a pass; report it separately.
Introspect schemas, selectors and identifiers before using them; do not guess.
Keep tool-result images out of long main threads: use a discarded-context subagent or a short session for screenshots, preferring a scripted assertion where possible; images Rob attaches to the opening prompt stay.
Never wait by issuing bare sleep over 60 seconds; use a Monitor-shaped until/while loop for a real completion signal.
During implementation, run targeted checks covering the changed area. Before completion, run one proportionate final gate covering the change and its likely regressions. Run the project’s full build + test + lint gate only for cross-cutting or high-risk changes, when repository instructions require it, when preparing a release, or when Rob asks.
Evidence, not assertion — never claim green without having seen the output.
Once the acceptance criteria are satisfied and the selected checks pass, stop. Do not repeat unchanged tests or reviews without new evidence, a relevant code change, or a failure requiring investigation.

Git policy lives elsewhere

Squashing and branch conventions are per-repo and live in each project’s own CLAUDE.md / AGENTS.md. The one global exception — commit and push straight to main on Rob’s own repos — is owned by git-push-bypass.

Read ~/.claude/reference/github-token-mint.md before wiring a GitHub token mint into CI.

Knowledge work

For substantial knowledge work, freeze the question, authoritative source and date window, target tenant or account, audience, and required output format up front; at handoff separate verified facts from estimates and name what was not checked.