From bea626456a45c97ef37368a0a032ea2cc5df53a6 Mon Sep 17 00:00:00 2001 From: krishicks Date: Wed, 19 Aug 2026 20:33:23 +0000 Subject: [PATCH] docs(agent): always accept maintainer-authored issues Signed-off-by: Kris Hicks --- .agents/skills/build-from-issue/SKILL.md | 31 +++++++++++++++------ .agents/skills/create-github-issue/SKILL.md | 2 +- .agents/skills/sync-agent-infra/SKILL.md | 7 +++-- .agents/skills/triage-issue/SKILL.md | 8 ++++-- AGENTS.md | 4 +-- CONTRIBUTING.md | 28 +++++++++---------- 6 files changed, 49 insertions(+), 31 deletions(-) diff --git a/.agents/skills/build-from-issue/SKILL.md b/.agents/skills/build-from-issue/SKILL.md index 06d1324b02..e9c2964fc8 100644 --- a/.agents/skills/build-from-issue/SKILL.md +++ b/.agents/skills/build-from-issue/SKILL.md @@ -59,11 +59,13 @@ Fetch issue + comments ├─ topic:security present? │ → Route to review-security-issue or fix-security-issue; STOP │ - ├─ Triage incomplete, awaiting information, or awaiting human disposition? + ├─ state:needs-info present? │ → Report the blocking state and STOP │ ├─ state:accepted and roadmap association both absent? - │ → Human has not accepted the issue; STOP + │ → Check whether the author currently has repository maintain/admin permission + │ → If verified, treat maintainer authorship as acceptance and continue + │ → Otherwise, human has not accepted the issue; STOP │ ├─ No plan comment and no direct planning request and agent:plan-requested absent? │ → No request for agent planning; STOP @@ -109,13 +111,17 @@ If the issue is closed, report that and stop. If `topic:security` is present, stop. General build agents must not plan or implement security issues. Route planning/review to `review-security-issue` and authorized remediation to `fix-security-issue`. -Stop before planning in any of these states: +Always stop before planning when `state:needs-info` is present because triage is waiting for evidence from the reporter. -- `state:triage-needed`: the issue has not been assessed; use `triage-issue`. -- `state:needs-info`: triage is waiting for evidence from the reporter. -- `state:validated` without roadmap placement: triage is complete, but a human has not yet decided whether OpenShell should invest in the work. +Next, require a human acceptance signal: `state:accepted`, placement on the roadmap, or verified maintainer authorship. When the first two signals are absent, get the issue author's login from the fetched issue and query their current repository permission: -Next, require a human acceptance signal: either `state:accepted` or placement on the roadmap. The label records acceptance without requiring scheduling; roadmap placement records acceptance and sequencing. If no plan exists, require either a direct user request for planning or the human-applied `agent:plan-requested` label before generating one. Never add or remove `state:accepted`, either human request label, or the `roadmap` label. +```bash +gh api repos/{owner}/{repo}/collaborators//permission --jq '.permission' +``` + +Treat only `maintain` or `admin` as verified maintainer authorship. This records acceptance without requiring a state label, but it does not record roadmap sequencing or authorize an unattended phase. Fail closed if the permission lookup fails or returns any other value. For issues without verified maintainer authorship, stop on `state:triage-needed`, or on `state:validated` without roadmap placement, as work still awaits assessment or human disposition. + +If no plan exists, require either a direct user request for planning or the human-applied `agent:plan-requested` label before generating one. Never add or remove `state:accepted`, either human request label, or the `roadmap` label. ## Step 2: Fetch and Classify Comments @@ -140,7 +146,7 @@ Using the state machine above, determine what to do based on: 1. Whether a plan comment exists 2. Whether there are human comments newer than the last agent comment (plan or conversation) 3. Whether this is direct mode and which phase the user requested -4. Which disposition, roadmap, and agent-workflow labels are present (`state:accepted`, `agent:plan-requested`, `agent:plan-ready`, `agent:implementation-requested`, `agent:in-progress`, `agent:pr-opened`, and the `roadmap` label) +4. Which acceptance signals are present (`state:accepted`, roadmap placement, or verified maintainer authorship) and which agent-workflow labels are present (`agent:plan-requested`, `agent:plan-ready`, `agent:implementation-requested`, `agent:in-progress`, and `agent:pr-opened`) Follow the appropriate branch below. @@ -727,6 +733,15 @@ User says: "Build issue #42" 12. No agent-workflow label transition is needed 13. Report PR URL and workflow run status to user +### Run on a maintainer-authored issue without an acceptance label + +User says: "Build issue #42" + +1. Fetch issue #42 — neither `state:accepted` nor roadmap placement is present +2. Query the author's current repository permission and receive `maintain` or `admin` +3. Treat maintainer authorship as the human acceptance signal +4. Continue through planning and implementation using the direct request as phase authorization; do not add an acceptance or agent-workflow label + ### Run on issue with existing PR User says: "Build issue #42" diff --git a/.agents/skills/create-github-issue/SKILL.md b/.agents/skills/create-github-issue/SKILL.md index 609d55ad15..92050e2017 100644 --- a/.agents/skills/create-github-issue/SKILL.md +++ b/.agents/skills/create-github-issue/SKILL.md @@ -123,7 +123,7 @@ EOF GitHub built-in issue types (`Bug`, `Feature`, `Task`) should come from the matching issue template when possible, or be set manually afterward. Do not try to emulate them through labels. -Creating an issue does not accept it or queue agent work. Agents never apply `state:accepted`, the `roadmap` label, add issues to the roadmap project, or apply `agent:plan-requested` or `agent:implementation-requested`. Community issues proceed through `triage-issue`; a human accepts technically validated work with `state:accepted` or roadmap placement. The request labels queue work for unattended agents; a user may instead direct an agent to a specific issue. +Creating an issue does not normally accept it or queue agent work. An issue authored by a user who currently has repository `maintain` or `admin` permission is implicitly accepted without a separate state label. Agents never apply `state:accepted`, the `roadmap` label, add issues to the roadmap project, or apply `agent:plan-requested` or `agent:implementation-requested`. Community issues proceed through `triage-issue`; a human accepts technically validated work with `state:accepted` or roadmap placement. The request labels queue work for unattended agents; a user may instead direct an agent to a specific issue. ## Useful Options diff --git a/.agents/skills/sync-agent-infra/SKILL.md b/.agents/skills/sync-agent-infra/SKILL.md index bd01bfebde..416c7c4adc 100644 --- a/.agents/skills/sync-agent-infra/SKILL.md +++ b/.agents/skills/sync-agent-infra/SKILL.md @@ -11,7 +11,7 @@ Detect and fix drift across the agent-first infrastructure files. These files re |------|---------------| | `AGENTS.md` | Project identity, workflow chains, architecture overview, issue/PR conventions, skill maintenance pointer | | `CONTRIBUTING.md` | Skills table, workflow chains, "When to Open an Issue" guidance, skill references | -| `docs/resources/issue-lifecycle.mdx` | Human-facing issue states, roadmap decisions, and direct-versus-queued agent ownership | +| `CONTRIBUTING.md` issue lifecycle section | Human-facing issue states, roadmap decisions, acceptance signals, and direct-versus-queued agent ownership | | `README.md` | "Built With Agents" section, "Explore with your agent" skill references | | `.github/ISSUE_TEMPLATE/bug_report.yml` | Skill name references in diagnostic guidance | | `.github/ISSUE_TEMPLATE/feature_request.yml` | Skill name references in investigation guidance | @@ -88,7 +88,7 @@ The canonical workflow chains are defined in `AGENTS.md` under "## Workflow Chai ### Labels -The canonical label set is used by skills and templates. The key labels are: `state:triage-needed`, `state:needs-info`, `state:validated`, `state:accepted`, `agent:plan-requested`, `agent:plan-ready`, `agent:implementation-requested`, `agent:in-progress`, `agent:pr-opened`, `roadmap`, `topic:security`, `good first issue`, `help wanted`, `spike`, and the relevant `area:*`, `topic:*`, `integration:*`, and `test:*` labels. The `agent:*` request labels control unattended queue pickup; they are not prerequisites when a user directly asks an agent to work on a specific issue. +The canonical label set is used by skills and templates. The key labels are: `state:triage-needed`, `state:needs-info`, `state:validated`, `state:accepted`, `agent:plan-requested`, `agent:plan-ready`, `agent:implementation-requested`, `agent:in-progress`, `agent:pr-opened`, `roadmap`, `topic:security`, `good first issue`, `help wanted`, `spike`, and the relevant `area:*`, `topic:*`, `integration:*`, and `test:*` labels. The `agent:*` request labels control unattended queue pickup; they are not prerequisites when a user directly asks an agent to work on a specific issue. Verified issue authorship by a user with current repository `maintain` or `admin` permission is an acceptance signal that does not require a label. ## Step 2: Check Each File for Drift @@ -109,8 +109,9 @@ For each file in the table above, check for the following inconsistencies: ### Issue Lifecycle Documentation -1. **`docs/resources/issue-lifecycle.mdx`** — State, roadmap, and agent-workflow meanings must match `AGENTS.md` and `CONTRIBUTING.md`. +1. **`CONTRIBUTING.md` issue lifecycle section** — State, roadmap, acceptance-signal, and agent-workflow meanings must match `AGENTS.md`. 2. **Invocation modes** — The `agent:*` request labels must control unattended queue pickup without being presented as prerequisites for a direct user request to a specific agent. +3. **Maintainer authorship** — Guidance must consistently define current repository `maintain` or `admin` permission as implicit acceptance and require permission lookups to fail closed. ### `README.md` diff --git a/.agents/skills/triage-issue/SKILL.md b/.agents/skills/triage-issue/SKILL.md index ebd353d6f8..cd1f8ffeac 100644 --- a/.agents/skills/triage-issue/SKILL.md +++ b/.agents/skills/triage-issue/SKILL.md @@ -25,7 +25,7 @@ Triage establishes technical validity; it does not decide whether valid work bel OpenShell has no `priority:*` labels. Sequencing comes from association with an item on the OpenShell Roadmap, and that association is a maintainer decision. -`state:validated` means the factual assessment is complete and awaits human disposition. A human declines by closing the issue as not planned with a rationale, or accepts by applying `state:accepted`, placing the issue on the roadmap, or doing both as documented in `CONTRIBUTING.md`. Accepted work may remain human-owned. A maintainer can queue deeper agent investigation or planning with `agent:plan-requested`, or directly ask an agent to work on a specific issue. +`state:validated` means the factual assessment is complete and awaits human disposition. A human declines by closing the issue as not planned with a rationale, or accepts by applying `state:accepted`, placing the issue on the roadmap, or doing both as documented in `CONTRIBUTING.md`. An issue authored by a user who currently has repository `maintain` or `admin` permission already records that maintainer's acceptance without a separate state label. Accepted work may remain human-owned. A maintainer can queue deeper agent investigation or planning with `agent:plan-requested`, or directly ask an agent to work on a specific issue. The optional `agent:*` workflow controls unattended queue pickup: `agent:plan-requested` queues planning, and `agent:implementation-requested` queues implementation after plan review. A direct user instruction separately authorizes the phase it requests and does not require either label. @@ -98,7 +98,7 @@ Search the issue comments for the triage agent marker (`> **📋 triage-agent**` - **If the marker is found** and no subsequent human comments exist with new information or questions, report that the issue has already been triaged and stop. - **If the marker is found** but there are newer human comments with additional information, proceed to Step 3 to re-evaluate with the new context. -- **If a human already declined the issue, applied `state:accepted`, or placed it on the roadmap**, do not undo or reinterpret that decision. +- **If a human already declined the issue, applied `state:accepted`, placed it on the roadmap, or authored it with current repository `maintain` or `admin` permission**, do not undo or reinterpret that decision. - **If the marker is not found**, proceed to Step 3. ## Step 3: Check Report Completeness @@ -211,6 +211,8 @@ Post a structured comment with the triage marker: > `agent:plan-requested`. You can instead directly ask an agent to use > `create-spike` or `build-from-issue` on this issue. If no, close it as not > planned and record the rationale. + +For an issue with verified maintainer authorship, replace `Human Decision Required` with `Acceptance Recorded`, state that maintainer authorship already records acceptance, and retain only the ownership, sequencing, and agent-authorization choices. ``` For other outcomes, replace the impact and decision sections with the exact information request, objective resolution, or safe routing guidance. @@ -228,7 +230,7 @@ Community issue filed | state:validated | - human decline OR state:accepted / roadmap placement + human decline OR state:accepted / roadmap placement / maintainer authorship | create-spike (if deeper investigation is approved) | diff --git a/AGENTS.md b/AGENTS.md index bd532c1971..15f1492415 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +17,7 @@ Agent skills live in `.agents/skills/`. Your harness can discover and load them These pipelines connect skills into end-to-end workflows. Individual skill files don't describe these relationships. - **Community inflow:** `triage-issue` → human disposition and roadmap placement → `create-spike` when needed → `build-from-issue` - - Triage establishes facts and marks technically valid issues `state:validated`. A human signals that the project should pursue the work by applying `state:accepted` or placing the issue on the roadmap. The `agent:*` labels support unattended agents that scan for queued work: a human queues a plan with `agent:plan-requested`, the agent returns `agent:plan-ready`, and a human queues implementation with `agent:implementation-requested`. A direct user request to an agent authorizes the requested phase without those labels. + - Triage establishes facts and marks technically valid issues `state:validated`. A human signals that the project should pursue the work by applying `state:accepted`, placing the issue on the roadmap, or authoring the issue while holding repository `maintain` or `admin` permission. The `agent:*` labels support unattended agents that scan for queued work: a human queues a plan with `agent:plan-requested`, the agent returns `agent:plan-ready`, and a human queues implementation with `agent:implementation-requested`. A direct user request to an agent authorizes the requested phase without those labels. - **Internal development:** `create-spike` → human disposition and roadmap placement → `build-from-issue` - Spike explores feasibility and marks its issue `state:validated` when sufficient evidence exists. A human accepts it with `state:accepted` or roadmap placement, or declines it, and optionally queues it through the `agent:*` workflow or directs an agent to it. - **Security:** `review-security-issue` → `fix-security-issue` @@ -79,7 +79,7 @@ These pipelines connect skills into end-to-end workflows. Individual skill files - **Bug reports and feature requests** must include a User Story, Problem Statement, Impact / Why This Matters, and Acceptance Criteria. The impact should explain the consequences of the current behavior, the current workaround, and why that workaround is insufficient. Bug reports additionally require reproduction steps and environment details and may include concise, redacted logs. - **Feature requests** must also include a Proposed Design and Alternatives Considered. The design should define the user-facing workflow and externally observable behavior while leaving internal implementation choices open. Agent investigation is optional. - **New features** must start as GitHub issues using the feature request template. Open an RFC only after an issue exists; maintainers decide when one is needed and assign RFC numbers from the issue. -- **Issue triage** establishes technical validity and impact evidence. Agents never decide acceptance, apply `state:accepted`, place issues on the roadmap, or apply `agent:plan-requested` or `agent:implementation-requested`. Humans accept or decline validated work; `state:accepted` or roadmap placement records acceptance, and roadmap association additionally carries sequencing. The request labels queue work for unattended agents; an explicit user instruction can instead authorize an agent to plan or implement a specific issue. OpenShell has no `priority:*` labels. +- **Issue triage** establishes technical validity and impact evidence. Agents never decide acceptance, apply `state:accepted`, place issues on the roadmap, or apply `agent:plan-requested` or `agent:implementation-requested`. Humans accept or decline validated work; `state:accepted`, roadmap placement, or issue authorship by a user who currently has repository `maintain` or `admin` permission records acceptance. Maintainer authorship does not record sequencing or authorize an unattended phase. Agents must verify the author's current repository permission through GitHub and fail closed if the lookup fails. The request labels queue work for unattended agents; an explicit user instruction can instead authorize an agent to plan or implement a specific issue. OpenShell has no `priority:*` labels. - **PRs** must follow the PR template structure: Summary, Related Issue, Changes, Testing, Checklist. Contributors should use their agent to investigate the current code and behavior for accepted issue-backed work, verify any diagnostics already on the issue, understand the change they submit, and report the resulting implementation and verification—not paste an earlier issue-filing diagnostic. - **PRs for features, user-visible behavior, public APIs, architecture, or multi-PR efforts** must link an accepted issue. Small docs fixes, mechanical maintenance, and obvious localized bug fixes may state why no issue is required. - **PRs from unvouched external contributors** are automatically closed. See the Vouch System section above. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cc52782560..cd211e9d28 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,7 +34,7 @@ We use a vouch system. This exists because AI makes it trivial to generate plaus Issues labeled [`good first issue`](https://github.com/NVIDIA/OpenShell/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) are scoped, well-documented, and friendly to new contributors. Start there. If you need guidance, comment on the issue. -An open issue is not necessarily accepted or ready to be worked on. Human contributors should look for `state:accepted`, roadmap placement, `good first issue`, or `help wanted`, or ask a maintainer before starting. Unattended agents additionally require the appropriate human-applied `agent:*` request label; an agent directly asked to work on a specific issue does not. +An open issue is not necessarily accepted or ready to be worked on. Human contributors should look for `state:accepted`, roadmap placement, `good first issue`, or `help wanted`, or ask a maintainer before starting. An issue authored by a user who currently has repository `maintain` or `admin` permission is also accepted without a separate state label. Unattended agents additionally require the appropriate human-applied `agent:*` request label; an agent directly asked to work on a specific issue does not. ## Before You Open an Issue @@ -118,11 +118,11 @@ Each issue can require four independent decisions: | Decision | Question | Recorded by | |---|---|---| | Assessment | Is the report technically valid, and is there enough evidence to act on it? | `state:*` | -| Disposition | Should OpenShell pursue the work? | `state:accepted`, roadmap placement, or closure as not planned | +| Disposition | Should OpenShell pursue the work? | `state:accepted`, roadmap placement, maintainer authorship, or closure as not planned | | Sequencing | Where does accepted work sit relative to everything else? | Placement on the [OpenShell Roadmap](https://github.com/orgs/NVIDIA/projects/233) | | Ownership | Will a human implement the issue, will a user directly instruct an agent, or will a maintainer queue it for an unattended agent? | Direct instruction or optional `agent:*` workflow | -`state:validated` confirms that the factual assessment is complete, but it does not mean the project has accepted the work. A maintainer signals acceptance with `state:accepted` or roadmap placement. Roadmap placement also communicates sequencing, but it does not assign an owner or queue an unattended agent. +`state:validated` confirms that the factual assessment is complete, but it does not mean the project has accepted the work. A maintainer signals acceptance with `state:accepted`, roadmap placement, or by authoring the issue while holding repository `maintain` or `admin` permission. Roadmap placement also communicates sequencing, but neither a state label nor maintainer authorship assigns an owner or queues an unattended agent. #### Who Controls Each Decision @@ -133,7 +133,7 @@ Agents investigate issues, collect evidence, and report technical findings. Huma | Assess technical validity and impact | Triage agent or human triager | | Request missing evidence | Triage agent or human triager | | Mark the assessment complete with `state:validated` | Triage agent or human triager | -| Accept or decline the work with `state:accepted`, roadmap placement, or closure | Maintainer | +| Accept or decline the work with `state:accepted`, roadmap placement, maintainer authorship, or closure | Maintainer | | Place the issue on the roadmap or move it | Maintainer | | Directly request an agent plan | User | | Queue an agent plan with `agent:plan-requested` | Maintainer | @@ -141,11 +141,11 @@ Agents investigate issues, collect evidence, and report technical findings. Huma | Directly request agent implementation | User | | Queue approved implementation with `agent:implementation-requested` | Maintainer | -Agents do not apply `state:accepted`, place issues on the roadmap, or apply `agent:plan-requested` or `agent:implementation-requested`. +Agents do not apply `state:accepted`, place issues on the roadmap, or apply `agent:plan-requested` or `agent:implementation-requested`. When relying on maintainer authorship as acceptance, an agent checks the issue author's current repository permission through GitHub. Only `maintain` and `admin` qualify; if the permission lookup fails, the agent requires another acceptance signal. #### Issue State -The `state:*` namespace records the issue's disposition for all contributors, regardless of who might implement it. +The `state:*` namespace normally records the issue's disposition for all contributors, regardless of who might implement it. Verified maintainer authorship can record acceptance without a state label. | State | Meaning | Normal next action | |---|---|---| @@ -154,7 +154,7 @@ The `state:*` namespace records the issue's disposition for all contributors, re | `state:validated` | The factual assessment is complete. | A maintainer accepts the issue, declines it, or asks for more evidence. | | `state:accepted` | A maintainer decided that OpenShell should pursue the issue. | A human may implement it, or a maintainer may delegate work to an agent. | -Keep one of these states on an open issue. When new evidence resolves a `state:needs-info` request, reassess the issue and move it to `state:validated` if the evidence is sufficient. +Keep one of these states on an open issue unless verified maintainer authorship records acceptance without a label. When new evidence resolves a `state:needs-info` request, reassess the issue and move it to `state:validated` if the evidence is sufficient. `state:stale` is an inactivity marker, not a lifecycle decision. Accepted issues and issues awaiting human disposition are exempt from stale handling. An issue in `state:needs-info` can become stale if no new evidence arrives. @@ -179,11 +179,11 @@ Triage establishes facts and impact. It does not decide whether the project shou When an issue reaches `state:validated`, a maintainer chooses one of three paths: -- **Accept:** apply `state:accepted`, place the issue on the roadmap, or do both. Either action signals that OpenShell should pursue the work; roadmap placement additionally records sequencing. +- **Accept:** apply `state:accepted`, place the issue on the roadmap, or do both. A maintainer may also record acceptance by authoring the issue directly. These signals mean that OpenShell should pursue the work; roadmap placement additionally records sequencing. - **Decline:** close it as not planned and record the rationale. - **Await more evidence:** replace `state:validated` with `state:needs-info` and leave it off the roadmap. -Do not use `state:accepted` as shorthand for technical validity, roadmap sequencing, or agent authorization. It records the human decision that OpenShell should pursue the work. Roadmap placement records the same acceptance decision plus sequencing. +Do not use `state:accepted` as shorthand for technical validity, roadmap sequencing, or agent authorization. It records the human decision that OpenShell should pursue the work. Maintainer authorship records the same acceptance decision without adding a label. Roadmap placement records acceptance plus sequencing. #### Roadmap @@ -212,7 +212,7 @@ Maintainers use the `agent:*` workflow to queue work for always-on or unattended The normal delegated workflow is: ```text -(state:accepted OR roadmap placement) +(state:accepted OR roadmap placement OR maintainer authorship) | +-- agent:plan-requested | @@ -256,11 +256,11 @@ A user may instead directly request review or remediation from the specialized s | You are | Ready when | |---|---| | A human contributor | The issue has `state:accepted`, roadmap placement, an invitation to contribute, or maintainer confirmation, and has no conflicting owner or implementation. | -| An unattended agent scanning for planning work | The issue has `state:accepted` or roadmap placement, plus the human-applied `agent:plan-requested` label. | -| An unattended agent scanning for implementation work | The issue has `state:accepted` or roadmap placement, plus an approved plan and the human-applied `agent:implementation-requested` label. | -| An agent directly instructed by a user | The issue has `state:accepted` or roadmap placement, no conflicting owner or implementation, and the instruction explicitly requests the phase the agent will perform. | +| An unattended agent scanning for planning work | The issue has `state:accepted`, roadmap placement, or verified maintainer authorship, plus the human-applied `agent:plan-requested` label. | +| An unattended agent scanning for implementation work | The issue has `state:accepted`, roadmap placement, or verified maintainer authorship, plus an approved plan and the human-applied `agent:implementation-requested` label. | +| An agent directly instructed by a user | The issue has `state:accepted`, roadmap placement, or verified maintainer authorship; has no conflicting owner or implementation; and the instruction explicitly requests the phase the agent will perform. | -Issues with `state:triage-needed`, `state:needs-info`, or `state:validated` are not ready for implementation unless a maintainer has separately placed them on the roadmap. Either `state:accepted` or roadmap placement records the required human acceptance decision. +`state:needs-info` always blocks implementation until the requested evidence arrives. For issues not authored by a maintainer, `state:triage-needed` and `state:validated` also block implementation unless a maintainer has separately placed the issue on the roadmap or applied `state:accepted`. Verified maintainer authorship records the required human acceptance decision without a state label. #### Stale Issues