Skip to content

docs(agents): respect assignments, and claim work before starting it #3040

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
louistrue merged 2 commits into from
Aug 21, 2026
Merged

docs(agents): respect assignments, and claim work before starting it #3040

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1503523
docs(agents): respect assignments, and claim work before starting it
louistrue Aug 21, 2026
f170963
docs(agents): helping is welcome, taking over is not
louistrue Aug 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,28 @@ report that you bounded it. Mutate the halves separately; they fail differently
## New source files
- MPL-2.0 header on every new file: see [`./LICENSE_HEADER.md`](./LICENSE_HEADER.md).

## Claiming work

**Respect assignments, and assign yourself before you start.** This is not etiquette, it is the mechanism that stops two people building the same thing.

Before touching an issue:

1. `gh issue view <n> --json assignees,title` — **if someone else is assigned, it is theirs.** Do not start. If you think it is stalled or you have context they lack, say so in a comment and let them answer.
2. `gh pr list --search "<n>"` — an open PR referencing the issue is a claim even when nobody is assigned.

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Search for an exact issue reference

For a common issue number or one that also appears as a version, count, or unrelated identifier, gh pr list --search "<n>" performs a general search rather than resolving PR-to-issue links. As gh pr list --help documents, this is a search query with a default 30-result limit, and its default output does not expose the matching text or linked issues; agents can therefore treat an unrelated hit as a claim or miss the real claim outside the capped results. Use structured link fields or require inspection of exact #<n> references before deciding the issue is claimed.

AGENTS.md reference: AGENTS.md:L174-L177

Useful? React with 👍 / 👎.

3. If both are clear, `gh issue edit <n> --add-assignee <you>` **before** writing code, not when you open the PR. An assignment made at PR time claims nothing; the window it needed to cover has already closed.

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Detect concurrent assignees immediately after claiming

When two agents start the same unassigned issue concurrently, both can pass the initial checks before either edit completes. The local gh issue edit --help describes --add-assignee as adding users, so both edits succeed and both agents proceed; the prescribed recheck occurs only after the duplicated implementation work is already done. Re-read the assignees immediately after the edit and require the claimant to be the sole assignee, or use another claim operation that detects this race.

AGENTS.md reference: AGENTS.md:L176-L180

Useful? React with 👍 / 👎.


Check again immediately before opening the PR. A claim can appear while you work, and the second check is the cheap one.

When you find you have duplicated someone:

- **The person who was assigned keeps the work.** Not whoever is further along, and not whoever noticed first.
- Do not close the duplicate silently. Enumerate what it holds that the surviving one does not, so nothing is lost when it goes, and post that list on both.
- Never push to a branch you do not own to "help". If a fix is a one-liner, say the one line in a comment.

This rule exists because it was broken. Issue #2951 was filed by an external contributor, assigned to them, and implemented in #2952 — and #2970 arrived fifteen hours later implementing the same thing. They were right to object. The cost is not the wasted effort, it is that a contributor who did everything correctly watched their work get duplicated by the project they contributed to.

Applies to every agent and every session, including short-lived subagents.

## Delegating to subagents
- Any delegated agent must obey this file: use the canonical load/geometry/export paths here, preserve IFC EXPRESS names, add no second load path, and prove changes with the narrowest local verification command. Treat delegated implementation output as a patch proposal until `git diff` plus local verification pass.
- Keep the orchestrator's context clean: delegate token-heavy filesystem work (broad search, log triage, fixture inspection, first-pass test repair) and get back a concise summary (files changed, commands run, result, risks), not raw logs or fixture dumps.
Expand Down