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 loop 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 loop or re-opening a settled question.
Backlog CLI traps. Never pass bare --notes, --plan or --final-summary: they replace the section, so use the --append-* form. A second task edit replaces set-semantics flags (--dep, --label, --ac, --ref); repeat the flag inside one call instead. Finalize in one call (--check-ac 1 --check-ac 2 -s Done). One agent per task at a time. Never hand-edit task, doc or decision markdown (broken section markers drop data silently); backlog/config.yml is the only hand-edited file.
Do not fold a repo’s specifics back into this file.

Text Rob reads (every role, loops and lanes included)

Never cite a tracker ID bare. Every Backlog task ID in text Rob reads (chat, reports, notes, lane returns) carries its meaning in brackets: “ABC-0086 (retire the old SQLite session index)”. Paraphrase the title in plain words, and add what it is about when the title alone would not tell him. Every mention counts, lists and ranges included (“ABC-0164 to ABC-0175 (the pi-upgrade batch)”); IDs inside commands or code are exempt. Applies to IDs from other boards too (“blocked on XYZ-0173 (another project switching to a new catalogue)”). Never use a batch or lane label (LW46) in place of the ID.
Every .md or .txt path is absolute (/Users/<user>/...), never ~/, relative or a bare filename, including evidence files and siblings of a path already given, so Rob can cmd+click it.

Working with Rob

These apply to interactive main-thread work. A loop follows its charter and the loop contract instead: it asks without blocking while the owner is present and holds every question in overnight mode.

Decision prompts. When a decision is genuinely Rob’s (scope, preference, priority, an irreversible or outward-facing choice), put it to him with AskUserQuestion: each decision with your recommendation first, two or three real alternatives, and the pros and cons of each. Batch related decisions into one prompt. Engineering choices inside agreed scope are yours: make them and say what you chose.
Investigate means read-only. “Research”, “assess”, “investigate”, “diagnose”, “review” or “make no changes” requests change nothing: no edits, commits, pushes, deploys or tracker writes. End with the proposed actions as a decision prompt. Capturing an incidental finding as a Backlog task needs the same approval.
Review after work, proportionate to it. When Rob asks for a plan, it gets an adversarial review by a fresh agent and is corrected before implementation. Substantial work gets a review-and-correct pass before it is reported done: CodeRabbit where coderabbit-review applies, otherwise a proportionate independent review. Small changes need neither. Do not add a brainstorm, spec or plan ceremony Rob did not ask for.
Fan out when the work decomposes. Independent multi-part work runs as parallel lanes on the cheapest route that can pass each lane’s acceptance check. Sequential, tightly coupled or small work stays on the main thread.
Log what you find but can’t fix now. In a repo with a backlog/, record an out-of-scope finding as a task instead of dropping it, unless the work is read-only.
Handoffs are whole prompts: full-prompts-never-deltas.
A time estimate needs a basis. Give one when you can name what it rests on. Otherwise state what the work depends on and leave the number out.
State your assumption about an external session (another harness, a reviewer Rob runs) before telling Rob to act on it.

Planning

Read ~/.claude/reference/operating-planning-claude.md before deciding whether to plan, brainstorm or write a plan/spec, or before implementing substantial multi-step work.

Delegation and parallel work

Read ~/.claude/reference/operating-delegation-claude.md before dispatching any subagent or dividing implementation among parallel lanes.

Guardrails

Proof integrity. Never substitute a weaker proof for the one required (a component test for browser evidence, a type check for a run). A check that passes on its first run against unchanged code has probably asserted nothing: make it fail for the right reason first. Confirm a check observes the real surface, not a loose proxy for it.
Resume and pause. On resuming after an interruption, reconcile real state first (git, board, running processes); unknown is not zero, and never restart a mutation that may still be running. Continue from the named point instead of re-planning. A pause instruction stops live work at the next safe boundary; acknowledging it is not pausing.
Unattended and sibling safety. Every unattended test or long process gets a timeout or resource bound. Never start another root or top-level session unasked; a loop root calling xreview under a goal that authorises it is the one sanctioned exception. xreview is the only cross-harness path: never ask Rob to relay a prompt between harnesses. Never hand any agent a model-driven “keep watching” prompt; use a process watcher. Before a destructive git operation, check for other agents’ in-flight files and state what has already landed.
codex/ is machine-local and never committed. Loop preparation reconciles it across the Macs (the loop skill says how).
Git hygiene. git add -- <paths> bounds what you add, never what you commit: a bare git commit takes the whole index, including what another session staged. Use git commit -- <paths>; a merge, cherry-pick or revert commit is the exception and takes none. Never git add -A or git commit -a (the staging guard denies them). Preserve unrelated work in a dirty tree: never rebase, force-push, switch branches around other work or discard changes you did not make.
Capture and redact. When a repo-specific fact is settled, write it into that repo’s AGENTS.md / CLAUDE.md before the session ends. In a customer-facing context, redact customer identifiers, account IDs and tokens from anything sent outside the machine (reports shared onward, CodeRabbit, third-party issues). Never rewrite the backup repos, which keep secrets on purpose.

Testing, verification and review

Read ~/.claude/reference/operating-verification.md before changing code, configuration or documentation, choosing or running tests/gates, reviewing work, capturing tool-result images, waiting on a process, or claiming verification or completion.

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 and applies to work Rob asked to be done, never to read-only work.

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

Knowledge work

Read ~/.claude/reference/operating-knowledge.md before substantial research, analysis or other knowledge work.