docs(cli): clarify issue ownership workflow (#1414)

770b65a61ad98f5bba179a79874e738e1448075b · 2026-05-14 16:36:44 -0700 · Trevin Chow
Files touched

M AGENTS.md
Diff

commit 770b65a61ad98f5bba179a79874e738e1448075b
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Thu May 14 16:36:44 2026 -0700

    docs(cli): clarify issue ownership workflow (#1414)
---
 AGENTS.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 592184cc..19d7a2ac 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -97,7 +97,9 @@ 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 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.
+Contributor agents without maintainer or admin access must make sure a GitHub issue exists before fixing a bug or behavior change. Maintainers and admins may bypass these issue-ownership rules for maintainer-owned direct work. Do not treat a private plan, external doc, review artifact, or PR body as the only problem statement. Search open and recently closed issues first; reuse an existing issue when one matches instead of filing a duplicate. If no issue exists, open one with enough context for maintainers to understand the bug, scope, and intended fix.
+
+Before implementation, claim the issue: assign it 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. Assignment may fail because of permissions; that is fine, but still leave the claim comment. 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.
← 46ad86b2 fix(cli): stop generated main.go from printing every error t · back to Cli Printing Press · feat(cli): surface per-endpoint evidence and confidence from f32214ea →