docs(cli): require claim and unclaim on issue ownership (#939)

d7be66f0a48070753984ef2248cda34d0fbbff0e · 2026-05-10 11:21:59 -0700 · Trevin Chow

Expand AGENTS.md "Issue Work Ownership" so agents claim issues before
coding (not after a fix is ready), post a short comment when picking
work up, and unclaim with a comment if they stop or hand off before a
PR exists.

Files touched

M AGENTS.md

Diff

commit d7be66f0a48070753984ef2248cda34d0fbbff0e
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Sun May 10 11:21:59 2026 -0700

    docs(cli): require claim and unclaim on issue ownership (#939)
    
    Expand AGENTS.md "Issue Work Ownership" so agents claim issues before
    coding (not after a fix is ready), post a short comment when picking
    work up, and unclaim with a comment if they stop or hand off before a
    PR exists.
---
 AGENTS.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index b00cf410..8e073654 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -97,7 +97,11 @@ See [`docs/GLOSSARY.md`](docs/GLOSSARY.md) for the full term table and disambigu
 **`Printer` (slug @handle) vs `PrinterName` (display) — parallel pair, distinct from Owner/OwnerName.** `APISpec` and `CLIManifest` carry a second slug-vs-display pair for printer attribution. `Printer` is the GitHub @handle of the human who originally ran the press (e.g. `mvanhorn`), drives the per-CLI README byline link and the library-side registry attribution, and reads `git config github.user`. `PrinterName` is the prose-shaped display name (e.g. `Matt Van Horn`), rendered as the README byline parenthetical, and reads raw `git config user.name`. Resolution is tiered for both: the existing manifest wins over git config, so regens by other contributors do not overwrite the original printer (mirrors `resolveOwnerForExisting`'s preserve-on-regen guarantee). When `Printer` is unset at `Generate()` time, the generator emits a stderr warning and leaves it empty; the publish skill (Step 6) refuses to publish empty or literal `"USER"`/`"user"` sentinel values. Distinct from `Owner`/`OwnerName` (which carry the API-spec / wrapper-author identity); the printer is the human, the owner is the API vendor or wrapper author.
 
 ## Issue Work Ownership
-When starting work from a GitHub issue, claim the issue before implementation: assign it to yourself, or to the GitHub user you are explicitly working on behalf of. If the issue already has an assignee, treat that as active ownership until you can determine otherwise from recent activity or direct confirmation. For a plausibly stale assignment, ask the current assignee by tagging them in an issue comment before taking over or reassigning the issue.
+When starting work from a GitHub issue, claim it before implementation — not after the fix is ready: assign the issue to yourself (or to the GitHub user you are explicitly working on behalf of) and post a short comment stating you are picking it up. Claim *before* you start coding so duplicate work is prevented at the moment it would otherwise begin; claiming after a PR is open is too late.
+
+If the issue already has an assignee, treat that as active ownership until you can determine otherwise from recent activity or direct confirmation. For a plausibly stale assignment, ask the current assignee by tagging them in an issue comment before taking over or reassigning the issue.
+
+If you stop, abandon, or hand off the work before opening a PR, unclaim the issue: remove the assignment and post a short comment so the next picker-upper knows it is free. You do not need to unclaim on successful completion — a merged PR closes the issue.
 
 ## Commit Style
 Format: `type(scope): description`. Both type and scope are required.

← a1d39bf3 fix(cli): seed template-var placeholders in verify mode (#93 · back to Cli Printing Press · fix(cli): infer resource-prefixed IDField from item-schema p 6cd57cc2 →