The best way to control Claude Code, Codex and more from any computer or phone

main
md 101 lines 5.22 KB
Rendered Raw
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.