The best way to control Claude Code, Codex and more from any computer or phone
| 1 | --- |
| 2 | name: pr-queue |
| 3 | description: Run a pull-request (or issue) queue for an area of alchemy — search GitHub for open PRs/issues matching a criteria (e.g. "cloudflare", "docker", "aws/rds", an author, a label), shortlist the top 10 ordered by ease of fixing, then launch each one as its own detached top-level T3 thread (`t3_thread_launch`, `workspaceStrategy: "worktree"`): each thread checks out, merges main, resolves conflicts, audits tests and JSDoc, runs the suites, rewrites the PR description as DX snippets, and asks the user directly to merge or close it, while this thread keeps the status table. Use for "start working on a pull request queue for cloudflare", "PR queue for docker", "triage open PRs for X", "work through the open fix(aws) PRs", "next PR" while a queue is running. |
| 4 | metadata: |
| 5 | internal: true |
| 6 | --- |
| 7 | |
| 8 | # Pull request queue |
| 9 | |
| 10 | This thread is the coordinator. Build the catalog once, then launch one |
| 11 | **detached top-level thread** per PR or issue, each in its own worktree. Each |
| 12 | thread owns its item end to end: it fixes it, pushes it, watches CI, and asks |
| 13 | the user to merge or close it. The user merges; no thread ever does. |
| 14 | |
| 15 | Item threads MUST be top-level threads from `t3_thread_launch`, never |
| 16 | subagent threads from `delegate_task`. A subagent thread can't watch CI, |
| 17 | reports only back to the coordinator, and routes every user answer through |
| 18 | it. A top-level thread sits in the sidebar on its own, the user talks to it |
| 19 | directly, and it carries its PR to merge-ready without the coordinator. |
| 20 | |
| 21 | ## 1. Build the catalog and shortlist |
| 22 | |
| 23 | Turn the user's criteria into a search. An area like `docker` or `cloudflare` |
| 24 | matches conventional-commit scopes (`feat(docker)`, `fix(cloudflare/r2)!`) and |
| 25 | PRs that touch that provider's paths. |
| 26 | |
| 27 | ```sh |
| 28 | gh pr list --state open --limit 300 --json number,title,author,isDraft,mergeable,additions,deletions,changedFiles,updatedAt,isCrossRepository,maintainerCanModify,headRefName,baseRefName,url \ |
| 29 | > /tmp/pr-queue.json |
| 30 | # scope match: ^\w+!?\((<area>)(/[^)]*)?\)!?: (case-insensitive) |
| 31 | # path match for anything the title missed: |
| 32 | gh pr view <n> --json files --jq '.files[].path' | grep -i '<Area>/' |
| 33 | ``` |
| 34 | |
| 35 | For issues use `gh issue list --state open --search "<area> in:title,body"`. |
| 36 | Free-form criteria map onto `--author`, `--label`, `--search`. Leave out the |
| 37 | user's own PRs unless asked, and honor any exclusions they give (e.g. "ignore |
| 38 | the container PRs"). |
| 39 | |
| 40 | Print the **catalog**, grouped by theme when it's large: |
| 41 | `PR (link) | Author | Size | Behind main | What it does | Audit notes`, with |
| 42 | ✅/❌ against the standards in |
| 43 | [audit/procedure.md §3](../audit/procedure.md#3-review-the-code). Annotate: |
| 44 | |
| 45 | - **stacks** — a PR whose `baseRefName` is another PR's branch |
| 46 | (`base #N ← child #M`) |
| 47 | - **overlaps** — PRs fixing the same issue or touching the same files; plan a |
| 48 | merge order and which ones to close |
| 49 | - drafts, and PRs waiting on the author's answer to an earlier question |
| 50 | |
| 51 | Then the **shortlist: top 10, easiest first** — |
| 52 | `# | PR (link) | Author | Size | Tests now | Likely work`. Rank by clean merge, |
| 53 | small diff, tests already in the right shape, single concern. Exclude drafts, |
| 54 | PRs waiting on the author, and forks we can't push to |
| 55 | (`maintainerCanModify: false`). PRs needing a test rewrite go on a separate |
| 56 | **rework list**. If fewer than 10 match, say it's the whole list. |
| 57 | |
| 58 | Keep the shortlist as a status table with a thread link per row |
| 59 | (`[title](t3-thread://v1/<threadId>)`) and a status (`todo` / `ready → merge?` / |
| 60 | `close?` / `merged` / `closed` / `parked`), and re-print it whenever it changes. |
| 61 | |
| 62 | ## 2. Launch one thread per item |
| 63 | |
| 64 | Start each item with `t3_thread_launch`: |
| 65 | |
| 66 | ```ts |
| 67 | t3_thread_launch({ |
| 68 | title: "#<N> <short title>", |
| 69 | workspaceStrategy: { type: "worktree", baseRef: "origin/main" }, // its own checkout |
| 70 | message: "<contents of /tmp/pr-queue/brief-<N>.md>", |
| 71 | }) |
| 72 | ``` |
| 73 | |
| 74 | Keep each returned thread `link` in the status table. Launch the whole |
| 75 | shortlist; there is no cap on running threads. Send the launches in batches |
| 76 | of about 3: each one cuts a worktree, and cutting many at once in the same |
| 77 | repo contends for git's locks. The brief checks out the PR branch (or a new |
| 78 | `fix/…` branch for an issue) itself. |
| 79 | |
| 80 | A PR's brief starts with `/audit <N>`; an issue's says to fix it per |
| 81 | [audit/procedure.md](../audit/procedure.md) and open a PR ending in |
| 82 | `Fixes #<N>`. Every brief adds: `pnpm install` first, no subagents of its |
| 83 | own, one live suite at a time with `--concurrency 8`, `link_pull_request` on |
| 84 | every PR, for features post the proposed API and wait before building, after |
| 85 | each push `watch_pull_request` the PR and end the turn, and leave the PR with |
| 86 | every CI check passing on its final head |
| 87 | ([audit/procedure.md §6](../audit/procedure.md#6-push-and-update-the-pr)) |
| 88 | before asking the user to merge per |
| 89 | [audit/procedure.md §7](../audit/procedure.md#7-report-and-ask). |
| 90 | |
| 91 | If a thread fails in preparation, launch a fresh one; don't relaunch into the |
| 92 | same branch by hand. |
| 93 | |
| 94 | ## 3. Coordinate |
| 95 | |
| 96 | Don't do an item's work here, and don't poll threads (`sleep`, |
| 97 | `t3_thread_wait`). Item threads report to the user, not to this thread. When |
| 98 | the user asks for status, `t3_thread_read` each thread, update the table, and |
| 99 | re-print it. Answers and merge decisions go to the item's own thread, not |
| 100 | through here. On "enqueue more", re-run the §1 search and launch the next |
| 101 | batch. |