From 1d66ad0393ab00a1b3888afbdd4bbd7d2246f98d Mon Sep 17 00:00:00 2001 From: Astrid Gealer Date: Thu, 15 Oct 2026 12:16:45 +0100 Subject: [PATCH 01/12] docs(claude): coordinate parallel work through issue assignment Document how people and their agents pick issues in priority order and claim them by self-assignment (or a claim comment without write access) before starting, so two contributors never fix the same issue in parallel. Covers race checks, respecting existing claims, stale-claim handoff, linking PRs, and releasing dropped issues. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 9c31898cb..ddc25dbe6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -67,6 +67,61 @@ surfaced bugs found while working here go into this repository's GitHub issues instead. See `CONTRIBUTING.md` under "Known Issues Sweep" for the full convention (including the cross-component sweep in the platform repo). +## Issue assignment — claim before you work (MANDATORY) + +Several people (and their agents) work through this repo's issue queue in +parallel. GitHub issue assignment is the lock that keeps two of them from +fixing the same thing. The `~/.claude/agent-comms/` bus below only +coordinates agents on one machine; assignment is what coordinates people. + +1. **Pick work in priority order.** Take the highest-priority open issue + that nobody owns, oldest first within a priority. Skip anything + labelled `status/blocked`, `status/needs-info` or `status/wontdo`: + + ```bash + for p in p0 p1 p2 p3; do + echo "== priority/$p" + gh issue list --repo LeanerCloud/cloud-commitments-cli --label "priority/$p" \ + --search "no:assignee -label:status/blocked -label:status/needs-info -label:status/wontdo sort:created-asc" \ + --json number,title --jq '.[] | "#\(.number) \(.title)"' + done + ``` + + Issues with no `priority/*` label come after `p3`. The query only sees + assignees, so open the issue and check its comments for a claim (step 2) + too. Before claiming, also check that no open PR already addresses it: + `gh pr list --repo LeanerCloud/cloud-commitments-cli --search " in:body"`. + +2. **Claim it before writing any code.** Assign yourself, then re-read the + assignees. If anyone else is also assigned, you lost the race: remove + yourself and pick another issue. + + ```bash + gh issue edit --repo LeanerCloud/cloud-commitments-cli --add-assignee @me + gh issue view --repo LeanerCloud/cloud-commitments-cli --json assignees --jq '[.assignees[].login]' + ``` + + If you cannot assign yourself (no write access yet), comment + `Claiming: working on this` on the issue instead. A claim comment + counts the same as an assignment, including the 7-day rule in step 3. + +3. **Respect other people's claims.** An issue that is assigned, or has a + claim comment, belongs to that person. Do not work on it, even if it + looks stale. If it has had no activity and no linked PR for 7 days, ask + on the issue and only take it over once the owner agrees or unassigns. + +4. **Link the PR.** Put `Closes #` in the PR body so the issue and PR + stay connected (and the PR labeling rule below can find the issue). + +5. **Release what you drop.** If you stop working on an issue without a + PR, unassign yourself (`gh issue edit --repo LeanerCloud/cloud-commitments-cli --remove-assignee @me`) + and leave a short comment on where you got to, so the next person + can pick it up. + +Work that is not tracked by an issue yet (for example a larger UI or +integration effort) gets an issue first, assigned to whoever is doing it, +so it shows up as taken. + ## Post-push CI watcher (MANDATORY — even for one-line fix commits) After **every** `git push` that publishes new commits to a PR branch on From 6d9da75a69361da01a19e6e66f8f805d8896618e Mon Sep 17 00:00:00 2001 From: Astrid Gealer Date: Thu, 15 Oct 2026 12:34:39 +0100 Subject: [PATCH 02/12] docs(claude): address review on issue-assignment section List unprioritised issues and raise the result limit, resolve competing claims by earliest claim, and define the stale-claim handoff when the owner does not reply. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index ddc25dbe6..9f2d0c484 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -81,10 +81,14 @@ coordinates agents on one machine; assignment is what coordinates people. ```bash for p in p0 p1 p2 p3; do echo "== priority/$p" - gh issue list --repo LeanerCloud/cloud-commitments-cli --label "priority/$p" \ + gh issue list --repo LeanerCloud/cloud-commitments-cli --label "priority/$p" --limit 500 \ --search "no:assignee -label:status/blocked -label:status/needs-info -label:status/wontdo sort:created-asc" \ --json number,title --jq '.[] | "#\(.number) \(.title)"' done + echo "== no priority label" + gh issue list --repo LeanerCloud/cloud-commitments-cli --limit 500 \ + --search "no:assignee -label:status/blocked -label:status/needs-info -label:status/wontdo sort:created-asc -label:priority/p0 -label:priority/p1 -label:priority/p2 -label:priority/p3" \ + --json number,title --jq '.[] | "#\(.number) \(.title)"' ``` Issues with no `priority/*` label come after `p3`. The query only sees @@ -93,8 +97,9 @@ coordinates agents on one machine; assignment is what coordinates people. `gh pr list --repo LeanerCloud/cloud-commitments-cli --search " in:body"`. 2. **Claim it before writing any code.** Assign yourself, then re-read the - assignees. If anyone else is also assigned, you lost the race: remove - yourself and pick another issue. + assignees and comments. If someone else is also assigned or has posted + a claim comment, the earliest claim on the issue timeline wins; if that + is not you, remove yourself and pick another issue. ```bash gh issue edit --repo LeanerCloud/cloud-commitments-cli --add-assignee @me @@ -104,11 +109,16 @@ coordinates agents on one machine; assignment is what coordinates people. If you cannot assign yourself (no write access yet), comment `Claiming: working on this` on the issue instead. A claim comment counts the same as an assignment, including the 7-day rule in step 3. + After posting, re-read the issue the same way: if an earlier claim + exists, delete your comment and pick another issue. 3. **Respect other people's claims.** An issue that is assigned, or has a claim comment, belongs to that person. Do not work on it, even if it looks stale. If it has had no activity and no linked PR for 7 days, ask - on the issue and only take it over once the owner agrees or unassigns. + on the issue, mentioning the owner. Take it over once they agree or + unassign. If they have not replied after 3 more days, comment that you + are taking it over, then claim it as in step 2 (a maintainer can move + the assignment if you lack write access). 4. **Link the PR.** Put `Closes #` in the PR body so the issue and PR stay connected (and the PR labeling rule below can find the issue). From 3fc0c0c7b3808dba692103c1c2ab2f97db5e1a19 Mon Sep 17 00:00:00 2001 From: Astrid Gealer Date: Thu, 15 Oct 2026 14:50:32 +0100 Subject: [PATCH 03/12] docs(claude): let a takeover comment supersede a stale claim Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9f2d0c484..f4a86e2d0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -117,8 +117,10 @@ coordinates agents on one machine; assignment is what coordinates people. looks stale. If it has had no activity and no linked PR for 7 days, ask on the issue, mentioning the owner. Take it over once they agree or unassign. If they have not replied after 3 more days, comment that you - are taking it over, then claim it as in step 2 (a maintainer can move - the assignment if you lack write access). + are taking it over. That takeover comment supersedes the stale claim: + claim the issue as in step 2, but only claims posted after your + takeover comment count when checking for an earlier claim. A + maintainer can move the assignment if you lack write access. 4. **Link the PR.** Put `Closes #` in the PR body so the issue and PR stay connected (and the PR labeling rule below can find the issue). From a2a39f9732544176114e12490de9f459cb0ef638 Mon Sep 17 00:00:00 2001 From: Astrid Gealer Date: Thu, 15 Oct 2026 15:01:30 +0100 Subject: [PATCH 04/12] docs(claude): scope takeover to the stale claim and move the assignment Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f4a86e2d0..118ae7fa8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -117,10 +117,12 @@ coordinates agents on one machine; assignment is what coordinates people. looks stale. If it has had no activity and no linked PR for 7 days, ask on the issue, mentioning the owner. Take it over once they agree or unassign. If they have not replied after 3 more days, comment that you - are taking it over. That takeover comment supersedes the stale claim: - claim the issue as in step 2, but only claims posted after your - takeover comment count when checking for an earlier claim. A - maintainer can move the assignment if you lack write access. + are taking it over. That comment is your claim and supersedes only the + stale owner's claim: when you check for an earlier claim as in step 2, + ignore the stale owner, but any other claim posted before your takeover + comment still wins. Then move the assignment to yourself: + `gh issue edit --repo LeanerCloud/cloud-commitments-cli --add-assignee @me --remove-assignee ` + (or ask a maintainer to, if you lack write access). 4. **Link the PR.** Put `Closes #` in the PR body so the issue and PR stay connected (and the PR labeling rule below can find the issue). From 6ba7e771b4bd4f8fb826a56ec17e1731401a37ef Mon Sep 17 00:00:00 2001 From: Astrid Gealer Date: Thu, 15 Oct 2026 22:11:40 +0100 Subject: [PATCH 05/12] docs(claude): include claim comments in the post-claim check Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 118ae7fa8..c84066e30 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -103,7 +103,10 @@ coordinates agents on one machine; assignment is what coordinates people. ```bash gh issue edit --repo LeanerCloud/cloud-commitments-cli --add-assignee @me - gh issue view --repo LeanerCloud/cloud-commitments-cli --json assignees --jq '[.assignees[].login]' + gh issue view --repo LeanerCloud/cloud-commitments-cli --json assignees,comments \ + --jq '{assignees: [.assignees[].login], + claims: [.comments[] | select(.body | test("(?i)claim")) + | "\(.createdAt) \(.author.login): \(.body[0:80])"]}' ``` If you cannot assign yourself (no write access yet), comment From 0e801b5704a7a54c23aeb2b7ede1f9f54a06b989 Mon Sep 17 00:00:00 2001 From: Astrid Gealer Date: Thu, 15 Oct 2026 22:25:48 +0100 Subject: [PATCH 06/12] docs(claude): use Claiming/Taking over/Released markers to order claims Assignment times aren't visible to gh issue view and keyword matching both misses takeovers and keeps released claims, so claims, takeovers and releases are now marker comments whose timestamps decide precedence. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 65 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 38 insertions(+), 27 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c84066e30..e2c2017ae 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -96,34 +96,44 @@ coordinates agents on one machine; assignment is what coordinates people. too. Before claiming, also check that no open PR already addresses it: `gh pr list --repo LeanerCloud/cloud-commitments-cli --search " in:body"`. -2. **Claim it before writing any code.** Assign yourself, then re-read the - assignees and comments. If someone else is also assigned or has posted - a claim comment, the earliest claim on the issue timeline wins; if that - is not you, remove yourself and pick another issue. +2. **Claim it before writing any code.** Post a claim comment, and also + assign yourself if you have write access. Claims, takeovers and releases + are all comments starting with a fixed marker (`Claiming:`, + `Taking over:` or `Released:`), because comment timestamps are what + decide who claimed first; `gh issue view` cannot show when someone was + assigned. ```bash - gh issue edit --repo LeanerCloud/cloud-commitments-cli --add-assignee @me - gh issue view --repo LeanerCloud/cloud-commitments-cli --json assignees,comments \ - --jq '{assignees: [.assignees[].login], - claims: [.comments[] | select(.body | test("(?i)claim")) - | "\(.createdAt) \(.author.login): \(.body[0:80])"]}' + gh issue comment --repo LeanerCloud/cloud-commitments-cli --body "Claiming: working on this" + gh issue edit --repo LeanerCloud/cloud-commitments-cli --add-assignee @me # needs write access ``` - If you cannot assign yourself (no write access yet), comment - `Claiming: working on this` on the issue instead. A claim comment - counts the same as an assignment, including the 7-day rule in step 3. - After posting, re-read the issue the same way: if an earlier claim - exists, delete your comment and pick another issue. - -3. **Respect other people's claims.** An issue that is assigned, or has a - claim comment, belongs to that person. Do not work on it, even if it - looks stale. If it has had no activity and no linked PR for 7 days, ask - on the issue, mentioning the owner. Take it over once they agree or - unassign. If they have not replied after 3 more days, comment that you - are taking it over. That comment is your claim and supersedes only the - stale owner's claim: when you check for an earlier claim as in step 2, - ignore the stale owner, but any other claim posted before your takeover - comment still wins. Then move the assignment to yourself: + Then list the markers and work out who holds the issue: + + ```bash + gh issue view --repo LeanerCloud/cloud-commitments-cli --json comments \ + --jq '.comments[] | select(.body | test("^(Claiming|Taking over|Released):")) + | "\(.createdAt) \(.author.login): \(.body | split("\n")[0])"' + ``` + + A person's claim is active when their latest marker is `Claiming:` or + `Taking over:`; a later `Released:` from them ends it. The earliest + active claim wins. If that is not you, edit your comment to + `Released: claimed by someone else first`, remove yourself as assignee + and pick another issue. An assignment with no marker comment (for + example a maintainer assigning someone) still means the issue is taken, + and so does an older free-form claim comment such as `claimed by `. + +3. **Respect other people's claims.** An issue with an active claim or an + assignee belongs to that person. Do not work on it, even if it looks + stale. If it has had no activity and no linked PR for 7 days, ask on + the issue, mentioning the owner. Take it over once they agree or + release it. If they have not replied after 3 more days, post + `Taking over: no reply since `. That marker is your claim and + supersedes only the stale owner's claim: when you work out the earliest + active claim as in step 2, ignore the stale owner, but any other active + claim posted before your takeover still wins. Then move the assignment + to yourself: `gh issue edit --repo LeanerCloud/cloud-commitments-cli --add-assignee @me --remove-assignee ` (or ask a maintainer to, if you lack write access). @@ -131,9 +141,10 @@ coordinates agents on one machine; assignment is what coordinates people. stay connected (and the PR labeling rule below can find the issue). 5. **Release what you drop.** If you stop working on an issue without a - PR, unassign yourself (`gh issue edit --repo LeanerCloud/cloud-commitments-cli --remove-assignee @me`) - and leave a short comment on where you got to, so the next person - can pick it up. + PR, post `Released: ` and unassign yourself + (`gh issue edit --repo LeanerCloud/cloud-commitments-cli --remove-assignee @me`), so the next + person can pick it up. If the issue turns out to be already fixed, say + which PR or commit fixed it and ask a maintainer to close it. Work that is not tracked by an issue yet (for example a larger UI or integration effort) gets an issue first, assigned to whoever is doing it, From 59e3714d70c897d365fa3c30b5148087e23a6659 Mon Sep 17 00:00:00 2001 From: Astrid Gealer Date: Fri, 16 Oct 2026 00:08:21 +0100 Subject: [PATCH 07/12] docs(claude): address review nits on the issue-assignment section Worker ids for agents sharing a login, maintainer override, a command for releasing (post a new Released: marker), a higher result limit with a note that it truncates silently. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e2c2017ae..9b6235cb7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -81,17 +81,18 @@ coordinates agents on one machine; assignment is what coordinates people. ```bash for p in p0 p1 p2 p3; do echo "== priority/$p" - gh issue list --repo LeanerCloud/cloud-commitments-cli --label "priority/$p" --limit 500 \ + gh issue list --repo LeanerCloud/cloud-commitments-cli --label "priority/$p" --limit 1000 \ --search "no:assignee -label:status/blocked -label:status/needs-info -label:status/wontdo sort:created-asc" \ --json number,title --jq '.[] | "#\(.number) \(.title)"' done echo "== no priority label" - gh issue list --repo LeanerCloud/cloud-commitments-cli --limit 500 \ + gh issue list --repo LeanerCloud/cloud-commitments-cli --limit 1000 \ --search "no:assignee -label:status/blocked -label:status/needs-info -label:status/wontdo sort:created-asc -label:priority/p0 -label:priority/p1 -label:priority/p2 -label:priority/p3" \ --json number,title --jq '.[] | "#\(.number) \(.title)"' ``` - Issues with no `priority/*` label come after `p3`. The query only sees + `--limit` truncates silently, so if a priority ever has more than 1000 + open issues, raise it. Issues with no `priority/*` label come after `p3`. The query only sees assignees, so open the issue and check its comments for a claim (step 2) too. Before claiming, also check that no open PR already addresses it: `gh pr list --repo LeanerCloud/cloud-commitments-cli --search " in:body"`. @@ -118,14 +119,19 @@ coordinates agents on one machine; assignment is what coordinates people. A person's claim is active when their latest marker is `Claiming:` or `Taking over:`; a later `Released:` from them ends it. The earliest - active claim wins. If that is not you, edit your comment to - `Released: claimed by someone else first`, remove yourself as assignee - and pick another issue. An assignment with no marker comment (for + active claim wins. If that is not you, post + `gh issue comment --repo LeanerCloud/cloud-commitments-cli --body "Released: claimed by someone else first"` + (your latest marker is what counts), remove yourself as assignee and + pick another issue. Agents that share one GitHub login can't tell their + claims apart by author, so each puts its worker id in every marker + (for example `Claiming: working on this [cc-platform-w3]`) and compares + claims by worker id; same-machine agents can also use the bus below. An assignment with no marker comment (for example a maintainer assigning someone) still means the issue is taken, and so does an older free-form claim comment such as `claimed by `. 3. **Respect other people's claims.** An issue with an active claim or an - assignee belongs to that person. Do not work on it, even if it looks + assignee belongs to that person. A maintainer's assignment or + `Taking over:` overrides any claim. Do not work on it, even if it looks stale. If it has had no activity and no linked PR for 7 days, ask on the issue, mentioning the owner. Take it over once they agree or release it. If they have not replied after 3 more days, post @@ -141,7 +147,7 @@ coordinates agents on one machine; assignment is what coordinates people. stay connected (and the PR labeling rule below can find the issue). 5. **Release what you drop.** If you stop working on an issue without a - PR, post `Released: ` and unassign yourself + PR, post `Released: ` as a new comment and unassign yourself (`gh issue edit --repo LeanerCloud/cloud-commitments-cli --remove-assignee @me`), so the next person can pick it up. If the issue turns out to be already fixed, say which PR or commit fixed it and ask a maintainer to close it. From fc8bf3c9d16e3aee68c1e098ef31ebe82f6aa246 Mon Sep 17 00:00:00 2001 From: Astrid Gealer Date: Fri, 16 Oct 2026 00:08:45 +0100 Subject: [PATCH 08/12] docs(claude): reflow issue-assignment step 2 Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9b6235cb7..e908111ee 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -125,8 +125,9 @@ coordinates agents on one machine; assignment is what coordinates people. pick another issue. Agents that share one GitHub login can't tell their claims apart by author, so each puts its worker id in every marker (for example `Claiming: working on this [cc-platform-w3]`) and compares - claims by worker id; same-machine agents can also use the bus below. An assignment with no marker comment (for - example a maintainer assigning someone) still means the issue is taken, + claims by worker id; same-machine agents can also use the bus below. + An assignment with no marker comment (for example a maintainer + assigning someone) still means the issue is taken, and so does an older free-form claim comment such as `claimed by `. 3. **Respect other people's claims.** An issue with an active claim or an From 85c4f04db4911fea85bf621b9c887865dd5f4a3d Mon Sep 17 00:00:00 2001 From: Astrid Gealer Date: Fri, 16 Oct 2026 00:16:46 +0100 Subject: [PATCH 09/12] docs(claude): split queries that hit GitHub's 1000-result search cap Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e908111ee..f25518ff0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -91,8 +91,10 @@ coordinates agents on one machine; assignment is what coordinates people. --json number,title --jq '.[] | "#\(.number) \(.title)"' ``` - `--limit` truncates silently, so if a priority ever has more than 1000 - open issues, raise it. Issues with no `priority/*` label come after `p3`. The query only sees + GitHub search returns at most 1000 results whatever `--limit` says, and + truncates silently. If a query returns exactly 1000, split it into + non-overlapping windows (for example add `created:<2026-07-01` and + `created:>=2026-07-01`) and run each. Issues with no `priority/*` label come after `p3`. The query only sees assignees, so open the issue and check its comments for a claim (step 2) too. Before claiming, also check that no open PR already addresses it: `gh pr list --repo LeanerCloud/cloud-commitments-cli --search " in:body"`. From 66ea0f8c0943a141ce4229c1be7c5fc96256e3d3 Mon Sep 17 00:00:00 2001 From: Astrid Gealer Date: Fri, 16 Oct 2026 00:26:58 +0100 Subject: [PATCH 10/12] docs(claude): worker ids in every marker example, maintainer-only override, show assignees in the claim check Rewrites steps 2, 3 and 5 for readability: commands in fenced blocks wrapped under 100 columns, [] in every marker example, the override limited to a maintainer's assignment or Taking over:, and the post-claim check printing assignees alongside the markers. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 82 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 49 insertions(+), 33 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f25518ff0..8c0a85726 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -94,9 +94,10 @@ coordinates agents on one machine; assignment is what coordinates people. GitHub search returns at most 1000 results whatever `--limit` says, and truncates silently. If a query returns exactly 1000, split it into non-overlapping windows (for example add `created:<2026-07-01` and - `created:>=2026-07-01`) and run each. Issues with no `priority/*` label come after `p3`. The query only sees - assignees, so open the issue and check its comments for a claim (step 2) - too. Before claiming, also check that no open PR already addresses it: + `created:>=2026-07-01`) and run each. Issues with no `priority/*` label + come after `p3`. The query only sees assignees, so open the issue and + check its comments for a claim (step 2) too. Before claiming, also check + that no open PR already addresses it: `gh pr list --repo LeanerCloud/cloud-commitments-cli --search " in:body"`. 2. **Claim it before writing any code.** Post a claim comment, and also @@ -104,53 +105,68 @@ coordinates agents on one machine; assignment is what coordinates people. are all comments starting with a fixed marker (`Claiming:`, `Taking over:` or `Released:`), because comment timestamps are what decide who claimed first; `gh issue view` cannot show when someone was - assigned. + assigned. Agents that share one GitHub login can't tell their claims + apart by author, so each ends every marker with its worker id, shown as + `[]` below (leave it out if the login is yours alone), and + compares claims by worker id; same-machine agents can also use the bus + below. ```bash - gh issue comment --repo LeanerCloud/cloud-commitments-cli --body "Claiming: working on this" - gh issue edit --repo LeanerCloud/cloud-commitments-cli --add-assignee @me # needs write access + gh issue comment --repo LeanerCloud/cloud-commitments-cli \ + --body "Claiming: working on this []" + gh issue edit --repo LeanerCloud/cloud-commitments-cli \ + --add-assignee @me # needs write access ``` - Then list the markers and work out who holds the issue: + Then list the assignees and markers and work out who holds the issue: ```bash - gh issue view --repo LeanerCloud/cloud-commitments-cli --json comments \ - --jq '.comments[] | select(.body | test("^(Claiming|Taking over|Released):")) - | "\(.createdAt) \(.author.login): \(.body | split("\n")[0])"' + gh issue view --repo LeanerCloud/cloud-commitments-cli --json assignees,comments \ + --jq '"assignees: \([.assignees[].login] | join(", "))", + (.comments[] | select(.body | test("^(Claiming|Taking over|Released):")) + | "\(.createdAt) \(.author.login): \(.body | split("\n")[0])")' ``` - A person's claim is active when their latest marker is `Claiming:` or + A claim is active when its owner's latest marker is `Claiming:` or `Taking over:`; a later `Released:` from them ends it. The earliest - active claim wins. If that is not you, post - `gh issue comment --repo LeanerCloud/cloud-commitments-cli --body "Released: claimed by someone else first"` - (your latest marker is what counts), remove yourself as assignee and - pick another issue. Agents that share one GitHub login can't tell their - claims apart by author, so each puts its worker id in every marker - (for example `Claiming: working on this [cc-platform-w3]`) and compares - claims by worker id; same-machine agents can also use the bus below. + active claim wins. If that is not you, release it and pick another + issue (your latest marker is what counts): + + ```bash + gh issue comment --repo LeanerCloud/cloud-commitments-cli \ + --body "Released: claimed by someone else first []" + gh issue edit --repo LeanerCloud/cloud-commitments-cli --remove-assignee @me + ``` + An assignment with no marker comment (for example a maintainer - assigning someone) still means the issue is taken, - and so does an older free-form claim comment such as `claimed by `. + assigning someone) still means the issue is taken, and so does an older + free-form claim comment such as `claimed by `. 3. **Respect other people's claims.** An issue with an active claim or an - assignee belongs to that person. A maintainer's assignment or - `Taking over:` overrides any claim. Do not work on it, even if it looks - stale. If it has had no activity and no linked PR for 7 days, ask on - the issue, mentioning the owner. Take it over once they agree or - release it. If they have not replied after 3 more days, post - `Taking over: no reply since `. That marker is your claim and - supersedes only the stale owner's claim: when you work out the earliest - active claim as in step 2, ignore the stale owner, but any other active - claim posted before your takeover still wins. Then move the assignment - to yourself: - `gh issue edit --repo LeanerCloud/cloud-commitments-cli --add-assignee @me --remove-assignee ` - (or ask a maintainer to, if you lack write access). + assignee belongs to that person. Do not work on it, even if it looks + stale. A maintainer's assignment or a maintainer's `Taking over:` + overrides any claim; everyone else uses the flow below. If the issue + has had no activity and no linked PR for 7 days, ask on the issue, + mentioning the owner. Take it over once they agree or release it. If + they have not replied after 3 more days, post + `Taking over: no reply since []`. That marker is your + claim and supersedes only the stale owner's claim: when you work out + the earliest active claim as in step 2, ignore the stale owner, but any + other active claim posted before your takeover still wins. Then move + the assignment to yourself (or ask a maintainer to, if you lack write + access): + + ```bash + gh issue edit --repo LeanerCloud/cloud-commitments-cli \ + --add-assignee @me --remove-assignee + ``` 4. **Link the PR.** Put `Closes #` in the PR body so the issue and PR stay connected (and the PR labeling rule below can find the issue). 5. **Release what you drop.** If you stop working on an issue without a - PR, post `Released: ` as a new comment and unassign yourself + PR, post `Released: []` as a new comment + and unassign yourself (`gh issue edit --repo LeanerCloud/cloud-commitments-cli --remove-assignee @me`), so the next person can pick it up. If the issue turns out to be already fixed, say which PR or commit fixed it and ask a maintainer to close it. From 3a3e82dea971aca838289f0b8d28b9cd74352ec9 Mon Sep 17 00:00:00 2001 From: Astrid Gealer Date: Fri, 16 Oct 2026 00:35:33 +0100 Subject: [PATCH 11/12] docs(claude): show legacy "claimed by" comments in the claim check Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8c0a85726..70f24b669 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -123,7 +123,8 @@ coordinates agents on one machine; assignment is what coordinates people. ```bash gh issue view --repo LeanerCloud/cloud-commitments-cli --json assignees,comments \ --jq '"assignees: \([.assignees[].login] | join(", "))", - (.comments[] | select(.body | test("^(Claiming|Taking over|Released):")) + (.comments[] | select((.body | test("^(Claiming|Taking over|Released):")) + or (.body | test("claimed by"; "i"))) | "\(.createdAt) \(.author.login): \(.body | split("\n")[0])")' ``` From 73f4f5201104e35d69b29962121f9b490c8c7a0b Mon Sep 17 00:00:00 2001 From: Astrid Gealer Date: Fri, 16 Oct 2026 01:44:16 +0100 Subject: [PATCH 12/12] docs(claude): limit the existing-PR search; keep a shared-login assignment another worker still holds Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 70f24b669..c15cc4ad4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -98,7 +98,8 @@ coordinates agents on one machine; assignment is what coordinates people. come after `p3`. The query only sees assignees, so open the issue and check its comments for a claim (step 2) too. Before claiming, also check that no open PR already addresses it: - `gh pr list --repo LeanerCloud/cloud-commitments-cli --search " in:body"`. + `gh pr list --repo LeanerCloud/cloud-commitments-cli --limit 1000 --search " in:body"` + (split it the same way if it returns 1000). 2. **Claim it before writing any code.** Post a claim comment, and also assign yourself if you have write access. Claims, takeovers and releases @@ -139,6 +140,10 @@ coordinates agents on one machine; assignment is what coordinates people. gh issue edit --repo LeanerCloud/cloud-commitments-cli --remove-assignee @me ``` + Skip the `--remove-assignee` when another worker on your shared login + still holds an active claim: the assignment is that worker's too, and + removing it would make the issue look unowned. + An assignment with no marker comment (for example a maintainer assigning someone) still means the issue is taken, and so does an older free-form claim comment such as `claimed by `. @@ -167,7 +172,8 @@ coordinates agents on one machine; assignment is what coordinates people. 5. **Release what you drop.** If you stop working on an issue without a PR, post `Released: []` as a new comment - and unassign yourself + and unassign yourself (unless another worker on your shared login + still holds an active claim) (`gh issue edit --repo LeanerCloud/cloud-commitments-cli --remove-assignee @me`), so the next person can pick it up. If the issue turns out to be already fixed, say which PR or commit fixed it and ask a maintainer to close it.