# Agent Fleet Operating Contracts

Copy-and-paste templates for the paperwork that makes an agent fleet run: the handoff, the
status report, the escalation, the daily digest, the project board, the decision log, and
the incident runbook.

Companion to `agent-fleet-playbook.md`. Version 1.0, 2026-08-21.
Source article: https://jwatte.com/blog/claude-code-agent-fleet-org-chart/

Every template here is plain text on purpose. Agents read and write text reliably. They do
not reliably maintain a database, and you do not want your fleet's memory living anywhere
you cannot open with a text editor at 2am.

---

## 1. The handoff contract

Used every time work crosses a layer: human to lead, lead to project lead, project lead to
IC. Seven fields, no exceptions. If a field is empty, the work is not ready.

```
CONTRACT <project>-<nnn>
TO             <role or agent name>
FROM           <role or agent name>
OPENED         <YYYY-MM-DD HH:MM tz>

OBJECTIVE      One sentence. What is different in the world when this is done.

DONE WHEN      1. <checkable condition>
               2. <checkable condition>
               3. <checkable condition>

CONSTRAINTS    Do not change: <files, interfaces, behaviour, tone>
               Must keep working: <the things a regression would break>
               Style: <the rules that apply to output>

CONTEXT        Read first: <path>, <path>
               Related prior work: <log line ids or contract ids>
               Known traps: <the two or three things that have bitten before>

ARTIFACT       <exact path or output location>
               Format: <diff, report, file, board update>

ESCALATE IF    - <condition> -> L2
               - <condition> -> L3

BUDGET         Tokens: <ceiling>   Wall clock: <ceiling>   May start: <0 or N> agents
```

### Rules

* The DONE WHEN list is written by the sender, never by the receiver. An agent that writes
  its own success criteria will meet them.
* Every DONE WHEN item must be checkable by someone who did not do the work.
* "Known traps" is the highest-value field over time. Every incident adds one line to some
  future contract's traps list. A fleet that does not accumulate traps repeats them.
* If the receiver cannot restate the objective in its own words, the contract is unclear and
  goes back. That costs five minutes. Cleanup costs a day.

---

## 2. The status report

Returned by an IC when a contract closes. Also the shape a project lead uses upward.

```
CONTRACT <id>            STATUS: DONE | PARTIAL | BLOCKED | ABANDONED

WHAT CHANGED
  <one line per real change, with the path>

DONE WHEN
  1. <condition> ...... MET | NOT MET | NOT CHECKED
  2. <condition> ...... MET | NOT MET | NOT CHECKED

EVIDENCE
  <command run> -> <exact result, not a summary>
  <artifact path> -> <size, count, or checksum>

NOT DONE
  <anything in the contract that was not completed, and why>

ASSUMPTIONS MADE
  <every assumption made in place of asking, flagged>

SPEND
  Tokens: <n>   Wall clock: <n>   Agents started: <n>

TRAPS FOUND
  <anything a future contract in this area should be warned about>
```

### Rules

* **NOT CHECKED is a legal answer and a required one.** An agent that marks a condition MET
  without running the check has told you nothing. The three-state field exists so that
  honesty is cheaper than bluffing.
* **EVIDENCE holds output, not adjectives.** "Tests pass" is an adjective. "47 passed, 0
  failed, 0 skipped" is evidence.
* **PARTIAL is not a failure state.** Presenting partial work as DONE is the failure state.
* Empty ASSUMPTIONS on a non-trivial contract is usually a sign the agent did not notice it
  was assuming.

---

## 3. The escalation

Sent upward when the escalation contract triggers. One page, always with a recommendation.

```
ESCALATION <id>          LEVEL: L2 | L3
FROM         <role>
CONTRACT     <id>
OPENED       <YYYY-MM-DD HH:MM tz>

DECISION NEEDED
  <the actual question, in one sentence, phrased as a choice>

WHY IT IS NOT MINE
  <which escalation trigger fired, quoted from the charter>

OPTIONS
  A. <option>   Cost: <effort/tokens/risk>   Reversible: yes/no
  B. <option>   Cost: <...>                  Reversible: yes/no

RECOMMENDATION
  <A or B>, because <one or two sentences>

DEFAULT IF NO REPLY
  I will <do X> at <time>. This is reversible / not reversible.

WHAT IS BLOCKED MEANWHILE
  <what stops, what continues>
```

