Created a new template for feature requests

.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:
+  - "@<author>"
+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(<author>): 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(<author>): ...` placeholders for incomplete sections. Make each TODO
+specific enough that the user knows what to add.
+
+Good TODOs:
+
+- `TODO(<author>): describe the target users for this feature.`
+- `TODO(<author>): explain the current workaround and why it is insufficient.`
+- `TODO(<author>): 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(<author>)` 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.

.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 <pr-number-or-url> --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: <concise description>" \
+  --title "feat: <concise feature title>" \
   --body "$(cat <<'EOF'
-## Problem Statement
+## Feature request document or PR
+
+<Link the completed feature request document, or the PR containing it if the
+document is not merged yet.>
 
-<What problem does this solve? Why does it matter?>
+## Summary
 
-## Proposed Design
+<Briefly summarize the feature and user-visible outcome.>
 
-<How should this work? Describe the system behavior, components involved,
-and user-facing interface.>
+## Review focus
 
-## Alternatives Considered
+<What feedback do you want from maintainers?>
 
-<What other approaches were evaluated? Why is this design better?>
+## Related work and prior art
 
-## Agent Investigation
+<Link related issues, discussions, docs, examples, or similar features in other
+projects.>
 
-<If the agent explored the codebase to assess feasibility, paste findings here.>
+## 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:

.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

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
 
@@ -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 feature proposal with a design — not a "please build this" request.
+- 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`
 
@@ -196,12 +200,26 @@ 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. 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. 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.
 
 ## Documentation