From 4de5e3b3a5461572ad41a1253b4c72e6e1fb6a35 Mon Sep 17 00:00:00 2001 From: Varun Katta Date: Mon, 28 Sep 2026 20:40:28 -0700 Subject: [PATCH 1/2] docs(operating-model): the work loop runs as a dispatcher with one sub-agent per job The launched agent only dispatches: it picks a job, claims it and launches one fresh clean-context sub-agent, one at a time, then reads its report and loops. A run is bounded by the job limit and then stops completely until a human says go. Adds the models and vendor mechanics section (Codex: codex exec per job), two project-set parameters and a decision-log row. Co-Authored-By: Claude Opus 5.5 --- operating-model/README.md | 2 +- operating-model/agent-work-loop.md | 126 +++++++++++++++++++++++------ operating-model/decision-log.md | 1 + 3 files changed, 102 insertions(+), 27 deletions(-) diff --git a/operating-model/README.md b/operating-model/README.md index 4a3da05..a115a06 100644 --- a/operating-model/README.md +++ b/operating-model/README.md @@ -29,7 +29,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: what next, when to stop, who reviews and repairs. Projects inherit it and override only its parameters. | +| [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. | | [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/agent-work-loop.md b/operating-model/agent-work-loop.md index f390ff6..db70ec5 100644 --- a/operating-model/agent-work-loop.md +++ b/operating-model/agent-work-loop.md @@ -1,21 +1,26 @@ # Agent work loop How an AI coding agent (Claude, Codex or any other) takes work from a shared work board: an issue queue that agents -claim from, such as Beads. It covers what to take next, when to stop, who may review or repair what, and how work -passes between agents. +claim from, such as Beads. It covers what to take next, who does the work, when to stop, who may review or repair +what, and how work passes between agents. + +The agent you launch is a **dispatcher**: it picks jobs and launches one fresh sub-agent per job, one at a time. It +never does a job itself. Each sub-agent works with a clean context, does one job and reports back. Projects inherit this protocol. A project may set the parameters in the table at the end and may add rules; it may -not change the rules below. See [Inheritance](#5-inheritance). +not change the rules below. See [Inheritance](#7-inheritance). **Contents** - [Terms](#terms) - [1. The work loop](#1-the-work-loop) -- [2. The stop rule](#2-the-stop-rule) -- [3. Independence](#3-independence) -- [4. Hand-offs are signals on the board](#4-hand-offs-are-signals-on-the-board) -- [5. Inheritance](#5-inheritance) +- [2. The dispatcher and its sub-agents](#2-the-dispatcher-and-its-sub-agents) +- [3. The stop rule](#3-the-stop-rule) +- [4. Independence](#4-independence) +- [5. Hand-offs are signals on the board](#5-hand-offs-are-signals-on-the-board) +- [6. Models and vendor mechanics](#6-models-and-vendor-mechanics) +- [7. Inheritance](#7-inheritance) - [Project-set parameters](#project-set-parameters) @@ -25,21 +30,25 @@ not change the rules below. See [Inheritance](#5-inheritance). |---|---| | **Board** | The shared queue of jobs. The project names it and its commands. | | **Job** | One unit an agent claims: a new task, a review, or a repair. | -| **Doer** | The agent that built a piece of work. | -| **Reviewer** | An agent that checks someone else's work and gives a verdict. | +| **Run** | One launch of the dispatcher: up to the project's job limit of jobs, then a full stop. | +| **Dispatcher** | The launched agent. It reads the board, claims a job and launches a sub-agent for it. It does no job itself. | +| **Sub-agent** | A fresh agent, with a clean context, launched by the dispatcher to do exactly one job. | +| **Doer** | The sub-agent that built a piece of work. | +| **Reviewer** | A sub-agent that checks someone else's work and gives a verdict. | | **Repair** | Fixing work after a REVISE verdict. The repairer works on the same branch and PR. | -| **Actor** | The identity an agent uses to claim a job on the board. | +| **Actor** | The identity used to claim a job on the board and to write to it. | ## 1. The work loop -An agent never goes idle while eligible work exists. After finishing any job it goes back to the board and takes -the next one, in this order: +The dispatcher never goes idle while eligible work exists and its job limit is not reached. After each job it goes +back to the board and picks the next one, in this order. "Its own" work means work built by a sub-agent it +launched in this run: | Priority | Take | Condition | |---|---|---| -| 1 | **Its own open repair**: a REVISE on work it built | Always first, so its own work doesn't wait | -| 2 | **A review that is waiting** | Work it did not build or repair. Prefer work built by another vendor | -| 3 | **A repair of another agent's work whose doer is gone** | "Gone" is the project's threshold. Never a repair of work it reviewed | +| 1 | **Its own open repair**: a REVISE on work built in this run | Always first, so its own work doesn't wait | +| 2 | **A review that is waiting** | Work no sub-agent of this run reviewed or repaired. Prefer work built by another vendor | +| 3 | **A repair of another agent's work whose doer is gone** | "Gone" is the project's threshold. Never a repair of work this run reviewed | | 4 | **A brand-new task** | Only when nothing above is eligible | Reviews and repairs come before new work because unfinished work is worth more once it is finished. A new task @@ -48,29 +57,68 @@ that starts while a review waits only adds to the pile. A job is finished when its output is handed in on the board: a PR marked for review, a verdict posted, or a repair pushed and marked for review again. -## 2. The stop rule +## 2. The dispatcher and its sub-agents + +The agent you launch works with a small, clean context and never builds, reviews or repairs anything itself. Each +job goes to a fresh sub-agent, so no job inherits another job's context. + +**The dispatcher's round.** Each round it: + +1. Reads the board, read-only, and picks the next job in the priority order of [section 1](#1-the-work-loop). +2. Claims the job with the job's actor, before launching anything. +3. Launches **one** sub-agent with a fresh context and a short brief: the job kind, the board id, the task id, the + actor to use, and a pointer to the project's doer and reviewer rules. +4. Waits for the sub-agent to end and reads its report. +5. Checks the board's new state and the PR or verdict the report names. +6. Logs one line (job, kind, result, PR and head), then starts the next round. + +**Rules for the dispatcher** + +- **One sub-agent at a time.** It never runs two sub-agents at once. +- **No reading of code or diffs.** It reads the board and the sub-agent's report only, so its context stays small. +- **No repairing a sub-agent's failure itself.** If a sub-agent fails or stops on a rule, the dispatcher logs it, + releases or flags the claim as the project says, and moves on. It never re-does the job in its own context. + +**Rules for the sub-agent** + +- It does **exactly one job**: build, review or repair. +- It works under the actor the dispatcher claimed with. +- It makes the job's board transition itself: hand-in (open the review item and mark the task "in review"), post + the verdict, or post the REPAIRED signal. See [section 5](#5-hand-offs-are-signals-on-the-board). +- It reports back and ends. It never launches the next job and never picks another from the board. + +**Claims.** The dispatcher claims before it launches, so two dispatchers never start the same job. +## 3. The stop rule + +- **A run is bounded.** After the project's job limit of sub-agent jobs, the dispatcher **stops completely** and + writes its report. It takes no further job until a human tells it to go again, which starts a new run of the same + size. It never restarts itself. - When nothing is eligible, re-check the board at the project's interval, up to the project's number of re-checks. If it is still empty, stop and write a short report. -- Stop after the project's job limit or budget limit per session, even if work remains, and write the report. +- Stop at the project's budget limit, even if work remains, and write the report. - Never poll without a bound. Every check costs credits. -The report lists: each job taken (id, kind, result, PR and head), anything stopped on, and why the session ended +The report lists: each job taken (id, kind, result, PR and head), anything stopped on, and why the run ended (board empty, job limit, or budget limit). -## 3. Independence +## 4. Independence - Never review your own work. - Never repair work you reviewed. - A reviewer never changes the implementation. It reports; someone else repairs. -- One actor identity per job. A reviewer or a repairer never uses the doer's actor, even when one agent session - does all three jobs on different work. A doer repairing its own work may keep its own actor. +- One actor identity per job. A reviewer or a repairer never uses the doer's actor. A doer repairing its own work + may keep its own actor. +- Each sub-agent has a clean context and its own actor, and does one job. So a dispatcher may launch a review of + work a sibling sub-agent built earlier in the same run. Prefer work another vendor built. A sub-agent never + reviews work it built, since it does one job only. - Claims are atomic and the first claim wins. If a claim fails because someone else holds the job, take the next eligible job. If it fails on a lock or busy error, wait briefly and retry a bounded number of times. -## 4. Hand-offs are signals on the board +## 5. Hand-offs are signals on the board -Agents don't call each other. The board is the mailbox. +Agents don't call each other. The board is the mailbox. The dispatcher and its sub-agents talk through a short +brief and a final report; everything else that other agents must see goes on the board. | Step | Signal | |---|---| @@ -84,7 +132,31 @@ Agents don't call each other. The board is the mailbox. A project may also run a reconciliation job as a backstop: it reads the source of truth (for example the PRs) and posts any signal an agent missed. It is a backstop, not a replacement: agents still post their own signals. -## 5. Inheritance +## 6. Models and vendor mechanics + +**Models** + +- The dispatcher uses the cheapest capable model tier: it only reads the board and launches. +- A sub-agent uses the tier the task asks for. Projects define the tiers (for example light, standard and deep) and + map them to each vendor's models. +- A review uses at least the task's tier. +- Where a vendor has no tier mapping, the sub-agent uses that vendor's default model unless the launch prompt says + otherwise. + +**Launching a sub-agent.** Use the vendor's own mechanism and name it in the launch prompt or the project's page. +Every mechanism must give the sub-agent a fresh context and let the dispatcher wait for its report. + +| Vendor | Mechanism | +|---|---| +| Claude | Its sub-agent tool (Agent / Task) with a chosen model | +| Codex | `codex exec`: a fresh non-interactive process per job, with the brief as the prompt and `-m` for a model. `-o ` writes the final message to a file the dispatcher reads as the report. Codex also lists a `multi_agent` feature; check `codex features list` on the installed version before relying on it | +| Any other | A fresh non-interactive process or session per job | + +**If a vendor cannot launch sub-agents,** its agent falls back to one job per session with a clean context. The +human, or a script, launches the next session. The rest of this protocol still holds: one job, its actor, its board +transition, then stop. + +## 7. Inheritance - A project inherits this protocol. Its agent instructions link here rather than restate it. - A project may only set the parameters below and add rules of its own (its board commands, labels, quality gates @@ -100,6 +172,8 @@ posts any signal an agent missed. It is a backstop, not a replacement: agents st | Re-check count | How many empty checks before the agent stops | | Doer "gone" threshold | How long without activity before another agent may repair a doer's work | | REVISE round limit | How many REVISE rounds before the work goes to the owner | -| Job limit | The most jobs one agent session takes | -| Budget limit | The most one agent session may spend | +| Job limit | The most sub-agent jobs one run takes | +| Budget limit | The most one run may spend | | Cross-vendor review | Preferred or required | +| Dispatcher sub-agent model | The model tier for the dispatcher, and the mapping from task tier to each vendor's sub-agent model | +| Jobs per run, then full stop until a human says go | Whether the dispatcher stops completely at the job limit and resumes only when a human says "go" (starting another run of the same size), and the number of jobs that run takes | diff --git a/operating-model/decision-log.md b/operating-model/decision-log.md index 06ed887..7c4534c 100644 --- a/operating-model/decision-log.md +++ b/operating-model/decision-log.md @@ -38,3 +38,4 @@ Status is intentionally explicit: | 2026-09-28 | Confirmed | Use `vim` as the default editor for long prompts. | Set `VISUAL=vim`, falling back to `EDITOR=vim` where needed; Codex uses `VISUAL` first. | | 2026-09-28 | Confirmed | Agents on a shared work board never go idle while work exists: finish reviews and repairs before starting a new task, and stop after a bounded number of empty re-checks. Projects inherit the protocol here and override only its parameters. | The owner asked that agents pick the next job instead of idling, with verification and repair ahead of brand-new work, and that projects inherit this protocol from here rather than keep a second copy. See `agent-work-loop.md`. | | 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. | From 75cf68399467bb0275c6b7e91ec26cc9ea877eaa Mon Sep 17 00:00:00 2001 From: Varun Katta Date: Mon, 28 Sep 2026 20:53:58 -0700 Subject: [PATCH 2/2] docs(operating-model): align priority rows with the fresh-sub-agent independence rule Co-Authored-By: Claude Opus 5.5 --- operating-model/agent-work-loop.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/operating-model/agent-work-loop.md b/operating-model/agent-work-loop.md index db70ec5..216aa0f 100644 --- a/operating-model/agent-work-loop.md +++ b/operating-model/agent-work-loop.md @@ -47,8 +47,8 @@ launched in this run: | Priority | Take | Condition | |---|---|---| | 1 | **Its own open repair**: a REVISE on work built in this run | Always first, so its own work doesn't wait | -| 2 | **A review that is waiting** | Work no sub-agent of this run reviewed or repaired. Prefer work built by another vendor | -| 3 | **A repair of another agent's work whose doer is gone** | "Gone" is the project's threshold. Never a repair of work this run reviewed | +| 2 | **A review that is waiting** | Any waiting review: the reviewing sub-agent is fresh and has its own actor. Prefer work built by another vendor | +| 3 | **A repair of another agent's work whose doer is gone** | "Gone" is the project's threshold. Work built in this run is priority 1, not this | | 4 | **A brand-new task** | Only when nothing above is eligible | Reviews and repairs come before new work because unfinished work is worth more once it is finished. A new task