From 76b03dadbec40b1ed80cd1d8494204280cfbe059 Mon Sep 17 00:00:00 2001 From: Varun Katta Date: Thu, 8 Oct 2026 12:09:43 -0700 Subject: [PATCH] docs(operating-model): vendor-neutral cross-project rules and checkpoint procedure - working-style: model tiers (deep, standard, light, premium) with a vendor mapping table, premium launches need the owner's per-launch yes, launches and costs, addressing the owner; carry the Data location and Shared Mastrix repositories rows, product-strategy read-only - execution-and-handoffs: fresh brief for a scope change; scratch and worktree locations without a vendor path, never /tmp - procedures/checkpoint.md: vendor-neutral checkpoint and resume; the Claude skill becomes a thin loader - decision-log and README index Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 + CLAUDE.md | 2 + claude/skills/README.md | 1 + .../skills/pre-compaction-checkpoint/SKILL.md | 57 ++-------------- operating-model/README.md | 1 + operating-model/decision-log.md | 1 + operating-model/execution-and-handoffs.md | 16 ++++- operating-model/procedures/checkpoint.md | 66 +++++++++++++++++++ operating-model/working-style.md | 23 ++++++- 9 files changed, 112 insertions(+), 57 deletions(-) create mode 100644 operating-model/procedures/checkpoint.md diff --git a/AGENTS.md b/AGENTS.md index b1d406b..7bc7e5c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,8 @@ order: 4. [`operating-model/decision-log.md`](operating-model/decision-log.md) 5. [`operating-model/agent-work-loop.md`](operating-model/agent-work-loop.md), when you take work from a shared board (an issue queue such as Beads) +6. [`operating-model/procedures/checkpoint.md`](operating-model/procedures/checkpoint.md), before a context + compaction or handoff, and when resuming after one Use [`operating-model/project-profile.template.md`](operating-model/project-profile.template.md) to establish a project profile. The target project’s own guidance, handoff, diff --git a/CLAUDE.md b/CLAUDE.md index 796165e..5af8025 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,6 +9,8 @@ technical project, read the shared operating model in this order: 4. [`operating-model/decision-log.md`](operating-model/decision-log.md) 5. [`operating-model/agent-work-loop.md`](operating-model/agent-work-loop.md), when you take work from a shared board (an issue queue such as Beads) +6. [`operating-model/procedures/checkpoint.md`](operating-model/procedures/checkpoint.md), before a context + compaction or handoff, and when resuming after one Use [`operating-model/project-profile.template.md`](operating-model/project-profile.template.md) when establishing project-specific context. Project repositories remain the diff --git a/claude/skills/README.md b/claude/skills/README.md index d30cd0a..21d7f39 100644 --- a/claude/skills/README.md +++ b/claude/skills/README.md @@ -9,3 +9,4 @@ mkdir -p ~/.claude/skills && ln -s ~/work/code/personal/env/claude/skills/ ## Available skills - **pre-compaction-checkpoint**: Use before a context compaction (/compact), when the user says they are about to compact, or when asked to "record everything so nothing is lost". Materializes every fact, decision, approval, in-flight task and next step into durable files, so the session can resume exactly where it left off without hallucinating. + This skill is a thin loader; the procedure itself is `operating-model/procedures/checkpoint.md`. diff --git a/claude/skills/pre-compaction-checkpoint/SKILL.md b/claude/skills/pre-compaction-checkpoint/SKILL.md index 995723e..6c834c1 100644 --- a/claude/skills/pre-compaction-checkpoint/SKILL.md +++ b/claude/skills/pre-compaction-checkpoint/SKILL.md @@ -5,57 +5,8 @@ description: Use before a context compaction (/compact), when the user says they # Pre-compaction checkpoint (and resume) -**Goal:** after compaction you remember only a summary. Anything not written to disk may be lost or misremembered. -Before compacting, write down everything needed to continue; after compacting, reload it from disk and verify it -against live sources before acting. +This skill is a loader. The procedure is vendor-neutral and lives in one place: +`~/work/code/personal/env/operating-model/procedures/checkpoint.md`. -**The principle: disk, not memory. Verify, don't recall.** Every fact you record should come from a source you -just checked (git, `gh`, files), not from what you remember of the conversation. - -## A. Before compaction (checkpoint) - -1. **Freeze new work.** Don't launch new tasks until the checkpoint is written. Tasks already running may continue. -2. **Capture the user's words verbatim.** Append every user ruling, approval, answer and preference given since the - last checkpoint to the project's rulings log, with the date, quoted exactly as typed (typos included). Add a - short "reading" beneath each only if you need to interpret it. Approvals of cost, merges and scope matter most. -3. **Capture your own decisions.** Append every decision you made (on reviews, deviations, contradictions, plans) - to the project's decisions or notes log, with its reason and what it supersedes. -4. **Snapshot live state from the sources**, not from memory: - - the main branch SHA; every PR merged since the last checkpoint with its merge SHA (`gh pr view N --json - mergeCommit`); every open PR with its head SHA, merge state, checks and next step; - - the running background tasks and agents: their id, role, current state, and what each is waiting for; - - spend: approved against actual, per budget line, read from ledgers or logs; - - the open questions for the user, and questions already answered (so they aren't asked again). -5. **Write ONE dated state file, READ FIRST,** that supersedes the previous one. It has these sections: - - 0. Role, and the standing rules (how to work, what is forbidden, who approves what); - - 1. Where the truth lives (paths); - - 2. Git and PR state (tables with SHAs); - - 3. The work items or tasks by milestone; - - 4. Costs (approved and spent); - - 5. Open questions for the user; - - 6. Answered questions (don't re-ask); - - 7. Next actions, in order; - - 8. The running agents, with ids and how to resume each. -6. **Update persistent memory.** Point a "READ FIRST" entry at the top of the memory index to the new state file. - Save each new standing preference the user gave as its own feedback memory (the rule, why, how to apply). Update - or delete memories the session proved wrong. -7. **Put durable decisions in version control where the project expects them** (e.g. a decisions file or ADR), or - list them in the state file as "owed to Git" with the PR that will land them. -8. **Verify the checkpoint:** - - every user message since the last checkpoint maps to a line in the rulings log; - - every open PR and running agent is in the state file; - - every number in the state file was read from a source this turn; - - grep the state file for "TODO" or "?" and resolve each. -9. **Tell the user** what was recorded and where, what is still in flight (and that it keeps running), and that - it's safe to compact. - -## B. After compaction (resume) - -1. Read the READ-FIRST state file in full, then the tail of the rulings log and the decisions log, then the memory - index. -2. **Re-verify live state before acting:** the main SHA, the open PRs (`gh pr list`), and each running agent's - status. Trust the live state over the file where they differ, and note the difference. -3. Don't redo finished work. Don't re-ask answered questions. Don't restate the summary to the user. -4. Continue from "Next actions" in order, and pick up messages from agents that arrived during the compaction. -5. If anything in the file is ambiguous, check the source (the PR, the log, the report) before deciding. Never fill - a gap from memory. +Read that file in full and follow it: part A before a compaction, part B right after one. Do not keep a copy of the +steps here; amend the procedure file instead. diff --git a/operating-model/README.md b/operating-model/README.md index a115a06..7191aa4 100644 --- a/operating-model/README.md +++ b/operating-model/README.md @@ -30,6 +30,7 @@ repository or secure system. | [Working style](working-style.md) | Confirmed collaboration preferences and communication expectations. | | [Execution and handoffs](execution-and-handoffs.md) | How bounded work, delegation, reviews, checkpoints, and blockers are handled. | | [Agent work loop](agent-work-loop.md) | How agents take work from a shared board: a dispatcher launches one clean-context sub-agent per job; what next, when to stop, who reviews and repairs. Projects inherit it and override only its parameters. | +| [Checkpoint and resume](procedures/checkpoint.md) | A vendor-neutral procedure to record everything before a context compaction or handoff, and to resume from disk afterwards. | | [Project profile template](project-profile.template.md) | A reusable starting point for a project-specific operating context. | | [Decision log](decision-log.md) | Dated, evidence-based operating decisions and observations. | diff --git a/operating-model/decision-log.md b/operating-model/decision-log.md index 8cad8f6..dd1dcb6 100644 --- a/operating-model/decision-log.md +++ b/operating-model/decision-log.md @@ -40,3 +40,4 @@ Status is intentionally explicit: | 2026-09-28 | Confirmed | Long documents carry a table of contents with jump links | Sections with four or more `##` level headings get a TOC block right after the title. Automated tooling in projects regenerates and validates the TOC. See `working-style.md` and `agent-work-loop.md`. | | 2026-09-29 | Confirmed | The agent launched on a work board is a dispatcher: one fresh, clean-context sub-agent per job, one at a time, up to five jobs per run, then a full stop until a human says go. | Owner: "ideally, you want each agent to work with a clean context, then each agent is launching a sub-agent be the model then, so subagent finishes a bead and changes bead status and reports back to parent agent. parent agent at any point in only running a single sub agent. after the sub agent finished, the parent agent is lanching the next one in a loop, up to a maximum of five and then completely stop until human asks it go again for another five". The dispatcher only reads the board, claims, launches, reads the report and logs; the sub-agent does one job and makes its board transition. Refines the 2026-09-28 work-loop row: the loop and priorities stay, the agent that runs them changes. See `agent-work-loop.md` sections 2, 3, 4 and 6. | | 2026-09-29 | Confirmed | Projects keep their launch prompts as named, versioned files in the repo, with an index; a launch is one line naming the prompt and its path, plus parameters; the run report names the prompt version it ran. | The owner approved the lead's design ("go") for replacing pasted launch text with checked-in prompts, so a launch is repeatable and a report says which prompt version produced it. Adds to the 2026-09-29 dispatcher row. See `agent-work-loop.md` section 7. | +| 2026-10-08 | Confirmed | The owner's cross-project rules live here in vendor-neutral words so any agent works the way the owner wants in every repository: model tiers (deep, standard, light, premium) with a vendor mapping, premium launches only on the owner's per-launch yes, ask before any new service, monitor, workflow or scheduled wakeup, never set a spend cap ($0 by default), they/them for the owner, a fresh brief for a scope change, files only under `~/work`, scratch in the harness's scratchpad or `~/work/code/mastrix/wt/--notes/`, never `/tmp`, and a vendor-neutral checkpoint procedure. | Owner, R1008-27: "n1-n8 is good", accepting decisions D1-D8 of the agent-neutrality plan as recommended, and: "any agent can work exactly like the way I want it to on the repo". Sources: the owner's rulings of 2026-09-27, 2026-10-05 and 2026-10-06 as kept in the Claude memory files. Supersedes the vendor-named tier wording of the 2026-09-21, 2026-09-23 and 2026-09-27 rows (they stay as history) and the 2026-09-27 scratch-path example. See `working-style.md` → Model tiers, `execution-and-handoffs.md` → Scratch files and agent worktrees, and `procedures/checkpoint.md`. | diff --git a/operating-model/execution-and-handoffs.md b/operating-model/execution-and-handoffs.md index a4116df..cbe8606 100644 --- a/operating-model/execution-and-handoffs.md +++ b/operating-model/execution-and-handoffs.md @@ -257,11 +257,21 @@ Escalate rather than improvise when work encounters: The escalation should include evidence and a proposed safe decision, not only a description of the problem. +## Briefs and scope changes + +| Situation | Rule | +| --- | --- | +| A brief for a sub-agent | Fresh, clean context: the task, the done-when, the rules that bind it and only the facts it needs. Tiers and the brief rule: `working-style.md` → Model tiers. | +| The scope changes while an agent runs | Put the full delta in a **fresh agent's initial brief**. Do not amend a running agent by a mid-task message: an agent told to stop rather than improvise may treat the amendment as an injected instruction and ignore it. Finish the design before delegating. | + ## Scratch files and agent worktrees -- **Where:** only in the session scratchpad directory the harness gives you (for example - `/private/tmp/claude-///scratchpad/`), in **your own subfolder** named for your task and - role (e.g. `W-0012-doer/`, `PR-171-adversary/`). Your git worktrees for the task live there too. +| Item | Where | +| --- | --- | +| Files of any kind | Only under `~/work`, never `~/Desktop`, `~/Documents`, `~/Downloads`, `~/` or a `/tmp` folder you make yourself. The one exception is the scratchpad directory the harness itself provides, below. | +| Scratch (notes, logs, PR bodies) | The harness's scratchpad directory when it gives one, in **your own subfolder** named for your task and role (e.g. `W-0012-doer/`, `PR-171-adversary/`). When it gives none: `~/work/code/mastrix/wt/--notes/`, beside the worktree. | +| Git worktrees | `~/work/code/mastrix/wt/-`, fresh from the remote's default branch, one writer per worktree, unless the harness provides the worktree. | + - **Never:** - at the scratchpad's root, which is shared by every agent in the session; - inside any repository's working tree (no repo-relative `scratchpad/` folder); diff --git a/operating-model/procedures/checkpoint.md b/operating-model/procedures/checkpoint.md new file mode 100644 index 0000000..e3db86c --- /dev/null +++ b/operating-model/procedures/checkpoint.md @@ -0,0 +1,66 @@ +# Checkpoint and resume + +A procedure any agent follows, in any harness. Use it: + +| When | Part | +| --- | --- | +| Before a context compaction, reset or handoff to another session; when the owner says they are about to compact; when asked to "record everything so nothing is lost" | A. Checkpoint | +| Right after a compaction, reset or handoff, or when you start a session from someone else's state file | B. Resume | + +**Goal:** after a compaction an agent holds only a summary, and anything not written to disk may be lost or +misremembered. Before it, write down everything needed to continue; after it, reload that from disk and verify it +against live sources before acting. + +**Principle: disk, not memory. Verify, don't recall.** Every fact recorded comes from a source just checked (git, +`gh`, files), not from the conversation. + +Where the files live is the project's rule (its lane or state folder). This procedure names the files by role. + +| Role | Holds | +| --- | --- | +| State file | The one dated, READ-FIRST file that supersedes the previous one | +| Rulings log | The owner's words, verbatim, with dates | +| Decisions or notes log | The agent's own decisions, with reasons | + +## A. Before compaction (checkpoint) + +| # | Do | Check | +| --- | --- | --- | +| 1 | **Freeze new work.** Launch nothing new until the checkpoint is written. Tasks already running may continue. | | +| 2 | **Capture the owner's words verbatim.** Append every ruling, approval, answer and preference given since the last checkpoint to the rulings log, with the date, quoted exactly as typed (typos included). Add a short "reading" beneath each only if it needs interpreting. Approvals of cost, merges and scope matter most. | Every owner message since the last checkpoint maps to a line. | +| 3 | **Capture your own decisions.** Append every decision you made (on reviews, deviations, contradictions, plans) to the decisions log, with its reason and what it supersedes. | | +| 4 | **Snapshot live state from the sources.** The main branch SHA; every PR merged since the last checkpoint with its merge SHA (`gh pr view N --json mergeCommit`); every open PR with its head SHA, merge state, checks and next step; the running agents and background tasks (id, role, state, what each waits for); spend, approved against actual per budget line, read from ledgers or logs; the open questions for the owner and the questions already answered. | Every number was read from a source this turn. | +| 5 | **Write ONE dated state file, READ FIRST,** sections 0 to 8 below. | Every open PR and running agent is in it. | +| 6 | **Update the agent's persistent memory, if the harness has one,** as pointers only: a READ-FIRST entry naming the new state file, and for each rule a pointer to its canonical home in Git. Rule text is not kept in memory. Delete or correct entries the session proved wrong. | | +| 7 | **Put durable decisions in version control** where the project expects them (a decisions file, an ADR), or list them in the state file as "owed to Git" with the PR that will land them. | | +| 8 | **Verify the checkpoint.** Search the state file for "TODO" and "?" and resolve each. | Nothing unresolved remains. | +| 9 | **Tell the owner** what was recorded and where, what is still in flight (and that it keeps running), and that it is safe to compact. | | + +State file sections: + +| # | Section | +| --- | --- | +| 0 | Role, and the standing rules (how to work, what is forbidden, who approves what) | +| 1 | Where the truth lives (paths) | +| 2 | Git and PR state (tables with SHAs) | +| 3 | The work items or tasks, by milestone | +| 4 | Costs, approved and spent | +| 5 | Open questions for the owner | +| 6 | Answered questions (do not re-ask) | +| 7 | Next actions, in order | +| 8 | The running agents, with ids and how to resume each | + +## B. After compaction (resume) + +| # | Do | +| --- | --- | +| 1 | Read the READ-FIRST state file in full, then the tail of the rulings log and the decisions log, then the memory index if the harness has one. | +| 2 | **Re-verify live state before acting:** the main SHA, the open PRs (`gh pr list`), and each running agent's status. Trust the live state over the file where they differ, and note the difference. | +| 3 | Do not redo finished work. Do not re-ask answered questions. Do not restate the summary to the owner. | +| 4 | Continue from "Next actions" in order, and pick up messages from agents that arrived during the compaction. | +| 5 | If anything in the file is ambiguous, check the source (the PR, the log, the report) before deciding. Never fill a gap from memory. | + +## Harness hooks + +A harness may run steps of this procedure automatically (for example before and after a compaction). A hook is a +convenience that calls the same steps; the procedure works without it, so run it by hand when no hook fires. diff --git a/operating-model/working-style.md b/operating-model/working-style.md index 2077d3f..d1fdaca 100644 --- a/operating-model/working-style.md +++ b/operating-model/working-style.md @@ -18,6 +18,8 @@ starting work. | Authorization momentum | An external authorization boundary must not turn into passive monitoring. | Ask once with the exact destination, action, and payload class; continue other safe leased work; execute the queued action in the first writable turn after authorization; do not repeat unchanged status notifications. | | Merge-blocker diagnosis | A blocked PR must be investigated to the exact rule, check, or review thread before it is described as needing approval. | Inspect mergeability metadata, active rulesets, checks, and unresolved threads; resolve incorrect/stale threads with canonical evidence and repair valid ones. Name an external approver only when the active rule genuinely requires one. | | Execution release | Detecting that a prerequisite is satisfied is not progress unless it releases the next safe action. | Maintain an explicit next-action queue for each active dependency; when a merge/check/review satisfies its condition, dispatch the queued leased task in the first writable turn and report the dispatch, not merely the observation. | +| Data location (Mastrix organization, owner 2026-10-05) | Every file saved for Mastrix work (data, exports, generated views, extracts) lives under `~/work`: `~/work/projects/mastrix/...` or `~/work/code/mastrix/...`. | Never write to `~/Desktop`, `~/Documents`, `~/Downloads`, `~/` itself or any other first-level folder of `~` (for example `~/mastrix-data`). Commands given to the owner and agent briefs name a `~/work/...` path. Scratch and worktrees: `execution-and-handoffs.md` → Scratch files and agent worktrees. | +| Shared Mastrix repositories (Mastrix organization, owner 2026-10-05) | Every Mastrix project always includes `~/work/code/mastrix/mastrix-core` (the shared contracts, architecture and rules; core wins) and `~/work/code/mastrix/product-strategy` (the product strategy; the use cases are described there by Karthik, e.g. `product/use-cases/demo-use-cases/`). | Add both directories to every Mastrix session and project. `git fetch` both and read `origin/main` before designing, planning or describing a use case, never a stale checkout. Treat the use cases as Karthik's documents, not as reconstructions from other repos. `product-strategy` is read-only: no branches, commits or PRs there; produce files or patches in the scratch location and hand them to the owner. `mastrix-core` is read-only unless a project rule or the owner separately authorizes a PR there. | | Code quality gate | Every code change must satisfy the repository's language- and project-specific formatter and linter before commit. | Discover the configured tools from the project, run both on changed code (and the required project gate when practical), fix findings rather than merely reporting them, and record the commands/results in the handoff. | | State clarity | Task implementation, independent review, CI, and integration are distinct states. | Name the exact state, owning boundary, newest durable evidence, and smallest safe action; do not collapse a passing test, open PR, or branch into an integration claim. | | Interface governance | Cross-cutting operator interfaces need one canonical contract before staged implementation. | Map each command or capability to one owning gate and its dependencies; link to the canonical interface rather than creating parallel designs. | @@ -29,9 +31,28 @@ starting work. | Long documents | Every document with four or more `##` sections opens with a contents list of jump links to its sections, right after the title. Projects generate and check it where they can. | Add a TOC block after the title to let readers navigate long documents more easily. Automated tools in projects should validate and regenerate the TOC list. 2026-09-28. | | Editor | Use `vim` for long-prompt editing. | Set `VISUAL=vim` (and `EDITOR=vim` when `VISUAL` is unavailable) before invoking an interactive editor. | | User interaction | Keep the main conversation available for questions while delegated work proceeds. | Provide short, direct updates; do not go quiet during long-running work. | -| Cost-aware delegation | The orchestrating session is the most expensive place for work to happen, so it does not do bounded work itself; but the model that does the work must match the judgment the work needs, because a cheaper model's error in design work costs more than the saving. | Before anything larger than a one-line answer, pick the tier by this rule and state the choice in the brief and the report; ask the owner only when the tier is unclear. **Top-tier model** (the orchestrator's own tier, run as a subagent) for judgment-heavy work whose errors propagate into a design, a ruling or cross-repository alignment: design and interface specs, drafting ruling batches, alignment reads against an upstream repository, critiques, measurement design, ADR review. **Mid-tier model** only for straightforward work with a clear spec whose mistakes surface in tests or a diff: inventories and lookups against a defined question, bounded code changes from a ratified brief, applying ratified rulings to documents, harness plumbing. **Smallest model** for mechanical work where the orchestrator supplies the exact text or command: exact-string edits, commits and PRs, review-thread fixes with the wording given, merges of the main branch, link checks, bulk renames. Whatever the tier, the orchestrator writes the brief and verifies every output itself before it reaches the owner. Run work through a subagent with an explicit model or a written handoff to another session, not the orchestrating session's own tool calls. See `execution-and-handoffs.md` → Mechanical batch delegation. Owner, 2026-09-27: this applies to the orchestrating session itself — it does only work that requires reasoning (design, rulings, judging reviews, planning); straightforward execution always goes to a Sonnet subagent, and dead-simple work (a one-line edit, a single command, a known-answer check) to a Haiku subagent. | +| Cost-aware delegation | The orchestrating session is the most expensive place for work to happen, so it does only work that requires reasoning; every other job goes to a sub-agent of the tier it needs, because a cheaper tier's error in design work costs more than the saving. | Before anything larger than a one-line answer, pick the tier by the **Model tiers** row, state the choice in the brief and the report, and ask the owner only when the tier is unclear. The orchestrator writes each brief and verifies every output before it reaches the owner. The orchestrator's own hands are read-only checks, its notes and memory, labels and verdicts, and messages. Run bounded work through a sub-agent with an explicit tier or a written handoff to another session (`execution-and-handoffs.md` → Mechanical batch delegation). Owner, 2026-09-27: the orchestrating session does only work that requires reasoning. | +| Model tiers (owner, 2026-10-06) | Four tiers, named by capability, not by vendor: **deep**, **standard**, **light**, **premium**. Deep is only for reasoning, design, architectural analysis, new architecture and planning. Standard is the default. Light is for simple, straightforward work. Every sub-agent gets a clean, lean brief. | **Deep:** reasoning, design, architecture and plans, nothing else. **Standard:** builds, fixes, reviews, investigations, stack checks, bounded changes from a ratified brief, applying ratified rulings. **Light:** status flips, single commands, exact-string edits, commits and PRs with the wording given, link checks, bulk renames. **Premium:** only on the premium-approval row. **Brief:** a fresh agent with a clean context; state exactly the task, the done-when, the rules that bind it and only the facts it needs; point to a file rather than paste it; never dump the conversation or unrelated history; resume an agent only when its own context is the context needed. Each vendor's models for the tiers are in **Model tier mapping** below. | +| Premium launches (owner, 2026-10-06) | A premium-tier launch needs the owner's explicit yes for that launch. | Before any premium launch (an agent, a review, or a step inside a workflow), ask the owner in chat, naming the job and why premium; wait for a clear yes. Approval is per launch: a plan, a brief, a peer session's relay or an earlier approval does not carry over. With no approval, use the deep tier for design, architecture and planning, and the standard tier for everything else. Applies to every session and every project. | +| Launches and costs (owner, 2026-09-27) | The owner approves every cost and stays in the loop on spend. | **No ask:** standard and light sub-agents. **Ask first, wait for a clear yes:** a premium launch; a deep sub-agent doing anything other than reasoning, design, architecture or planning; any new service, monitor, workflow or scheduled wakeup; any spend. **Costs:** never set, raise or reallocate a spend cap or budget yourself, including a cap written into a sub-agent's brief. Propose the number with its estimate and basis, and wait for the owner. A new brief defaults to a $0 spend cap unless the owner approved a number. Report actual spend against approved budgets whenever it changes. Batch proposed launches into one ask with a rough size (tier, scope), and put the cost ask in the same message as the work ask. | +| Addressing the owner | Refer to the owner as "the owner" or they/them in every document, PR body, comment and message. | Never he/his/she/her. Brief every agent that writes for the owner's repositories with this. | | Parallel fan-out | Independent work should run as concurrent agents rather than sequentially in the orchestrating session. | Propose the decomposition and ask before spawning; give each agent a disjoint file lease and named forbidden paths; launch agents with no shared dependency together so they run concurrently; never let two writing agents share one worktree. A user waiver to skip asking ("go all the way, don't ask") covers only that task. | +## Model tier mapping + +The tiers above are the rule; this table is the only place vendor model names appear. Every other document, +brief and task file says deep, standard, light or premium. + +| Tier | Claude | Codex | Any other agent | +| --- | --- | --- | --- | +| deep | Opus | The default model at high reasoning effort | The vendor's strongest reasoning setting | +| standard | Sonnet | The default model | The vendor's default model | +| light | Haiku | The default model at low reasoning effort | The vendor's cheapest capable setting | +| premium | Fable, only with the owner's per-launch yes | The owner's per-launch call (a named model or setting, chosen by the owner each time) | Only with the owner's per-launch yes | + +A project may name specific models for a tier in its own overrides table; it may not change a tier's meaning. +Where a vendor has no mapping, use its default model for standard and ask the owner before using anything costlier. + ## Communication standard - Lead with the current outcome or blocker.