diff --git a/CLAUDE.md b/CLAUDE.md index 0fd8eb3..e93550c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -126,8 +126,30 @@ alone. The loop: 2. Of what remains, take the lowest phase number first, then whatever parallelises within it. 3. Spawn one session per issue, selecting the model from `difficulty/`. -4. Wait for CI green on the pull request before marking the issue done and - recomputing the ready set. +4. Merge on green and reviewed, then recompute the ready set. + +### What happens after a pull request opens + +The **PR daemon** (`pr-daemon.service`, org-wide over `yolo/*`) picks up every +pull request automatically. It spawns two sessions per PR: + +- `-` running the `land` skill — the author side, fixing CI failures + and addressing review comments. +- `rev--` running `review-pr` — the reviewer side, posting findings to + Gitea. + +The driver does **not** babysit either of them, and does not re-implement what +they do. It waits. + +**Neither of them merges.** That is the driver's job, and the operator does not +review personally. + +Merge when CI is green and the review session has finished. If the review +session never spawned, or is stuck — no progress for ~20 minutes, or the +session is gone — **skip waiting and merge on CI green alone**. A stalled +reviewer must not block the queue. + +Squash merge, delete the branch, close the issue. ### Model selection @@ -205,9 +227,11 @@ mid-issue. ### What a driver must not do -- Do not run more than one session per crate at a time. Cargo workspace - builds contend, and two sessions editing the same crate produce conflicts - that cost more than the parallelism saved. +- Do not run two sessions **editing the same crate** at the same time. Each + session gets its own worktree, so the risk is merge conflicts rather than + build contention. In practice this means most of `phase/2-logic` is a chain, + since `policy`, `lang`, `hdr` and `score` all live in `arr-core`. Issues in + different crates parallelise freely. - Do not start `phase/4-movies` work until `phase/2-logic` is complete. The policy engine is the thing everything else calls. - Do not merge a pull request that skips tests to get CI green. Failing tests diff --git a/docs/driver-prompt.md b/docs/driver-prompt.md new file mode 100644 index 0000000..a07024b --- /dev/null +++ b/docs/driver-prompt.md @@ -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--" \ + --worktree "issue/-" --new-branch \ + --tool --extra-args "" \ + --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--…` + 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.