From 0ce35c04618054cbae1538384d6e1e51c6163f63 Mon Sep 17 00:00:00 2001 From: gavinbee <29419542+gavinbee@users.noreply.github.com> Date: Wed, 28 Oct 2026 00:18:03 -0400 Subject: [PATCH 1/3] Ask before acting in the author's name An agent works through its author's accounts, so what it posts or overwrites reads as the author's own words. Write that rule down: draft and ask before issues, comments, review replies, body edits and writes to shared documents or sheets, and before changing saved state; treat the author's request as the go-ahead; a yes covers one action. The work loop's "open an issue first" now says the agent drafts it for the author, and "When in doubt" no longer sends questions to issue or PR comments. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 21 ++++++++++++++++++--- CONTRIBUTING.md | 31 ++++++++++++++++++++++++++++++- 2 files changed, 48 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c58caab..952fd7f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,7 +43,8 @@ gcloud auth application-default login For **every** change: -1. **Open a GitHub issue first.** Describe the change. This is the unit of work. +1. **Open a GitHub issue first.** Describe the change. This is the unit of work. Draft it + for the author and post it on their yes (see [below](#acting-in-the-authors-name)). - *Exception:* a change small enough to explain itself — a typo, a doc clarification, recording a decision already made — may go straight to a PR. Label it `no-issue` and end the description with `NO-ISSUE: `. Use a real issue whenever the @@ -67,6 +68,20 @@ For **every** change: Do not push directly to `main`. Do not use `--no-verify` or otherwise skip hooks. Create new commits rather than amending already-pushed ones. +### Acting in the author's name + +You work through the author's accounts, so what you post or overwrite reads as theirs. Full +rule: [CONTRIBUTING.md](CONTRIBUTING.md#acting-in-the-authors-name). + +- **Draft and ask first** for issues, comments, review replies, issue or PR body edits, and + writes to shared documents or sheets. Show the exact text; post on a yes. +- **Ask first** before changing saved state: logging a tool in or out, replacing a credential. +- **When the author asks, do it.** "Open the PR" means open it, not hand back a link. +- **A yes covers one action.** It does not carry to the next post or run. +- Committing, pushing a branch and reading need no pause. +- No unasked-for status comments; report to the author directly. +- Check the repo's own `CONTRIBUTING.md` for which of its commands need asking. + ## 4. Code comments - **Aspirational / TODO comments must link to a GitHub issue.** A note that says "out of @@ -151,6 +166,6 @@ Edit `AGENTS.md`. The pointer files don't need changes. - **Don't widen scope.** If an issue says "fix X," fix X. Don't refactor unrelated code. - **Don't generalise away the Canada specifics.** They are load-bearing. -- **Ask the human** in the issue/PR comments if a requirement is ambiguous, rather than - guessing. +- **Ask the human** directly if a requirement is ambiguous, rather than guessing, and + not in issue or PR comments, which would post the question in their name. - For the full rationale of any rule above, read [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e9da05c..5e735a3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,7 +30,8 @@ explicitly overrides it. 1. **Open an issue first.** Describe the problem or feature. This is the unit of work. See [the `no-issue` exception](#the-no-issue-exception) for changes small enough to - skip this. + skip this. An agent drafts the issue for its author to read before it is posted; see + [acting in the author's name](#acting-in-the-authors-name). 2. **Branch** off `main`, named `-` (e.g. `42-fix-date-parsing`), or a descriptive slug when there is no issue. 3. **Do the work.** Keep commits coherent. Run tests + lint locally before pushing. @@ -57,6 +58,34 @@ explicitly overrides it. deletes the branch. The squash commit message should carry the meaningful detail, not just the PR title. +### Acting in the author's name + +An agent works through its author's accounts: `gh`, `gcloud`, a tool's saved login. Whatever +it posts, overwrites or changes there appears as the author's own doing, to people who will +read it as the author's words. Closing an issue does not un-post it. + +- **Draft, then ask, before anything visible goes out in the author's name:** issues, + issue and PR comments, review replies, edits to an issue or PR body, and writes to shared + documents or sheets. Show the exact text, or say exactly what will be overwritten, and + wait for a yes. "File an issue for X" settles that the issue exists, not what it says. A + documented step such as "open an issue first" is not the go-ahead either. +- **Changes to the author's saved state need asking too:** logging a tool in or out, or + replacing a stored credential. +- **When the author asks for it, that is the go-ahead.** "Open the PR" or "post the + replies" means do it, not hand back a link to click. Asking a second time reads as not + listening. +- **A yes covers what was asked about, once.** Approving one post or one run does not + approve the next. +- **No pause needed** for committing, pushing a branch, or reading what the task needs. + These are visible, but they are not phrased as the author's own statement. +- **No unasked-for status comments.** Report finished work to the author directly, and let + them close their own issues. +- **If a plan changes after something is posted,** say so promptly rather than quietly + cleaning up. + +A repo whose tools write somewhere shared says which of its commands need asking first, in +its own `CONTRIBUTING.md`. + ### The `no-issue` exception A change small enough to explain itself — a typo, a doc clarification, recording a decision From de3634b048121fe5c37f8f85e7160e74ca8ef586 Mon Sep 17 00:00:00 2001 From: gavinbee <29419542+gavinbee@users.noreply.github.com> Date: Wed, 28 Oct 2026 00:20:10 -0400 Subject: [PATCH 2/3] Keep the rule in AGENTS.md, where agent guidance belongs Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 36 +++++++++++++++++++++++++----------- CONTRIBUTING.md | 31 +------------------------------ 2 files changed, 26 insertions(+), 41 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 952fd7f..d91c750 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -70,17 +70,31 @@ commits rather than amending already-pushed ones. ### Acting in the author's name -You work through the author's accounts, so what you post or overwrite reads as theirs. Full -rule: [CONTRIBUTING.md](CONTRIBUTING.md#acting-in-the-authors-name). - -- **Draft and ask first** for issues, comments, review replies, issue or PR body edits, and - writes to shared documents or sheets. Show the exact text; post on a yes. -- **Ask first** before changing saved state: logging a tool in or out, replacing a credential. -- **When the author asks, do it.** "Open the PR" means open it, not hand back a link. -- **A yes covers one action.** It does not carry to the next post or run. -- Committing, pushing a branch and reading need no pause. -- No unasked-for status comments; report to the author directly. -- Check the repo's own `CONTRIBUTING.md` for which of its commands need asking. +You work through the author's accounts: `gh`, `gcloud`, a tool's saved login. Whatever you +post, overwrite or change there appears as the author's own doing, to people who will read +it as the author's words. Closing an issue does not un-post it. + +- **Draft, then ask, before anything visible goes out in the author's name:** issues, + issue and PR comments, review replies, edits to an issue or PR body, and writes to shared + documents or sheets. Show the exact text, or say exactly what will be overwritten, and + wait for a yes. "File an issue for X" settles that the issue exists, not what it says. + Step 1's "open an issue first" is not the go-ahead either. +- **Ask before changing the author's saved state:** logging a tool in or out, or replacing + a stored credential. +- **When the author asks for it, that is the go-ahead.** "Open the PR" or "post the + replies" means do it, not hand back a link to click. Asking a second time reads as not + listening. +- **A yes covers what was asked about, once.** Approving one post or one run does not + approve the next. +- **No pause needed** for committing, pushing a branch, or reading what the task needs. + These are visible, but they are not phrased as the author's own statement. +- **No unasked-for status comments.** Report finished work to the author directly, and let + them close their own issues. +- **If a plan changes after something is posted,** say so promptly rather than quietly + cleaning up. + +A repo whose tools write somewhere shared lists which of its commands need asking first in +its own `AGENTS.md`. ## 4. Code comments diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e735a3..e9da05c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,8 +30,7 @@ explicitly overrides it. 1. **Open an issue first.** Describe the problem or feature. This is the unit of work. See [the `no-issue` exception](#the-no-issue-exception) for changes small enough to - skip this. An agent drafts the issue for its author to read before it is posted; see - [acting in the author's name](#acting-in-the-authors-name). + skip this. 2. **Branch** off `main`, named `-` (e.g. `42-fix-date-parsing`), or a descriptive slug when there is no issue. 3. **Do the work.** Keep commits coherent. Run tests + lint locally before pushing. @@ -58,34 +57,6 @@ explicitly overrides it. deletes the branch. The squash commit message should carry the meaningful detail, not just the PR title. -### Acting in the author's name - -An agent works through its author's accounts: `gh`, `gcloud`, a tool's saved login. Whatever -it posts, overwrites or changes there appears as the author's own doing, to people who will -read it as the author's words. Closing an issue does not un-post it. - -- **Draft, then ask, before anything visible goes out in the author's name:** issues, - issue and PR comments, review replies, edits to an issue or PR body, and writes to shared - documents or sheets. Show the exact text, or say exactly what will be overwritten, and - wait for a yes. "File an issue for X" settles that the issue exists, not what it says. A - documented step such as "open an issue first" is not the go-ahead either. -- **Changes to the author's saved state need asking too:** logging a tool in or out, or - replacing a stored credential. -- **When the author asks for it, that is the go-ahead.** "Open the PR" or "post the - replies" means do it, not hand back a link to click. Asking a second time reads as not - listening. -- **A yes covers what was asked about, once.** Approving one post or one run does not - approve the next. -- **No pause needed** for committing, pushing a branch, or reading what the task needs. - These are visible, but they are not phrased as the author's own statement. -- **No unasked-for status comments.** Report finished work to the author directly, and let - them close their own issues. -- **If a plan changes after something is posted,** say so promptly rather than quietly - cleaning up. - -A repo whose tools write somewhere shared says which of its commands need asking first, in -its own `CONTRIBUTING.md`. - ### The `no-issue` exception A change small enough to explain itself — a typo, a doc clarification, recording a decision From 21bbe3331cf2c6a90a6850d63765e25044321e2f Mon Sep 17 00:00:00 2001 From: gavinbee <29419542+gavinbee@users.noreply.github.com> Date: Wed, 28 Oct 2026 00:24:22 -0400 Subject: [PATCH 3/3] Make per-repo command lists a should, with a default when a repo has none From review on #59. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d91c750..6149b2e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -93,8 +93,9 @@ it as the author's words. Closing an issue does not un-post it. - **If a plan changes after something is posted,** say so promptly rather than quietly cleaning up. -A repo whose tools write somewhere shared lists which of its commands need asking first in -its own `AGENTS.md`. +A repo whose own commands can post, overwrite something shared, or change saved state +should say in its `AGENTS.md` which of them you may run without asking (`semotion-sync` +does). Where a repo does not say, ask before running any command that does one of those. ## 4. Code comments