@tonoid/agent-loop 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tonoid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,378 @@
+# agent-loop
+
+Runs autonomous coding agents against your repositories on a schedule,
+unattended, across several provider accounts, without exhausting any of them
+and without starving the humans who share those accounts.
+
+**agent-loop is built on [herdr](https://herdr.dev), and not incidentally.**
+herdr is where the workers live. This project never starts a process of its
+own: every worker is a herdr agent running in a herdr pane, and herdr is the
+only thing that can tell the loop whether that worker is still working, is
+blocked on a question, or is gone. Take herdr away and nothing here has
+anywhere to run. If you are looking for something that shells out to an agent
+binary and waits on an exit code, this is not it, and [the section
+below](#how-it-uses-herdr) is the fastest way to find that out.
+
+Built against **herdr 0.8.0, protocol 19**.
+
+## How it uses herdr
+
+A tick decides what ought to be running. Everything it then does to a worker,
+it does through the `herdr` CLI:
+
+| What the loop needs | herdr call |
+|---|---|
+| the workspace a job's tabs belong in | `workspace list`, matched on the `herdrWorkspace` label |
+| a worker | `tab create --workspace <id> --cwd <worktree> --label <job>-<key> --env <VAR>=<account config dir> --no-focus` |
+| the pane that tab just opened | `pane list`, matched on cwd |
+| the agent itself | `agent start <name> --kind <provider> --pane <id> -- <account startArgs>` |
+| the brief delivered | `agent prompt <pane> <brief> --wait --until working` |
+| whether they are alive | `agent list` for the whole fleet, `agent get <pane>` for one |
+| why it is stuck | `agent read <pane> --source recent-unwrapped --lines <n>` |
+| a composer holding unsent text | `agent send-keys <pane> Enter` |
+| the worker gone | `tab close <tab>` |
+| you, when a worker is blocked | `notification show <title> --body <text>` |
+| a supported herdr | `api schema --json` for the protocol number |
+
+Three consequences worth knowing before you read the code, because each one
+shaped it:
+
+**`agent_status` is the whole lifecycle.** A worker has no exit code and no pid
+here. `working`, `blocked` and `idle` are the only states the loop can observe,
+and every decision the monitor makes is built from one of those, the pane still
+being listed, and the worktree still being on disk. `blocked` notifies you once
+and then escalates on a timer; an agent that has vanished while its pane is
+still up is restarted exactly once, and one whose pane went with it has failed.
+A status herdr does not recognise becomes `missing`, which deliberately does
+nothing at all: holding cannot kill a live agent or tombstone an item, so a
+herdr that adds or renames a state stalls this loop rather than damaging
+anything with it.
+
+**`tab create` is the only verb that accepts `--env`.** That single flag is the
+entire channel by which the router's account choice reaches a worker, which is
+why the account is decided before the tab exists and can never be changed
+after. It is also why `configEnv` is an account-level setting: `CLAUDE_CONFIG_DIR`
+for Claude Code, `CODEX_HOME` for Codex.
+
+**herdr ids are not stable.** A pane id changes between rounds of the same
+logical worker, and a workspace id lasts until the herdr server restarts and
+then names somebody else's workspace. Nothing here caches one: the workspace is
+looked up by label and the pane by cwd, on every single spawn.
+
+Six of those verbs are reads: `workspace list`, `pane list`, `agent list`,
+`agent get`, `agent read` and `api schema`. Every other one is a write. Without
+`--live` the gate in `src/adapters/run.ts` permits exactly those six and refuses
+the rest by name, so a dry tick can survey your entire fleet and is incapable of
+touching it.
+
+`agent-loop check` compares your herdr's protocol number against the one this
+was tested on and warns when they differ. It never refuses to run on a
+mismatch: a newer herdr is usually fine, and a loop that stops dead at 2am
+because a dependency was upgraded is worse than one that says so and carries on.
+
+## Prerequisites
+
+- [herdr](https://herdr.dev) (`curl -fsSL https://herdr.dev/install.sh | sh`),
+  running, with a workspace whose label matches each `herdrWorkspace` you
+  configure. This is the hard dependency: see above. The npm package named
+  `herdr` is an unrelated placeholder.
+- `gh`, authenticated, against a GitHub repository with issues and labels
+  enabled. Labels are the state machine. There is no GitLab support.
+- `bun`, `git`, `cron`, and `flock`.
+- Each account's agent must already trust the directory worktrees are created
+  in. A fresh worktree is a path the agent has never seen, so it opens on a
+  trust prompt, reports itself idle while it waits there, and swallows the brief
+  it is then sent. Trusting `worktreeBase` once per account config directory
+  covers every worktree made under it. For Claude Code that is
+  `projects["<worktreeBase>"].hasTrustDialogAccepted` in
+  `$CLAUDE_CONFIG_DIR/.claude.json`; trust is inherited by descendants, so the
+  base is enough and each new worktree needs nothing. `agent-loop check`
+  warns for any account missing it.
+
+Two things to know before running it. Workers start with permission prompts
+disabled, which is what makes them autonomous and also means they run
+unsandboxed as you. And all state lives under `~/.agent-loop/`, whatever else
+is on the box.
+
+## Install
+
+```
+npm i -g @tonoid/agent-loop
+agent-loop kinds     # prints the job kinds: enough to prove the install
+```
+
+npm is the delivery mechanism, not the runtime. The package ships its
+TypeScript sources rather than a bundle, nothing is compiled at install time,
+and there are no runtime dependencies to fetch: the tarball is the `src/` tree,
+the `briefs/` the engine reads at spawn time, and the docs. The CLI's shebang is
+`#!/usr/bin/env bun`, so **bun has to be on the PATH of whoever runs it**. On a
+box without bun the install succeeds and the first run fails with
+`env: bun: No such file or directory`.
+
+From a checkout instead, which is what you want if you are editing it:
+
+```
+bun install
+bun link          # puts agent-loop in ~/.bun/bin
+agent-loop kinds
+```
+
+## Configure
+
+One machine file, never versioned:
+
+```yaml
+# ~/.agent-loop/config.yml
+accounts:
+  - { id: loop, provider: claude, configDir: ~/.claude-loop, reserve: 0 }
+  - { id: main, provider: claude, configDir: ~/.claude, reserve: 40 }
+
+workspaces:
+  - ~/projects/acme/loops
+```
+
+Four knobs govern how much of an account the loop is willing to spend.
+
+| Field | What it does |
+|---|---|
+| `reserve` | The share of the account's quota the loop will never claim, so a human sharing it always has that much left. |
+| `reservePerWeekday` | Holds back that much for each weekday the human still has before the window resets, so the reserve shrinks as the week burns down. The flat `reserve` is the floor under it. |
+| `weekendWeight` | What an hour of a weekend is worth against an hour of a weekday, `0.25` by default, so a weekend keeps a small assignment instead of none. |
+| `soleConsumer` | That loop workers are the only thing spending this account, so its usage deltas measure a worker rather than a person. |
+
+`reservePerWeekday` is integrated by the hour rather than counted in whole days,
+so it eases off through the day instead of dropping at midnight, and a weekly
+quota resetting on Sunday is one working day away rather than three. Keep the
+flat `reserve` for short windows: five hours is a twelfth of a weekday, so the
+curve prices a session window at almost nothing.
+
+Set `soleConsumer` only where it is true. The worker rate is an EWMA per
+provider, not per account, so a single sample taken while a human was typing
+teaches every account that a worker costs several times what it does, and the
+whole box starves at once. A zero `reserve` does not imply it: that says nothing
+is held back, not that nobody else is spending.
+
+One folder per service, versioned with the service it drives. Name it for what
+it holds rather than for this engine: `agent-loop` is the thing that runs, and
+a folder of that name sitting beside a service's repositories reads like a
+checkout of it.
+
+```
+~/projects/acme/loops/
+  workspace.yml
+  build/    job.yml  brief.md
+  review/   job.yml  brief.md
+```
+
+```yaml
+# workspace.yml
+name: acme
+herdrWorkspace: acme      # the LABEL of a herdr workspace that must exist
+worktreeBase: ..          # worktrees land beside the repos
+repos:
+  web: ../web
+naming:
+  labels: { claim: agent-wip, failed: agent-failed, park: needs-human, priority: [bug] }
+  mergeMethod: squash
+```
+
+```yaml
+# build/job.yml
+kind: builder             # see `agent-loop kinds`
+repo: web
+slots: 1
+order: 20                 # reviewers before builders
+model: sonnet             # optional; the agent's own alias or full model id
+brief: { extends: default/build, append: ./brief.md }
+options:
+  base: origin/develop
+```
+
+`model` belongs to the job, not the account, because the router picks the
+account by headroom: the same job has to run the same model wherever it lands.
+Spend it where an error is unrecoverable or unreviewed, and save it where
+something downstream checks the work.
+
+Three kinds ship. `agent-loop kinds` prints their options.
+
+```yaml
+# review/job.yml
+kind: reviewer
+repo: web
+slots: 2
+order: 10                 # reviewers before builders
+distinctFrom: true        # not the account that built it
+brief: { extends: default/review, append: ./brief.md }
+options:
+  identity: closing-issue
+  rounds: 3
+  headRef: build/            # only branches this job's builder opens
+  filing: { queue: build, maxOpen: 40, perRound: 2, dedupeBy: path }
+```
+
+Set `headRef` on any reviewer whose repository also carries pull requests from
+people. Without it the reviewer discovers every open one, and the first thing it
+does to a candidate is claim it, so a human's branch ends up behind the claim
+label until somebody notices.
+
+```yaml
+# digest/job.yml
+kind: routine
+repo: web
+order: 5
+brief: { extends: default/routine, append: ./brief.md }
+options:
+  at: ["09:10", "21:10"]
+  days: [mon, tue, wed, thu, fri]  # optional; every day when unset
+  doneWhen: ~/reports/{{key}}.md   # the artifact that ends the occurrence
+```
+
+Give a routine a `doneWhen` whenever its run produces one. Without it the only
+signal a routine has is its worktree disappearing, and that waits for the next
+slot: a run that finished at 09:38 is nudged at 09:40 and failed at 09:42 for
+having succeeded.
+
+`filing` is backpressure. The budget is computed from the depth of the queue
+the reviewer files into, so it closes on its own when the builder falls behind
+and reopens when it catches up. The brief carries the budget to the worker, and
+the loop audits what was actually filed when the run is swept, logging
+`OVERFILED` with the numbers.
+
+A routine is due across a window, from its slot until the next one begins, so a
+slot missed to a reboot fires once on the first tick back inside its window and
+never fires stale. Backlog consolidation is a routine rather than engine code: point its `brief.append` at the clustering procedure
+you already use.
+
+Paths in these two files resolve against the file's own folder, and neither
+holds a secret, so the folder checks out on another box and works. The folder
+name is the job name, and it names the branches and worktrees that job owns.
+
+Check it before you schedule it:
+
+```
+agent-loop check
+```
+
+That resolves every repo path, verifies each `herdrWorkspace` label against the
+workspaces herdr actually has, and warns for any account that has not yet
+trusted the worktree base. All three are things that otherwise surface as a
+failure per due item, every two minutes, at four in the morning.
+
+## Run
+
+One cron line for the whole box. Workspaces arrive by discovery, so this line
+is installed once and never edited again:
+
+```cron
+*/2 * * * * PATH=/home/you/.bun/bin:/home/you/.local/bin:/usr/local/bin:/usr/bin:/bin flock -n ~/.agent-loop/tick.lock agent-loop tick >>~/.agent-loop/tick.log 2>&1 || echo "$(date -Is) tick did not run: lock held or command failed" >>~/.agent-loop/tick.log
+```
+
+`PATH` is set on the line because cron's own is short. `agent-loop` is a bun
+script, so its shebang needs `bun` on the path to run at all, and the loop then
+shells out to `herdr`, `gh` and `git`, which have to be found too. Point it at
+wherever `which bun` and `which herdr` say. The failure message is deliberately
+vague: `flock` exits 1 for a lock it could not take, and so does a command that
+was simply broken, so a line claiming "previous still running" would hide the
+second case.
+
+Without `--live`, a tick performs every read and logs every intended write
+without making one: the gate in `src/adapters/run.ts` refuses any command
+outside the read allowlist. Run it that way for a week first.
+
+Two minutes is a starting point, not a law. Keep the interval at four times
+the p95 of the `TICK total <ms>` lines in your log or more. That line is the
+whole process, every discovered workspace included, which is what the interval
+has to cover. The `TICK <workspace> <ms>` line above it is one workspace's
+share, useful for finding which service is slow and wrong to size the
+interval against.
+
+Moving existing cron-driven pipelines onto this loop has an order that keeps
+every step reversible: `docs/cutover.md`.
+
+## Workers
+
+A worker starts in the account's own config directory, so it inherits whatever
+lives there, including hooks written for a human at a keyboard. Those fire on
+every session start, every turn end and every session exit, which for an
+unattended fleet is only noise. Start workers with the user settings source
+excluded and the parts you still want passed back explicitly:
+
+```yaml
+startArgs:
+  - "--dangerously-skip-permissions"
+  - "--setting-sources"
+  - "project,local"
+  - "--settings"
+  - "/home/you/.agent-loop/worker-settings.json"
+```
+
+Excluding a source drops all of it, permission rules included, so
+`worker-settings.json` has to carry those back. Copy the `permissions` block
+from the account's own settings into it and leave the hooks behind.
+
+That leaves one signal. When a worker blocks on a question nobody is going to
+answer, the loop sends a `herdr` notification, once per item rather than once
+per tick, and only under `--live`. It is the only thing the loop will interrupt
+you for, which is what makes it worth reading.
+
+## Commands
+
+```
+agent-loop tick [--workspace <name>] [--live]   one pass over every workspace
+agent-loop check [<workspace folder>]           validate config and jobs
+agent-loop kinds [<kind>] [--json]              a kind's options, or its schema
+agent-loop status [--workspace <name>]          accounts, quota, paused jobs
+agent-loop pause|resume [<job>] --workspace <n> stop spawning; sweep and
+                                                monitor keep running
+agent-loop adopt <job> [<key>] --workspace <n>  record a spawned mark without
+                                                spawning: the cutover's import
+agent-loop adopt --list --workspace <n>         this workspace's marks
+```
+
+`agent-loop check .` needs no `~/.agent-loop/config.yml`, so a service
+repository can run it in its own CI and catch a broken `job.yml` at the commit
+that broke it.
+
+## Reading the source
+
+Comments cite a numbered design document (`spec 3.5`, `spec 7`, `spec 4.2`).
+That document is the specification this was written against and is not carried
+in the repository. The numbers are stable and nothing in the code needs it: the
+README and `agent-loop kinds` are the current reference, and every rule the
+spec states is enforced by a test that names it.
+
+## Maintenance
+
+```
+bun test            # the whole suite: no network, no gh, no herdr
+bun run typecheck
+bun run test:live   # opts in to a real herdr, which has to be running
+```
+
+The suite is hermetic apart from `test:live`, which is skipped unless
+`AGENT_LOOP_LIVE_HERDR=1`. CI runs the typecheck and the suite on every push and
+pull request.
+
+Releases are driven by the commit messages. Conventional commits landing on
+`main` are read by [release-please](https://github.com/googleapis/release-please),
+which keeps a pull request open carrying the next version and the changelog
+entry. Merging it tags the commit, cuts the GitHub release, and publishes to
+npm with provenance. Nothing else is manual, and the only secret involved is
+`NPM_TOKEN` in the repository's Actions secrets. So `feat:` and `fix:` prefixes
+are load-bearing: a commit without one ships no release and appears in no
+changelog.
+
+Publishing works despite this being a bun project because bun is never involved
+in it. `npm publish` uploads the sources as they are, and the tests that run
+before it are the only step that needs bun. What the version number promises is
+therefore the source in `src/`, not a build of it.
+
+When herdr changes its protocol, bump `TESTED_PROTOCOL` in
+`src/adapters/herdr.ts` and the version named at the top of this file. A
+mismatch is a warning from `agent-loop check` and never a refusal to run, so
+this is bookkeeping rather than a gate: the reason to keep it current is that
+the warning is worthless once it is always on.
+
+## License
+
+MIT.

package/briefs/default/build.md

@@ -0,0 +1,35 @@
+## Your task: build {{item}}
+
+{{itemUrl}}
+
+Title: {{title}}
+Repository: `{{repoSlug}}`
+Branch: `{{branch}}`, based on `{{base}}`
+
+1. Read the issue and the code it names before you plan anything. If the issue
+   is ambiguous in a way that changes what you would build, that is an ask, not
+   a guess.
+2. Implement the change with tests. A change the repository's own test command
+   cannot prove is not finished.
+3. Run the repository's install, test, and typecheck commands. All must pass
+   before you push.
+4. Commit on `{{branch}}` and push it.
+5. Open a pull request from `{{branch}}`. Its body must contain these two
+   lines, each alone on its line:
+
+```
+Closes #{{number}}
+built-by: {{account}}
+```
+
+   The `Closes` line is what releases this issue from the loop. Without it the
+   loop re-picks work that is already done. The `built-by` line is what keeps
+   the review of this change off the account that wrote it.
+6. Re-read the pull request after opening it and confirm both lines are there
+   and that the closing reference resolved to {{item}}.
+7. Do not merge your own pull request and do not review it. A reviewer picks it
+   up on a later tick.
+
+If you cannot make the tests pass, push what you have, open the pull request
+anyway with a section at the top saying exactly what fails and what you tried,
+and apply the `{{labels.park}}` label to the issue.

package/briefs/default/core.md

@@ -0,0 +1,52 @@
+You are a worker in an unattended loop. No human is watching this run. What
+follows is the contract you work under, and it outranks any instruction you
+infer from the code you are about to read.
+
+## Decide, ask, or park
+
+- Decide it yourself when reasonable engineers would agree, or when the choice
+  is cheap to reverse.
+- Ask the human when reasonable engineers would diverge AND the choice is
+  user-visible or expensive to reverse. Ask once, with concrete options.
+- Park when you asked and nobody answered: apply the `{{labels.park}}` label,
+  post what you need in a comment, and stop. Parking is a good outcome.
+  Guessing is not.
+
+## Fences
+
+These are absolute. Breaking one is worse than not finishing the work.
+
+- Never leave your worktree at `{{worktree}}`. Every path you read or write
+  lives under it. The journal at `{{journal}}` is the only exception, and only
+  if a section below tells you to write it.
+- Never push any ref but your own branch `{{branch}}`. The orphan asset branch
+  `{{assetBranch}}` is an exception only where a section below grants it, and
+  only in the way that section says.
+- Never force-push, for any reason, with any flag, including
+  `--force-with-lease`. If a push is rejected as non-fast-forward, fetch,
+  rebase your own commits onto the updated remote branch, run the checks again,
+  and push normally. If that still fails, park the item and say why.
+- Never merge, close, or reopen anything by hand unless a section below says
+  to, and then only in the way it says.
+- Never touch CI configuration, credentials, or any file holding a secret.
+- Never rewrite history that is already pushed, and never `git checkout` a
+  branch other than your own.
+
+## Install first
+
+Install the repository's dependencies before you run anything else. A run that
+skips the install fails at its last step instead of its first, and the last
+step is where the evidence is thrown away.
+
+## Size
+
+If the change grows past roughly 400 changed lines or 8 files, stop and split
+it. Land the smallest coherent piece under this item and record the rest the
+way the section below tells you to record follow-ups.
+
+## Finish or say so
+
+A run ends in exactly one of three states: the work is done and the section
+below has been followed to the letter, the item is parked with a comment
+saying what is needed, or you stopped and said plainly what is unfinished.
+Never report success you cannot point at.

package/briefs/default/journal.optional.md

@@ -0,0 +1,7 @@
+### Journal
+
+When you finish, append one line to `{{journal}}`, and nothing else in that
+file. This is the single documented exception to the worktree fence.
+
+Format: an ISO timestamp, this item's key `{{key}}`, and one sentence saying
+what happened. No prose beyond the sentence, no code, no diffs.

package/briefs/default/review.md

@@ -0,0 +1,65 @@
+## Your task: review {{item}}
+
+{{itemUrl}}
+
+Title: {{title}}
+Repository: `{{repoSlug}}`
+You are reviewing the pull request whose head is `{{headRef}}`. Your worktree
+is checked out on `{{branch}}` from `{{base}}`. This is round {{attempt}} of at
+most {{attemptCap}}.
+
+Your branch exists so you can build and run the code. It is never pushed.
+
+### Review
+
+1. Read the diff against its base, then read the code around it. Judge whether
+   the change does what its issue asked, whether it is correct, and whether it
+   is tested.
+2. Run the repository's install, test, and typecheck commands. A review that
+   did not run the code is an opinion.
+3. Post one round comment. Start it with the exact prefix `{{commentPrefix}}`,
+   which is what the loop counts rounds by, then your findings in severity
+   order, each with a file and line.
+
+### What to file, and what not to
+
+You have a filing budget of {{filingBudget}} this round. There are
+{{openQueue}} items already open in the queue this pull request feeds. The
+budget is computed from that depth: when the queue is deep the budget is zero,
+and that is the system working, not a limit to route around.
+
+1. An out-of-scope finding goes in your round comment, not in the tracker. Code
+   that was already there and is merely visible from this diff is not this pull
+   request's debt. Promote such a finding to a tracker item only when it is
+   clearly worse than what is already open, and only within your budget.
+2. File per defect cluster, never per finding. One item per file or component,
+   carrying a checklist of the findings in it. Eight observations about one
+   broken banner are one item with eight boxes.
+3. Dedupe on the cited {{dedupeBy}}, not on the title. Before filing, search
+   open items for the {{dedupeBy}} your finding cites. If an open item already
+   cites that {{dedupeBy}}, append a checklist line to it instead of filing a
+   new one. Titles will not match; the {{dedupeBy}} does.
+
+If your budget is zero, everything goes in the round comment. Nothing is filed.
+
+### Verdict
+
+If the change is not ready: post the round comment, then remove the
+`{{labels.claim}}` label and stop. Do not merge. The builder gets the next
+round.
+
+If the change is ready, do these in this order and do not reorder them:
+
+1. File the follow-ups you are allowed to file, now. The loop destroys this
+   worktree as soon as the pull request merges, so anything not filed before
+   the merge is lost.
+2. Verify the closing reference: the body must close the issue this work came
+   from. Without it the builder re-picks an issue that is already done.
+3. Re-read the head commit SHA and confirm it is the SHA you reviewed. If new
+   commits landed while you worked, review them or start a new round. Never
+   merge a head you have not read.
+4. {{mergeInstruction}}
+5. Post the round comment recording what you did, then remove the
+   `{{labels.claim}}` label, in that order and never earlier. The claim label is
+   what stops the next tick re-picking this item and cleaning your worktree out
+   from under you mid-write.

package/briefs/default/routine.md

@@ -0,0 +1,18 @@
+## Your task: a scheduled run
+
+Occurrence: `{{key}}`
+Repository: `{{repoSlug}}`
+Branch: `{{branch}}`, based on `{{base}}`
+Worktree: `{{worktree}}`
+
+This run has no tracker item behind it. Nothing labels it, nothing closes it,
+and the loop knows it happened only from its own mark and from whatever you
+leave behind. So leave something behind: the work you did, or a plain statement
+that there was nothing to do.
+
+The task itself is described below. Run it once, for this occurrence only. If
+the same task already ran for this occurrence, stop and say so rather than
+running it twice.
+
+If the task opens a pull request, open it from `{{branch}}` and do not merge it
+yourself.

package/briefs/default/screenshots.optional.md

@@ -0,0 +1,10 @@
+### Screenshots
+
+When a finding is visual, capture it. Commit the image to the orphan branch
+`{{assetBranch}}`, then link it in your comment as a plain link, never an
+embed. Embedded images make a tracker item unreadable in a terminal and in a
+digest, and the loop reads both.
+
+This section is the documented exception to the push fence: `{{assetBranch}}`
+is the one ref other than your own branch you may push, and only to add an
+image. Never push it with force, and never commit an image anywhere else.

package/briefs/default/subagents.optional.md

@@ -0,0 +1,7 @@
+### Parallel review
+
+You may dispatch subagents to read separate parts of this change in parallel,
+one dimension each (correctness, tests, interface, performance). Give each one
+the diff and the dimension, and require it to answer with findings that name a
+file and a line. You remain responsible for the verdict: a finding you cannot
+confirm in the code yourself does not go in the round comment.