From b779d6773f3961c434f374c17d5921a03d7cd739 Mon Sep 17 00:00:00 2001 From: Varun Katta Date: Wed, 14 Oct 2026 04:01:22 -0700 Subject: [PATCH 1/7] Agent orchestration has one owner in env: roles, long-lived sessions, what a project binds Moves the long-lived-sessions rules out of execution-and-handoffs into agent-orchestration.md, adds the ownership table and roles, and turns the duplicate integration preflight into a pointer. Co-Authored-By: Claude Sonnet 5.5 --- operating-model/README.md | 3 +- operating-model/agent-orchestration.md | 97 +++++++++++++++++++++++ operating-model/agent-work-loop.md | 2 +- operating-model/decision-log.md | 1 + operating-model/execution-and-handoffs.md | 49 +----------- operating-model/working-style.md | 17 +--- 6 files changed, 107 insertions(+), 62 deletions(-) create mode 100644 operating-model/agent-orchestration.md diff --git a/operating-model/README.md b/operating-model/README.md index e3de987..ae0695f 100644 --- a/operating-model/README.md +++ b/operating-model/README.md @@ -28,7 +28,8 @@ repository or secure system. | Document | Use | | --- | --- | | [Working style](working-style.md) | Confirmed collaboration preferences and communication expectations. | -| [Execution and handoffs](execution-and-handoffs.md) | How bounded work, delegation, reviews, checkpoints, blockers, long-lived sessions (worker self-clears, model tier by task) and documentation batching are handled. | +| [Agent orchestration](agent-orchestration.md) | Who owns what, the agent roles, how long-lived sessions hold state and subagents do work, and what a project may bind. | +| [Execution and handoffs](execution-and-handoffs.md) | How bounded work, delegation, reviews, checkpoints, blockers and documentation batching 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. | diff --git a/operating-model/agent-orchestration.md b/operating-model/agent-orchestration.md new file mode 100644 index 0000000..ab34828 --- /dev/null +++ b/operating-model/agent-orchestration.md @@ -0,0 +1,97 @@ +# Agent orchestration + +This is the one owner of how agents are organised and run in any project: who does what, what a session keeps and +what it hands off, and what a project may bind. It states no model names, no board commands and no project facts. + +**Contents** + +- [Who owns what](#who-owns-what) +- [Roles](#roles) +- [Long-lived sessions: sessions hold state, subagents do work](#long-lived-sessions-sessions-hold-state-subagents-do-work) +- [What a project binds](#what-a-project-binds) + +## Who owns what + +One owner per fact. A rule is written in its owner and linked from everywhere else. + +| Topic | Owner | +| --- | --- | +| Roles, sessions and subagents, context clearing | This file | +| The dispatcher, the stop rule, independence, hand-offs on the board | [`agent-work-loop.md`](agent-work-loop.md) | +| Model tiers, the vendor mapping, premium launches, costs | [`working-style.md`](working-style.md) → Model tiers, Model tier mapping, Launches and costs | +| Bounded work, delegation, reviews, PR loops, checkpoints, documentation gates, scratch files and worktrees | [`execution-and-handoffs.md`](execution-and-handoffs.md) | +| Communication, theme, editor and other personal preferences | [`working-style.md`](working-style.md) | +| Why a rule exists, and when it was ruled | [`decision-log.md`](decision-log.md): history, never the rule | + +## Roles + +| Role | Does | Never does | +| --- | --- | --- | +| Orchestrator (a lead) | Plans, briefs, reviews, rules, routes approvals | Builds or runs what a cheaper tier can do | +| Design partner | Holds the design thread, rulings and open questions | Dispatches builders or code PRs | +| Workhorse (builder) | Keeps its queue and state note; one fresh subagent per PR | Asks the owner for approvals itself | +| Dispatcher and its sub-agents | One clean-context sub-agent per job, then stop ([`agent-work-loop.md`](agent-work-loop.md) section 2) | Reads code or diffs itself | +| Independent reviewer | Checks work at an exact head and reports a verdict | Reviews its own work or edits what it reviews | +| Inquiry session | Answers questions to build understanding, read-only on the project, with artifacts kept locally ([`working-style.md`](working-style.md) → Inquiry sessions) | Edits a project or opens PRs | + +## Long-lived sessions: sessions hold state, subagents do work + +Some projects run several long-lived sessions side by side, such as a lead, design partners and workhorses. A +session's context grows with every file it reads, and compaction loses details. So each session keeps only the state +it needs and hands the reading and building to fresh subagents. This extends the dispatcher of +[`agent-work-loop.md`](agent-work-loop.md) section 2 to sessions that live for days. + +| Role | Keeps in its own context | Hands to fresh subagents | Compacts or clears | +| --- | --- | --- | --- | +| Lead (orchestrator) | the board, the owner's rulings, approvals | every review, run preparation, wide reads | at the owner's word, after a checkpoint | +| Design partner | the design thread: rulings, open questions, what each document owns | measurements, scripts, wide code reads | at a design-PR boundary past about 60% of the window, after updating its state file; never mid-ruling | +| Workhorse (builder) | its queue, PR heads, review findings, a state note | each PR's build: one fresh subagent per PR | itself, at a landing, once its state note is written (see [Workers self-clear at landings](#workers-self-clear-at-landings)) | + +- **A brief stands alone.** It names the goal, the spec anchors, the exact files, the done-criteria (tests seen red + first, mutations, one full check) and what not to touch, and it points to the project's rules file. If a subagent + needs the session's memory to do the job, the brief is wrong. +- **The tier follows the task.** Builds and fix rounds use the default (standard) tier; mechanical sub-steps use the + lightest tier; the independent review of a behaviour change uses the deep tier. The orchestrator reasons and decides + and hands mechanical work down. The table is `working-style.md` → Model tiers; a premium launch still needs the + owner's per-launch yes. +- **Only conclusions come back:** the PR head, counts and disclosures, never file dumps. +- **A fix round goes back to the same subagent,** which still has the code in context. A new PR gets a new subagent. +- **Approvals never pass through subagents.** Costs, reads of protected data, writes to live systems and rebuilds stay + with the session the owner approves through. A subagent's own safety checks may refuse such actions, and that + refusal must not be routed around. +- **Compact at task boundaries, not on a timer.** Mid-task, compact only past about half the window, and only after + writing a state note (branch, head, done, next). Never compact while review findings are being fixed. +- **A lead or design partner clears rarely;** a worker clears at landings, below. Observed 2026-10-13 in the Claude + desktop app: it pauses one session's messages to other sessions after about ten sends without the owner typing, and + a cleared session is reachable only through that route. A session that dispatches subagents seldom needs clearing, + and a cleared worker is reached through its state note and the orchestrator's board, not through a message. + +### Workers self-clear at landings + +A worker does not wait to be told to clear. When its PR has landed and no fix round is open, it clears its own +context, and its state note is how it resumes. + +| Step | Rule | +| --- | --- | +| When | A worker's PR has landed and the worker has no fix round open. A worker may hold one PR in review while it builds the next, and clears at the first point where neither has an open fix round. | +| Before | Write the state note: the queue, open PRs with their heads, and pending findings. | +| Clear | The worker clears its own context. | +| Next action | Read the state note, then the project's operating rules. Nothing else carries over. | +| Never | While a fix round is open, or before the state note is written. | +| Orchestrator | At each landing it reports, check whether the worker cleared; if not, name the clear as the worker's next step. | + +## What a project binds + +A project inherits these rules. Its agent instructions link here and state only its own bindings +([`agent-work-loop.md`](agent-work-loop.md) section 7 sets the same rule for the work loop). + +| A project may bind | Example | +| --- | --- | +| Which session holds which role now | The lane table | +| Which model each tier names | The vendor mapping in `working-style.md` | +| Protected data and forbidden paths | Secrets, sealed or held-out data | +| Its landing mechanism | A label gate, who merges, size limits | +| Its own parameters and quality gates | Re-check interval, the project's checks | + +A project may not restate these rules or change what they mean. If a project file and this file disagree on a rule +this file owns, this file wins and the project file is fixed. diff --git a/operating-model/agent-work-loop.md b/operating-model/agent-work-loop.md index 4f10130..4b5ce76 100644 --- a/operating-model/agent-work-loop.md +++ b/operating-model/agent-work-loop.md @@ -90,7 +90,7 @@ job goes to a fresh sub-agent, so no job inherits another job's context. **Claims.** The dispatcher claims before it launches, so two dispatchers never start the same job. **Long-lived sessions.** For sessions that live for days (a lead, design partners, workhorses), see -[`execution-and-handoffs.md`](execution-and-handoffs.md) → Long-lived sessions. +[`agent-orchestration.md`](agent-orchestration.md) → Long-lived sessions. ## 3. The stop rule diff --git a/operating-model/decision-log.md b/operating-model/decision-log.md index ec2b2f6..46706aa 100644 --- a/operating-model/decision-log.md +++ b/operating-model/decision-log.md @@ -47,3 +47,4 @@ Status is intentionally explicit: | 2026-10-13 | Confirmed | Doc-only changes (decision records, status lines, nits, READMEs) ride in the code PR that implements or touches them; a doc that must land first is batched with the other pending doc changes into one PR per boundary. | Owner's rule to cut the number of landings and the CI load. It stays within the project's PR size and one-objective limits and never stacks PRs. See `execution-and-handoffs.md` → Documentation rides with code. | | 2026-10-14 | Confirmed | A long-lived worker clears its own context at a landing: when its PR has landed and no fix round is open, it writes its state note (queue, open PRs, pending findings), clears, then reads the state note and the operating rules. It may hold one PR in review while building the next and clears at the first point neither has a fix round open. The orchestrator checks for clears at each landing it reports. | Owner adopted the rule to keep worker contexts small without waiting for a prompt. Refines the 2026-10-13 long-lived-sessions row, which compacted a worker after its PR merged but left the trigger to the owner. See `execution-and-handoffs.md` → Long-lived sessions → Workers self-clear at landings. | | 2026-10-14 | Confirmed | Model tier follows the task: builds and fix rounds use the default (standard) tier; mechanical sub-steps (merging the base branch, label or head checks, log or state-note edits, simple searches) use the light tier; the independent review of a behaviour change uses the deep tier. The orchestrator reasons and decides, and hands mechanical work down. | Owner adopted the split. Refines the 2026-10-08 tier row: reviews were standard tier and deep was reasoning only; the independent review of a behaviour change is now deep, and no ask is needed for it. A premium launch still needs the owner's per-launch yes. See `working-style.md` → Model tiers and `execution-and-handoffs.md` → Long-lived sessions. | +| 2026-10-14 | Provisional | How agents are organised and run has one owner, `agent-orchestration.md`; duplicates elsewhere in env become pointers, and a project binds parameters only. | Proposed after a read of env, user-sandbox, core, the lead notes and memory found the same rules in several places and a few conflicting. Provisional until the owner confirms the layering and rules the open review-tier question. See `agent-orchestration.md`. | diff --git a/operating-model/execution-and-handoffs.md b/operating-model/execution-and-handoffs.md index 0ff70c7..6064c1a 100644 --- a/operating-model/execution-and-handoffs.md +++ b/operating-model/execution-and-handoffs.md @@ -289,51 +289,10 @@ description of the problem. | 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. | -## Long-lived sessions: sessions hold state, subagents do work - -Some projects run several long-lived sessions side by side, such as a lead, design partners and workhorses. A -session's context grows with every file it reads, and compaction loses details. So each session keeps only the state -it needs and hands the reading and building to fresh subagents. This extends the dispatcher of -[`agent-work-loop.md`](agent-work-loop.md) section 2 to sessions that live for days. - -| Role | Keeps in its own context | Hands to fresh subagents | Compacts or clears | -| --- | --- | --- | --- | -| Lead (orchestrator) | the board, the owner's rulings, approvals | every review, run preparation, wide reads | at the owner's word, after a checkpoint | -| Design partner | the design thread: rulings, open questions, what each document owns | measurements, scripts, wide code reads | at a design-PR boundary past about 60% of the window, after updating its state file; never mid-ruling | -| Workhorse (builder) | its queue, PR heads, review findings, a state note | each PR's build: one fresh subagent per PR | itself, at a landing, once its state note is written (see [Workers self-clear at landings](#workers-self-clear-at-landings)) | - -- **A brief stands alone.** It names the goal, the spec anchors, the exact files, the done-criteria (tests seen red - first, mutations, one full check) and what not to touch, and it points to the project's rules file. If a subagent - needs the session's memory to do the job, the brief is wrong. -- **The tier follows the task.** Builds and fix rounds use the default (standard) tier; mechanical sub-steps use the - lightest tier; the independent review of a behaviour change uses the deep tier. The orchestrator reasons and decides - and hands mechanical work down. The table is `working-style.md` → Model tiers; a premium launch still needs the - owner's per-launch yes. -- **Only conclusions come back:** the PR head, counts and disclosures, never file dumps. -- **A fix round goes back to the same subagent,** which still has the code in context. A new PR gets a new subagent. -- **Approvals never pass through subagents.** Costs, reads of protected data, writes to live systems and rebuilds stay - with the session the owner approves through. A subagent's own safety checks may refuse such actions, and that - refusal must not be routed around. -- **Compact at task boundaries, not on a timer.** Mid-task, compact only past about half the window, and only after - writing a state note (branch, head, done, next). Never compact while review findings are being fixed. -- **A lead or design partner clears rarely;** a worker clears at landings, below. Observed 2026-10-13 in the Claude - desktop app: it pauses one session's messages to other sessions after about ten sends without the owner typing, and - a cleared session is reachable only through that route. A session that dispatches subagents seldom needs clearing, - and a cleared worker is reached through its state note and the orchestrator's board, not through a message. - -### Workers self-clear at landings - -A worker does not wait to be told to clear. When its PR has landed and no fix round is open, it clears its own -context, and its state note is how it resumes. - -| Step | Rule | -| --- | --- | -| When | A worker's PR has landed and the worker has no fix round open. A worker may hold one PR in review while it builds the next, and clears at the first point where neither has an open fix round. | -| Before | Write the state note: the queue, open PRs with their heads, and pending findings. | -| Clear | The worker clears its own context. | -| Next action | Read the state note, then the project's operating rules. Nothing else carries over. | -| Never | While a fix round is open, or before the state note is written. | -| Orchestrator | At each landing it reports, check whether the worker cleared; if not, name the clear as the worker's next step. | +## Long-lived sessions + +Sessions hold state and subagents do work; workers self-clear at landings. These rules, with the roles table, live in +[`agent-orchestration.md`](agent-orchestration.md). ## Scratch files and agent worktrees diff --git a/operating-model/working-style.md b/operating-model/working-style.md index 16fa840..b9f2a63 100644 --- a/operating-model/working-style.md +++ b/operating-model/working-style.md @@ -88,21 +88,8 @@ decision and an agent's provisional inference. ## Integration-topology preflight -The integration owner must run and record this preflight before declaring a task ready for review, -CI, or integration: - -1. Confirm every implementation and verifier packet has one named owner, linked verifier, - integration owner, exact allowed/forbidden paths, and required acceptance commands. -2. Confirm the declared base is the actual shared ancestor of the registered branch/worktree and - descends from the accepted baseline; do not substitute a later activation commit merely because - it contains the packet. -3. Confirm a verifier branch starts from that clean shared base, not from the implementation - branch. It may inspect a candidate SHA, but its own diff may contain only its packet and report. -4. Run the full task/lease validator and each implementation and verifier branch-diff gate against - the exact integration/PR merge ref, not just a local happy-path command. -5. Treat any failure as an owned integration-readiness defect until a local reproduction identifies - a true external boundary. Assign the smallest bounded repair immediately; do not label it a CI - issue by assumption. +The integration owner runs the checks of [`execution-and-handoffs.md`](execution-and-handoffs.md) → Integration-readiness +sweep before declaring a task ready for review, CI or integration. ## Decision posture From bcf9407ce35d274d75fc14f05a756599942ec4a9 Mon Sep 17 00:00:00 2001 From: Varun Katta Date: Wed, 14 Oct 2026 08:41:39 -0700 Subject: [PATCH 2/7] Top-level guidance: a project defers to the shared rulebook it names on what that rulebook owns Co-Authored-By: Claude Sonnet 5.5 --- operating-model/agent-orchestration.md | 16 ++++++++++++---- operating-model/decision-log.md | 2 +- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/operating-model/agent-orchestration.md b/operating-model/agent-orchestration.md index ab34828..4eb4793 100644 --- a/operating-model/agent-orchestration.md +++ b/operating-model/agent-orchestration.md @@ -82,16 +82,24 @@ context, and its state note is how it resumes. ## What a project binds -A project inherits these rules. Its agent instructions link here and state only its own bindings +This file is the top-level guidance for every project's agents. A project's agent instructions are a router: they link +here, link to the shared rulebook the project defers to, and state only the project's own bindings ([`agent-work-loop.md`](agent-work-loop.md) section 7 sets the same rule for the work loop). +| Level | Owns | Wins over | +| --- | --- | --- | +| The owner's latest word | Everything | Everything below | +| This operating model | How agents are organised and run, in any project | A project file that restates or contradicts it | +| A shared rulebook the project names (for example a core repository) | Its engineering, review and landing rules, for the projects that defer to it | This model, on exactly what the rulebook owns, inside those projects | +| The project's own instructions | Bindings only (below) | Nothing above | + | A project may bind | Example | | --- | --- | | Which session holds which role now | The lane table | | Which model each tier names | The vendor mapping in `working-style.md` | | Protected data and forbidden paths | Secrets, sealed or held-out data | -| Its landing mechanism | A label gate, who merges, size limits | | Its own parameters and quality gates | Re-check interval, the project's checks | -A project may not restate these rules or change what they mean. If a project file and this file disagree on a rule -this file owns, this file wins and the project file is fixed. +A project may not restate these rules or change what they mean. Where a project defers to a shared rulebook, it links +the rulebook's rule and does not copy it. If a project file disagrees with the rule's owner, the owner wins and the +project file is fixed. diff --git a/operating-model/decision-log.md b/operating-model/decision-log.md index 46706aa..dc386e8 100644 --- a/operating-model/decision-log.md +++ b/operating-model/decision-log.md @@ -47,4 +47,4 @@ Status is intentionally explicit: | 2026-10-13 | Confirmed | Doc-only changes (decision records, status lines, nits, READMEs) ride in the code PR that implements or touches them; a doc that must land first is batched with the other pending doc changes into one PR per boundary. | Owner's rule to cut the number of landings and the CI load. It stays within the project's PR size and one-objective limits and never stacks PRs. See `execution-and-handoffs.md` → Documentation rides with code. | | 2026-10-14 | Confirmed | A long-lived worker clears its own context at a landing: when its PR has landed and no fix round is open, it writes its state note (queue, open PRs, pending findings), clears, then reads the state note and the operating rules. It may hold one PR in review while building the next and clears at the first point neither has a fix round open. The orchestrator checks for clears at each landing it reports. | Owner adopted the rule to keep worker contexts small without waiting for a prompt. Refines the 2026-10-13 long-lived-sessions row, which compacted a worker after its PR merged but left the trigger to the owner. See `execution-and-handoffs.md` → Long-lived sessions → Workers self-clear at landings. | | 2026-10-14 | Confirmed | Model tier follows the task: builds and fix rounds use the default (standard) tier; mechanical sub-steps (merging the base branch, label or head checks, log or state-note edits, simple searches) use the light tier; the independent review of a behaviour change uses the deep tier. The orchestrator reasons and decides, and hands mechanical work down. | Owner adopted the split. Refines the 2026-10-08 tier row: reviews were standard tier and deep was reasoning only; the independent review of a behaviour change is now deep, and no ask is needed for it. A premium launch still needs the owner's per-launch yes. See `working-style.md` → Model tiers and `execution-and-handoffs.md` → Long-lived sessions. | -| 2026-10-14 | Provisional | How agents are organised and run has one owner, `agent-orchestration.md`; duplicates elsewhere in env become pointers, and a project binds parameters only. | Proposed after a read of env, user-sandbox, core, the lead notes and memory found the same rules in several places and a few conflicting. Provisional until the owner confirms the layering and rules the open review-tier question. See `agent-orchestration.md`. | +| 2026-10-14 | Provisional | How agents are organised and run has one owner, `agent-orchestration.md`; duplicates elsewhere in env become pointers, and a project binds parameters only; the project's agents defer to the shared rulebook the project names (for Mastrix, mastrix-core) on what it owns (owner, 2026-10-14). | Proposed after a read of env, user-sandbox, core, the lead notes and memory found the same rules in several places and a few conflicting. Provisional until the owner confirms the layering and rules the open review-tier question. See `agent-orchestration.md`. | From 8a9ddd54a4aba1a4c05be4787d73c09ae8f77b1c Mon Sep 17 00:00:00 2001 From: Varun Katta Date: Wed, 14 Oct 2026 08:42:58 -0700 Subject: [PATCH 3/7] Tier-to-model mapping stays in env; a project binds only its lane table Co-Authored-By: Claude Sonnet 5.5 --- operating-model/agent-orchestration.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/operating-model/agent-orchestration.md b/operating-model/agent-orchestration.md index 4eb4793..0630326 100644 --- a/operating-model/agent-orchestration.md +++ b/operating-model/agent-orchestration.md @@ -18,7 +18,7 @@ One owner per fact. A rule is written in its owner and linked from everywhere el | --- | --- | | Roles, sessions and subagents, context clearing | This file | | The dispatcher, the stop rule, independence, hand-offs on the board | [`agent-work-loop.md`](agent-work-loop.md) | -| Model tiers, the vendor mapping, premium launches, costs | [`working-style.md`](working-style.md) → Model tiers, Model tier mapping, Launches and costs | +| Model tiers, the tier-to-model mapping, premium launches, costs | [`working-style.md`](working-style.md) → Model tiers, Model tier mapping, Launches and costs | | Bounded work, delegation, reviews, PR loops, checkpoints, documentation gates, scratch files and worktrees | [`execution-and-handoffs.md`](execution-and-handoffs.md) | | Communication, theme, editor and other personal preferences | [`working-style.md`](working-style.md) | | Why a rule exists, and when it was ruled | [`decision-log.md`](decision-log.md): history, never the rule | @@ -95,8 +95,7 @@ here, link to the shared rulebook the project defers to, and state only the proj | A project may bind | Example | | --- | --- | -| Which session holds which role now | The lane table | -| Which model each tier names | The vendor mapping in `working-style.md` | +| Which named session holds which role now, and what files or work each owns | The project's lane table | | Protected data and forbidden paths | Secrets, sealed or held-out data | | Its own parameters and quality gates | Re-check interval, the project's checks | From c3430d89261315722b591236aa891ad6a12fa9e6 Mon Sep 17 00:00:00 2001 From: Varun Katta Date: Wed, 14 Oct 2026 08:45:08 -0700 Subject: [PATCH 4/7] Generic lane table in env: roles with their tiers; a project's lane table binds them to named sessions Co-Authored-By: Claude Sonnet 5.5 --- operating-model/agent-orchestration.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/operating-model/agent-orchestration.md b/operating-model/agent-orchestration.md index 0630326..a0b58b5 100644 --- a/operating-model/agent-orchestration.md +++ b/operating-model/agent-orchestration.md @@ -25,14 +25,18 @@ One owner per fact. A rule is written in its owner and linked from everywhere el ## Roles -| Role | Does | Never does | -| --- | --- | --- | -| Orchestrator (a lead) | Plans, briefs, reviews, rules, routes approvals | Builds or runs what a cheaper tier can do | -| Design partner | Holds the design thread, rulings and open questions | Dispatches builders or code PRs | -| Workhorse (builder) | Keeps its queue and state note; one fresh subagent per PR | Asks the owner for approvals itself | -| Dispatcher and its sub-agents | One clean-context sub-agent per job, then stop ([`agent-work-loop.md`](agent-work-loop.md) section 2) | Reads code or diffs itself | -| Independent reviewer | Checks work at an exact head and reports a verdict | Reviews its own work or edits what it reviews | -| Inquiry session | Answers questions to build understanding, read-only on the project, with artifacts kept locally ([`working-style.md`](working-style.md) → Inquiry sessions) | Edits a project or opens PRs | +The generic lane table: each role, the tier it runs on ([`working-style.md`](working-style.md) → Model tiers) and what it +does and never does. A project's own lane table binds these roles to its named sessions and to its work splits; it adds +no role that this table covers. + +| Role | Tier | Does | Never does | +| --- | --- | --- | --- | +| Orchestrator (a lead) | deep | Plans, briefs, reviews, rules, routes approvals, keeps every change moving | Builds or runs what a cheaper tier can do | +| Design partner | deep | Holds the design thread, rulings and open questions; hands build items to the orchestrator | Dispatches builders or code PRs | +| Workhorse (builder) | standard | Keeps its queue and state note; one fresh subagent per PR; mechanical sub-steps go to light | Asks the owner for approvals itself | +| Dispatcher and its sub-agents | cheapest capable; the sub-agent runs the task's tier | One clean-context sub-agent per job, then stop ([`agent-work-loop.md`](agent-work-loop.md) section 2) | Reads code or diffs itself | +| Independent reviewer | per the review rule in Model tiers | Checks work at an exact head and reports a verdict | Reviews its own work or edits what it reviews | +| Inquiry session | standard | Answers questions to build understanding, read-only on the project, artifacts kept locally ([`working-style.md`](working-style.md) → Inquiry sessions) | Edits a project or opens PRs | ## Long-lived sessions: sessions hold state, subagents do work @@ -95,7 +99,7 @@ here, link to the shared rulebook the project defers to, and state only the proj | A project may bind | Example | | --- | --- | -| Which named session holds which role now, and what files or work each owns | The project's lane table | +| Which named session holds each role above, and how its work is split (by files, milestone or kind) | The project's lane table, for example DIS's | | Protected data and forbidden paths | Secrets, sealed or held-out data | | Its own parameters and quality gates | Re-check interval, the project's checks | From 7d8e4994ad3e964892ca010817b541f9f3aee91d Mon Sep 17 00:00:00 2001 From: Varun Katta Date: Wed, 14 Oct 2026 08:50:45 -0700 Subject: [PATCH 5/7] Peer workhorses share one queue; an area split is a preference, not a boundary Co-Authored-By: Claude Sonnet 5.5 --- operating-model/agent-orchestration.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/operating-model/agent-orchestration.md b/operating-model/agent-orchestration.md index a0b58b5..4bf32a6 100644 --- a/operating-model/agent-orchestration.md +++ b/operating-model/agent-orchestration.md @@ -38,6 +38,12 @@ no role that this table covers. | Independent reviewer | per the review rule in Model tiers | Checks work at an exact head and reports a verdict | Reviews its own work or edits what it reviews | | Inquiry session | standard | Answers questions to build understanding, read-only on the project, artifacts kept locally ([`working-style.md`](working-style.md) → Inquiry sessions) | Edits a project or opens PRs | +**Peer workhorses share one queue.** When a project runs more than one workhorse, a work split by area (for example +build side and answer side) is a preference, not a boundary. Work is balanced: an open item goes to the first workhorse +with room, and no workhorse sits idle while another is backlogged. The one limit is the existing fan-out rule: two +concurrent PRs never share files, so a lease on the files an item touches decides who may take it +([`working-style.md`](working-style.md) → Parallel fan-out). Owner, 2026-10-14. + ## Long-lived sessions: sessions hold state, subagents do work Some projects run several long-lived sessions side by side, such as a lead, design partners and workhorses. A From bf04d28e84f41b696ab120adb50cad0d82aa2268 Mon Sep 17 00:00:00 2001 From: Varun Katta Date: Wed, 14 Oct 2026 08:52:29 -0700 Subject: [PATCH 6/7] Workhorse affinity cuts conflicts; the orchestrator keeps the load fair Co-Authored-By: Claude Sonnet 5.5 --- operating-model/agent-orchestration.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/operating-model/agent-orchestration.md b/operating-model/agent-orchestration.md index 4bf32a6..7c50e5d 100644 --- a/operating-model/agent-orchestration.md +++ b/operating-model/agent-orchestration.md @@ -38,10 +38,12 @@ no role that this table covers. | Independent reviewer | per the review rule in Model tiers | Checks work at an exact head and reports a verdict | Reviews its own work or edits what it reviews | | Inquiry session | standard | Answers questions to build understanding, read-only on the project, artifacts kept locally ([`working-style.md`](working-style.md) → Inquiry sessions) | Edits a project or opens PRs | -**Peer workhorses share one queue.** When a project runs more than one workhorse, a work split by area (for example -build side and answer side) is a preference, not a boundary. Work is balanced: an open item goes to the first workhorse -with room, and no workhorse sits idle while another is backlogged. The one limit is the existing fan-out rule: two -concurrent PRs never share files, so a lease on the files an item touches decides who may take it +**Peer workhorses share one queue, with an affinity.** When a project runs more than one workhorse, each gets a default +kind of work (for example the build side or the answer side) so that concurrent PRs rarely touch the same files. That +affinity is a preference, not a boundary. The orchestrator also keeps the load fair: an item goes to its preferred +workhorse unless that one is backlogged and another has room, and no workhorse sits idle while another is backlogged, +nor is one starved while another is overloaded. The one hard limit is the fan-out rule: two concurrent PRs never share +files, so a lease on the files an item touches decides who may take it ([`working-style.md`](working-style.md) → Parallel fan-out). Owner, 2026-10-14. ## Long-lived sessions: sessions hold state, subagents do work From 3b06afcd616876f880f7796376b270431405a506 Mon Sep 17 00:00:00 2001 From: Varun Katta Date: Wed, 14 Oct 2026 10:41:52 -0700 Subject: [PATCH 7/7] Approvals stay in the orchestrator's session; owner blockers are raised loudly; no sed Co-Authored-By: Claude Sonnet 5.5 --- operating-model/agent-orchestration.md | 14 +++++++++++++- operating-model/decision-log.md | 1 + 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/operating-model/agent-orchestration.md b/operating-model/agent-orchestration.md index 7c50e5d..205374d 100644 --- a/operating-model/agent-orchestration.md +++ b/operating-model/agent-orchestration.md @@ -8,6 +8,7 @@ what it hands off, and what a project may bind. It states no model names, no boa - [Who owns what](#who-owns-what) - [Roles](#roles) - [Long-lived sessions: sessions hold state, subagents do work](#long-lived-sessions-sessions-hold-state-subagents-do-work) +- [Approvals and blockers](#approvals-and-blockers) - [What a project binds](#what-a-project-binds) ## Who owns what @@ -16,7 +17,7 @@ One owner per fact. A rule is written in its owner and linked from everywhere el | Topic | Owner | | --- | --- | -| Roles, sessions and subagents, context clearing | This file | +| Roles, sessions and subagents, context clearing, where approvals happen, raising blockers | This file | | The dispatcher, the stop rule, independence, hand-offs on the board | [`agent-work-loop.md`](agent-work-loop.md) | | Model tiers, the tier-to-model mapping, premium launches, costs | [`working-style.md`](working-style.md) → Model tiers, Model tier mapping, Launches and costs | | Bounded work, delegation, reviews, PR loops, checkpoints, documentation gates, scratch files and worktrees | [`execution-and-handoffs.md`](execution-and-handoffs.md) | @@ -92,6 +93,17 @@ context, and its state note is how it resumes. | Never | While a fix round is open, or before the state note is written. | | Orchestrator | At each landing it reports, check whether the worker cleared; if not, name the clear as the worker's next step. | +## Approvals and blockers + +Approvals stay in the orchestrator's session, and anything stuck on the owner is raised there at once. + +| Rule | Detail | +| --- | --- | +| **Approvals stay in the orchestrator's session** (owner, 2026-10-14: "I said all approvals should be done through the lead") | The owner is never sent to another session to approve. Costs, reads of protected data, writes to live systems and rebuilds are approved in the orchestrator's session only. | +| A step a peer's permission layer refuses | The peer reports it to the orchestrator with the exact command. The orchestrator either runs it in its own lane, where the approval prompt reaches the owner, or fixes the peer with a narrow allow rule or permission mode that the owner approves. Nobody routes around the refusal. | +| **Owner blockers are raised loudly** (owner, 2026-10-14) | Anything waiting on the owner is raised in the orchestrator's session at once, at the top of its reply under "Needs you now": the session, the exact action and what it blocks. It is raised again every hour while stuck. At each monitor re-arm the orchestrator sweeps every session for a waiting state. | +| No `sed` in any form (owner) | Not for editing and not in a read-only pipe; use the file tools or another command. | + ## What a project binds This file is the top-level guidance for every project's agents. A project's agent instructions are a router: they link diff --git a/operating-model/decision-log.md b/operating-model/decision-log.md index dc386e8..dee9f21 100644 --- a/operating-model/decision-log.md +++ b/operating-model/decision-log.md @@ -48,3 +48,4 @@ Status is intentionally explicit: | 2026-10-14 | Confirmed | A long-lived worker clears its own context at a landing: when its PR has landed and no fix round is open, it writes its state note (queue, open PRs, pending findings), clears, then reads the state note and the operating rules. It may hold one PR in review while building the next and clears at the first point neither has a fix round open. The orchestrator checks for clears at each landing it reports. | Owner adopted the rule to keep worker contexts small without waiting for a prompt. Refines the 2026-10-13 long-lived-sessions row, which compacted a worker after its PR merged but left the trigger to the owner. See `execution-and-handoffs.md` → Long-lived sessions → Workers self-clear at landings. | | 2026-10-14 | Confirmed | Model tier follows the task: builds and fix rounds use the default (standard) tier; mechanical sub-steps (merging the base branch, label or head checks, log or state-note edits, simple searches) use the light tier; the independent review of a behaviour change uses the deep tier. The orchestrator reasons and decides, and hands mechanical work down. | Owner adopted the split. Refines the 2026-10-08 tier row: reviews were standard tier and deep was reasoning only; the independent review of a behaviour change is now deep, and no ask is needed for it. A premium launch still needs the owner's per-launch yes. See `working-style.md` → Model tiers and `execution-and-handoffs.md` → Long-lived sessions. | | 2026-10-14 | Provisional | How agents are organised and run has one owner, `agent-orchestration.md`; duplicates elsewhere in env become pointers, and a project binds parameters only; the project's agents defer to the shared rulebook the project names (for Mastrix, mastrix-core) on what it owns (owner, 2026-10-14). | Proposed after a read of env, user-sandbox, core, the lead notes and memory found the same rules in several places and a few conflicting. Provisional until the owner confirms the layering and rules the open review-tier question. See `agent-orchestration.md`. | +| 2026-10-14 | Confirmed | Approvals happen only in the orchestrator's session; anything stuck on the owner is raised there at once and hourly; no `sed` in any form. | Relayed by the DIS lead from the owner's words the same day ("I said all approvals should be done through the lead"; "If something is stuck more than hour on me, then you need to bring it to my attention"). See `agent-orchestration.md` → Approvals and blockers. |