docs(rfc): improve template and add creation skill (#1889)

Add a create-rfc skill that directs agents through the OpenShell RFC process
and template.  Expand the RFC template with clearer section guidance and
suggested lengths.

Signed-off-by: Kris Hicks <khicks@nvidia.com>

Author: krishicks

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

@@ -0,0 +1,51 @@
+---
+name: create-rfc
+description: Create OpenShell RFC proposals in rfc/ from a design request. Use when the user asks to write, draft, start, create, or update an RFC, Request for Comments, architecture proposal, API proposal, process proposal, or cross-cutting design proposal that should follow the OpenShell RFC process and template.
+---
+
+# Create RFC
+
+## Workflow
+
+Create RFCs by following `rfc/README.md` and `rfc/0000-template/README.md`.
+Keep the template as the source of truth for section guidance.
+
+1. Read `rfc/README.md` to confirm when an RFC is appropriate, how to choose the
+   RFC number, and how the lifecycle works.
+2. Read `rfc/0000-template/README.md` before drafting. Follow its section
+   guidance, including scope, expected detail, and suggested section length.
+3. Choose the next available `NNNN` from the existing `rfc/NNNN-*` directories
+   unless the user provided a specific number.
+4. Create `rfc/NNNN-short-title/README.md` by copying the template and replacing
+   placeholders. Use a short hyphenated folder title.
+5. Fill in front matter with the RFC author, `state: draft`, and any related
+   links the user provided. If the author is unknown, use the requesting user's
+   GitHub handle when available or leave the template placeholder.
+6. Draft each section from the user's design context. Keep Summary concise,
+   Motivation readable by anyone, Non-goals explicit, Proposal focused on what
+   is being proposed, and Alternatives focused on credible competing approaches.
+7. Preserve uncertainty in Open questions instead of silently deciding unknowns.
+   If a missing decision blocks a coherent RFC, ask the user for that decision.
+8. Check the completed RFC against the template once more before finishing.
+
+## Writing Standards
+
+- Prefer concrete design statements over placeholder language.
+- Link to relevant issues, prior RFCs, and architecture docs when they provide
+  needed context.
+- Keep rejected or left-out designs in Alternatives, not Proposal.
+- Use Mermaid diagrams for architecture or data flow when a diagram would make
+  the proposal easier to review.
+- Do not update `architecture/` or published docs just because an RFC was
+  drafted. Those updates belong with implementation or with an accepted RFC when
+  the user asks for them.
+
+## Validation
+
+Before handing the RFC back to the user:
+
+- Verify the folder name and RFC number match the process in `rfc/README.md`.
+- Verify every template section is present or intentionally marked as not
+  applicable.
+- Run a Markdown formatting or lint check only if the repo already provides one
+  for Markdown-only changes.

.agents/skills/create-rfc/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Create RFC"
+  short_description: "Create OpenShell RFC proposals"
+  default_prompt: "Use $create-rfc to draft an OpenShell RFC from this design."

CONTRIBUTING.md

@@ -69,6 +69,7 @@ Skills live in `.agents/skills/`. Your agent's harness can discover and load the
 | Getting Started | `debug-openshell-cluster` | Diagnose gateway deployment and health issues                                                       |
 | 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    | `create-rfc`              | Create RFC proposals from the repository template                                                   |
 | Contributing    | `build-from-issue`        | Plan and implement work from a GitHub issue (maintainer workflow)                                   |
 | Contributing    | `create-github-issue`     | Create well-structured GitHub issues                                                                |
 | Contributing    | `create-github-pr`        | Create pull requests with proper conventions                                                        |
@@ -78,6 +79,7 @@ Skills live in `.agents/skills/`. Your agent's harness can discover and load the
 | Reviewing       | `test-release-canary`     | Dispatch and iterate on the Release Canary workflow that smoke-tests published artifacts            |
 | Triage          | `triage-issue`            | Assess, classify, and route community-filed issues                                                  |
 | Platform        | `generate-sandbox-policy` | Generate YAML sandbox policies from requirements or API docs                                        |
+| Platform        | `helm-dev-environment`    | Start and manage the local Kubernetes development environment                                       |
 | Platform        | `tui-development`         | Development guide for the ratatui-based terminal UI                                                 |
 | Documentation   | `update-docs`             | Scan recent commits and draft doc updates for user-facing changes                                   |
 | Maintenance     | `sync-agent-infra`        | Detect and fix drift across agent-first infrastructure files                                        |

rfc/0000-template/README.md

@@ -14,36 +14,132 @@ See rfc/README.md for the full RFC process and state definitions.
 
 ## Summary
 
-One paragraph explanation of the feature or change.
+Provide a brief overview of the change in one or two paragraphs. Focus on what
+the RFC proposes and the outcome it is intended to enable. Avoid diving into the
+full background, implementation detail, or tradeoff analysis here.
+
+A reader should be able to understand the intent of the RFC from this section
+alone.
 
 ## Motivation
 
-Why are we doing this? What problem does it solve? What use cases does it support?
+Explain why this change is necessary now. Describe the current problem, who it
+affects, and the workflows that are not well served today.
+
+Include enough context that anyone can follow the reasoning. Two to five
+paragraphs is usually enough. Cross-cutting or historically loaded changes may
+need more context, but prefer linking to relevant issues, prior RFCs,
+architecture docs, design discussions, bug reports, or external references
+instead of restating long background material.
+
+Useful questions to answer:
+
+- What is broken, missing, confusing, or unnecessarily difficult today?
+- What constraints make this worth solving through an RFC instead of a smaller
+  issue or pull request?
+- What happens if we leave the current design unchanged?
 
 ## Non-goals
 
-What is explicitly out of scope for this RFC?
+List the related problems, design options, or implementation details that this
+RFC intentionally does not address. Be explicit about boundaries so reviewers
+can focus on the decision at hand.
+
+Non-goals are especially useful when the RFC is part of a larger roadmap. Call
+out work that may happen later, work tracked by another issue or RFC, and
+requirements that are deliberately excluded.
+
+Most RFCs can cover non-goals in three to seven bullets, with one sentence each.
+Add a short explanation only when a boundary would otherwise be easy to misread.
 
 ## Proposal
 
-What are we actually proposing? Explain the design in enough detail that someone familiar with OpenShell can understand and implement it.
+This should be the main design section: explain the intended outcome, API shape,
+component boundaries, and any important invariants.
+
+Organize the proposal into focused subsections when helpful. This is usually the
+longest section, but most RFCs should fit in two to six subsections, with each
+subsection roughly one to four paragraphs plus any needed diagrams or examples.
+
+Include the high-value details reviewers need:
+
+- Public interfaces such as APIs, CLI behavior, or configuration.
+- Internal boundaries such as crate responsibilities or driver contracts.
+- User experience and compatibility impacts.
+- Security, privacy, and operational constraints.
+- Diagrams or examples when they make the design easier to review.
 
 ## Implementation plan
 
-How do we get from here to there? Consider rollout strategy, backwards compatibility, and migration.
+Explain how the project gets from the current state to the proposed state.
+Prefer concrete phases over a broad checklist when the work spans multiple
+components.
+
+Cover:
+
+- Required implementation, documentation, test, and release steps.
+- The intended order of changes and any temporary compatibility layers.
+- How existing users and integrations move forward.
+- How the change will be validated before and after release.
+- Whether the RFC can be implemented incrementally, behind a flag, or as a
+  breaking change.
+
+A short overview paragraph plus three to eight bullets or phases is usually
+enough. For phased work, keep each phase to one paragraph or a compact bullet
+list.
 
 ## Risks
 
-Why should we *not* do this? What are the costs?
+Explain why the project might choose not to adopt this proposal. Include costs
+that go beyond implementation difficulty.
+
+Consider:
+
+- Compatibility risks and migration burden.
+- Security, reliability, or performance risks.
+- Complexity added to OpenShell's architecture or contributor workflow.
+- New dependencies or support obligations.
+- Failure modes and how operators or users would diagnose them.
+
+Where possible, describe mitigations and remaining uncertainty separately.
+
+Most RFCs should cover three to six risks, with one paragraph or bullet per
+risk. Higher-risk proposals may need more detail, but keep the focus on risks
+that could change the decision.
 
 ## Alternatives
 
-What other designs have been considered? What is the impact of not doing this?
+Describe credible competing approaches that could solve the same problem,
+and explain why the proposal was chosen instead. Include the impact of doing
+nothing.
+
+For each meaningful alternative, capture the tradeoff that matters most, such as
+implementation complexity or compatibility. Alternatives should make the final
+proposal easier to evaluate, not just list rejected ideas.
+
+Most RFCs should cover one to four alternatives. If there are multiple
+alternatives, use one subsection per alternative and keep each subsection to one
+to three paragraphs.
 
 ## Prior art
 
-Does this feature exist in other projects? What can we learn from them?
+Identify existing systems or previous OpenShell decisions that informed this
+proposal. Explain the lesson that applies here.
+
+Prior art may include upstream projects, standards, RFCs from this repository,
+or operational experience from production systems.
+
+Two to five references or examples is usually enough, with one paragraph each
+explaining the relevant lesson.
 
 ## Open questions
 
-What parts of the design are still TBD?
+List unresolved design questions and decisions that need reviewer input. Keep
+this section current as the RFC evolves.
+
+Each open question should be specific enough for a reviewer to answer or route
+to the right owner. If an answer would change the proposal materially, call that
+out.
+
+This is usually a short bullet list. Keep each question to one or two sentences,
+and remove questions as they are answered.