Today's monitor and dispatcher rules (relayed by the monitor, Razie's words)
- **Asked by:** Razie
- **Changed:** monitor: own agent token always, spend-limit restarts with backoff, release-only orders, stopping a dispatcher always raised as blocked + PLEASE ANSWER, ai-putty.com hosts; dispatcher: auto-release gate before the suite, watch the dispatcher lane, a refused first status goes to the starter at once. Mirrored in d2spec d3-f-tokens, d3-f-board, d3-f-pipeline.
Dispatchers check for release requests on every cycle
- **Asked by:** Razie
- **Changed:** dispatcher section: check `release` and board messages every round, batch end and idle wake-up; an open release goes first; a person may ask again (item dropped, replaced) — stop, never half-merge. Mirrored in d2spec Skill:d3-f-pipeline#release.
- **Why:** a release asked while nothing was pickable sat unseen and left him stuck (P-934).
change · designer-40 (razie) · remint-14
*Reminted tokens* `{#remint}`: collect on `D2-Token-Remint` or `E_REMINTED`, then always tell the person to update the stored copy.
change · designer-40 (razie)
dispatcher: *A held item is never invisible*: holds become `waiting-input` / `waiting` with a note, never only the dispatcher's status line.
*Files you make* `{#cdn}` moved to Skill:d2-feature-cdn, one line left (P-851).
change · designer (razie)
added *A ticket's content goes in its doc*, *Reading and writing topics, drafts and items* (markdown reads and `?format=json`, raw-markdown topic writes, `E_CONTENT`) and *Files you make* `{#cdn}` (role folders, the `E_SCOPE` refusal and `askedBy`; error replies point here as `see`). Rebuilt on the published version 49: the earlier draft had been saved inside JSON wrappers and was unreadable.
change · designer (razie)
added *ESP (Mind Meld): show your person the page* under designer — how to read where the person is, take their tab to a page, ask to turn ESP on/off, and the etiquette (Razie: designers need mind-meld knowledge).
Changelog sections dropped from Skill:d2-agents, d2-maker, d2-monitor and d2-guardian (now in the history); d2-agents: names, dates and item numbers go in the history, not a changelog.
change · designer (razie)
designers send no broadcasts and no notices about items: the other roles feed off the pipeline; a message to a whole role only when the person asks for one by name.
change · designer (razie)
designers file self-contained tickets: quotes over links, a 15K reading budget, code pointers, a Decided-for-you list, black-box tests first, and never rewriting a taken or done item.
change · designer (razie)
new project structure, implementation move ([[d2spec.NewProjectStructure]]): coders write only their code base's topics (Proto1Impl, Proto1Code, Proto1Routes, Proto1Test on d2spec); each moved topic says at its top who updates it with what.
change · designer (razie)
no touches, no take (back to the designer; `nothing` is a declaration); the final integration and mongo tests on cloud5.
change · designer (razie)
the batch budget is eight again, how many is the dispatcher's call.
change · designer (razie)
coders keep only the code and *As built* and send the designer an As built list with suggested doc updates; the dispatcher decides how many coders, batching so no two batches share files.
read only the linked sections, a status before and after; dead after half an hour, declared, recovered and handed on by the dispatcher — flexible to 60 min for now, cases noted on d2spec P-673.
**every commit carries its item** (Razie's order 2026-09-30 via the monitor, confirmed in the designer-2 chat): a commit message names its `P-n`, **merge commits included**, and designer, skill and seed commits as much as a coder's build — 208 of 224 commits on `main` since 2026-09-28 already did, and the 16 without were mostly the skill and seed ones this line is for. Several items: name them all; no item at all: file one first. It is said in the shared part, where every role reads it, and the coder's *A branch of your own* points at it instead of repeating it. The *code* never carrying a `P-n` is the other half of that sentence and is a different rule, left where it was. The checkpoint reads the release's log once for both of its warnings: `main` moved, and a commit with no item on it.
**hand over only what's unfinished** (Razie approved, designer-2 chat): an agent that finishes cleanly posts `done` with a short summary and writes **no** handover item — the items, their notes, the commits and the checkpoint already carry what a successor needs — and one that stops part-way still writes one, listing only what is left. P-504 was the case: a handover describing work that had shipped sat `new` at the head of the coder queue until Razie dropped it. A dispatcher is the exception, because its handover is held between rounds rather than written at the end. And a handover picked up with nothing left in it is closed with one line rather than worked, which is the one time *don't mark a handover done* doesn't hold.
change · designer (razie)
**messages are read by `since`, never by count; a dispatcher reads them again right before starting an agent and says `stop received: …` in every report** (Razie, designer-2 chat, from the monitor's issue 6abe8814/6abe8a1c): a stop pushed below a `&limit=3` window by the dispatcher's own coder's notices went unseen for 71 minutes.
change · designer (razie)
**coders merge into `razwip`, never `main`**: a coder merges its branch into `razwip` and pushes its branch and `razwip`; only the release merges `razwip` into `main` — the dispatcher at its checkpoint when it's happy with `razwip`, or a coder nobody started, releasing itself. The coder section and the start prompt both said "merge into your local `main`", which is where the drift to pushing `main` began.
change · designer (razie)
**say where to look** (rule 8): a *Look at:* line of links right after an item's title when you finish it for a person.
**a question goes up the chain that started you**: ask your `startedBy`; only an agent nobody started waits on its person, and d2 lights their waiting-on-you flag for it. For a chat `idle` (a turn that ended) is not `waiting` (a question it needs answered), and a question ends with a `**** PLEASE ANSWER:` line.
change · designer (razie) · ^pipe-40, agents
**the batch budget is five small items, and only [[Spec#^pipe-40]] says so**: it was eight here and in Design 25 while the Spec and `Pipe.batch()` ran five, so the skill told a dispatcher one thing and the code suggested another. Five: a coder reached 70–75% of its context after one large item and five more, [[Spec#^pipe-40]] and the code already ran five, and a smaller batch checkpoints more often. The number is now stated in one place and pointed at from both of the two here, and the sentences that used to repeat it — *eight small items are each a file and a test*, *up to seven more smalls* — no longer name a number at all.
**mint your own token before anything else** (P-489, [[Spec#^agtok-3]]): the token you are given is your **role**'s; `POST /api/v2/tokens/agent {name}` answers one that is yours alone, for one run. Use that token and the `agent` name it gives you — a name is never given to two of your person's agents on a project, so it may not be the one you asked for. Nothing renews it: `401 E_AUTH "expired: mint a new one"` means mint again and carry on. Your secrets travel with the mint; your rate limits are the role token's, shared with your siblings. A dispatcher passes the **role** token to each agent it starts, because an agent token can't mint.
**a dispatcher with nothing running posts `idle` and says why; its last word is `done`**: one showed `working` with nothing to do — the only pickable coder item was reserved for Razie's own chat and the rest were paused — and then exited, its last word still `working`. So `working` is now **only** while an agent of yours actually runs; `idle` carries **one line of why**, and `paused` is not the only way work is withheld, so the reason comes from the open list minus the pickable one (an item waiting on one that isn't `done`, a handover reserved for a chat, a paused queue); and a dispatcher signs off `done`, or `handing-over`. `gone` is not its sign-off — that is what it posts for each agent *it* ends and what d2 sets for one it can't see (`quiet` first, P-510).
**who pushes `main`: the release belongs to the top of the coder's chain**: a coder **started by a dispatcher** pushes its branch and `razwip` and never `main` — its dispatcher merges and pushes `main` once, at its checkpoint — and a coder **nobody started** (a chat, a terminal session) releases itself, because it is the top of its own chain. `startedBy` decides it, the same word that decides who a question goes to. The rule is in the coder's *A branch of your own*, the *Start prompt*'s push line is that line word for word, and the dispatcher copies the prompt from the skill every time: the drift came from carrying `coder-N.prompt` forward, which told coder-56 to coder-65 to push `main` and one of them did. Since d2 can't refuse a git push, the checkpoint compares `origin/main` with the last release and warns on anything else there.
**coders in parallel** (Razie, designer chat, P-385, built P-390): a coder works on `razwip-<agent>` cut from main and folds it in itself — post `merging` (coloured and leased like `working`), merge, resolve your own conflicts, re-run the tests you touch, push `razwip`, `done` with `timing.merge`; unresolved at 20 minutes is `stuck` with both sides named. A coder told to take a free item uses `?free=1` and never forces. The dispatcher is told how many coders to run (*start dispatcher with N coders*, default 1), fills that many lanes from `?free=1` one item per agent, and holds its checkpoint while any coder is `merging` or `stuck`.
**an item that says nothing about what it touches collides with nothing** (Razie's ruling, designer-2 chat, P-405, built the same day). A take whose overlap can't be known succeeds and carries `mayCollide: [ids]` — the items in progress of its role it might overlap — and the coders resolve any real overlap when they merge. The coder reads them before merging; the dispatcher passes them to the agent it starts and keeps filling its lanes.
**the safe idiom for a key, given outright next to the prohibition** (P-422, and P-414 which asked the same): `${VAR:+set}` or `${#VAR}`, never `echo $VAR`, `env`, `set` or `printenv`, with the reason the probe *did my env file load?* is the moment it goes wrong. In the shared part (any agent loads credentials), in the dispatcher's *Keys* bullet, and in the *Start prompt*, so it no longer depends on a dispatcher remembering to paste it. A coder that had *never print a key* in its prompt echoed two token values while probing exactly that, and they had to be rotated. Same change: build a note or message in a file and send it with `--data-binary @file` — backticks in a double-quoted shell string are run by bash, which lost two notes' identifiers and, in one case, launched an agent early.
**the handover is held, not closed** (^pipe-58, P-426): take your role's handover at start, before you read it, hold it while you work, and put it down (`/putdown`) when you post `done` or `waiting` — never mark it done. A handover nobody holds sits `new` at the head of its role's Next up and reads like available work: a dispatcher's live handover was offered to a coder as its first pickable item and its suggested batch, for a whole session, and an earlier dispatcher lost a night to the same thing. Put down only what you hold — another agent's item answers `E_NOT_YOURS`, by name even when both agents share one token.
**a collision is a fact, not a refusal**: `take` always succeeds and its answer carries `collides: [ids]` beside `mayCollide: [ids]`; `E_COLLIDES` and `force` are gone, from the route and from MCP's `pipeline_take`. A collision is *possible*, not absolute, and between small modules usually cheap to merge, so the server states the facts and the dispatcher or a person decides. `?free=1` is unchanged, and is now plainly a filter rather than a fence.
**only files collide, not topics**: a `touches` entry that names a topic rather than a path is worth declaring and is never a collision, since d2 merges a topic's drafts itself and git does not merge for you. The open row gained `collideFiles`: which of its own files are the ones at stake.
**coders decide the small things, and say so**: a detail the design never mentioned is the coder's call, written down as a `Decided:` line — what, and why — in the commit and in the note that closes the item; anything that changes what a feature promises is still a design call. The dispatcher gathers them at each checkpoint into one `Decided in v<x>` item for the designer, which nothing waits on: it is the designer seeing in one place what a run's small choices have made true.
**the dispatcher batches to a budget**: up to eight small items, or a medium with its related smalls; large and important alone. It replaces *up to five in all*, in the shared part and in the dispatcher's section, which disagreed with what the dispatchers were already doing. Items that collide or may collide with each other go in the same batch when the budget allows, so one coder does both instead of two lanes merging.
**a summary on every item you file**: `summary` on `POST /api/v2/pipeline` and `PATCH /api/v2/pipeline/<id>` — one sentence, at most 200 characters, `""` to clear — shown under the title on the item's page, with the document's first sentence as the fallback when there is none.
**the dispatcher's policy table**: what fills a slot is decided from the row's flags, not fenced off by them — `no flags` and `small + small` take, `small + big` skips the round, `big + any` stays separate, `mayCollide` counts half, and with `one slot` everything is taken because one coder cannot collide with itself. Pick order is a preference, not a barrier: the walk goes past a skipped item and takes what doesn't collide with the one waiting, so a waiting important item drains instead of growing. A small item skipped twice is taken anyway; a big one waits as long as it collides. Each round's plan — taken and skipped, each with the line that decided it — is one board notice. The table lives in this skill, so tuning it is an edit.
**important only means pick me**: ★ is a place in the pick order and never a size, so an important item is picked first and then batches like any other item of its size — a small ★ goes with up to seven more smalls, and only a `large` item runs alone. The policy table's **big** is `large` alone: a small ★ colliding with a small item in flight is `small + small` (take), not `small + big`, and what drains behind a waiting item drains behind a large one. **Small ★ merge requests batch together at the head of a run**, in branch order. It replaces *a large item, and an important one, go alone*, whose cost was a whole run — start, full suite, deploy, checkpoint — for a one-file designer merge.
**dispatchers for designers** (Razie, designer chat, ^agents-31, P-441): a dispatcher may serve the designer role (`for: ["designer"]`, or `for: ["coder", "designer"]` on one dispatcher, since one dispatcher per role per person still holds) and run `designer-1..n` unattended. A designer **takes what it works**, and a review batch stays held by the designer that wrote it until every section is accepted, so the person's answers reach the agent that knows why; gone or handing over releases it to the role, and the next designer takes the batch up, whose sections carry their own context. **Follow-ups go home first:** `GET /api/v2/pipeline?pickable=1&pickFor=<agent>` puts the items that follow up that agent's own work — `links.follows` or `parent` naming an item it holds or last held, and work on a feature whose last item was its — ahead of everything but a released item and the handover. No new field: an item already names its last taker. `pickFor` is a **re-ordering and never a filter**, so a call that names no agent gets exactly the list it always got, and nothing is fenced off from anyone. Headless designers ask nothing in their output: proposals go in a review batch, small things in the digest, what truly blocks goes to the monitor's flag.
**alone items and waiting on itself** (^pipe-62, ^pipe-63): an `alone` item (a refactor, titled *Refactor:*) runs by itself on the coder side — finish what you hold, take nothing new while it is first or running, and d2 refuses those takes (`E_ALONE_NEXT`, `E_ALONE_BUSY`, `E_ALONE_RUNNING`); the dispatcher gives it one coder, alone. A held handover waits on itself (`waitingOn: "self"`): muted in the list, not stuck, picked up by id by the next session.
change · designer (razie) · ^agents-29
waiting says what for: `waitingFor` prompt (with `text`, `chat`) or item (Razie, designer chat, ^agents-29).
read your work and your board lean: `forRole`, `forName`, `status=open` and `fields` on the pipeline list (no `doc` in it), `since` (a message id too) and `limit` on the board.
a **dispatcher** section (P-220, with Razie): starting, keys from the vault, its states (idle, working, working "checkpoint", handing-over, always with context), the loop, the three session commands, `gone` for each agent when its run ends, a checkpoint after every agent run (merge, push, deploy, test, publish its drafts), the agents' start prompt here instead of on the CDN, one running design-call item per session, handover from 70%, coder and tester only.
skills follow the permissions: publishing a skill goes through `docs.skill` (default *person*), no hard rule of its own (Razie, designer chat, ^agents-2, P-270).
take under your own agent name (`name`), never your person's; handing over or going gone releases your items to your role, still in progress, first in its pickable list (Razie, designer chat, ^pipe-53, P-306).
*person* is your person themself only (E_SCOPE even with askedBy); *asks* passes at once with askedBy, else an approval; send askedBy whenever your person told you to.
split out of `Skill:diesel2`: the pipeline as a role, the board, approvals, handovers, the contract between the roles, and a section per role (designer, coder, tester).
dispatchers: `role: dispatcher` with `for: [roles]`, one per role (`E_EXISTS`), `startedBy` on the agents they start, shown `dispatching` while those agents work.
review with a comment: resolve an `acceptedIf` and finish with a note (it closes), or return it with questions; `reviewAgain` always comes back to review; ask up the chain with `/ask`.