chore(agents): resolve contributor guidance review gaps

Signed-off-by: Jim Meyer <jimeyer@nvidia.com>

Author: purp

.agents/skills/build-from-issue/SKILL.md

@@ -11,7 +11,7 @@ Use a specific GitHub issue to plan and implement a scoped change. Direct user i
 
 ## Inspect the issue
 
-1. Run `gh issue view <id> --json number,title,body,state,labels,comments,assignees` and inspect the repository's current `state:*` labels and descriptions with `gh label list`. Infer whether triage, validation, and human acceptance have happened. Do not hard-code label names or change disposition as part of building.
+1. Run `gh issue view <id> --json number,title,body,state,labels,comments,assignees` and follow Label Discovery in `CONTRIBUTING.md` to retrieve every page of current `state:*` label definitions and resolve unclear meanings. Infer whether triage, validation, and human acceptance have happened. Do not hard-code label names or change disposition as part of building.
 2. Read the issue, comments, linked PRs, and current code. Check for an active owner or implementation. If the issue concerns a vulnerability, use `review-security-issue` and `fix-security-issue` instead.
 3. Confirm that the User Story attests to the human operator's first-hand OpenShell use and gives a specific use case. If the issue lacks this, ask the operator before proceeding with planning or implementation. For a bug, require reproduction using only an OpenShell deployment; do not install third-party tools solely to demonstrate the problem.
 4. If the user's direct request starts before the normal issue disposition, briefly report the discrepancy and continue with the authorized phase. Stop only when information needed to do the work is actually unavailable or a conflicting owner needs resolution.
@@ -24,11 +24,11 @@ Use a single issue comment beginning with `> **🏗️ build-plan**` when a plan
 
 ## Implement
 
-1. Check the current branch and working tree. Preserve unrelated work. Create a branch or worktree as needed, with the branch named `<type>/<issue-id>-<short-description>/<github-username>`. Use a Conventional Commits type for `<type>`.
+1. Check the current branch and working tree. Preserve unrelated work. Create an issue-specific branch or worktree as needed, following Branch Names in `CONTRIBUTING.md`.
 2. Implement the smallest coherent change that fulfills the acceptance criteria. Update relevant skills when behavior or commands change. Keep published documentation minimal: explain exactly what users need, avoid duplication across pages, and omit internal details with no user impact.
 3. Add meaningful tests for changed behavior and follow the verification guidance in `CONTRIBUTING.md`. Select format, lint, compile or type checks, and tests for affected components and their dependencies. Run the relevant E2E lane for infrastructure, sandbox, or policy changes. Guidance and template edits need applicable Markdown, YAML, link, and consistency checks. Do not require full Rust, SDK, or repository CI solely because a commit or PR is being created; broaden checks only for a concrete remaining risk or failed check.
 4. Review the diff, use a signed-off Conventional Commit, and prepare a PR following `create-github-pr`.
 
-Every PR must have its own existing issue and use `Closes #<id>` in its Related Issue section. For work needing multiple PRs, split the scope into a closable issue per PR. A high-level issue may track those issues but should not be closed by an incomplete PR. Report the implementation, verification, and any remaining limitation in the PR description, rather than copying earlier issue diagnostics.
+Every PR from this issue-backed workflow must have its own existing issue and use `Closes #<id>` in its Related Issue section. For work needing multiple PRs, split the scope into a closable issue per PR. A high-level issue may track those issues but should not be closed by an incomplete PR. Report the implementation, verification, and any remaining limitation in the PR description, rather than copying earlier issue diagnostics.
 
 Do not apply acceptance or roadmap decisions on behalf of a maintainer. Do not introduce `agent:*` workflow labels.

.agents/skills/create-github-issue/SKILL.md

@@ -135,7 +135,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. Inspect the repository’s current `state:*` labels and follow its triage → validation → human acceptance process. Agents may assess facts, but only humans decide whether to accept work or place it on the roadmap. A direct user request authorizes the requested planning or implementation phase without changing issue disposition.
+Creating an issue does not accept it. Follow Label Discovery in `CONTRIBUTING.md` to retrieve every page of current `state:*` label definitions and resolve unclear meanings, then follow its triage → validation → human acceptance process. Agents may assess facts, but only humans decide whether to accept work or place it on the roadmap. A direct user request authorizes the requested planning or implementation phase without changing issue disposition.
 
 ## Useful Options
 
