Loop ready issue (herdr)
Optional maintainer aid for draining a personal GitHub readiness queue inside herdr: one Python driver tab plus serial worker tabs. It is not an llmwiki subcommand, is not shipped in the PyPI wheel, and does not change /implement-feature or /fix-bug unless you start the loop.
Opt-in only
Nothing in the delivery commands requires this loop. If you never run the driver, you keep picking issues and opening workers by hand exactly as today.
herdr required
The loop depends on herdr (driver tab, worker tabs, herdr agent lifecycle). Without herdr there is no supported path — use /implement-feature and /fix-bug manually. This spike does not add a shell-only or headless product mode.
Morning start
From a git checkout of this repository (repository root as cwd), open a dedicated herdr tab and run:
python3 scripts/loop_ready_issue_herdr.py --label <NAME>
Replace <NAME> with the readiness label you use on GitHub (docs and examples may say agent-ready; the running value is whatever you pass). Prerequisites: authenticated gh, herdr on PATH, and the repo checkout the workers should use.
Useful variants:
python3 scripts/loop_ready_issue_herdr.py --label <NAME> --dry-run
python3 scripts/loop_ready_issue_herdr.py --label <NAME> --once
python3 scripts/loop_ready_issue_herdr.py --label <NAME> --agent-kind claude
python3 scripts/loop_ready_issue_herdr.py --label <NAME> --repo OWNER/NAME
--dry-run prints the work-for-today summary, the planned eligible queue in driver order (important then issue number, blockers excluded) with in-progress tickets (an open issue-N herdr tab) listed first, oldest tab first, and marked (in progress, tab open), and next: (the ticket the driver would resume or start) without spawning herdr. It reads herdr tab list read-only; if herdr is missing or errors it prints in-progress: unknown (herdr unavailable: <reason>) and falls back to plain queue order, so dry-run never fails because of herdr. --once processes at most one ticket then exits. --repo overrides the default (gh repo view from cwd).
There is no Make wrapper for this script: the repo has no other Makefile surface, and a target that still requires LABEL=… is not more convenient than calling python3 scripts/loop_ready_issue_herdr.py --label … directly.
Queue membership
An issue enters the automation queue only when it is open, carries the label you passed, and is assigned to you (the gh api user login running the driver). Issues with the label but another assignee are ignored; issues assigned to you without the label are ignored.
Work for today counts
On startup (and in --dry-run), the driver prints a one-line queue summary, for example 22 with 'self-heal' label, 1 is assigned on 'AlexanderMakarov'. Only the assigned subset is eligible for automatic starts. A live run also prints params: (poll-seconds, agent-kind, mode=loop|once) and, after each spawn, {tab} herdr tab opened for #{n} gh issue … at HH:MM:SS. While it waits on a ticket, every GitHub poll that does not advance prints one status line, for example #323 open; no merged PR closes it yet — waiting 300s, #323: PR #335 merged; post-merge CI 3/5 green (2 pending) — waiting 300s, or … no check runs yet on the merge commit …, with (worker gone) appended once the worker agent has disappeared. If a GitHub merge/CI poll fails, the driver retries and leaves the worker agent running — that poll only gates starting the next ticket.
Eligibility and sort order
Among assigned, labeled, open issues, the driver skips any issue that still has an open GitHub “blocked by” blocker. It then picks one ticket at a time: issues with the important label before those without, then ascending issue number.
Serial workers (N = 1)
At most one ticket worker runs at a time. Before starting new work, the driver resumes an eligible ticket that already has an open issue-N herdr tab (a session restored after a reboot, or a driver restart), even when another issue sorts ahead of it; if several eligible tickets have open tabs, it resumes the one whose tab is oldest (lowest herdr tab number, i.e. leftmost in the tab bar; ties by tab id), prints a WARNING naming the others (WARNING: N eligible issues have an open issue-N tab; resuming #311 first (oldest tab); the others (#256) wait their turn and are adopted later with no new prompt.), and adopts each in turn later with no new prompt. Tab bar order is start order (new tabs append; herdr restore keeps it), so drag tabs to reprioritize. An issue-N tab whose issue is not in the eligible queue (closed, unlabeled, unassigned, or blocked) prints one WARNING per driver run (issue-N tab open but #N is not in the eligible queue (closed, unlabeled, unassigned, or blocked); close the tab or restore label/assignee.) and does not hold the queue. Each new ticket gets a new herdr worker tab and agent session; the driver does not reuse the previous agent as “the next issue.” The driver owns queue advance — the one-ticket helper never fetches or starts the next GitHub issue.
Thin skill (driver-inlined)
Routing for a single ticket lives in .claude/skills/loop-ready-issue-herdr/SKILL.md with disable-model-invocation: true — agents must not self-invoke it. That path is the repo’s canonical contributor-skill tree (same place as /release), not a Claude-only product surface: Cursor also loads top-level .claude/skills/ from this checkout, and Codex can mirror from there when you install skills. For this loop the file is mainly a source blob the Python driver reads and pastes into herdr agent prompt, so the worker (default Cursor, or --agent-kind claude / codex) receives the one-ticket contract in the prompt and does not need to discover the skill by name. The body routes bug → /fix-bug, otherwise → /implement-feature, for that issue URL only, and names each command's file (.claude/commands/fix-bug.md, .claude/commands/implement-feature.md): a slash command inside a pasted prompt is not expanded, so the worker must open the file and execute it from its first stage — the isolated worktree — and never check out a branch or edit files in MAIN. Without the file name, Cursor workers improvised from the finish-line outcomes and implemented in the primary checkout. There is no slash command wrapper.
The prompt is long, and some TUIs fold a long paste into a placeholder (Cursor CLI shows [Pasted text #1 +31 lines]) and can swallow the Enter herdr sends right after it, leaving the prompt typed but unsent. So the driver submits with herdr agent prompt --wait --until working and, when the agent does not start within 3 s, presses Enter (herdr agent send-keys <pane> Enter) and waits again, up to twice. If the agent still has not started it prints WARNING: herdr pane <pane>: prompt pasted but the agent did not start … — open that tab and press Enter.
Human gates and notifications
While a worker waits on you (herdr blocked — approval, question, permission), the driver holds the queue and does not start the next ticket. While the worker is actively delivering (including CI watch inside the delivery command), the driver keeps waiting. herdr idle or done alone does not mean “start the next issue.” This spike does not add a custom notifier; rely on herdr’s built-in agent status and notifications when a worker needs you.
AWOS vs herdr skill (#215): Smoke confirm, local review, PR timing, merge confirmation, and pull on MAIN are owned by /implement-feature, /fix-bug, and context/product/delivery-flow.md — change those via /awos:flow (Cursor: /awos-flow), not by editing generated commands by hand. The driver-inlined skill is a thin wrapper: before (one ticket, MAIN=), route to the slash command, and finish-line outcomes for the worker (closed issue, #N on main, sync on MAIN) — it must not restate AWOS stage lists or driver Phase A/B polling rules (those live in this doc). Delivery-flow itself never names this loop; the contract below is what this driver requires from the flow's Definition of Done.
Delivery-flow contract (what this loop needs)
The optional ready-issue loop does not change /implement-feature or /fix-bug. It only advances when a delivered run has already satisfied these flow DoD facts (recorded in context/product/delivery-flow.md §2 / §5):
$MAINis the primary checkout — workers implement in an isolated worktree ($WT); they never mutate files in$MAIN. The driver injectsMAIN=…into the worker prompt when it can.- Issue markers on the landed commits — delivery commits name
#Nin the subject, or use a closing keyword (Closes/Fixes/Resolves #N) in the body. A body-onlyRelevant to #N(or a bare#Nin the body) is not a closing marker for Path 1's message fallback. - Post-merge pull on
$MAINbefore Done — after merge and post-merge CI green, the worker runsgit -C "$MAIN" fetch origin mainandgit -C "$MAIN" pull --ff-only origin main. Phase A only reads local history; without that pull, Path 1 never sees the merge commit even when GitHub already shows it merged. - Pull before worktree cleanup — close-stage removal of
$WT/ the local branch runs only after the$MAINpull, so local history is current while the worktree still exists. - Accurate
ClosesvsRelevant to— a complete delivery should close the GitHub issue on merge; a stuck-open issue after a complete PR blocks Path 1 / Path 2 advance until someone closes it.
Merge and review: Workers run the slash command’s merge stage. Herdr does not authorize unattended merges. When CI is green but GitHub requires review (REVIEW_REQUIRED), the worker should report ready-to-merge and stop; the driver keeps polling until a merged closing PR appears (you or a reviewer merges in the browser or with gh from your account).
Advance rule (local Phase A → GitHub Phase B, or closed without merge)
Phase A local ticks never run git fetch / git pull — they only read local history on the main checkout (driver cwd). Untracked or modified files on that checkout do not block advance (the next ticket uses a fresh worktree). The driver still polls GitHub every --poll-seconds during Phase A solely to detect Path 2 (closed without a merged PR) and to print “merged on GitHub; merge commit not in local main yet”; it never advances Path 1 from Phase A. It starts every adopt/restart in Phase A, then moves to Phase B once local history shows the delivery, by either of two signals: the closing PR's merge commit (SHA from the last GitHub poll) is an ancestor of local HEAD (git merge-base --is-ancestor), which works whatever the commit messages say and however many commits landed since; or one of the last 10 commits names the ticket — #N in its subject, or a closing keyword (Closes / Fixes / Resolves #N) in its body, so a body-only Closes #N counts (GitHub's merge-commit subject names the PR, not the issue) while a cross-reference such as Relevant to #N does not. The message check is the fallback before the first successful GitHub poll.
Path 1 — merged closing PR: after Phase A sees #N in local git log, Phase B polls GitHub every --poll-seconds (default 300) until the issue is CLOSED, the closing PR is merged, and every check run on the merge commit is green (α — same as before: non-empty check runs, all success / skipped / neutral). Phase B alone is not enough: GitHub can show merged/green before the worker pulls main.
Path 2 — closed without a merged closing PR: no Phase A requirement; GitHub every --poll-seconds; advance at once with CI skipped, e.g. Advanced #323 (closed: COMPLETED, no merged closing PR; CI gate skipped).
Operator skip: from the same main checkout as the running driver, python3 scripts/loop_ready_issue_herdr.py --skip-issue N (no --label needed) writes a gitignored .herdr/skip-issue file; the driver force-advances that ticket with a WARNING (one-shot). Do not run --skip-issue from a gate worktree — the driver would not see that file.
AWOS: workers must satisfy the Delivery-flow contract above (especially the $MAIN pull). Spec: context/spec/303-loop-ready-issue-herdr/advance-wait-redesign.md.
Optional agent helper (not used by the driver): python3 scripts/wait_post_merge_ci.py.
On advance, the driver always closes the finished worker tab (even if the agent already went idle/disappeared — that only stops herdr agent wait, not tab cleanup) and opens a fresh one for the next issue — you do not need to close the tab yourself to unlock the queue. If a tab labeled issue-N is already open when the driver reaches issue N (a herdr session restored after a reboot, or a driver restart), the driver adopts it: it sends no new prompt and just polls GitHub for α, so in-progress delivery is not restarted. herdr restores tabs after a reboot without their agent; when no pane in the adopted tab runs an agent, the driver prints issue-N tab <tab_id> has no agent (restored after reboot?); prompting a worker and starts and prompts a worker in that pane — the delivery flow resumes from its flow-log, branch and PR. When a merged PR already closes the issue (only post-merge CI is left), it starts no worker and just waits for α. To pause a ticket, close its tab: quitting only the agent leaves an empty tab that gets a new worker on the next driver start. Close that tab first if you want a fresh worker. At startup and at the top of every queue cycle the driver lists herdr tabs labeled issue-N once — for this sweep and for resume-first selection (if the list fails, selection falls back to queue order and the driver still refuses to spawn a worker it cannot check for a duplicate tab) — asks GitHub for those issues' state in one batched query, and closes each tab whose issue is already CLOSED (Closed herdr tab issue-N (<tab_id>): #N is closed.) — leftovers from an earlier run or a ticket closed while the driver was stopped. A tab whose issue GitHub cannot resolve is left alone, and a herdr or GitHub failure in this sweep only prints a WARNING. Closing a worker tab early is a valid hard stop for that ticket; the driver does not treat it as successful delivery and does not auto-advance as if merged.
Polling intervals
- Phase A (local):
--local-poll-seconds(default 10, range 10–30) — localgit merge-base/git log -n 10only (no git network); Path-2ghstill on the--poll-secondsschedule. - Phase B / Path 2 (GitHub):
--poll-seconds(default 300) between merge/CI polls.
herdr agent wait is interleaved between ticks. Empty-queue re-listing (without --once) sleeps --poll-seconds between attempts.
Trust model
Queue membership is gated on you (the gh viewer login) and the readiness label you pass — the driver only auto-starts issues assigned to you with that label. Issue titles, bodies, and comments are untrusted input to the autonomous worker agent (public-tracker prompt-injection surface); the assignee gate limits who can trigger automation but does not sanitize issue text. The driver never closes GitHub issues on your behalf. Collaborators with triage rights can still apply your readiness label to issues; treat unexpected labeled tickets as something to fix in GitHub before the driver picks them up.
herdr workspace
The driver opens worker tabs in the herdr workspace it runs in (HERDR_WORKSPACE_ID of its pane) and only looks at issue-N tabs there when it adopts, resumes or sweeps tabs, so you can work in another workspace while it runs and a loop in another workspace is never touched. Pass --workspace <WORKSPACE_ID> (see herdr workspace list) to target a different workspace. Started outside herdr without --workspace, the driver prints a WARNING and falls back to herdr's defaults: new tabs open in the workspace active in the UI and tabs from every workspace are considered. Startup and --dry-run print the workspace on a herdr workspace: line.
Hard stop and restore
If you close the worker tab or the agent disappears before merge + green post-merge CI, the driver prints a WARNING with restore steps: continue delivery for that issue URL in a new worker. Re-running the driver adopts the open issue-N tab instead of spawning a new worker; close it first to start the ticket over. Press Ctrl+C to stop the driver loop; in-flight workers are left open until you close them, until advance closes them, or until a later driver run finds their issue CLOSED and closes the tab. The driver keeps polling GitHub for advance on that issue until α is satisfied or you stop.
Empty queue
When no eligible issues remain, the driver sleeps --poll-seconds and re-lists; it does not invent work. Ctrl+C exits cleanly.
Default agent kind
--agent-kind defaults to cursor. Optional values are claude and codex where your herdr install supports them.
Related material
- Functional spec:
context/spec/303-loop-ready-issue-herdr/functional-spec.md - Roadmap item: GitHub #296