OpenShell/feature-requests

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 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. 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

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
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 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

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. 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

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,
• treating an agent-started draft as complete or approved,
• 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:

---
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, 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.
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 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, 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(<author>) placeholders.

The generated draft is a starting point, not a completed proposal.

2. Complete the feature request

Each feature request lives in its own folder:

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.

The template folder is:

feature-requests/0000-template

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. Create the linked GitHub issue

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

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.