### Rules

* No recommendation, no escalation. Send it back.
* The DEFAULT clause is what keeps a human from becoming a blocking queue. If the default is
  "nothing happens", say that. If the default is unsafe, the level is L3 and there is no
  default.
* An escalation with three or more options is usually an unfinished analysis. Narrow it.

---

## 4. The project board

One per project. This file is the project. If it disagrees with an agent's memory, the file
wins.

```
# PROJECT <name>
LEAD          <project lead role/agent>
UPDATED       <YYYY-MM-DD HH:MM tz>          <- if this is stale, nothing below is trusted
GOAL          <one sentence, the reason this project exists>
DONE WHEN     <the condition under which this project closes and the agents stand down>

## IN FLIGHT
| Contract | Owner | Opened | Expected | Status |
|---|---|---|---|---|
| p1-014 | ic-generalist-2 | 08-19 | 08-21 | running |

## BLOCKED
| Contract | Blocked on | Owner of unblock | Since |
|---|---|---|---|
| p1-011 | decision: pricing table format | human | 08-20 |

## NEXT THREE
1. <contract to open next, and why it is next>
2. ...
3. ...

## DONE THIS WEEK
- <contract id> <one line> <artifact path>

## TRAPS
- <thing that has bitten this project before, and the rule that prevents it>

## OPEN QUESTIONS
- <question> (asked <date>, owner <role>)
```

### Rules

* **UPDATED is load-bearing.** A board with an old timestamp is the single clearest signal
  that a project has silently stalled. Make the digest check it.
* NEXT THREE, not NEXT TWENTY. A backlog belongs somewhere else. The board holds only what
  the next work is.
* TRAPS is append-mostly. Deleting a trap requires a reason in the log.
* Anything in BLOCKED for more than two days is an escalation, whether or not anyone noticed.

---

## 5. The decision log

Append-only. One line per decision. This is what a fresh agent reads to understand why the
project looks the way it does.

```
2026-08-19 14:02  p1-009  ic-specialist-1  DECIDED  Used the existing table parser rather
                  than a new one. Reason: the new one would duplicate 200 lines and the
                  existing one already handles the two edge cases we hit. Reversible.
2026-08-19 16:40  p1-011  project-lead-1   ESCALATED L3  Pricing table format. Two valid
                  layouts, the choice is a taste call the owner should make.
2026-08-20 09:15  p1-011  human            DECIDED  Layout B. Reason: matches the existing
                  corpus. Not revisiting.
```

### Rules

* One line per decision, including the reason. A decision without a reason will be re-litigated.
* Log reversals too, with the new reason. A log that only records decisions that stuck is a
  log that teaches nothing.
* Never rewrite a log line. Append a correction.
* The log is not a transcript. Do not put reasoning chains in it. One line.

---

## 6. The daily digest

Produced by the verification lead. This is the only thing the human is required to read.

```
DIGEST <YYYY-MM-DD>              projects: <n>   agents active: <n>

1. SHIPPED
   <project> <contract> <one line> -> <artifact path>

2. IN FLIGHT
   <project> <contract> <owner> running <n>h, expected <when>

3. BLOCKED
   <project> <contract> blocked on <what> since <when>, unblock owned by <who>

4. DECISIONS FOR YOU
   <escalation id> <one-line question> | recommend: <X> | default: <Y> at <time>

5. SPEND
   Today <n>. 7-day average <n>. Largest single project: <name> at <n>.

6. ANOMALIES
   - Boards not updated in 24h: <list>
   - Agents with no artifact in <n>h: <list>
   - Contracts running past 2x their estimate: <list>
   - Gates that have never failed: <list>
   - Retry counts above threshold: <list>
```

### Rules

* Section 6 is the reason the digest exists. Sections 1 to 5 are what you would have guessed.
  Section 6 is what you would have missed.
