From 2205577b490b2b7fe795b049f9739417a909886f Mon Sep 17 00:00:00 2001 From: Kirit93 Date: Tue, 5 May 2026 11:38:15 -0700 Subject: [PATCH 1/4] Added feature request template --- feature-requests/0000-template/README.md | 152 +++++++++++++++++ feature-requests/README.md | 208 +++++++++++++++++++++++ rfc/0000-template/README.md | 15 +- rfc/README.md | 79 +++++++-- 4 files changed, 440 insertions(+), 14 deletions(-) create mode 100644 feature-requests/0000-template/README.md create mode 100644 feature-requests/README.md diff --git a/feature-requests/0000-template/README.md b/feature-requests/0000-template/README.md new file mode 100644 index 000000000..516a6833d --- /dev/null +++ b/feature-requests/0000-template/README.md @@ -0,0 +1,152 @@ +--- +authors: + - "@your-github-username" +state: draft +links: + - (GitHub issue where this feature request is discussed) + - (related discussions, RFCs, PRs, docs, or prior art) +--- + +# Feature Request NNNN - Your Title Here + + + +## Summary + +Briefly describe the feature and the user-visible outcome. + +## User problem + +What user problem does this solve? Who experiences it, how often, and what is +the impact today? + +## Target users + +Who is this for? + +## Use cases + +Describe the main workflows this feature should support. + +Example: + +> As a ... +> I want ... +> So that ... + +## Why this belongs in OpenShell + +Explain why OpenShell should own this capability instead of leaving it to user +configuration, documentation, an external tool, a downstream fork, or a +platform-specific workaround. + +## Product scope + +What should be included in this feature? + +## Non-goals + +What is intentionally out of scope? + +## Suggested product surface + +Where should users experience this capability? + +- Built-in OpenShell behavior available across supported environments +- A capability exposed by one or more compute drivers +- A provider or external-service integration +- Sandbox policy or security configuration +- Inference routing configuration +- CLI, TUI, SDK, docs, or examples +- Not sure; maintainer guidance requested + +## Availability and support expectations + +Where should users expect this feature to work? Answer in terms of user +expectations and portability, not implementation details. + +- Should every OpenShell user expect this feature to exist? +- Is the feature only meaningful in specific operating environments or + deployment modes? +- Is this mainly about integrating with a specific external service? +- What should users be able to rely on consistently across environments? + +## Requirements + +List product requirements. These should describe observable behavior, not code +structure. + +- The feature must ... +- The feature should ... +- The feature may ... + +## User experience + +Describe the expected user experience at a high level. Include example commands, +screens, settings, or docs only when they clarify the product behavior. + +## Success criteria + +How will maintainers know this feature worked? How can success be measured? + +## Priority and urgency + +Why should this be done now? What happens if it is deferred? + +## Risks and tradeoffs + +What are the product risks? + +Examples: + +- increases OpenShell scope too much +- creates confusing overlap with an existing capability +- adds maintenance burden for drivers or providers +- creates inconsistent behavior across environments +- weakens security, privacy, or policy expectations + +## Alternatives and workarounds + +What can users do today? Why is that insufficient? + +What other product approaches were considered? + +## Related work and prior art + +Link to related issues, discussions, docs, or examples in OpenShell and other +projects. + +## Technical RFC + +Link an RFC here if this feature is approved and needs detailed technical +design. + +- RFC: TBD + +## Contribution intent + +Would you or your organization help move this forward? + +- [ ] I can help define requirements +- [ ] I can test or validate the feature +- [ ] I can contribute implementation after the feature is approved +- [ ] I need maintainer guidance before committing to contribution +- [ ] I cannot contribute at this time + +## Open questions + +- ... diff --git a/feature-requests/README.md b/feature-requests/README.md new file mode 100644 index 000000000..5a1e6af88 --- /dev/null +++ b/feature-requests/README.md @@ -0,0 +1,208 @@ +# OpenShell Feature Requests + +Feature requests are product proposals for OpenShell. They describe a user need, +why the capability belongs in OpenShell, what the product should do, and how +maintainers should evaluate success. They are intentionally lighter than RFCs: +feature requests decide **whether** a capability should exist and where it +belongs at the product level; RFCs decide **how** approved, technically involved +capabilities should be designed. + +Use feature requests to create a durable record of product intent before +implementation begins. + +## Feature requests vs other artifacts + +OpenShell has several places where ideas and design information live. Use this +guide to pick the right one: + +| Artifact | Purpose | When to use | +|----------|---------|-------------| +| **GitHub Discussion** | Gauge interest in a rough idea | You have an early thought and want feedback before writing a proposal | +| **GitHub issue** | Discuss a concrete feature request | You have a feature request draft or clear product ask and need a durable discussion record | +| **Feature request** | Define product requirements and decide whether OpenShell should own a capability | You know the user problem and want maintainers to evaluate scope, priority, and product fit | +| **Spike issue** (`create-spike`) | Investigate implementation feasibility for scoped work | You need codebase research before an RFC or implementation issue | +| **RFC** | Propose detailed technical design for an approved or likely feature | The change affects architecture, public contracts, multiple components, or requires broad technical consensus | +| **Architecture doc** (`architecture/`) | Document how things work today | Living reference material updated as the system evolves | + +The key distinction: **feature requests are product requirements; RFCs are +technical design proposals.** A feature request may lead to an RFC, a spike, a +normal implementation issue, or rejection. + +## When to use a feature request + +Use a feature request when you want to propose: + +- a new user-facing capability, +- a change to OpenShell's product behavior or supported workflows, +- a new environment-specific capability that users should be able to rely on, +- a new supported integration surface, +- a cross-platform behavior whose availability and support expectations need + to be clear, +- a significant documentation or example initiative that changes how users + adopt OpenShell. + +Feature requests should be written from a user and product perspective. They +should explain the problem, target users, use cases, product scope, non-goals, +success criteria, and why OpenShell is the right layer for the capability. + +## When not to use a feature request + +Skip the feature request process for: + +- bugs, +- small implementation tasks for already-approved behavior, +- routine refactors, +- dependency updates, +- documentation fixes that do not change product direction, +- detailed technical designs without an approved product need. + +If the main question is "how should this be implemented?", start with an RFC or +a spike after the product need is clear. + +## Best practices + +Strong feature requests: + +- start with a concrete user problem, +- identify who benefits and how often they encounter the problem, +- explain why the capability belongs in OpenShell rather than user config, + external tooling, or a downstream fork, +- distinguish product requirements from implementation choices, +- describe where users should expect the feature to be available, +- define non-goals so the scope does not drift, +- describe observable success criteria, +- include current workarounds and why they are not enough, +- link related issues, discussions, RFCs, docs, and prior art, +- call out security, privacy, policy, or portability tradeoffs at the product + level. + +Avoid: + +- proposing code structure, internal APIs, or detailed implementation plans, +- treating the feature request as a "please build this" ticket, +- bundling several unrelated features into one proposal, +- assuming every useful integration should be built in, +- skipping non-goals and tradeoffs. + +## Availability and support expectations + +Feature requests should explain where users should expect a capability to work. +This is a product question, not an implementation design question. + +- Should every OpenShell user expect this capability to exist? +- Is it only meaningful in certain operating environments or deployment modes? +- Is it tied to a specific external service or integration? +- What should users be able to rely on consistently across environments? +- Can the user need be met by documenting an existing supported workflow? + +If the answer requires detailed contracts, capability negotiation, or technical +design, link a follow-up RFC after the feature request is approved. + +## Feature request metadata and state + +Every feature request starts with YAML front matter: + +```yaml +--- +authors: + - "@username" +state: draft +links: + - https://github.com/NVIDIA/OpenShell/issues/123 + - https://github.com/NVIDIA/OpenShell/discussions/456 +--- +``` + +We track the following metadata: + +- **authors**: The authors and owners of the feature request. Use GitHub + usernames. +- **state**: The current lifecycle state. +- **links**: Related issues, discussions, RFCs, PRs, docs, or prior art. +- **superseded_by**: *(optional)* For feature requests in the `superseded` + state, the feature request number that replaces this one. + +A feature request can be in one of the following states: + +| State | Description | +|-------|-------------| +| `draft` | The proposal is being written and is not ready for review. | +| `review` | Under active discussion in a linked GitHub issue and pull request. | +| `accepted` | Maintainers agree the feature belongs in OpenShell. | +| `rejected` | The feature was reviewed and declined. | +| `implemented` | The accepted feature has shipped or is otherwise complete. | +| `superseded` | Replaced by a newer feature request. | + +Acceptance means the product direction is approved. It does not necessarily mean +the implementation is ready to begin; maintainers may still require an RFC, +spike, or smaller implementation issues. + +## Lifecycle + +### 1. Start with discussion when the idea is rough + +If the problem or product fit is still uncertain, consider opening a GitHub +Discussion first. Early discussion helps validate the need, surface tradeoffs, +and find the right reviewers. + +When the feature is concrete enough for product review, open a GitHub issue. +That issue is the durable discussion record for the feature request and should +be linked from the feature request front matter. + +### 2. Reserve a feature request number + +Look at the existing folders in this directory and choose the next available +number. If two authors choose the same number on separate branches, the later PR +should pick the next available number during review. + +### 3. Create the feature request + +Each feature request lives in its own folder: + +```text +feature-requests/NNNN-my-feature/ + README.md + (optional: supporting files) +``` + +Where `NNNN` is the feature request number, zero-padded to four digits, and +`my-feature` is a short descriptive name. + +To start a new feature request, copy the template folder: + +```shell +cp -r feature-requests/0000-template feature-requests/NNNN-my-feature +``` + +Fill in the metadata, include the linked GitHub issue, and keep the state as +`draft` while you are iterating. + +### 4. Open a pull request + +When the proposal is ready for review, update the state to `review` and open a +pull request. Link the GitHub issue, pull request, and any related discussions, +prior art, or RFCs in the front matter. + +### 5. Iterate and decide + +Maintainers and contributors review the product need, OpenShell fit, scope, +tradeoffs, priority, and availability expectations. The linked issue should +capture the product discussion; the pull request should carry the concrete doc +updates. The author should update the proposal as the discussion converges. + +If accepted, update the state to `accepted`. If declined, update the state to +`rejected` and summarize why. If replaced by a newer proposal, update the state +to `superseded`. + +### 6. Follow-up work + +After acceptance, maintainers decide the next artifact: + +- an RFC for detailed technical design, +- a spike issue for feasibility research, +- one or more implementation issues, +- documentation or example work, +- no immediate work if the feature is accepted but not prioritized. + +When the feature is fully delivered, update the state to `implemented` and link +the relevant PRs, issues, docs, and RFCs. diff --git a/rfc/0000-template/README.md b/rfc/0000-template/README.md index ec66ca967..cbeb1e4ac 100644 --- a/rfc/0000-template/README.md +++ b/rfc/0000-template/README.md @@ -3,7 +3,7 @@ authors: - "@your-github-username" state: draft links: - - (related PRs, discussions, or issues) + - (approved feature request, GitHub issue, PRs, discussions, or prior art) --- # RFC NNNN - Your Title Here @@ -12,6 +12,19 @@ links: See rfc/README.md for the full RFC process and state definitions. --> +## Feature request approval + +Before opening this RFC for review, confirm the product proposal has already +been approved. + +- [ ] Feature request document exists: `feature-requests/NNNN-feature-name/README.md` +- [ ] Feature request was discussed in a linked GitHub issue +- [ ] Core maintainers approved the feature request +- [ ] This RFC links to the approved feature request and GitHub issue in the front matter + +If this RFC is not tied to a feature request, explain why the feature request +gate does not apply. + ## Summary One paragraph explanation of the feature or change. diff --git a/rfc/README.md b/rfc/README.md index 67a643848..d018e616d 100644 --- a/rfc/README.md +++ b/rfc/README.md @@ -1,17 +1,46 @@ # OpenShell RFCs -Substantial changes to OpenShell should be proposed in writing before implementation begins. An RFC provides a consistent way to propose an idea, collect feedback from the community, build consensus, and document the decision for future contributors. Not every change needs an RFC — bug fixes, small features, and routine maintenance go through normal pull requests. RFCs are for the changes that are cross-cutting, potentially controversial, or significant enough that stakeholders should weigh in before code is written. +Substantial technical changes to OpenShell should be proposed in writing before +implementation begins. An RFC provides a consistent way to review technical +design, collect feedback from the community, build consensus, and document the +decision for future contributors. + +RFCs are not the first step for new product capabilities. Feature-shaped work +should start with a feature request in `feature-requests/` so maintainers can +first decide whether the capability belongs in OpenShell, what product surface +it should occupy, and where users should expect it to be available. Once the +feature request has been discussed and approved by core maintainers, an RFC can +describe the detailed technical design. + +## Start with product approval + +Before opening an RFC for a new feature or product behavior, confirm: + +1. A feature request document exists under `feature-requests/`. +2. The feature request was discussed through a linked GitHub issue, with any + supporting discussion or pull request links included as needed. +3. Core maintainers approved the feature request. +4. The RFC links back to the approved feature request and GitHub issue. + +If the answer to any of these is "no", create or finish the feature request +before asking for RFC review. RFCs may skip this gate only when they are not +feature-shaped, such as internal process changes, test strategy, or technical +architecture cleanup without a new product capability. ## Start with a GitHub Discussion -Before writing an RFC, consider opening a [GitHub Discussion](https://github.com/NVIDIA/OpenShell/discussions) to gauge interest and get early feedback. This helps: +Before writing a feature request or RFC, consider opening a +[GitHub Discussion](https://github.com/NVIDIA/OpenShell/discussions) to gauge +interest and get early feedback. This helps: - Validate that the problem is worth solving - Surface potential concerns early - Build consensus before investing in a detailed proposal - Identify the right reviewers and stakeholders -If the discussion shows sufficient interest and the idea has merit, then it's time to write an RFC to detail the plan and technical approach. +If the discussion shows sufficient interest and the idea has merit, write a +feature request first when the work changes product behavior. After that feature +request is approved, write an RFC if detailed technical design is needed. ## RFCs vs other artifacts @@ -20,18 +49,26 @@ OpenShell has several places where design information lives. Use this guide to p | Artifact | Purpose | When to use | |----------|---------|-------------| | **GitHub Discussion** | Gauge interest in a rough idea | You have a thought but aren't sure it's worth a proposal yet | +| **Feature request** | Define product requirements and get maintainer approval for a capability | You know the user problem and want maintainers to evaluate OpenShell fit, scope, priority, and availability expectations | | **Spike issue** (`create-spike`) | Investigate implementation feasibility for a scoped change | You need to explore the codebase and produce a buildable issue for a specific component or feature | -| **RFC** | Propose a cross-cutting decision that needs broad consensus | Architectural changes, API contracts, process changes, or anything that spans multiple components or teams | +| **RFC** | Propose technical design for approved or clearly needed work that requires consensus | Architecture, API contracts, protocol changes, test design, or anything that spans multiple components or teams | | **Architecture doc** (`architecture/`) | Document how things work today | Living reference material — updated as the system evolves | -The key distinction: **spikes investigate whether and how something can be done; RFCs propose that we should do it and seek agreement on the approach.** A spike may precede an RFC (to gather data) or follow one (to flesh out implementation details). When an RFC reaches `implemented`, its relevant content should be folded into the appropriate `architecture/` docs so the living reference stays current. +The key distinction: **feature requests decide whether OpenShell should own a +capability; RFCs decide how an approved capability or technical change should be +designed; spikes investigate whether and how something can be done.** A spike +may precede an RFC to gather data or follow one to flesh out implementation +details. When an RFC reaches `implemented`, its relevant content should be +folded into the appropriate `architecture/` docs so the living reference stays +current. ## When to use an RFC The following are examples of when an RFC is appropriate: +- An approved feature request needs detailed technical design - An architectural or design decision for the platform -- Change to an API or command-line tool +- Change to an API, protocol, or command-line contract - Change to an internal API or tool - Add or change a company or team process - A design for testing @@ -42,6 +79,7 @@ RFCs don't only apply to technical ideas but overall project ideas and processes Not everything needs an RFC. Skip the RFC process for: +- Feature ideas that have not gone through feature request approval - Bug fixes - Small feature additions scoped to a single component (use a spike instead) - Documentation changes @@ -85,11 +123,26 @@ An RFC can be in one of the following states: ## RFC lifecycle -### 1. Reserve an RFC number +### 1. Confirm feature request approval + +For feature-shaped work, make sure the product proposal is complete before +starting RFC review: + +- Create a feature request under `feature-requests/`. +- Link the GitHub issue where the feature request was discussed, plus any + supporting discussion or PR links. +- Confirm core maintainers approved the feature request. +- Add the approved feature request and GitHub issue links to the RFC front + matter. + +If the RFC is not tied to a feature request, explain why the feature request gate +does not apply. + +### 2. Reserve an RFC number Look at the existing RFC folders in this directory and choose the next available number. If two authors happen to pick the same number on separate branches, the conflict is resolved during PR review — the later PR simply picks the next available number. -### 2. Create your RFC +### 3. Create your RFC Each RFC lives in its own folder: @@ -109,25 +162,25 @@ cp -r rfc/0000-template rfc/NNNN-my-feature Fill in the metadata and start writing. The state should be `draft` while you're iterating. -### 3. Open a pull request +### 4. Open a pull request -When you're ready for feedback, update the state to `review` and open a pull request. Add the PR link to the `pr` field in the metadata. +When you're ready for feedback, update the state to `review` and open a pull request. Add the PR link to the `links` field in the metadata. The PR is where discussion happens. Anyone subscribed to the repo will get a notification and can read your RFC and provide feedback. -### 4. Iterate and build consensus +### 5. Iterate and build consensus The comments you choose to accept are up to you as the owner of the RFC, but you should remain empathetic in how you engage. For those giving feedback, be sure that all feedback is constructive. RFCs rarely go through this process unchanged. Make edits as new commits to the PR and leave comments explaining your changes. -### 5. Merge the pull request +### 6. Merge the pull request After there has been time for folks to comment, the RFC author requests merge and a maintainer approves and merges. The state should be updated from `review` to `accepted`. If the proposal is declined, the state should be set to `rejected`. The timing is left to the author's discretion. As a guideline, a few business days seems reasonable, but circumstances may dictate a different timeline. In general, RFCs shouldn't be merged if no one else has read or commented on it. If no one is reading your RFC, it's time to explicitly ask someone to give it a read! -### 6. Implementation +### 7. Implementation Once an RFC has been entirely implemented, its state should be moved to `implemented`. This represents ideas that have been fully developed. While discussion on implemented RFCs is permitted, changes would be expected to be infrequent. From eaade3a5c6ca7f41c9ef981ee218e2e52bb06e7e Mon Sep 17 00:00:00 2001 From: Kirit93 Date: Tue, 5 May 2026 11:41:44 -0700 Subject: [PATCH 2/4] Updated contributing.md --- CONTRIBUTING.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0121ad608..d203b62bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,7 +34,7 @@ We use a vouch system. This exists because AI makes it trivial to generate plaus Issues labeled [`good-first-issue`](https://github.com/NVIDIA/OpenShell/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue) are scoped, well-documented, and friendly to new contributors. Start there. If you need guidance, comment on the issue. -All open issues are actionable — if it's in the issue tracker, it's ready to be worked on. +Open issues are not all the same: bugs and implementation issues may be ready to work, while feature proposal issues are product discussions until maintainers accept the feature request. ## Before You Open an Issue @@ -48,7 +48,7 @@ This project ships with [agent skills](#agent-skills-for-contributors) that can ### 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. +- A concrete feature idea that needs product discussion. Open a GitHub issue first; for substantial product changes, create a feature request under `feature-requests/` and link it from the issue. - An infrastructure problem that the gateway deployment troubleshooting skill could not resolve. - An inference setup problem that the `debug-inference` skill could not resolve. - Security vulnerabilities must follow [SECURITY.md](SECURITY.md) — **not** GitHub issues. @@ -196,12 +196,25 @@ These are the primary `mise` tasks for day-to-day development: | `docs/` | Published Fern docs source, navigation, and content assets | | `fern/` | Fern site config, components, and theme assets | | `architecture/` | Architecture docs and plans | +| `feature-requests/` | Product requirements and feature proposal templates | | `rfc/` | Request for Comments proposals | | `.agents/` | Agent skills and persona definitions | -## RFCs +## Feature Requests and RFCs -For cross-cutting architectural decisions, API contract changes, or process proposals that need broad consensus, use the RFC process. RFCs live in `rfc/` — copy the template, fill it in, and open a PR for discussion. See [rfc/README.md](rfc/README.md) for the full lifecycle and guidelines on when to write an RFC versus a spike issue or architecture doc. +Feature requests are product proposals. Use them when you want maintainers to decide whether a capability belongs in OpenShell, who it serves, what user outcome it should provide, and where users should expect it to be available. Feature requests live in `feature-requests/`; copy `feature-requests/0000-template`, fill it in, and link the GitHub issue where the feature is discussed. + +RFCs are technical design proposals. Use them after a feature request has been discussed and approved by core maintainers, or for non-feature technical decisions such as architecture, API contracts, process changes, or test design. RFCs live in `rfc/`; copy the template, fill it in, and link the approved feature request when applicable. + +Typical flow for new product capabilities: + +1. Open a GitHub issue to discuss the feature. +2. Create a feature request under `feature-requests/` and link the issue. +3. Get core maintainer approval on the product direction. +4. Create an RFC only if detailed technical design is needed. +5. Break accepted work into implementation issues or PRs. + +See [feature-requests/README.md](feature-requests/README.md) and [rfc/README.md](rfc/README.md) for the full processes. ## Documentation From 17b0889acf99b90518c952424955e2d39a6a955c Mon Sep 17 00:00:00 2001 From: Kirit93 Date: Wed, 6 May 2026 11:22:24 -0700 Subject: [PATCH 3/4] Added skill and simplified workflow for creating an issue --- .../skills/create-feature-request/SKILL.md | 140 ++++++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.yml | 41 +++-- CONTRIBUTING.md | 21 ++- feature-requests/0000-template/README.md | 46 +++++- feature-requests/README.md | 69 +++++---- 5 files changed, 255 insertions(+), 62 deletions(-) create mode 100644 .agents/skills/create-feature-request/SKILL.md diff --git a/.agents/skills/create-feature-request/SKILL.md b/.agents/skills/create-feature-request/SKILL.md new file mode 100644 index 000000000..da4f4e725 --- /dev/null +++ b/.agents/skills/create-feature-request/SKILL.md @@ -0,0 +1,140 @@ +--- +name: create-feature-request +description: Create a numbered OpenShell feature request document from a user's feature idea, populate it from the information provided, ask focused follow-up questions, and leave the user with a draft to complete. Use when the user says things like "create a feature request to do XYZ", "start a feature request doc", "draft a feature proposal", or "create a product proposal". +--- + +# Create Feature Request + +Create a repo-backed feature request document from the user's feature idea. The +feature request is a product proposal, not an implementation plan. + +The skill's job is to start and improve the draft. The user owns completing the +document before asking for review. + +## Core Flow + +```text +User asks: "create a feature request to do XYZ" + | + +-- Copy the feature request template into the next numbered folder + | + +-- Populate the new README with information the user already provided + | + +-- Ask focused follow-up questions about missing product context + | + +-- Update the doc with the user's answers + | + +-- Ask the user to complete any remaining TODOs +``` + +Do not create a GitHub issue, open a PR, mark the document complete, or change +the state from `draft` unless the user explicitly asks for that later. + +## Step 1: Create The Draft + +Feature requests live under `feature-requests/NNNN-short-slug/`. + +Find the next available number by inspecting existing folders: + +```bash +find feature-requests -maxdepth 1 -type d -name '[0-9][0-9][0-9][0-9]-*' | sort +``` + +Choose the next zero-padded number. Create a short lowercase slug from the +feature title using product language, not implementation details. + +Copy the template: + +```bash +cp -r feature-requests/0000-template feature-requests/NNNN-short-slug +``` + +Then edit `feature-requests/NNNN-short-slug/README.md`. + +Set the front matter: + +```yaml +--- +authors: + - "@" +state: draft +links: + - (GitHub issue to be created after this feature request doc is complete and GitHub-visible) + - (related discussions, RFCs, PRs, docs, or prior art) +--- +``` + +Use the user's GitHub username when known. Otherwise use +`TODO(): add GitHub username`. + +## Step 2: Populate From User-Provided Information + +Fill sections only when the user's request, notes, or existing draft provide +clear support. Do not invent product requirements. + +Use `TODO(): ...` placeholders for incomplete sections. Make each TODO +specific enough that the user knows what to add. + +Good TODOs: + +- `TODO(): describe the target users for this feature.` +- `TODO(): explain the current workaround and why it is insufficient.` +- `TODO(): define success criteria maintainers can evaluate.` + +Do not add code-level design, internal API structure, or implementation plans. +Feature requests stay focused on user problems, product requirements, scope, +non-goals, success criteria, risks, alternatives, and OpenShell fit. + +## Step 3: Ask Follow-Up Questions + +After the first draft is created, inspect the remaining TODOs and ask the user +for the highest-value missing information. Ask a small number of focused +questions rather than dumping the whole template back on the user. + +Prefer questions about: + +- the user problem, +- target users, +- desired outcome, +- current workaround, +- why OpenShell should own the capability, +- product scope and non-goals, +- availability and support expectations, +- success criteria, +- risks, tradeoffs, alternatives, and prior art. + +When the user answers, update the feature request doc with the new information +and leave unresolved sections as visible `TODO()` placeholders. + +## Step 4: Hand The Draft Back To The User + +When the draft has been populated with the available information, report: + +1. The created file path. +2. The sections that still need user input. +3. A clear instruction that the user should complete the remaining TODOs before + asking for review, opening a PR, or creating a linked discussion issue. + +Never present an agent-generated feature request as complete or approved. Core +maintainer approval is human-only. + +## Output Shape + +```markdown +Started feature request draft: +[README.md](/absolute/path/to/feature-requests/NNNN-short-slug/README.md:1) + +I populated the sections supported by your request. Please review the draft and complete any remaining +TODOs before asking for feature request review. +``` + +## Relationship To Other Workflows + +- Use this skill for substantial feature ideas that need a product + proposal. +- Use GitHub Discussions for rough feature ideas that are not ready for a + feature request document. +- Create a linked GitHub issue only after the feature request doc is complete + and GitHub-visible. +- Use the RFC process only after maintainers review the completed feature + request and ask for deeper technical design. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index bdf2cacc1..081f122fd 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,50 +1,43 @@ name: Feature Request -description: Propose a feature with a design. Not a "please build this" request. +description: Discuss a completed feature request document or PR. type: Feature body: - type: markdown attributes: value: | - ## Design-First Feature Proposals + ## Feature request discussion - OpenShell feature requests must include a design proposal — describe the system behavior you want, not just the outcome. If your agent explored the codebase to assess feasibility (e.g., using the `create-spike` skill), include its findings. + Use this issue to discuss a completed feature request document. For substantial proposals, start with `create-feature-request`, complete the draft under `feature-requests/`, make it visible through a GitHub URL, then open this issue with the document or PR linked. - type: textarea - id: problem + id: feature-request-doc attributes: - label: Problem Statement - description: What problem does this solve? Why does it matter? + label: Feature request document or PR + description: Link the completed feature request document, or the PR containing it if the document is not merged yet. validations: required: true - type: textarea - id: design + id: summary 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: Summary + description: Briefly summarize the feature and user-visible outcome. validations: required: true - type: textarea - id: alternatives + id: review-focus attributes: - label: Alternatives Considered - description: What other approaches did you evaluate? Why is the proposed design better? + label: Review focus + description: What feedback do you want from maintainers? validations: required: true - type: textarea - id: agent-investigation + id: related-work 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. - 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 + label: Related work and prior art + description: Link related issues, discussions, docs, examples, or similar features in other projects. validations: required: false @@ -53,7 +46,7 @@ body: attributes: label: Checklist options: - - label: I've reviewed existing issues and the architecture docs + - label: The linked feature request doc or PR is complete and ready for discussion required: true - - label: This is a design proposal, not a "please build this" request + - label: The linked feature request doc describes product requirements, not an implementation plan required: true diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d203b62bf..07646f2f4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,12 +43,14 @@ This project ships with [agent skills](#agent-skills-for-contributors) that can 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. +4. If the agent cannot resolve it, open an issue. For bug and troubleshooting + reports, attach the agent's diagnostic output; those issue templates require + it. ### When to Open an Issue - A real bug that your agent confirmed and could not fix. -- A concrete feature idea that needs product discussion. Open a GitHub issue first; for substantial product changes, create a feature request under `feature-requests/` and link it from the issue. +- A completed feature request document that needs product discussion. For substantial product changes, use `create-feature-request` to start a feature request draft, complete the draft, make it visible through a GitHub URL, and then create a GitHub issue that links to the doc or PR for discussion. - An infrastructure problem that the gateway deployment troubleshooting skill could not resolve. - An inference setup problem that the `debug-inference` skill could not resolve. - Security vulnerabilities must follow [SECURITY.md](SECURITY.md) — **not** GitHub issues. @@ -70,6 +72,7 @@ Skills live in `.agents/skills/`. Your agent's harness can discover and load the | Getting Started | `debug-inference` | Diagnose `inference.local`, host-backed local inference, and direct external inference setup issues | | Contributing | `create-spike` | Investigate a problem, produce a structured GitHub issue | | Contributing | `build-from-issue` | Plan and implement work from a GitHub issue (maintainer workflow) | +| Contributing | `create-feature-request` | Start and iteratively fill a numbered feature request draft | | Contributing | `create-github-issue` | Create well-structured GitHub issues | | Contributing | `create-github-pr` | Create pull requests with proper conventions | | Reviewing | `review-github-pr` | Summarize PR diffs and key design decisions | @@ -88,6 +91,7 @@ Skills connect into pipelines. Individual skill files don't describe these relat - **Community inflow:** `triage-issue` → `create-spike` → `build-from-issue` - **Internal development:** `create-spike` → `build-from-issue` +- **Feature proposals:** `create-feature-request` → user completes proposal → feature request PR/doc link → linked GitHub issue → product review - **Security:** `review-security-issue` → `fix-security-issue` - **Policy iteration:** `openshell-cli` → `generate-sandbox-policy` @@ -202,17 +206,18 @@ These are the primary `mise` tasks for day-to-day development: ## Feature Requests and RFCs -Feature requests are product proposals. Use them when you want maintainers to decide whether a capability belongs in OpenShell, who it serves, what user outcome it should provide, and where users should expect it to be available. Feature requests live in `feature-requests/`; copy `feature-requests/0000-template`, fill it in, and link the GitHub issue where the feature is discussed. +Feature requests are product proposals. Use them when you want maintainers to decide whether a capability belongs in OpenShell, who it serves, what user outcome it should provide, and where users should expect it to be available. For substantial proposals, use the `create-feature-request` skill to start a draft under `feature-requests/`, complete the draft, make it visible through a GitHub URL, and then create a GitHub issue that links to the completed feature request doc or PR. RFCs are technical design proposals. Use them after a feature request has been discussed and approved by core maintainers, or for non-feature technical decisions such as architecture, API contracts, process changes, or test design. RFCs live in `rfc/`; copy the template, fill it in, and link the approved feature request when applicable. Typical flow for new product capabilities: -1. Open a GitHub issue to discuss the feature. -2. Create a feature request under `feature-requests/` and link the issue. -3. Get core maintainer approval on the product direction. -4. Create an RFC only if detailed technical design is needed. -5. Break accepted work into implementation issues or PRs. +1. Use `create-feature-request` to start a numbered draft. +2. Complete the feature request draft. +3. Open a PR or push the doc so it has a GitHub URL. +4. Create a GitHub issue that links to the completed feature request doc or PR. +5. Review the feature request in the PR and linked issue, then get core maintainer approval on the product direction. +6. Create an RFC only if detailed technical design is needed. See [feature-requests/README.md](feature-requests/README.md) and [rfc/README.md](rfc/README.md) for the full processes. diff --git a/feature-requests/0000-template/README.md b/feature-requests/0000-template/README.md index 516a6833d..a730184c1 100644 --- a/feature-requests/0000-template/README.md +++ b/feature-requests/0000-template/README.md @@ -3,7 +3,7 @@ authors: - "@your-github-username" state: draft links: - - (GitHub issue where this feature request is discussed) + - (GitHub issue to be created after this feature request doc is complete and GitHub-visible) - (related discussions, RFCs, PRs, docs, or prior art) --- @@ -20,6 +20,10 @@ This document should explain what users need, why the feature belongs in OpenShell, how success will be evaluated, and whether the capability should be available everywhere or only in specific environments. +This document may start as an agent-generated draft from a feature idea. The +author is responsible for completing all `TODO()` placeholders before +asking for feature request review in a PR or linked GitHub issue. + Avoid detailed implementation design here. If maintainers approve the feature request and the work needs deeper technical design, link an RFC in the "Technical RFC" section below. @@ -29,15 +33,21 @@ request and the work needs deeper technical design, link an RFC in the Briefly describe the feature and the user-visible outcome. +TODO(): complete this section. + ## User problem What user problem does this solve? Who experiences it, how often, and what is the impact today? +TODO(): complete this section. + ## Target users Who is this for? +TODO(): complete this section. + ## Use cases Describe the main workflows this feature should support. @@ -48,20 +58,28 @@ Example: > I want ... > So that ... +TODO(): complete this section. + ## Why this belongs in OpenShell Explain why OpenShell should own this capability instead of leaving it to user configuration, documentation, an external tool, a downstream fork, or a platform-specific workaround. +TODO(): complete this section. + ## Product scope What should be included in this feature? +TODO(): complete this section. + ## Non-goals What is intentionally out of scope? +TODO(): complete this section. + ## Suggested product surface Where should users experience this capability? @@ -74,6 +92,8 @@ Where should users experience this capability? - CLI, TUI, SDK, docs, or examples - Not sure; maintainer guidance requested +TODO(): choose the expected product surface and remove irrelevant options. + ## Availability and support expectations Where should users expect this feature to work? Answer in terms of user @@ -85,6 +105,8 @@ expectations and portability, not implementation details. - Is this mainly about integrating with a specific external service? - What should users be able to rely on consistently across environments? +TODO(): complete this section. + ## Requirements List product requirements. These should describe observable behavior, not code @@ -94,19 +116,27 @@ structure. - The feature should ... - The feature may ... +TODO(): replace these examples with concrete product requirements. + ## User experience Describe the expected user experience at a high level. Include example commands, screens, settings, or docs only when they clarify the product behavior. +TODO(): complete this section. + ## Success criteria -How will maintainers know this feature worked? How can success be measured? +How will maintainers know this feature worked? How can success be measured? + +TODO(): complete this section. ## Priority and urgency Why should this be done now? What happens if it is deferred? +TODO(): complete this section. + ## Risks and tradeoffs What are the product risks? @@ -119,17 +149,23 @@ Examples: - creates inconsistent behavior across environments - weakens security, privacy, or policy expectations +TODO(): replace these examples with proposal-specific risks. + ## Alternatives and workarounds What can users do today? Why is that insufficient? What other product approaches were considered? +TODO(): complete this section. + ## Related work and prior art Link to related issues, discussions, docs, or examples in OpenShell and other projects. +TODO(): complete this section. + ## Technical RFC Link an RFC here if this feature is approved and needs detailed technical @@ -137,6 +173,8 @@ design. - RFC: TBD +TODO(): leave as TBD unless maintainers request an RFC. + ## Contribution intent Would you or your organization help move this forward? @@ -147,6 +185,10 @@ Would you or your organization help move this forward? - [ ] I need maintainer guidance before committing to contribution - [ ] I cannot contribute at this time +TODO(): select the applicable contribution intent and remove the rest. + ## Open questions - ... + +TODO(): list remaining questions for reviewers, or write "None". diff --git a/feature-requests/README.md b/feature-requests/README.md index 5a1e6af88..d7ddcaac0 100644 --- a/feature-requests/README.md +++ b/feature-requests/README.md @@ -3,12 +3,15 @@ Feature requests are product proposals for OpenShell. They describe a user need, why the capability belongs in OpenShell, what the product should do, and how maintainers should evaluate success. They are intentionally lighter than RFCs: -feature requests decide **whether** a capability should exist and where it -belongs at the product level; RFCs decide **how** approved, technically involved -capabilities should be designed. +feature requests decide **whether** a capability should exist and where users +should expect it to be available; RFCs decide **how** approved, technically +involved capabilities should be designed. Use feature requests to create a durable record of product intent before -implementation begins. +implementation begins. For substantial proposals, start with the feature request +document, complete it, make it visible through a GitHub URL, and then create a +GitHub issue that links to the completed document or the PR containing it for +discussion. ## Feature requests vs other artifacts @@ -18,15 +21,15 @@ guide to pick the right one: | Artifact | Purpose | When to use | |----------|---------|-------------| | **GitHub Discussion** | Gauge interest in a rough idea | You have an early thought and want feedback before writing a proposal | -| **GitHub issue** | Discuss a concrete feature request | You have a feature request draft or clear product ask and need a durable discussion record | -| **Feature request** | Define product requirements and decide whether OpenShell should own a capability | You know the user problem and want maintainers to evaluate scope, priority, and product fit | +| **Feature request** | Define product requirements and decide whether OpenShell should own a capability | You have a substantial product proposal that needs review | +| **GitHub issue** | Discuss a feature request | You have a completed, GitHub-visible feature request document or PR and need a durable discussion thread | | **Spike issue** (`create-spike`) | Investigate implementation feasibility for scoped work | You need codebase research before an RFC or implementation issue | | **RFC** | Propose detailed technical design for an approved or likely feature | The change affects architecture, public contracts, multiple components, or requires broad technical consensus | | **Architecture doc** (`architecture/`) | Document how things work today | Living reference material updated as the system evolves | -The key distinction: **feature requests are product requirements; RFCs are -technical design proposals.** A feature request may lead to an RFC, a spike, a -normal implementation issue, or rejection. +The key distinction: **feature requests capture product requirements; GitHub +issues host discussion; RFCs capture technical design.** A feature request may +lead to an RFC, a spike, a normal implementation issue, or rejection. ## When to use a feature request @@ -44,6 +47,9 @@ Use a feature request when you want to propose: Feature requests should be written from a user and product perspective. They should explain the problem, target users, use cases, product scope, non-goals, success criteria, and why OpenShell is the right layer for the capability. +Use the `create-feature-request` skill to start a numbered draft. After the user +completes the draft and makes it visible through a GitHub URL, create a linked +GitHub issue for product discussion. ## When not to use a feature request @@ -82,6 +88,7 @@ Avoid: - treating the feature request as a "please build this" ticket, - bundling several unrelated features into one proposal, - assuming every useful integration should be built in, +- treating an agent-started draft as complete or approved, - skipping non-goals and tradeoffs. ## Availability and support expectations @@ -126,7 +133,7 @@ A feature request can be in one of the following states: | State | Description | |-------|-------------| -| `draft` | The proposal is being written and is not ready for review. | +| `draft` | The proposal is being written, possibly from an agent-started draft, and is not ready for discussion or review. | | `review` | Under active discussion in a linked GitHub issue and pull request. | | `accepted` | Maintainers agree the feature belongs in OpenShell. | | `rejected` | The feature was reviewed and declined. | @@ -139,23 +146,20 @@ spike, or smaller implementation issues. ## Lifecycle -### 1. Start with discussion when the idea is rough +### 1. Start a feature request draft If the problem or product fit is still uncertain, consider opening a GitHub Discussion first. Early discussion helps validate the need, surface tradeoffs, and find the right reviewers. -When the feature is concrete enough for product review, open a GitHub issue. -That issue is the durable discussion record for the feature request and should -be linked from the feature request front matter. +When the feature is concrete enough for product review, use the +`create-feature-request` skill to start a numbered feature request document. The +agent reserves the next available folder, copies the template, fills only what +the user provided, and leaves explicit `TODO()` placeholders. -### 2. Reserve a feature request number +The generated draft is a starting point, not a completed proposal. -Look at the existing folders in this directory and choose the next available -number. If two authors choose the same number on separate branches, the later PR -should pick the next available number during review. - -### 3. Create the feature request +### 2. Complete the feature request Each feature request lives in its own folder: @@ -168,20 +172,29 @@ feature-requests/NNNN-my-feature/ Where `NNNN` is the feature request number, zero-padded to four digits, and `my-feature` is a short descriptive name. -To start a new feature request, copy the template folder: +The template folder is: ```shell -cp -r feature-requests/0000-template feature-requests/NNNN-my-feature +feature-requests/0000-template ``` -Fill in the metadata, include the linked GitHub issue, and keep the state as -`draft` while you are iterating. +The user owns completing the draft. Fill in the product requirements, scope, +non-goals, success criteria, risks, alternatives, and contribution intent before +asking for discussion or PR review. + +### 3. Open a pull request for review + +When the completed proposal is ready for review, update the state to `review` +and open a pull request. The PR gives reviewers a GitHub-visible link to the +feature request document while the proposal is still unmerged. -### 4. Open a pull request +### 4. Create the linked GitHub issue -When the proposal is ready for review, update the state to `review` and open a -pull request. Link the GitHub issue, pull request, and any related discussions, -prior art, or RFCs in the front matter. +After the feature request document is complete and available through a GitHub +URL, create a GitHub issue that links to it or to the PR containing it. The +issue is the durable discussion thread for the proposal. Link the GitHub issue, +pull request, and any related discussions, prior art, or RFCs in the front +matter. ### 5. Iterate and decide From fe53a12b48914dd3e51aebc98fc0ee58ea372439 Mon Sep 17 00:00:00 2001 From: Kirit93 Date: Wed, 6 May 2026 11:32:53 -0700 Subject: [PATCH 4/4] Updated create github issue skill --- .agents/skills/create-github-issue/SKILL.md | 52 ++++++++++++++++----- 1 file changed, 40 insertions(+), 12 deletions(-) diff --git a/.agents/skills/create-github-issue/SKILL.md b/.agents/skills/create-github-issue/SKILL.md index b1311a297..9c9cf7f51 100644 --- a/.agents/skills/create-github-issue/SKILL.md +++ b/.agents/skills/create-github-issue/SKILL.md @@ -1,6 +1,6 @@ --- name: create-github-issue -description: Create GitHub issues using the gh CLI. Use when the user wants to create a new issue, report a bug, request a feature, or create a task in GitHub. Trigger keywords - create issue, new issue, file bug, report bug, feature request, github issue. +description: Create GitHub issues using the gh CLI. Use when the user wants to create a new issue, report a bug, create a linked feature request discussion issue, or create a task in GitHub. Trigger keywords - create issue, new issue, file bug, report bug, feature request issue, github issue. --- # Create GitHub Issue @@ -56,32 +56,60 @@ 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. +Feature request issues are discussion threads for completed feature request +documents. They are not the first artifact for substantial feature ideas. + +If the user asks to create a feature issue but does not have a completed, +GitHub-visible feature request doc or PR, do not create the issue yet. Tell the +user to use `create-feature-request` first. + +If the user already has a PR containing the completed feature request doc, use +that PR as the link target. Confirm the PR contains or links to a +`feature-requests/NNNN-*/README.md` document before creating the issue. + +Useful PR lookup: + +```bash +gh pr view --json title,url,body,files +``` + +Do not add a type label automatically. Apply area or topic labels only when +they are clearly known. ```bash gh issue create \ - --title "feat: " \ + --title "feat: " \ --body "$(cat <<'EOF' -## Problem Statement +## Feature request document or PR + + - +## Summary -## Proposed Design + - +## Review focus -## Alternatives Considered + - +## Related work and prior art -## Agent Investigation + - +## Checklist + +- [ ] The linked feature request doc or PR is complete and ready for discussion +- [ ] The linked feature request doc describes product requirements, not an implementation plan EOF )" ``` +After creating a feature request discussion issue, report the issue URL and +suggest adding it back to the feature request doc front matter and PR +description. Do not update the PR or doc unless the user explicitly asks. + ### Tasks For internal tasks that don't fit bug/feature templates: