diff --git a/.agents/skills/build-from-issue/SKILL.md b/.agents/skills/build-from-issue/SKILL.md index 0c63e2a2..4e73a61b 100644 --- a/.agents/skills/build-from-issue/SKILL.md +++ b/.agents/skills/build-from-issue/SKILL.md @@ -1,6 +1,6 @@ --- name: build-from-issue -description: Given a GitHub issue number, plan and implement the work described in the issue. Operates iteratively - creates an implementation plan, responds to feedback, and only builds when 'agent-ready' label is applied. Includes tests, documentation updates, and PR creation. Trigger keywords - build from issue, implement issue, work on issue, build issue, start issue. +description: Given a GitHub issue number, plan and implement the work described in the issue. Operates iteratively - creates an implementation plan, responds to feedback, and only builds when the 'state:agent-ready' label is applied. Includes tests, documentation updates, and PR creation. Trigger keywords - build from issue, implement issue, work on issue, build issue, start issue. --- # Build From Issue @@ -14,11 +14,11 @@ This skill operates as a stateful workflow — it can be run repeatedly against - The `gh` CLI must be authenticated (`gh auth status`) - You must be in a git repository with a GitHub remote -## Critical: `agent-ready` Label Is Human-Only +## Critical: `state:agent-ready` Label Is Human-Only -The `agent-ready` label is a **human gate**. It signals that a human has reviewed the plan and authorized the agent to build. Under **no circumstances** should this skill or any agent: +The `state:agent-ready` label is a **human gate**. It signals that a human has reviewed the plan and authorized the agent to build. Under **no circumstances** should this skill or any agent: -- Apply the `agent-ready` label +- Apply the `state:agent-ready` label - Ask the user to let the agent apply it - Suggest automating its application - Bypass the check by proceeding without it @@ -57,7 +57,7 @@ Fetch issue + comments ├─ No plan comment (🏗️ build-plan) found? │ → Generate plan via principal-engineer-reviewer │ → Post plan comment - │ → Add 'review-ready' label + │ → Add 'state:review-ready' label │ → STOP │ ├─ Plan exists + new human comments since last agent response? @@ -65,20 +65,20 @@ Fetch issue + comments │ → Update the plan comment if feedback requires plan changes │ → STOP │ - ├─ Plan exists + 'agent-ready' label + no 'in-progress' or 'pr-opened' label? + ├─ Plan exists + 'state:agent-ready' label + no 'state:in-progress' or 'state:pr-opened' label? │ → Run scope check (warn if high complexity) │ → Check for conflicting branches/PRs │ → BUILD (Steps 6–14) │ - ├─ 'in-progress' label present? + ├─ 'state:in-progress' label present? │ → Detect existing branch and resume if possible │ → Otherwise report current state │ - ├─ 'pr-opened' label present? + ├─ 'state:pr-opened' label present? │ → Report that PR already exists, link to it │ → STOP │ - └─ Plan exists + no new comments + no 'agent-ready'? + └─ Plan exists + no new comments + no 'state:agent-ready'? → Report: "Plan is posted and awaiting review. No new comments to address." → STOP ``` @@ -93,7 +93,7 @@ gh issue view --json number,title,body,state,labels,author If the issue is closed, report that and stop. -If the issue has the `needs-agent-triage` label, report that the issue has not been triaged yet. Suggest using the `triage-issue` skill first to assess and classify the issue before planning implementation. Stop. +If the issue has the `state:triage-needed` label, report that the issue has not been triaged yet. Suggest using the `triage-issue` skill first to assess and classify the issue before planning implementation. Stop. ## Step 2: Fetch and Classify Comments @@ -117,7 +117,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. Which labels are present (`review-ready`, `agent-ready`, `in-progress`, `pr-opened`) +3. Which labels are present (`state:review-ready`, `state:agent-ready`, `state:in-progress`, `state:pr-opened`) Follow the appropriate branch below. @@ -193,10 +193,10 @@ EOF )" ``` -### A3: Add the `review-ready` Label +### A3: Add the `state:review-ready` Label ```bash -gh issue edit --add-label "review-ready" +gh issue edit --add-label "state:review-ready" ``` Report to the user that the plan has been posted and is awaiting review. Stop. @@ -267,7 +267,7 @@ Report to the user what feedback was addressed and whether the plan was updated. ## Branch C: Build -If the plan exists and the `agent-ready` label is present (and neither `in-progress` nor `pr-opened` is set), proceed with implementation. +If the plan exists and the `state:agent-ready` label is present (and neither `state:in-progress` nor `state:pr-opened` is set), proceed with implementation. ### Step 4: Scope Check @@ -277,7 +277,7 @@ Read the plan comment and check the **Complexity** and **Confidence** fields. > "This issue is rated High complexity / Low confidence. The plan includes open questions that may need human decisions during implementation. Proceeding, but flagging this for your awareness." - Continue — do not hard-stop. The human chose to apply `agent-ready`. + Continue — do not hard-stop. The human chose to apply `state:agent-ready`. ### Step 5: Conflict Detection @@ -322,10 +322,10 @@ git pull origin main git checkout -b -/$USERNAME ``` -### Step 7: Add `in-progress` Label +### Step 7: Add `state:in-progress` Label ```bash -gh issue edit --add-label "in-progress" +gh issue edit --add-label "state:in-progress" ``` ### Step 8: Implement the Changes @@ -599,10 +599,10 @@ Include **every test** that ran (not just the new ones) so the reviewer can see #### Update labels -Remove `in-progress` and `review-ready`, add `pr-opened`: +Remove `state:in-progress` and `state:review-ready`, add `state:pr-opened`: ```bash -gh issue edit --remove-label "in-progress" --remove-label "review-ready" --add-label "pr-opened" +gh issue edit --remove-label "state:in-progress" --remove-label "state:review-ready" --add-label "state:pr-opened" ``` #### Report workflow run URL @@ -620,7 +620,7 @@ Report the workflow run URL and suggest the user can use the `watch-github-actio ## Branch D: Resume In-Progress Build -If the `in-progress` label is present, the skill was previously started but may not have completed. +If the `state:in-progress` label is present, the skill was previously started but may not have completed. 1. Check for an existing branch matching the issue ID: ```bash @@ -628,7 +628,7 @@ If the `in-progress` label is present, the skill was previously started but may ``` 2. If found, check it out and inspect the state (are there uncommitted changes? committed but not pushed? pushed but no PR?). 3. Resume from the appropriate step (9, 10, 12, or 13). -4. If the state is unrecoverable, report to the user and suggest starting fresh (remove `in-progress` label and re-run). +4. If the state is unrecoverable, report to the user and suggest starting fresh (remove `state:in-progress` label and re-run). --- @@ -660,7 +660,7 @@ User says: "Build from issue #42" 3. Pass issue to `principal-engineer-reviewer` for analysis 4. Reviewer produces a plan: feat type, Medium complexity, 3 implementation steps, unit + integration tests needed 5. Post the plan comment with the `🏗️ build-plan` marker -6. Add `review-ready` label +6. Add `state:review-ready` label 7. Report to user: "Plan posted on issue #42. Awaiting review." ### Second run — human left feedback @@ -683,15 +683,15 @@ User says: "Check issue #42" 4. Edit the plan comment to include search endpoint pagination — Revision 2 5. Report to user: "Updated plan to include search pagination (Revision 2)." -### Fourth run — agent-ready applied +### Fourth run — state:agent-ready applied User says: "Build issue #42" -1. Fetch issue #42 — labels include `agent-ready` +1. Fetch issue #42 — labels include `state:agent-ready` 2. Plan exists (Revision 2), complexity: Medium, confidence: High 3. No conflicting branches or PRs 4. Create branch `feat/42-add-pagination/jmyers` -5. Add `in-progress` label +5. Add `state:in-progress` label 6. Implement pagination for both endpoints per the plan 7. Add unit tests for pagination logic, integration tests for both endpoints 8. `mise run pre-commit` passes on first attempt @@ -699,14 +699,14 @@ User says: "Build issue #42" 10. `arch-doc-writer` updates `architecture/gateway.md` with pagination details 10. Commit, push, create PR with `Closes #42` 11. Post summary comment on issue with PR link -12. Update labels: remove `in-progress` + `review-ready`, add `pr-opened` +12. Update labels: remove `state:in-progress` + `state:review-ready`, add `state:pr-opened` 13. Report PR URL and workflow run status to user ### Run on issue with existing PR User says: "Build issue #42" -1. Fetch issue #42 — `pr-opened` label present +1. Fetch issue #42 — `state:pr-opened` label present 2. Find existing PR #789 linked to the issue 3. Report: "PR [#789](...) already exists for issue #42. Nothing to build." @@ -714,7 +714,7 @@ User says: "Build issue #42" User says: "Build issue #99" -1. Fetch issue #99 — `agent-ready` label present +1. Fetch issue #99 — `state:agent-ready` label present 2. Plan exists: complexity High, confidence Low, has open questions 3. Warn user: "Issue #99 is rated High complexity / Low confidence. Proceeding but flagging for your awareness." 4. Continue with build diff --git a/.agents/skills/create-github-issue/SKILL.md b/.agents/skills/create-github-issue/SKILL.md index 7e2fa38f..15063d2c 100644 --- a/.agents/skills/create-github-issue/SKILL.md +++ b/.agents/skills/create-github-issue/SKILL.md @@ -17,12 +17,11 @@ This project uses YAML form issue templates. When creating issues, match the tem ### Bug Reports -Use the `bug` label. The body must include an **Agent Diagnostic** section — this is required by the template and enforced by project convention. +Do not add a type label automatically. The body must include an **Agent Diagnostic** section — this is required by the template and enforced by project convention. Apply area or topic labels only when they are clearly known. ```bash gh issue create \ --title "bug: " \ - --label "bug" \ --body "$(cat <<'EOF' ## Agent Diagnostic @@ -57,12 +56,11 @@ EOF ### Feature Requests -Use the `feat` label. The body must include a **Proposed Design** — not a "please build this" request. +Do not add a type label automatically. The body must include a **Proposed Design** — not a "please build this" request. Apply area or topic labels only when they are clearly known. ```bash gh issue create \ --title "feat: " \ - --label "feat" \ --body "$(cat <<'EOF' ## Problem Statement @@ -107,6 +105,8 @@ 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. + ## Useful Options | Option | Description | diff --git a/.agents/skills/create-github-pr/SKILL.md b/.agents/skills/create-github-pr/SKILL.md index 56719901..63f8dd5a 100644 --- a/.agents/skills/create-github-pr/SKILL.md +++ b/.agents/skills/create-github-pr/SKILL.md @@ -141,7 +141,7 @@ gh pr create --draft --title "WIP: New feature" --assignee "@me" ### With Labels ```bash -gh pr create --title "Title" --label "component::evaluator" --label "bug" +gh pr create --title "Title" --label "area:cli" --label "topic:security" ``` ### Target a Different Branch diff --git a/.agents/skills/create-spike/SKILL.md b/.agents/skills/create-spike/SKILL.md index 29350c3a..faa7aca0 100644 --- a/.agents/skills/create-spike/SKILL.md +++ b/.agents/skills/create-spike/SKILL.md @@ -115,10 +115,10 @@ gh label list --limit 100 Based on the investigation results, select appropriate labels: -- **Always include the issue type** as a label (e.g., `feat`, `fix`, `refactor`, `chore`, `perf`, `docs`) -- **Include component labels** if they exist in the repo (e.g., `sandbox`, `proxy`, `policy`, `cli`) +- **Do not add issue type labels** — GitHub built-in issue types come from issue templates or manual follow-up, not labels +- **Include area labels** if they exist in the repo (e.g., `area:sandbox`, `area:proxy`, `area:policy`, `area:cli`) - **Do not invent labels** — only use labels that already exist in the repo -- **Add `review-ready`** — the issue is ready for human review upon creation +- **Add `state:review-ready`** — the issue is ready for human review upon creation ## Step 4: Create the GitHub Issue @@ -127,7 +127,7 @@ Create the issue with a structured body containing both the stakeholder-readable ```bash gh issue create \ --title ": " \ - --label "" --label "" --label "review-ready" \ + --label "" --label "state:review-ready" \ --body "$(cat <<'EOF' ## Problem Statement @@ -259,7 +259,7 @@ User says: "Allow sandbox egress to private IP space via networking policy" - Reads `architecture/security-policy.md` and `architecture/sandbox.md` - Identifies exact insertion points: policy field addition, SSRF check bypass path, OPA rule extension - Assesses: Medium complexity, High confidence, ~6 files -3. Fetch labels — select `feat`, `sandbox`, `proxy`, `policy`, `review-ready` +3. Fetch labels — select `area:sandbox`, `area:proxy`, `area:policy`, `state:review-ready` 4. Create issue: `feat: allow sandbox egress to private IP space via networking policy` — body includes both the summary and full investigation (code references, architecture context, alternative approaches) 5. Report: "Created issue #59. The investigation found that private IP blocking is enforced at the SSRF check layer in the proxy. The proposed approach adds a policy-level override. Review the issue and use `build-from-issue` when ready." @@ -275,7 +275,7 @@ User says: "The proxy retry logic seems too aggressive — I'm seeing cascading - Maps the failure propagation path - Identifies that retries happen without backoff jitter, causing thundering herd - Assesses: Low complexity, High confidence, ~2 files -3. Fetch labels — select `fix`, `proxy`, `review-ready` +3. Fetch labels — select `area:proxy`, `state:review-ready` 4. Create issue: `fix: proxy retry logic causes cascading failures under load` — body includes both the summary and full investigation (retry code references, current behavior trace, comparison to standard backoff patterns) 5. Report: "Created issue #74. The proxy retries without jitter or circuit breaking, which amplifies failures under load. Straightforward fix. Review and use `build-from-issue` when ready." @@ -291,6 +291,6 @@ User says: "Policy evaluation is getting slow — can we cache compiled OPA poli - Reads the policy reload/hot-swap mechanism - Identifies that policies are recompiled on every evaluation - Assesses: Medium complexity, Medium confidence (cache invalidation is a design decision), ~4 files -3. Fetch labels — select `perf`, `policy`, `review-ready` +3. Fetch labels — select `area:policy`, `state:review-ready` 4. Create issue: `perf: cache compiled OPA policies to reduce evaluation latency` — body includes both the summary and full investigation (compilation hot path, per-request overhead, cache invalidation strategies with trade-offs) 5. Report: "Created issue #81. Policies are recompiled per-request with no caching. The main design decision is the cache invalidation strategy — flagged as an open question. Review and use `build-from-issue` when ready." diff --git a/.agents/skills/fix-security-issue/SKILL.md b/.agents/skills/fix-security-issue/SKILL.md index b8c8b423..7df9b417 100644 --- a/.agents/skills/fix-security-issue/SKILL.md +++ b/.agents/skills/fix-security-issue/SKILL.md @@ -1,6 +1,6 @@ --- name: fix-security-issue -description: Implement a fix for a reviewed security issue. Takes an issue number or scans for issues labeled "security" and "agent-ready". Reads the security review from the issue comments and implements the remediation plan. Trigger keywords - fix security issue, remediate security, implement security fix, patch vulnerability. +description: Implement a fix for a reviewed security issue. Takes an issue number or scans for issues labeled "topic:security" and "state:agent-ready". Reads the security review from the issue comments and implements the remediation plan. Trigger keywords - fix security issue, remediate security, implement security fix, patch vulnerability. --- # Fix Security Issue @@ -11,7 +11,7 @@ Implement a code fix for a security issue that has already been reviewed by the - The `gh` CLI must be authenticated (`gh auth status`) - You must be in a git repository with a GitHub remote -- The issue **must** have both the `security` and `agent-ready` labels. If either is missing, do not proceed. +- The issue **must** have both the `topic:security` and `state:agent-ready` labels. If either is missing, do not proceed. - The issue must have a prior security review comment (posted by `review-security-issue`) with a **Legitimate concern** determination and a remediation plan ## Agent Comment Marker @@ -34,10 +34,10 @@ Strip any leading `#` and proceed to Step 2 with that issue ID. ### If no issue number is provided -Scan for open issues labeled `security` and `agent-ready`: +Scan for open issues labeled `topic:security` and `state:agent-ready`: ```bash -gh issue list --label "security" --label "agent-ready" --state open --json number,title,labels,updatedAt +gh issue list --label "topic:security" --label "state:agent-ready" --state open --json number,title,labels,updatedAt ``` - **If no issues are found**, report to the user that there are no security issues ready for fixing and stop. @@ -52,18 +52,18 @@ Fetch the issue details: gh issue view --json number,title,body,state,labels,author ``` -### Require both `security` and `agent-ready` labels +### Require both `topic:security` and `state:agent-ready` labels **This is a hard gate.** Check the issue's `labels` array from the response above. Both of the following labels **must** be present: -- `security` -- `agent-ready` +- `topic:security` +- `state:agent-ready` If **either label is missing**, do **not** proceed. Report to the user which label(s) are missing and stop. For example: -- Missing `agent-ready`: "Issue #42 has the `security` label but is not marked `agent-ready`. It may still need review or human triage before a fix can be implemented." -- Missing `security`: "Issue #42 is marked `agent-ready` but does not have the `security` label. This skill only handles security issues." -- Missing both: "Issue #42 is missing both the `security` and `agent-ready` labels. Cannot proceed." +- Missing `state:agent-ready`: "Issue #42 has the `topic:security` label but is not marked `state:agent-ready`. It may still need review or human triage before a fix can be implemented." +- Missing `topic:security`: "Issue #42 is marked `state:agent-ready` but does not have the `topic:security` label. This skill only handles security issues." +- Missing both: "Issue #42 is missing both the `topic:security` and `state:agent-ready` labels. Cannot proceed." **Do not offer to add the labels or bypass this check.** The labels are a deliberate human-controlled gate. @@ -208,7 +208,7 @@ Create a PR that closes the security issue. Put the full fix summary in the PR d gh pr create \ --title "fix(security): " \ --assignee "@me" \ - --label "security" \ + --label "topic:security" \ --body "$(cat <<'EOF' > **🔧 security-fix-agent** @@ -262,7 +262,7 @@ Summarize what was done: | Command | Description | | --- | --- | -| `gh issue list --label "security" --label "agent-ready" --state open` | Find open security issues ready for fixing | +| `gh issue list --label "topic:security" --label "state:agent-ready" --state open` | Find open security issues ready for fixing | | `gh issue view --json number,title,body,state,labels,author` | Fetch full issue metadata | | `gh issue view --json comments` | Fetch all comments on an issue | | `gh pr create --title "..." --body "..."` | Create a pull request | @@ -290,7 +290,7 @@ User says: "Fix security issue #42" User says: "Fix any ready security issues" -1. Query for open issues with labels `security` + `agent-ready` +1. Query for open issues with labels `topic:security` + `state:agent-ready` 2. Find issue #78: "SQL injection in search endpoint" 3. Fetch the review comment -- determination is "Legitimate concern" 4. Implement parameterized queries @@ -307,20 +307,20 @@ User says: "Fix security issue #99" 3. Report to the user: "Issue #99 was reviewed and determined to be not actionable. No fix is needed." 4. Stop -### Issue missing `agent-ready` label +### Issue missing `state:agent-ready` label User says: "Fix security issue #55" 1. Fetch issue #55 metadata -2. Labels are `["security"]` -- missing `agent-ready` -3. Report to the user: "Issue #55 has the `security` label but is not marked `agent-ready`. It may still need review or human triage before a fix can be implemented." +2. Labels are `["topic:security"]` -- missing `state:agent-ready` +3. Report to the user: "Issue #55 has the `topic:security` label but is not marked `state:agent-ready`. It may still need review or human triage before a fix can be implemented." 4. Stop ### Issue without a review User says: "Fix security issue #60" -1. Fetch issue #60 metadata -- labels include both `security` and `agent-ready` +1. Fetch issue #60 metadata -- labels include both `topic:security` and `state:agent-ready` 2. Fetch comments -- no `security-review-agent` comment found 3. Report to the user: "Issue #60 has not been reviewed yet. Run the review-security-issue skill first." 4. Stop diff --git a/.agents/skills/review-security-issue/SKILL.md b/.agents/skills/review-security-issue/SKILL.md index 0445774b..caac9fd1 100644 --- a/.agents/skills/review-security-issue/SKILL.md +++ b/.agents/skills/review-security-issue/SKILL.md @@ -40,7 +40,7 @@ gh issue view --json title,body,state,labels,author First, check the issue's labels from the metadata fetched in Step 1. -- **If the issue has the `agent-ready` label**, the issue has already been reviewed and is ready for implementation. There is no review to perform. Report to the user that this issue is already reviewed and marked as agent-ready, and suggest using the `fix-security-issue` skill instead. Stop. +- **If the issue has the `state:agent-ready` label**, the issue has already been reviewed and is ready for implementation. There is no review to perform. Report to the user that this issue is already reviewed and marked as `state:agent-ready`, and suggest using the `fix-security-issue` skill instead. Stop. Next, fetch existing comments on the issue: @@ -133,12 +133,12 @@ EOF )" ``` -## Step 5: Add `review-ready` Label +## Step 5: Add `state:review-ready` Label -After posting the review comment (whether legitimate or not actionable), add the `review-ready` label to the issue: +After posting the review comment (whether legitimate or not actionable), add the `state:review-ready` label to the issue: ```bash -gh issue edit --add-label "review-ready" +gh issue edit --add-label "state:review-ready" ``` This signals to humans and downstream skills (e.g., `fix-security-issue`) that the review is complete. @@ -163,7 +163,7 @@ For each unanswered human comment: | `gh issue view --json title,body,state,labels,author` | Fetch full issue metadata as JSON | | `gh issue view --json comments --jq '.comments[].body'` | Fetch all comments on an issue | | `gh issue comment --body "..."` | Post a comment on an issue | -| `gh issue edit --add-label "review-ready"` | Add a label to an issue | +| `gh issue edit --add-label "state:review-ready"` | Add a label to an issue | ## Example Usage @@ -176,7 +176,7 @@ User says: "Review security issue #42" 3. No prior review found -- pass issue to `principal-engineer-reviewer` with security lens 4. Reviewer determines it's a legitimate XSS vulnerability in the API response handler 5. Post a comment with severity assessment and remediation plan -6. Add the `review-ready` label to the issue +6. Add the `state:review-ready` label to the issue 7. Report the finding and posted comment to the user ### Re-review with new comments diff --git a/.agents/skills/sync-agent-infra/SKILL.md b/.agents/skills/sync-agent-infra/SKILL.md index 4139bdc7..2c87dd41 100644 --- a/.agents/skills/sync-agent-infra/SKILL.md +++ b/.agents/skills/sync-agent-infra/SKILL.md @@ -18,7 +18,7 @@ Detect and fix drift across the agent-first infrastructure files. These files re | `.github/workflows/issue-triage.yml` | Comment text referencing skills | | `.agents/skills/triage-issue/SKILL.md` | Skill name references in gate check and diagnosis steps | | `.agents/skills/openshell-cli/SKILL.md` | Companion skills table | -| `.agents/skills/build-from-issue/SKILL.md` | `needs-agent-triage` label awareness | +| `.agents/skills/build-from-issue/SKILL.md` | `state:triage-needed` label awareness | ## When to Run @@ -60,7 +60,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: `agent-ready`, `review-ready`, `in-progress`, `pr-opened`, `security`, `bug`, `feat`, `needs-agent-triage`, `good-first-issue`, `spike`. +The canonical label set is used by skills and templates. The key labels are: `state:agent-ready`, `state:review-ready`, `state:in-progress`, `state:pr-opened`, `state:triage-needed`, `topic:security`, `good first issue`, `spike`, and the relevant `area:*`, `topic:*`, `integration:*`, and `test:*` labels. ## Step 2: Check Each File for Drift diff --git a/.agents/skills/triage-issue/SKILL.md b/.agents/skills/triage-issue/SKILL.md index 083dcdd8..e4998a05 100644 --- a/.agents/skills/triage-issue/SKILL.md +++ b/.agents/skills/triage-issue/SKILL.md @@ -1,6 +1,6 @@ --- name: triage-issue -description: Assess, classify, and route community-filed issues. Takes a specific issue number or processes all open issues with the needs-agent-triage label in batch. Validates agent-first gate compliance, attempts diagnosis using relevant skills, and classifies issues for routing into the spike-build pipeline. Trigger keywords - triage issue, triage, assess issue, review incoming issue, triage issues. +description: Assess, classify, and route community-filed issues. Takes a specific issue number or processes all open issues with the state:triage-needed label in batch. Validates agent-first gate compliance, attempts diagnosis using relevant skills, and classifies issues for routing into the spike-build pipeline. Trigger keywords - triage issue, triage, assess issue, review incoming issue, triage issues. --- # Triage Issue @@ -12,9 +12,9 @@ Assess, classify, and route community-filed issues. This is the front door for c - The `gh` CLI must be authenticated (`gh auth status`) - You must be in a git repository with a GitHub remote -## Critical: `agent-ready` Label Is Human-Only +## Critical: `state:agent-ready` Label Is Human-Only -The `agent-ready` label is a **human gate**. Triage **never** applies this label. Triage assesses and classifies — humans decide what gets built. This is a non-negotiable safety control. +The `state:agent-ready` label is a **human gate**. Triage **never** applies this label. Triage assesses and classifies — humans decide what gets built. This is a non-negotiable safety control. ## Agent Comment Marker @@ -45,10 +45,10 @@ Assess one specific issue. Proceed to Step 1 with the given issue number. triage issues ``` -Query all open issues with the `needs-agent-triage` label and process them in sequence: +Query all open issues with the `state:triage-needed` label and process them in sequence: ```bash -gh issue list --label "needs-agent-triage" --state open --json number,title --jq '.[].number' +gh issue list --label "state:triage-needed" --state open --json number,title --jq '.[].number' ``` For each issue returned, run the full triage workflow (Steps 1-6). Report a summary at the end listing each issue and its classification. @@ -81,9 +81,9 @@ Check whether the issue body contains a substantive agent diagnostic section. Lo **If the diagnostic section is missing or clearly placeholder:** -1. Add the `needs-agent-triage` label if not already present: +1. Add the `state:triage-needed` label if not already present: ```bash - gh issue edit --add-label "needs-agent-triage" + gh issue edit --add-label "state:triage-needed" ``` 2. Post a comment with the triage marker: ``` @@ -132,12 +132,12 @@ Based on the investigation, classify the issue into one of these categories: | Classification | Criteria | Action | |---------------|----------|--------| -| **bug-confirmed** | Agent diagnostic and codebase analysis confirm a real defect | Label `bug`, remove `needs-agent-triage` | -| **feature-valid** | Design proposal is sound, feasible given the architecture | Label `feat`, remove `needs-agent-triage` | +| **bug-confirmed** | Agent diagnostic and codebase analysis confirm a real defect | Apply relevant `area:*` or `topic:*` labels as needed, remove `state:triage-needed`, and assign the built-in `Bug` issue type manually if needed | +| **feature-valid** | Design proposal is sound, feasible given the architecture | Apply relevant `area:*` or `topic:*` labels as needed, remove `state:triage-needed`, and assign the built-in `Feature` issue type manually if needed | | **duplicate** | An existing open issue covers this | Link the duplicate, close with comment | | **user-error** | The reported behavior is expected, or the issue is a misconfiguration | Comment with explanation and guidance, close | -| **needs-more-info** | Report is substantive but missing critical reproduction details | Comment requesting specifics, keep `needs-agent-triage` | -| **needs-investigation** | Report appears valid but requires deeper analysis (spike candidate) | Label `spike`, remove `needs-agent-triage` | +| **needs-more-info** | Report is substantive but missing critical reproduction details | Comment requesting specifics, keep `state:triage-needed` | +| **needs-investigation** | Report appears valid but requires deeper analysis (spike candidate) | Label `spike`, remove `state:triage-needed` | ## Step 6: Post Triage Comment @@ -162,7 +162,7 @@ Post a structured comment with the triage marker: Apply the appropriate labels as determined in Step 5. -**Do not apply `agent-ready`.** That is always a human decision. +**Do not apply `state:agent-ready`.** That is always a human decision. ## Relationship to Other Skills @@ -175,7 +175,7 @@ Community issue filed | create-spike (if classification is needs-investigation) | - build-from-issue (if human applies agent-ready) + build-from-issue (if human applies state:agent-ready) ``` - **triage-issue** decides whether an issue is valid and how to classify it. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index a4b531a0..fbb62245 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,7 +1,6 @@ name: Bug Report description: Report a bug. Your agent should investigate first — see CONTRIBUTING.md. -title: "bug: " -labels: ["bug"] +type: Bug body: - type: markdown attributes: diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index cbdce243..bdf2cacc 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,7 +1,6 @@ name: Feature Request description: Propose a feature with a design. Not a "please build this" request. -title: "feat: " -labels: ["feat"] +type: Feature body: - type: markdown attributes: diff --git a/.github/workflows/branch-e2e.yml b/.github/workflows/branch-e2e.yml index a59f84b6..ad53bb63 100644 --- a/.github/workflows/branch-e2e.yml +++ b/.github/workflows/branch-e2e.yml @@ -10,7 +10,7 @@ permissions: jobs: build-gateway: - if: contains(github.event.pull_request.labels.*.name, 'e2e') + if: contains(github.event.pull_request.labels.*.name, 'test:e2e') uses: ./.github/workflows/docker-build.yml with: component: gateway @@ -18,7 +18,7 @@ jobs: runner: build-arm64 build-cluster: - if: contains(github.event.pull_request.labels.*.name, 'e2e') + if: contains(github.event.pull_request.labels.*.name, 'test:e2e') uses: ./.github/workflows/docker-build.yml with: component: cluster diff --git a/.github/workflows/issue-triage.yml b/.github/workflows/issue-triage.yml index 241af7f6..50bdd31e 100644 --- a/.github/workflows/issue-triage.yml +++ b/.github/workflows/issue-triage.yml @@ -37,12 +37,12 @@ jobs: console.log('Agent diagnostic section missing or placeholder. Flagging.'); - // Add needs-agent-triage label + // Add state:triage-needed label await github.rest.issues.addLabels({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number, - labels: ['needs-agent-triage'] + labels: ['state:triage-needed'] }); // Post redirect comment diff --git a/AGENTS.md b/AGENTS.md index f5cf5269..8e31c4ac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,9 +19,9 @@ These pipelines connect skills into end-to-end workflows. Individual skill files - **Community inflow:** `triage-issue` → `create-spike` → `build-from-issue` - Triage assesses and classifies community-filed issues. Spike investigates unknowns. Build implements. - **Internal development:** `create-spike` → `build-from-issue` - - Spike explores feasibility, then build executes once `agent-ready` is applied by a human. + - Spike explores feasibility, then build executes once `state:agent-ready` is applied by a human. - **Security:** `review-security-issue` → `fix-security-issue` - - Review produces a severity assessment and remediation plan. Fix implements it. Both require the `security` label; fix also requires `agent-ready`. + - Review produces a severity assessment and remediation plan. Fix implements it. Both require the `topic:security` label; fix also requires `state:agent-ready`. - **Policy iteration:** `openshell-cli` → `generate-sandbox-policy` - CLI manages the sandbox lifecycle; policy generation authors the YAML constraints. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 88a30acb..f9e1fc1c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -91,6 +91,8 @@ Skills connect into pipelines. Individual skill files don't describe these relat - **Security:** `review-security-issue` → `fix-security-issue` - **Policy iteration:** `openshell-cli` → `generate-sandbox-policy` +Workflow state labels use the `state:*` prefix, and security work uses `topic:security`. GitHub issue templates assign built-in issue types where applicable, and agent-created issues should use issue types or manual follow-up rather than type labels. + ## Prerequisites Install [mise](https://mise.jdx.dev/). This is used to set up the development environment.