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..205374d --- /dev/null +++ b/operating-model/agent-orchestration.md @@ -0,0 +1,128 @@ +# 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) +- [Approvals and blockers](#approvals-and-blockers) +- [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, 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) | +| 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 + +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 | + +**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 + +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. | + +## 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 +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 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 | + +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/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..dee9f21 100644 --- a/operating-model/decision-log.md +++ b/operating-model/decision-log.md @@ -47,3 +47,5 @@ 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; 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. | 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