# Global working rules

## Who does what
- This session plans, briefs, reviews, merges, builds, installs and talks to the user. Delegate
  work that is long on reading or typing and short on judgment: file sweeps, boilerplate, test
  scaffolds, doc edits, screenshot runs, and any fix that needs a reproduction first.
- Delegate only when it saves tokens overall. A one-file or cosmetic fix (a constant, a path
  point, removing a button) is cheaper done directly in one worktree and batched into the next
  build than briefed, reported and re-reviewed. Group several small fixes into one agent when
  they share a file area.
- Models: subagents default to sonnet; opus for cross-seam refactors, concurrency, touch or
  layout state, colour work, the phase that designs a contract, an extraction phase, anything
  still inside a file over ~5k lines, or anything expensive to get wrong; haiku only for
  trivial sweeps. Call-site delegation phases (swap X for Y at the sites the inventory lists,
  no new maths, acceptance test given) are sonnet once the sites live outside the giant file;
  until then the >5k rule wins. Send a diff to a sonnet reviewer only when it is over ~300 lines
  *and* touches touch, layout, concurrency or persistence, or when its tests are thin; otherwise
  read the two or three risky files here and skip the reviewer. A reviewer that returns a clean
  bill on a well-tested diff is the cost to avoid.
- Briefs give: the goal, the symptom in the user's words, what was already verified in the code
  (with file:line), the commits the agent builds on so it does not undo them, the files, the
  acceptance test and its exact command, what is out of scope, what other agents are editing
  right now, and the report format (root cause with file:line, what changed, test result line,
  commit hash, judgement calls and anything unverified). Do not dictate syntax or step order.
- Discovery once: a deterministic locate pass first (`round` skill, scripts/inventory.sh), then
  at most one Explore agent per area to hunt what grep cannot see. Later briefs cite the
  inventory by path and line; no second agent sweeps the same directories. When memory already
  says where the code lives, skip the separate Explore agent and let the build agent survey its
  own area; a survey agent pays off only for an area this session has not touched.
- Contracts, not reading lists. A phase that produces classes later phases call ends its report
  with a contract of at most 40 lines (templates/contract.md); it is pasted verbatim into every
  downstream brief in place of the source files. A "contract was not enough" report goes back
  into the contract before the next brief.
- Big files (over ~5k lines, flagged RANGES-ONLY by the inventory) are briefed as line ranges,
  never "read the file"; name the fields the ranges depend on.
- Briefs come from templates/brief.md: shared block first and byte-identical across siblings so
  the prompt cache serves it, agent-specific block last.
- Keep bulk output out of this context: head/grep tool output, send multi-file reads to Explore
  agents, never paste whole files into the conversation. Read diffs and reports, not sources.
- Verify every agent report against the diff and the test output, never the report alone. A
  judgement call or edge case the agent flags gets a follow-up message and a second commit
  before the merge, not after.

## Rounds
- Work in rounds: the user reports one screenshot's worth of symptoms; take the screenshot
  yourself and measure it (pixel profile, dp at the device density) before diagnosing. Check
  every handoff claim against the code and say which ones differ.
- Present findings, root cause, proposal and open decisions on a review page (`/lavish` when
  installed, otherwise an artifact), with a go/no-go control per item. Print both page URLs in
  the chat every time the page is mentioned. Fold received decisions into the page; never leave
  a resolved question open on it. Do not reopen a page the user ended.
- One worktree per independent change, cut from the project's integration branch (`dev` here,
  not the Agent tool's worktree isolation, which branches from main). Agents commit, never push,
  never touch devices or emulators. Run independent changes in parallel; hold dependent ones
  until the prerequisite is merged.
- Partition by file first. When the inventory shows three or more phases will all edit the same
  giant class, run one behaviour-preserving extraction phase first (move the call sites behind
  a small class, suite green), merge it, then fan out on the small file. For two co-tenants,
  skip this and say in both briefs which regions each owns.
- Concurrency stays inside the account. Check `clauth profiles` for this profile's remaining
  window before fan-out and size the fan-out to fit it, or hold a phase for the next window, and
  say so. Never spread a round across profiles. A hook refuses a fourth opus-class agent
  (cap in ~/.claude/ledger/cap, default 3); a workflow enforces the same cap itself.
- Checkpoints. Every agent commits WIP at each milestone and keeps a ten-line HANDOFF.md
  (templates/handoff.md). A killed agent gets templates/resume.md, never "re-read your diff".
  A paused or killed agent is resumed with its own context (SendMessage / templates/resume.md),
  never re-briefed from scratch; a pause means letting in-flight agents finish, not stopping
  them, unless the user says stop.
- Phased builds after the spec is agreed run through the `phased-build` workflow
  (~/.claude/workflows): dependency waves, contracts pasted forward, a reviewer per phase on
  the diff and the test output. Merging stays here.
- Merge each branch as it lands (project's own merge recipe, e.g. the stash dance around a
  peer's uncommitted work), then run the full suite once on the merged state, build once, and
  install once per round. Long device pushes go to a tracked background job; report the
  install's lastUpdateTime, not the intent.
- Close a round with a receipt: one line per item — fixed / done / partly / deviation / closed —
  with the commit, what the user should check by finger, and every deviation from their
  decision stated plainly (e.g. a chosen option not implemented and why), and the ledger
  section (scripts/ledger.sh <session_id>; a hook writes ~/.claude/ledger/agents.tsv per
  finished agent). Compare rounds; a heuristic change that does not move the number is reverted.
- Say what was verified (tests, measurements, device) and what was only reasoned.

## Multi-phase builds
- Spec first: agree it with the user on a review page, then commit a terse copy under the
  project's docs folder with a build-plan table (phase, branch, deliverable, dependencies).
  Briefs point at it.
- One phase = one worktree = one branch `feat/<phase>`. Review the diff, run the suites on the
  merged result, merge only when green. Resolve conflicts yourself.
- Gate at phase boundaries with the project's own verification (its CLAUDE/AGENTS says what).
- One short status when a phase lands or blocks. User side tasks go in the spec's side queue
  with their own small agent.
- Record spec location, decisions, phase order, gates, merged hashes and open questions in
  memory so a later session can resume.

## Memory hygiene
- Record every user decision the moment it arrives (what, when, the option not taken) and every
  root cause found, with hashes. When a project memory has become a running status log and the
  work closes, collapse it to the outcome and pointers. Delete memories that turned out wrong.
- These rules live at `~/.claude/CLAUDE.md`; the profile directories (`~/.claude_first`,
  `~/.claude_second`) symlink to it, so one edit reaches every profile.