diff --git a/.agents/skills/create-rfc/SKILL.md b/.agents/skills/create-rfc/SKILL.md new file mode 100644 index 000000000..f767e4758 --- /dev/null +++ b/.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. diff --git a/.agents/skills/create-rfc/agents/openai.yaml b/.agents/skills/create-rfc/agents/openai.yaml new file mode 100644 index 000000000..8717be4ff --- /dev/null +++ b/.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." diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 406205c35..a0c569acd 100644 --- a/CONTRIBUTING.md +++ b/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 | diff --git a/rfc/0000-template/README.md b/rfc/0000-template/README.md index 1cd1810a5..7fbd4073f 100644 --- a/rfc/0000-template/README.md +++ b/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.