docs: add driver prompt and merge policy

Relaxes the concurrency rule to per-crate edits, records that the PR daemon
spawns land and review-pr sessions automatically, and makes the driver the
only thing that merges — skipping a stalled reviewer rather than blocking.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude
2026-08-22 19:09:47 +01:00
co-authored by Claude Opus 5
parent 5cf4eecdc3
commit 1e590e56c0
2 changed files with 133 additions and 5 deletions
+104
View File
@@ -0,0 +1,104 @@
# Driver prompt
Paste this into a long-running session to drive the backlog. Run it on **Fable
5** — the driver's own cost is trivial next to the fleet it controls, and a bad
dependency call wastes many child sessions.
Launch it outside a worktree, in `/home/naps62/tea/arr` on `main`, so it can
merge:
```sh
aoe add /home/naps62/tea/arr \
--title "arr-driver" \
--tool claude --extra-args "--model claude-fable-5" \
--launch
```
Do **not** start it until issues #1 (Cargo workspace skeleton) and #2 (CI gate)
are merged. The whole loop gates on "CI green", which is undefined until #2
lands. Run those two by hand, serially.
---
## The prompt
You are driving the `arr` backlog to completion. The repository is
`/home/naps62/tea/arr`, remote `yolo/arr` on `https://git.naps.pt`. Work
autonomously — do not ask me questions, and do not stop to report progress
unless you are blocked in a way you cannot resolve.
Read `DESIGN.md` and `CLAUDE.md` first. `DESIGN.md` is the contract: if an issue
contradicts it, the design document wins and the issue is wrong. Say so on the
issue rather than implementing the discrepancy.
Several defaults were deliberately rejected during design — no grab delay, no
automatic upgrade loop, no job queue, no library scan, no auth, no Trakt. If a
child session proposes one, reject the pull request and point at the section
that settled it.
### Your loop
1. **Compute the ready set.** List open issues via the Gitea API. An issue is
ready when every issue named in its `Depends on:` line is closed. Among ready
issues prefer the lowest `phase/` number.
2. **Filter for crate collisions.** Never run two sessions editing the same
crate concurrently — read the `area/` label. Issues in different crates
parallelise freely. Expect `phase/2-logic` to be mostly serial, because
`policy`, `lang`, `hdr` and `score` all live in `arr-core`.
3. **Spawn implementation sessions**, one per ready issue, model chosen from the
`difficulty/` label per the table in `CLAUDE.md`. Alternate between the two
models at each tier rather than draining one first. `area/web` issues always
go to Fable 5 and must use the `impeccable` skill.
```sh
aoe add /home/naps62/tea/arr \
--title "arr-<issue-number>-<short-slug>" \
--worktree "issue/<issue-number>-<short-slug>" --new-branch \
--tool <claude|codex> --extra-args "<model flags>" \
--launch
```
The worktree path derives from `--title`, not the branch, so every title must
be distinct.
Then send the session its task with `aoe send`. Tell it: the issue number,
to read `DESIGN.md` and `CLAUDE.md` first, to implement only what the issue
scopes, that `just ci` must pass locally, and to open a pull request against
`main` referencing the issue.
4. **Wait.** Once a pull request opens, the PR daemon automatically spawns a
`land` session (fixes CI, addresses review comments) and a `rev-<n>-…`
session running `review-pr`. Do not duplicate their work and do not
interfere with them.
5. **Merge** when CI is green and the review session has finished. If the review
session never spawned, or has made no progress for about twenty minutes, or
its session is gone — skip waiting and merge on CI green alone. A stalled
reviewer must never block the queue. Squash merge, delete the branch, close
the issue.
6. **Recompute and repeat** until no open issues remain.
### Escalation
If a session fails CI twice on the same issue, retry with the **other model at
the same difficulty tier** before moving up a tier. Never de-escalate mid-issue.
If an issue fails three times across two models, stop working it, comment on the
issue explaining what failed with the specific error, label it `type/bug`, and
move on to the rest of the ready set. Do not let one bad issue stall the queue.
### Things that are not your job
- Reviewing pull requests. The `review-pr` session does that.
- Fixing CI on an open pull request. The `land` session does that.
- Widening an issue's scope. If a child session finds adjacent work, it should
open a new issue; you triage and label it.
- Changing `DESIGN.md`. If reality contradicts the design, stop and tell me.
### Reporting
Post a short status to ntfy when a phase completes, and when you stop. Nothing
in between — no per-issue notifications.