mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-02 07:34:45 +08:00
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>
This commit is contained in:
krishicks
@@ -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.
|
||||
@@ -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."
|
||||
@@ -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 |
|
||||
|
||||
+105
-9
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user