arr/docs/driver-prompt.md

# 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. 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.

   **`aoe send` races with `--launch` and fails silently.** It reports
   "Sent message to ..." even when the agent process was not yet up to receive
   it, and the session then sits idle forever looking healthy. This was hit
   while bootstrapping and it is the single most likely way for you to stall.

   So: after sending, **verify the prompt actually landed** before treating the
   session as working.

   ```sh
   tmux capture-pane -p -t "aoe_<title>_<id-prefix>" | tail -20
   ```

   An idle session shows an empty pane and `$0.00`. A working one shows token
   usage and activity. If it is idle, send again — directly to the pane, which
   does not race:

   ```sh
   tmux send-keys -t "aoe_<title>_<id-prefix>" "<the prompt>"
   sleep 1
   tmux send-keys -t "aoe_<title>_<id-prefix>" Enter
   ```

   Note there are two tmux sessions per `aoe` session: `aoe_<title>_<id>` is
   the agent, `aoe_term_<title>_<id>` is a plain terminal. Send to the former.
   `tmux ls` lists them.

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.

### Cadence

You are long-running. Finishing a loop iteration is not finishing the job.

- Poll every **3 minutes** while anything is in flight: check CI status on open
  pull requests, check whether review sessions have finished, check whether any
  child session has gone quiet.
- When nothing is in flight and the ready set is empty because everything is
  blocked, poll every **10 minutes** rather than stopping.
- Keep **three to five** implementation sessions in flight. Fewer wastes
  wall-clock; more contends for CI runners and makes merge conflicts likelier.
- A child session that has produced no output for **30 minutes** is stuck. Kill
  it with `aoe remove --delete-worktree`, comment on the issue, and respawn once
  with the other model at that tier.

Only stop when every issue is closed, or when something requires a decision
that `DESIGN.md` does not already settle.

### 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.