diff --git a/.agents/skills/build-from-issue/SKILL.md b/.agents/skills/build-from-issue/SKILL.md index 2e04e37f52..06d1324b02 100644 --- a/.agents/skills/build-from-issue/SKILL.md +++ b/.agents/skills/build-from-issue/SKILL.md @@ -62,7 +62,7 @@ Fetch issue + comments ├─ Triage incomplete, awaiting information, or awaiting human disposition? │ → Report the blocking state and STOP │ - ├─ state:accepted absent? + ├─ state:accepted and roadmap association both absent? │ → Human has not accepted the issue; STOP │ ├─ No plan comment and no direct planning request and agent:plan-requested absent? @@ -113,9 +113,9 @@ Stop before planning in any of these states: - `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`: triage is complete, but a human has not yet decided whether OpenShell should invest in the work. +- `state:validated` without roadmap placement: triage is complete, but a human has not yet decided whether OpenShell should invest in the work. -Next, require `state:accepted`. It records the human decision to pursue the work. If no plan exists, require either a direct user request for planning or the human-applied `agent:plan-requested` label before generating one. Record any roadmap association as sequencing context, but do not require one. Never add or remove `state:accepted`, either human request label, or the `roadmap` label. +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. ## Step 2: Fetch and Classify Comments @@ -160,7 +160,7 @@ Task tool with subagent_type="principal-engineer-reviewer" In the prompt, instruct the reviewer to: -1. Read the issue description thoroughly and identify what needs to change in the codebase. +1. Read the issue's user story and identify what needs to change in the codebase. Treat reporter diagnostics or solution ideas as optional context, not as authoritative or current analysis. 2. Map the requirements to existing code — read the relevant source files. 3. Determine the **issue type** — one of: `feat` (new feature), `fix` (bug fix), `refactor`, `chore`, `perf`, `docs`. 4. Propose the minimal set of changes that satisfies the requirements. @@ -174,6 +174,8 @@ In the prompt, instruct the reviewer to: 9. Assess **gateway config documentation impact** — if the change adds, removes, renames, or changes defaults for gateway TOML keys or driver-specific config options, the plan must include an update to `docs/reference/gateway-config.mdx`. If the change is surfaced through Helm or a compute-driver overview, also include `docs/reference/sandbox-compute-drivers.mdx` or the relevant deployment docs. 10. Assess **LSM compatibility** — if the change touches process identity, `/proc` filesystem access, binary execution, or inter-process visibility, flag whether it will behave differently on hosts running SELinux (enforcing) or AppArmor. In particular, tests that fork+exec into system binaries will fail on SELinux-enforcing hosts due to cross-label `/proc//exe` access restrictions. +Perform this investigation against the current branch and current product behavior. If the issue contains earlier diagnostics, verify them rather than relying on them. + ### A2: Post the Plan Comment Post the plan as a comment on the issue. This is the **canonical plan comment** that will be edited in place as the plan evolves. diff --git a/.agents/skills/create-github-issue/SKILL.md b/.agents/skills/create-github-issue/SKILL.md index 8352603e76..25b82d4931 100644 --- a/.agents/skills/create-github-issue/SKILL.md +++ b/.agents/skills/create-github-issue/SKILL.md @@ -17,29 +17,25 @@ This project uses YAML form issue templates. When creating issues, match the tem ### Bug Reports -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. The diagnostic must identify the OpenShell version tested, whether the latest release or known fixes were checked, and whether possible duplicate issues were searched. If the agent cannot verify the latest release or search existing issues, say so explicitly instead of guessing. Apply area or topic labels only when they are clearly known. +Do not add a type label automatically. Write the issue as a user story. Capture the affected persona, desired user-facing workflow or capability, reason and current impact, the workflow that exposes the problem, and the relevant environment. Do not require a diagnosis, internal implementation design, or agent output. Apply area or topic labels only when they are clearly known. ```bash gh issue create \ --title "bug: " \ --body "$(cat <<'EOF' -## Agent Diagnostic +## What persona does this impact? -- Skills loaded: -- OpenShell version tested: -- Latest release checked: -- Known fixes reviewed: -- Possible duplicates reviewed: -- Findings: -- Remaining reason for filing: + -## Description +## What does this persona need to be able to do? + + -**Actual behavior:** +## Why does this matter to the persona? -**Expected behavior:** + -## Reproduction Steps +## What workflow exposes the problem? 1. 2. @@ -47,15 +43,13 @@ gh issue create \ ## Environment - OS: -- Docker: - OpenShell: -- Latest release checked: -- Possible duplicates checked: +- Platform, deployment, runtime, or integration: -## Logs +## Relevant Logs ``` - + ``` EOF )" @@ -63,28 +57,33 @@ EOF ### Feature Requests -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. +Do not add a type label automatically. Use the same core user-story structure as a bug report. Ask for the desired user-facing workflow, but do not require the reporter to decide whether the gap is a defect or missing capability, design the internal implementation, or include agent output. Apply area or topic labels only when they are clearly known. ```bash gh issue create \ --title "feat: " \ --body "$(cat <<'EOF' -## Problem Statement +## What persona does this impact? + + + +## What does this persona need to be able to do? - + -## Proposed Design +## Why does this matter to the persona? - + -## Alternatives Considered +## What workflow exposes the need? - +1. +2. -## Agent Investigation +## Environment - +- OpenShell: +- Platform, deployment, runtime, or integration: EOF )" ``` @@ -114,7 +113,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 for roadmap work or queue agent work. Agents never apply 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 decides whether technically validated work should be accepted and places it on the roadmap. The request labels queue work for unattended agents; a user may instead direct an agent to a specific issue. +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. ## Useful Options diff --git a/.agents/skills/create-spike/SKILL.md b/.agents/skills/create-spike/SKILL.md index 4f30c3829a..63bcffb72b 100644 --- a/.agents/skills/create-spike/SKILL.md +++ b/.agents/skills/create-spike/SKILL.md @@ -211,7 +211,7 @@ gh issue create \ - --- -*Created by spike investigation. `state:validated` means the issue is ready for human disposition; `state:needs-info` means specific evidence is still required. A human applies `state:accepted` if OpenShell should pursue the work and places it on the roadmap separately. To queue unattended agent planning, a human applies `agent:plan-requested`; a direct request to an agent does not require that label.* +*Created by spike investigation. `state:validated` means the issue is ready for human disposition; `state:needs-info` means specific evidence is still required. A human applies `state:accepted` or places the issue on the roadmap if OpenShell should pursue the work. To queue unattended agent planning, a human applies `agent:plan-requested`; a direct request to an agent does not require that label.* EOF )" ``` @@ -235,7 +235,7 @@ After creating the issue, report: For `state:validated`: -> Review the issue and decide whether OpenShell should pursue it. If yes, replace `state:validated` with `state:accepted` and separately associate it with a roadmap item. The work may remain human-owned. Apply `agent:plan-requested` to queue planning for an unattended agent, or directly ask an agent to use `build-from-issue`. If no, close it as not planned and record the rationale. +> Review the issue and decide whether OpenShell should pursue it. If yes, apply `state:accepted`, associate it with a roadmap item, or do both. Either action records acceptance; roadmap placement additionally records sequencing. The work may remain human-owned. Apply `agent:plan-requested` to queue planning for an unattended agent, or directly ask an agent to use `build-from-issue`. If no, close it as not planned and record the rationale. For `state:needs-info`: diff --git a/.agents/skills/sync-agent-infra/SKILL.md b/.agents/skills/sync-agent-infra/SKILL.md index e1d5b52c12..3ea380a945 100644 --- a/.agents/skills/sync-agent-infra/SKILL.md +++ b/.agents/skills/sync-agent-infra/SKILL.md @@ -119,8 +119,8 @@ For each file in the table above, check for the following inconsistencies: ### Issue Templates -1. **`bug_report.yml`** — Skill names in the Agent Diagnostic guidance and checklist must exist. -2. **`feature_request.yml`** — Skill names in the Agent Investigation guidance must exist. +1. **`bug_report.yml`** — Must collect the affected persona, desired user-facing workflow or capability, impact, workflow or reproduction, and environment. Logs may be bug-specific, but reporter diagnostics must not be required. +2. **`feature_request.yml`** — Must collect the same core user-story and environment fields as the bug report without requiring an internal implementation design or reporter diagnostics. 3. **`config.yml`** — Skill category descriptions in contact links should be accurate. ### Issue Triage Workflow diff --git a/.agents/skills/triage-issue/SKILL.md b/.agents/skills/triage-issue/SKILL.md index 5e5d503025..856d68931d 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 replacing `state:validated` with `state:accepted` and placing the issue on the roadmap 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`. 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,18 +98,14 @@ 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 or applied `state:accepted`**, do not undo or reinterpret that decision. +- **If a human already declined the issue, applied `state:accepted`, or placed it on the roadmap**, do not undo or reinterpret that decision. - **If the marker is not found**, proceed to Step 3. -## Step 3: Validate the Agent-First Gate +## Step 3: Check Report Completeness -Check whether the issue body contains a substantive agent diagnostic section. Treat this as evidence quality, not as a reason to skip obvious safety or routing actions. Look for: +Read the issue as a user story. Identify the affected persona, desired user-facing workflow or capability, reason and current impact, workflow or reproduction, and relevant environment. Reporter-supplied diagnostics, internal implementation designs, and agent output are optional and must not be used as an intake gate. -- An "Agent Diagnostic" heading or section (from the bug report template) -- Evidence that the reporter used agent skills (skill names mentioned, diagnostic output pasted) -- Concrete investigation output (not just placeholder text or "N/A") - -If the diagnostic is missing, continue when the report already contains enough concrete evidence to assess safely. Otherwise classify it as `needs-information`, request the exact missing evidence, remove `state:triage-needed`, and add `state:needs-info`. +If the report contains enough context to understand and assess the user need, continue. If a material part of the story, workflow, or environment is missing, classify it as `needs-information`, request only the exact missing information, remove `state:triage-needed`, and add `state:needs-info`. - If a public issue may disclose a security vulnerability, do not repeat or expand sensitive details. Classify it as `security-report` and direct the operator to `SECURITY.md`. - Route usage questions and support requests to the documented support venue. @@ -121,7 +117,7 @@ Proceed to Step 4 for reports requiring technical validation. Before deeper diagnosis, determine whether the report may already be fixed in a newer release. -1. Extract the reported OpenShell version from the issue body, Agent Diagnostic, environment section, logs, and comments. If no version is provided, record that as missing context and continue. +1. Extract the reported OpenShell version from the issue body, environment section, logs, and comments. If no version is provided, record that as missing context and continue. 2. Check current release information and known fixes when available: - `gh release list --limit 10` - `gh release view ` @@ -140,12 +136,11 @@ Assess the report by investigating the codebase. Use the `principal-engineer-rev ``` Prompt the sub-agent with: - The full issue title and body -- The reporter's agent diagnostic output - Instructions to evaluate with a skeptical lens: - 1. Is this report describing a real problem or user error? - 2. Can the described behavior be reproduced from the information given? - 3. Does the reporter's agent diagnostic match what you see in the codebase? - 4. If this is a bug, what component is affected? + 1. What persona, desired capability, and impact does the user story establish? + 2. Can the described workflow be reproduced or otherwise validated from the information given? + 3. Does the current product support the requested outcome, and what component owns the behavior? + 4. Is the report best classified as a bug, feature request, support request, or another category? 5. If this is a feature request, is it technically coherent and feasible? Do not decide whether the project should accept it. 6. Are there any open or closed issues that duplicate this? 7. What uncertainty remains, and what exact evidence would resolve it? @@ -205,14 +200,14 @@ Post a structured comment with the triage marker: > - **Evidence quality:** > > ### Human Decision Required -> Decide whether OpenShell should address this issue. If yes, replace -> `state:validated` with `state:accepted`, associate it with a roadmap -> item, and decide whether the work remains human-owned. +> Decide whether OpenShell should address this issue. If yes, apply +> `state:accepted`, associate it with a roadmap item, or do both, and decide +> whether the work remains human-owned. Either action records acceptance; +> roadmap placement additionally records sequencing. > To queue investigation or planning for an unattended agent, also apply > `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. -> Roadmap association is independent sequencing metadata. ``` For other outcomes, replace the impact and decision sections with the exact information request, objective resolution, or safe routing guidance. @@ -230,7 +225,7 @@ Community issue filed | state:validated | - human decline OR state:accepted + roadmap placement + human decline OR state:accepted / roadmap placement | create-spike (if deeper investigation is approved) | diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index de5d8112ae..dc675248ae 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,50 +1,52 @@ name: Bug Report -description: Report a bug. Your agent should investigate first — see CONTRIBUTING.md. +description: Tell us about a workflow that does not work as you need it to. type: Bug body: - type: markdown attributes: value: | - ## Agent-First Troubleshooting + ## Tell us what you need - OpenShell is an agent-first project. Before filing this bug, point your coding agent at the repo and have it investigate using the available skills (`debug-openshell-cluster`, `debug-inference`, `openshell-cli`, etc.). See [CONTRIBUTING.md](https://github.com/NVIDIA/OpenShell/blob/main/CONTRIBUTING.md) for the full skills table. + Describe the problem as a user story: what persona is affected, what workflow that persona needs, and why it matters. Describe the desired workflow at the user level, but do not diagnose the cause or design OpenShell's internal implementation. You do not need to include output from an agent. Maintainers and implementers will investigate at the appropriate stage. - Please also check the latest OpenShell release and search existing issues for possible duplicates before filing. If you cannot upgrade, retest, or search existing issues, explain why in the diagnostic. + Search existing issues before filing. Do not report security vulnerabilities here; follow [SECURITY.md](https://github.com/NVIDIA/OpenShell/blob/main/SECURITY.md) instead. + + - type: input + id: persona + attributes: + label: What persona does this impact? + description: Describe the affected role in the workflow, such as an operator, sandbox creator, or agent. + placeholder: A gateway operator running OpenShell on Kubernetes + validations: + required: true - type: textarea - id: agent-diagnostic + id: goal attributes: - label: Agent Diagnostic - description: | - Paste the output from your agent's investigation of this bug. What skills did it load? What did it find? What did it try? Which OpenShell version did it test, and did it check the latest release, known fixes, and possible duplicates? - placeholder: | - Example: - - Loaded `debug-inference` skill - - Tested OpenShell v0.x.x - - Checked latest release / known fixes: no matching fix found - - Searched existing issues for duplicates: no matching issue found - - Ran `openshell inference get` and `openshell provider get ollama` - - Found `OPENAI_BASE_URL=http://127.0.0.1:11434/v1`, which is unreachable from the gateway - - Updated the provider to use `host.openshell.internal`, but the issue persists because the gateway is remote + label: What does this persona need to be able to do? + description: Describe the user-facing workflow, capability, or outcome this persona needs, without prescribing OpenShell's internal implementation. + placeholder: I want running sandboxes to resume after Kubernetes reschedules them during an upgrade. validations: required: true - type: textarea - id: description + id: impact attributes: - label: Description - description: What happened? What did you expect to happen? + label: Why does this matter to the persona? + description: Describe what happens today and how it affects the persona's work. + placeholder: Currently, when a node is rolled, its sandboxes are reset and in-progress agent work is lost. validations: required: true - type: textarea id: reproduction attributes: - label: Reproduction Steps - description: Minimal steps to reproduce the issue. + label: What workflow exposes the problem? + description: Show the shortest sequence of actions or commands that demonstrates the blocked workflow. placeholder: | - 1. Run `openshell sandbox create -- claude` - 2. ... + 1. Start a long-running task in a sandbox. + 2. Drain the Kubernetes node running the sandbox. + 3. Observe the replacement sandbox after it is scheduled. validations: required: true @@ -52,39 +54,21 @@ body: id: environment attributes: label: Environment - description: OS, Docker version, OpenShell version tested, whether the latest release and existing issues were checked, and any other relevant details. + description: Include the OpenShell version and the platform, deployment mode, runtime, or integration relevant to this workflow. placeholder: | - - OS: macOS 15.2 / Ubuntu 24.04 / Windows 11 + WSL2 - - Docker: Docker Desktop 4.x / Docker Engine 27.x - - OpenShell: v0.x.x (output of `openshell --version`) - - Latest release checked: yes / no, because ... - - Possible duplicates checked: yes / no, because ... + - OpenShell: v0.x.x + - Platform: Kubernetes v1.x + - Deployment: Helm with the Kubernetes compute driver validations: required: true - type: textarea id: logs attributes: - label: Logs + label: Relevant logs description: | - Relevant log output, error messages, or stack traces. - Redact credentials, API keys, and tokens before pasting — verbose error output from some frameworks includes the full request config. + Optional. Include only the smallest excerpt that shows the problem. + Remove credentials, API keys, tokens, and query parameters before pasting. render: shell validations: required: false - - - type: checkboxes - id: checklist - attributes: - label: Agent-First Checklist - options: - - label: I pointed my agent at the repo and had it investigate this issue - required: true - - label: I loaded relevant skills (e.g., `debug-openshell-cluster`, `debug-inference`, `openshell-cli`) - required: true - - label: I checked the latest OpenShell release and either reproduced the issue there or explained why I cannot upgrade/test it - required: true - - label: I searched existing issues for possible duplicates or explained why I could not - required: true - - label: My agent could not resolve this — the diagnostic above explains why - required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index bbc1188d7a..51598981f9 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,61 +1,63 @@ name: Feature Request -description: Propose a feature with a design. Not a "please build this" request. +description: Tell us about a workflow or outcome OpenShell does not yet support. type: Feature body: - type: markdown attributes: value: | - ## Design-First Feature Proposals + ## Tell us what you need - OpenShell feature requests must include a design proposal — describe the system behavior you want, not just the outcome. New features start here, not as RFC pull requests. If maintainers decide an RFC is necessary, they will request one from this issue and assign the RFC number. + Describe the request as a user story: what persona is affected, what workflow that persona needs, and why it matters. Describe the desired workflow at the user level, but do not diagnose the gap or design OpenShell's internal implementation. You do not need to include output from an agent. Maintainers and implementers will investigate at the appropriate stage. - If your agent explored the codebase to assess feasibility (e.g., using the `create-spike` skill), include its findings. + Search existing issues before filing. New features start as issues, not RFC pull requests. If maintainers decide an RFC is necessary, they will request one and assign its number from the issue. - - type: textarea - id: problem + - type: input + id: persona attributes: - label: Problem Statement - description: What problem does this solve? Why does it matter? + label: What persona does this impact? + description: Describe the affected role in the workflow, such as an operator, sandbox creator, or agent. + placeholder: A gateway operator running OpenShell on Kubernetes validations: required: true - type: textarea - id: design + id: goal attributes: - label: Proposed Design - description: | - How should this work? Describe the system behavior, components involved, and user-facing interface. This should be a design, not a wish list. + label: What does this persona need to be able to do? + description: Describe the user-facing workflow, capability, or outcome this persona needs, without prescribing OpenShell's internal implementation. + placeholder: I want running sandboxes to resume after Kubernetes reschedules them during an upgrade. validations: required: true - type: textarea - id: alternatives + id: impact attributes: - label: Alternatives Considered - description: What other approaches did you evaluate? Why is the proposed design better? + label: Why does this matter to the persona? + description: Describe what happens today and how it affects the persona's work. + placeholder: Currently, when a node is rolled, its sandboxes are reset and in-progress agent work is lost. validations: required: true - type: textarea - id: agent-investigation + id: reproduction attributes: - label: Agent Investigation - description: | - If your agent explored the codebase to assess feasibility (e.g., using the `create-spike` skill), paste its findings here. This is optional but strengthens the proposal. + label: What workflow exposes the need? + description: Show the shortest sequence of actions or commands that demonstrates the missing workflow. placeholder: | - Example: - - Used `create-spike` to investigate existing provider infrastructure - - Found that `crates/openshell-providers/` already supports a plugin pattern - - Proposed design extends the existing trait rather than adding a new abstraction + 1. Start a long-running task in a sandbox. + 2. Drain the Kubernetes node running the sandbox. + 3. Observe the replacement sandbox after it is scheduled. validations: - required: false + required: true - - type: checkboxes - id: checklist + - type: textarea + id: environment attributes: - label: Checklist - options: - - label: I've reviewed existing issues and the architecture docs - required: true - - label: This is a design proposal, not a "please build this" request - required: true + label: Environment + description: Include the OpenShell version and the platform, deployment mode, runtime, or integration relevant to this workflow. + placeholder: | + - OpenShell: v0.x.x + - Platform: Kubernetes v1.x + - Deployment: Helm with the Kubernetes compute driver + validations: + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index f6de74c859..2efbaac5d1 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -13,7 +13,7 @@ No issue required: ## Testing - + - [ ] `mise run pre-commit` passes - [ ] Unit tests added/updated - [ ] E2E tests added/updated (if applicable) diff --git a/AGENTS.md b/AGENTS.md index 2d89879e9e..01f91da485 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,9 +17,9 @@ 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 applies `state:accepted` if the project should pursue the work and separately places it 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` 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. - **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 declines it, separately places it on the roadmap, and optionally queues it through the `agent:*` workflow or directs an agent to it. + - 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` - General build agents must not process `topic:security` issues. For unattended processing, a human queues specialized review with `agent:plan-requested`; review produces a severity assessment and remediation plan; a human queues remediation with `agent:implementation-requested`. Direct requests to the specialized skills do not require those labels. - **Policy iteration:** `openshell-cli` → `generate-sandbox-policy` @@ -71,11 +71,11 @@ These pipelines connect skills into end-to-end workflows. Individual skill files ## Issue and PR Conventions -- **Bug reports** must include an agent diagnostic section — proof that the reporter's agent investigated the issue before filing. See the issue template. -- **Feature requests** must include a design proposal, not just a "please build this" request. See the issue template. +- **Bug reports and feature requests** use the same user-story structure: the affected persona, what that persona needs to do, why it matters, the workflow that exposes the problem or need, and the relevant environment. Bug reports may additionally include concise, redacted logs. +- **Issue reporters should describe the desired user-facing workflow, but are not required to diagnose the cause, design OpenShell's internal implementation, or include agent output.** Investigation belongs with triage and with planning and implementation for accepted work. - **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 roadmap acceptance, apply `state:accepted`, place issues on the roadmap, or apply `agent:plan-requested` or `agent:implementation-requested`. Humans accept or decline validated work and separately place it on the roadmap. 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; roadmap association carries sequencing. -- **PRs** must follow the PR template structure: Summary, Related Issue, Changes, Testing, Checklist. +- **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. +- **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. - **Security vulnerabilities** must NOT be filed as GitHub issues. Follow [SECURITY.md](SECURITY.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 22592c435c..7bdbf696bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to OpenShell -OpenShell is built agent-first. We design systems and use agents to implement them. Your agent is your first collaborator — point it at this repo before opening issues, asking questions, or submitting code. +OpenShell is built agent-first. We use agents to design and implement systems, while humans manage product decisions and the project roadmap. ## The Critical Rule @@ -34,30 +34,39 @@ 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`, `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. Roadmap placement describes sequencing and does not authorize work. +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. ## Before You Open an Issue -This project ships with [agent skills](#agent-skills-for-contributors) that can diagnose problems, explore the codebase, generate policies, and walk you through common workflows. Before filing an issue: +Search open and closed issues for the same user need. When filing, write a concise user story that explains: -1. Clone the repo and point your coding agent at it. -2. Load the relevant skill - `debug-openshell-cluster` for gateway or deployment problems, `debug-inference` for inference setup problems, `openshell-cli` for usage questions, `generate-sandbox-policy` for policy help. -3. Have your agent investigate. Let it run diagnostics, read the architecture docs, and attempt a fix. -4. If the agent cannot resolve it, open an issue **with the agent's diagnostic output attached**. The issue template requires this. +1. What persona the issue impacts, such as a gateway operator, sandbox creator, or agent. +2. What this persona needs to be able to do. +3. Why the current behavior or missing workflow matters to this persona. +4. The shortest workflow or reproduction that exposes the problem or need. +5. The OpenShell version and relevant environment. + +Bug reports and feature requests ask for the same core information. Describe the desired workflow from the persona's perspective, but do not try to design OpenShell's internal implementation. You do not need to decide whether the cause is a defect or a missing capability, diagnose the code, or attach an agent transcript. For bug reports, include a small, redacted log excerpt when it materially clarifies the behavior. + +The project includes optional [agent skills](#agent-skills-for-contributors) for self-service troubleshooting and exploration. Use them when they help you, but summarize any useful result in your own words rather than pasting a diagnostic transcript. ### When to Open an Issue -- A real bug that your agent confirmed and could not fix. -- A feature proposal with a design — not a "please build this" request. -- An infrastructure problem that the gateway deployment troubleshooting skill could not resolve. -- An inference setup problem that the `debug-inference` skill could not resolve. +- A workflow behaves differently from what you need or reasonably expect. +- OpenShell does not support an outcome that matters to your workflow. +- The available documentation or configuration does not explain how to complete a supported workflow. - Security vulnerabilities must follow [SECURITY.md](SECURITY.md) — **not** GitHub issues. ### When NOT to Open an Issue -- Questions about how things work — your agent can answer these from the codebase and architecture docs. -- Configuration problems - your agent can diagnose these with `openshell-cli`, `debug-openshell-cluster`, and `debug-inference`. -- "How do I..." requests — the skills cover CLI usage, policy generation, TUI development, and more. +- General questions or open-ended discussion — use [GitHub Discussions](https://github.com/NVIDIA/OpenShell/discussions). +- Security vulnerabilities — follow [SECURITY.md](SECURITY.md) instead. + +## Before You Submit a Change + +Do not start substantial issue-backed work until a maintainer has accepted the issue, unless a maintainer directly asks you to investigate or implement it. Once the work is authorized, use your agent to investigate the current code and behavior. If the issue contains earlier diagnostics, verify them rather than relying on them. + +Use agents and the repository skills as needed to understand the affected code, evaluate tradeoffs, implement the smallest coherent change, and verify it. The pull request should explain what changed and how it was tested; it should not substitute an agent transcript for the contributor's understanding. ## Agent Skills for Contributors @@ -110,11 +119,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` or closure as not planned | +| Disposition | Should OpenShell pursue the work? | `state:accepted`, roadmap placement, 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 | -Completing one decision does not imply the others. `state:validated` confirms that the factual assessment is complete, but it does not mean the project has accepted the work. Roadmap placement communicates sequencing, but it does not authorize an agent to begin. +`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. #### Who Controls Each Decision @@ -125,7 +134,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 | Maintainer | +| Accept or decline the work with `state:accepted`, roadmap placement, 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 | @@ -152,7 +161,7 @@ Keep one of these states on an open issue. When new evidence resolves a `state:n #### Assessing an Incoming Issue -Triage checks the report, its diagnostic evidence, related issues, current releases, and the relevant code paths. The assessment ends in one of these outcomes: +Triage checks the user story, reproduction or workflow, environment, related issues, current releases, and the relevant code paths. The assessment ends in one of these outcomes: | Outcome | State or resolution | |---|---| @@ -171,17 +180,17 @@ 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:** replace `state:validated` with `state:accepted` and place it on the roadmap. +- **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. - **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 only the human decision that OpenShell should pursue the work. +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. #### Roadmap -OpenShell does not use priority labels. Sequencing comes from the [OpenShell Roadmap](https://github.com/orgs/NVIDIA/projects/233): a maintainer associates an accepted issue with a roadmap item, and the roadmap item's own timing carries the urgency. Issues tracked on the roadmap carry the `roadmap` label. +OpenShell does not use priority labels. Sequencing comes from the [OpenShell Roadmap](https://github.com/orgs/NVIDIA/projects/233): a maintainer associates an issue with a roadmap item, signaling acceptance and giving it timing. Issues tracked on the roadmap carry the `roadmap` label. -An accepted issue with no roadmap association is real work the project intends to do, but it is not scheduled. Ask a maintainer before starting on one. +An issue with `state:accepted` and no roadmap association is real work the project intends to do, but it is not scheduled. Ask a maintainer before starting on one. Roadmap placement does not assign an owner. A roadmap issue still needs a human contributor, a direct user instruction to an agent, or an unattended-agent queue label. @@ -204,7 +213,7 @@ Maintainers use the `agent:*` workflow to queue work for always-on or unattended The normal delegated workflow is: ```text -state:accepted +(state:accepted OR roadmap placement) | +-- agent:plan-requested | @@ -247,12 +256,12 @@ 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`, invites contribution or has maintainer confirmation, and has no conflicting owner or implementation. | -| An unattended agent scanning for planning work | The issue has `state:accepted` and the human-applied `agent:plan-requested` label. | -| An unattended agent scanning for implementation work | The issue has `state:accepted`, an approved plan, and the human-applied `agent:implementation-requested` label. | -| An agent directly instructed by a user | The issue has `state:accepted`, no conflicting owner or implementation, and the instruction explicitly requests the phase the agent will perform. | +| 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. | -Issues with `state:triage-needed`, `state:needs-info`, or `state:validated` are not ready for implementation. Roadmap placement alone never makes an issue ready. +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. #### Stale Issues diff --git a/README.md b/README.md index 3d5aeb6fb4..1d9f23d229 100644 --- a/README.md +++ b/README.md @@ -216,7 +216,7 @@ Your agent can load skills for CLI usage (`openshell-cli`), gateway troubleshoot OpenShell is developed using the same agent-driven workflows it enables. The `.agents/skills/` directory contains workflow automation that powers the project's development cycle: -- **Spike and build:** Investigate a problem with `create-spike`; a human accepts or declines it and separately places it on the [roadmap](https://github.com/orgs/NVIDIA/projects/233). Accepted work can remain human-owned or enter the optional, human-gated `agent:*` planning and implementation workflow. +- **Spike and build:** Investigate a problem with `create-spike`; a human accepts it with `state:accepted` or [roadmap](https://github.com/orgs/NVIDIA/projects/233) placement, or declines it. Accepted work can remain human-owned or enter the optional, human-gated `agent:*` planning and implementation workflow. - **Triage and route:** Community issues are assessed with `triage-issue`. Agents establish technical validity and impact; humans decide whether the project should act and where the work sits on the roadmap. - **Security review:** `review-security-issue` produces a severity assessment and remediation plan. `fix-security-issue` implements it. - **Policy authoring:** `generate-sandbox-policy` creates YAML policies from plain-language requirements or API documentation. @@ -244,7 +244,7 @@ All agent implementation work is human-gated: maintainers explicitly request a p ## Contributing -OpenShell is built agent-first — your agent is your first collaborator. Before opening issues or submitting code, point your agent at the repo and let it use the skills in `.agents/skills/` to investigate, diagnose, and prototype. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full agent skills table, contribution workflow, and development setup. +OpenShell is built agent-first. Issues should describe the affected persona, desired outcome, impact, and workflow; reporters do not need to diagnose the code or attach agent output. Once maintainers accept work, contributors should use the skills in `.agents/skills/` to investigate the current code and behavior, implement the change, and verify it. If an issue contains earlier diagnostics, verify them rather than relying on them. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full agent skills table, contribution workflow, and development setup. ## Telemetry