* "Gates that have never failed" belongs in the anomalies list permanently. A check that has
  passed 400 times and never once failed is either genuinely stable or completely broken, and
  the digest cannot tell which. You can, in about a minute, by breaking it on purpose.
* If the digest is longer than one screen, the fleet is reporting activity rather than
  outcomes. Cut it back.

---

## 7. The health check between leads

Run on an interval by each lead against the other. Deliberately dumb, because a clever health
check has more failure modes than the thing it monitors.

```
HEALTH CHECK <lead> -> <other lead>    at <timestamp>

1. Has the other lead produced any artifact in the last <interval>?
   <artifact path and time, or NONE>

2. Has every project board that lead owns been updated in the last 24h?
   <list of stale boards, or NONE>

3. Is there an unanswered message older than <interval>?
   <list, or NONE>

VERDICT   HEALTHY | DEGRADED | STALLED

IF STALLED
   - Post one line to the log naming what was stalled.
   - Restart the other lead with: its charter, the current boards, the last digest, and a
     one-paragraph summary of what it was doing when it stopped.
   - Do NOT take over its projects. Restart it and hand them back.
   - If it stalls twice in one day, stop restarting and escalate L3.
```

### Rules

* **The restart hands back context, it does not absorb the work.** A verification lead that
  starts doing execution work has quietly collapsed your two-lead design into a one-lead
  design with extra steps.
* **Twice in one day is an escalation, not a third restart.** Repeated restarts of the same
  agent on the same work is the loop that produces surprise bills.
* An artifact means a file written or a board updated. A message is not an artifact. This
  matters, because a stalled lead often keeps chatting.

---

## 8. The incident runbook

For when something has gone off the rails. This is the 5 percent of your attention that the
whole design is built to protect.

```
INCIDENT <id>   opened <timestamp>   severity: COST | CORRECTNESS | EXPOSURE

STEP 1  STOP
        Halt the affected agents. Not all of them, unless you do not yet know which.
        Record the time you stopped.

STEP 2  PRESERVE
        Do not clean up. Copy transcripts, boards and logs to a dated folder first.
        The evidence is the only way you learn the real cause.

STEP 3  BOUND IT
        What did it touch? Files, external calls, money, people.
        What is the worst case if everything it did was wrong?

STEP 4  ROLL BACK
        Revert to the last known-good state. Confirm the revert, do not assume it.

STEP 5  FIND THE GATE THAT SHOULD HAVE CAUGHT IT
        Every incident has one. Either it does not exist, or it exists and did not fire.
        Both are fixable. "The agent made a mistake" is not a root cause.

STEP 6  WRITE THE TRAP
        One line into the affected project's TRAPS section, and one line into the charter of
        whichever role should have prevented it.

STEP 7  RESTART SMALL
        Bring back one agent, not the fleet. Watch one full cycle before scaling back up.
```

### Severity definitions

* **COST**: spend anomaly, loop, runaway spawn. Stop first, diagnose second.
* **CORRECTNESS**: wrong work shipped or nearly shipped. Roll back, then find the gate.
* **EXPOSURE**: something left the building. A message sent, data written somewhere public,
  a credential used where it should not have been. This one is L3 the moment it is suspected,
  not when it is confirmed.

---

## 9. Charter review, weekly

Fifteen minutes, and the thing most fleets skip until their agents are following rules that
describe a world that no longer exists.

```
For each charter:
  [ ] Did I repeat any instruction to this role this week? -> add it to the charter
  [ ] Did this role escalate something it should have decided? -> widen "owns"
  [ ] Did this role decide something it should have escalated? -> widen "does not own"
  [ ] Does every path in "inputs" still exist?
  [ ] Is any rule in here describing a system we no longer run? -> delete it
  [ ] Is the charter longer than two screens? -> something in it is not load-bearing
```

The last check matters more than it looks. A charter that grows without pruning becomes a
document the agent reads less carefully, which is exactly the opposite of what you wanted
when you added the rule.

---

Companion files at https://jwatte.com/downloads/

* `agent-fleet-playbook.md`
* `agent-fleet-role-charters.md`
* `agent-fleet-safety-and-cost-controls.md`
* `agent-fleet-smb-quickstart.md`

Written by J.A. Watte. https://jwatte.com