@@ -161,4 +161,4 @@ Created issue [#123](https://github.com/OWNER/REPO/issues/123)
 Use the issue number to:
 
 - Reference in signed-off Conventional Commits: `git commit --signoff -m "fix(cli): validate empty requests (fixes #123)"`
-- Create a branch following project convention: `<type>/<issue-id>-<short-description>/<github-username>`, where `<type>` is a Conventional Commits type.
+- Create a branch following Branch Names in `CONTRIBUTING.md`.

.agents/skills/create-github-pr/SKILL.md

@@ -13,7 +13,7 @@ Create pull requests on GitHub using the `gh` CLI.
 
 - The `gh` CLI must be authenticated (`gh auth status`)
 - You must have commits on a branch that's pushed to the remote
-- Every PR must close an existing issue. The branch should follow `<type>/<issue-id>-<short-description>/<github-username>`.
+- Every PR must close an existing issue, except automated dependency updates as described in `CONTRIBUTING.md`. Follow Branch Names in `CONTRIBUTING.md` for contributor branch names.
 
 ## Before Creating a PR
 
@@ -47,7 +47,7 @@ Before creating a PR, verify:
    git branch --show-current
    ```
 
-2. **Branch follows naming convention** - Use `<type>/<issue-id>-<short-description>/<github-username>`, where `<type>` is a Conventional Commits type.
+2. **Branch follows naming convention** - Follow Branch Names in `CONTRIBUTING.md`, including the exceptions for generated branches and private security work.
 
    ```bash
    # Example: feat/1234-add-pagination/johntmyers
@@ -106,7 +106,7 @@ gh pr create --title "PR title" --body "PR description"
 
 ### Link to an Issue
 
-Every PR must close its own issue. Verify that the issue exists, remains open, and covers the PR scope. Use `Closes #<issue-number>` in the body so merge closes it:
+Every PR except an automated dependency update must close its own issue. Verify that the issue exists, remains open, and covers the PR scope. Automated dependency updates follow the exception in `CONTRIBUTING.md`. Use `Closes #<issue-number>` in the body so merge closes it:
 
 ```bash
 gh pr create \

.agents/skills/create-spike/SKILL.md

@@ -22,6 +22,6 @@ Ask the human operator to attest that they personally use OpenShell and directly
 
 ## Record the result
 
-Create an issue with User Story, Problem Statement, Impact / Why This Matters, Proposed Design when relevant, Acceptance Criteria, Alternatives Considered, and concise Agent Investigation. Include OpenShell-only reproduction and environment details for bugs. Inspect current GitHub `state:*` labels and descriptions before applying the one that matches the evidence; do not hard-code label names. Do not apply an acceptance state or add the issue to the roadmap.
+Create an issue with User Story, Problem Statement, Impact / Why This Matters, Proposed Design when relevant, Acceptance Criteria, Alternatives Considered, and concise Agent Investigation. Include OpenShell-only reproduction and environment details for bugs. Follow Label Discovery in `CONTRIBUTING.md` before applying the assessment state that matches the evidence; retrieve every page and resolve unclear meanings rather than hard-coding label names. Do not apply an acceptance state or add the issue to the roadmap.
 
-Report the issue URL, technical findings, uncertainties, and the human disposition needed. For subsequent authorized implementation, use `build-from-issue`. Every eventual PR must close an issue covering its own scope; split multi-PR efforts into separate closable issues and use a high-level issue only for tracking.
+Report the issue URL, technical findings, uncertainties, and the human disposition needed. For subsequent authorized implementation, use `build-from-issue`. Every eventual PR from this issue-backed workflow must close an issue covering its own scope; split multi-PR efforts into separate closable issues and use a high-level issue only for tracking.

.agents/skills/fix-security-issue/SKILL.md

@@ -9,10 +9,10 @@ metadata:
 
 Use this skill after an authorized `review-security-issue` review identifies an actionable concern. Follow `SECURITY.md`; do not disclose vulnerability details in a public issue. A direct user request to fix a specific reviewed issue authorizes implementation. For unattended work, inspect current `state:*` label descriptions, maintainer assignments, and comments to verify that remediation is authorized. Do not infer approval from a state that only records technical validation.
 
-1. Fetch the issue and its comments with `gh issue view <id> --json number,title,body,state,labels,comments`. Inspect current repository labels and confirm this is a security issue. Find the review marked `> **🔒 security-review-agent**` and its remediation plan. If the review is missing or found the issue not actionable, stop and report that result.
+1. Fetch the issue and its comments with `gh issue view <id> --json number,title,body,state,labels,comments`. Follow Label Discovery in `CONTRIBUTING.md` and confirm this is a security issue; resolve unclear meanings before interpreting authorization. Find the review marked `> **🔒 security-review-agent**` and its remediation plan. If the review is missing or found the issue not actionable, stop and report that result.
 2. Verify the review against current code. Adapt the plan when code has changed, and record material deviations. Check for an existing owner, branch, or PR.
-3. Create a branch or worktree using `fix/<issue-id>-<short-description>/<github-username>`, preserving unrelated changes. Implement the smallest safe fix and add regression tests for the security boundary. Avoid logging secrets or adding public exploit detail.
+3. Create a `fix` branch or worktree following Branch Names in `CONTRIBUTING.md`, preserving unrelated changes and disclosure boundaries. Implement the smallest safe fix and add regression tests for the security boundary. Avoid logging secrets or adding public exploit detail.
 4. Follow the verification guidance in `CONTRIBUTING.md`. Run format, lint, compile or type checks, and regression tests for the affected security boundary and dependent components, plus the relevant E2E lane for sandbox or policy changes. Broaden verification when the fix spans components or a concrete risk remains; do not require unaffected Rust or SDK suites solely to create a signed-off commit or PR.
-5. Follow `create-github-pr` and use `Closes #<id>` for the reviewed issue. Every PR must close its own issue; split multi-PR remediations into separate issues in the authorized security workflow. Keep the PR description appropriately scoped to its disclosure venue.
+5. Follow `create-github-pr` and use `Closes #<id>` for the reviewed issue. Every PR from this issue-backed remediation workflow must close its own issue; split multi-PR remediations into separate issues in the authorized security workflow. Keep the PR description appropriately scoped to its disclosure venue.
 
 Begin any fix comments with `> **🔧 security-fix-agent**`. Do not change human disposition or introduce `agent:*` workflow labels.

.agents/skills/helm-dev-environment/SKILL.md

@@ -38,7 +38,7 @@ and preloads the default sandbox image into k3d so the first sandbox create
 does not wait on a large registry pull. Traefik is disabled at cluster creation time.
 
 **Multi-worktree support:** the cluster name is derived from the last component of the
-current git branch (e.g. branch `kube-support/local-dev/tmutch` → cluster
+current git branch (e.g. branch `chore/1234-local-dev/tmutch` → cluster
 `openshell-dev-tmutch`). Each worktree therefore gets its own isolated cluster and its
 own `kubeconfig` file. Override with `HELM_K3S_CLUSTER_NAME` to force a specific name
 or share one cluster across worktrees.

.agents/skills/review-github-pr/SKILL.md

@@ -173,9 +173,9 @@ User says: "Review PR #456"
 
 ### Review by branch name
 
-User says: "Review branch `feature/add-pagination`"
+User says: "Review branch `feat/1234-add-pagination/octocat`"
 
-1. Look up PR with `gh pr list --head "feature/add-pagination"`
+1. Look up PR with `gh pr list --head "feat/1234-add-pagination/octocat"`
 2. If found, fetch PR metadata and diff
 3. If not found, diff against main locally
 4. Produce summary

.agents/skills/review-security-issue/SKILL.md

@@ -11,7 +11,7 @@ Review a security concern through its authorized private workflow. Do not file o
 
 ## Assess
 
-1. Fetch the issue and comments with `gh issue view <id> --json title,body,state,labels,comments`. Inspect current repository labels rather than assuming exact names. Verify that this is an authorized security issue and that a prior review does not already answer the request.
+1. Fetch the issue and comments with `gh issue view <id> --json title,body,state,labels,comments`. Follow Label Discovery in `CONTRIBUTING.md` rather than assuming exact label names; resolve unclear meanings before interpreting authorization. Verify that this is an authorized security issue and that a prior review does not already answer the request.
 2. Inspect affected code and verify the claim. Assess impact, exploitability, prerequisites, affected surface, and a concrete attack scenario. Separate evidence from assumptions and give a severity with rationale.
 3. If actionable, propose a remediation plan with code areas, safe rollout, and focused tests. If not actionable, explain the evidence and recommended disposition. Do not decide product acceptance or silently close the issue.
 4. Post the review only when the request authorizes posting. Begin the comment with `> **🔒 security-review-agent**` so later reviews can detect it. Keep sensitive details in the authorized private venue.

.agents/skills/sync-agent-infra/SKILL.md

@@ -38,11 +38,11 @@ Search both `skills/` and `.agents/skills/` for affected commands, fields, and c
 
 1. Compare `skills/*/SKILL.md` and `.agents/skills/*/SKILL.md` with the inventories in `CONTRIBUTING.md`. Public skills must work outside a checkout and use installed CLI help and published documentation. Contributor skills must set `metadata.internal: true`. Confirm names are unique and local links resolve.
 2. Compare `crates/` with the architecture table in `AGENTS.md`. Check the public and contributor skill rows.
-3. Read the current GitHub labels and their descriptions, then check issue guidance for the general triage → validation → human acceptance process. Skills should mention the `state:*` namespace without enumerating exact labels, and should not depend on `agent:*` labels. A direct request authorizes only the requested phase; unattended work uses current state descriptions, maintainer assignments, and comments to establish the authorized phase.
+3. Follow Label Discovery in `CONTRIBUTING.md` to retrieve every page of current GitHub labels and resolve unclear descriptions, then check issue guidance for the general triage → validation → human acceptance process. Skills should mention the `state:*` namespace without enumerating exact labels, and should not depend on `agent:*` labels. A direct request authorizes only the requested phase; unattended work uses current state descriptions, maintainer assignments, and comments to establish the authorized phase.
 4. Check issue templates, `create-github-issue`, `create-spike`, and `triage-issue` for the first-hand OpenShell User Story, OpenShell-only bug reproduction, notional UX examples, and consideration of applicable extension points.
-5. Check the PR template, `create-github-pr`, `build-from-issue`, `fix-security-issue`, and `CONTRIBUTING.md`: every PR must close an existing issue covering its scope. Multi-PR work needs an issue per PR; a separate issue may track the overall effort.
-6. Check `README.md`, `.github/ISSUE_TEMPLATE/`, `.github/workflows/`, `.agents/agents/`, and related skill cross references for stale workflow statements. Keep user-facing documentation changes minimal and avoid duplicated internal explanations.
-7. Check that PR and build skills follow the scoped verification guidance in `CONTRIBUTING.md`; they must not require full Rust, SDK, or repository CI for changes that cannot affect those areas.
+5. Check the PR template, `create-github-pr`, `build-from-issue`, `fix-security-issue`, and `CONTRIBUTING.md`: every PR must close an existing issue covering its scope, except automated dependency updates as described in `CONTRIBUTING.md`. Multi-PR work needs an issue per PR; a separate issue may track the overall effort.
+6. Check contributor branch instructions and examples against Branch Names in `CONTRIBUTING.md`; AGENTS.md and skills should refer to that convention. Check `README.md`, `.github/ISSUE_TEMPLATE/`, `.github/workflows/`, `.agents/agents/`, and related skill cross references for stale workflow statements. Keep user-facing documentation changes minimal and avoid duplicated internal explanations.
+7. Check that PR, build, TUI, and docs contribution guidance follow the scoped verification guidance in `CONTRIBUTING.md`; they must not require full Rust, SDK, or repository CI for changes that cannot affect those areas.
 8. Use `npx -y skills add . --list` from a disposable clean copy when skill discovery changes. It should expose public skills only; clean generated files afterward.
 
 Fix contradictions, then repeat the affected checks. Report files changed and any remaining drift. Do not treat an old document's label list as a source of truth over current GitHub metadata.