From govctl
Facilitates design discussions: researches RFC/ADR governance context via govctl, clarifies requirements, drafts RFCs/ADRs for spec phase handoff.
npx claudepluginhub govctl-org/govctl --plugin govctlThis skill is limited to using the following tools:
Facilitate a design discussion about: `$ARGUMENTS`
Facilitates Request for Comments (RFC) process for technical proposals and design decisions. Supplies templates, ADR comparisons, best practices, and IETF-adapted guidance.
Guides writing RFCs for features, architecture, processes, deprecations, migrations, and standards with workflow: type selection, git research, required sections (summary, problem, solution, alternatives, risks), review management, decision logging, and git commit to docs/rfcs/. Use for proposals needing team buy-in on large changes.
Share bugs, ideas, or general feedback.
Facilitate a design discussion about: $ARGUMENTS
Purpose: Understand a design problem, research existing governance context, and produce draft RFC or ADR artifacts. This workflow is for the spec phase — no implementation, no work items.
Outputs: Draft RFC and/or proposed ADR, then handoff to /spec or /gov as appropriate.
Artifact roles: RFCs define obligations, ADRs explain decisions, and work items track execution. Keep those authority boundaries intact while drafting.
# Context discovery
govctl status # Project overview
govctl rfc list # List all RFCs
govctl adr list # List all ADRs
# RFC drafting
govctl rfc new "<title>" # Create RFC (auto-assigns ID)
govctl clause new <RFC-ID>:C-<NAME> "<title>" -s "<section>" -k <kind>
govctl clause edit <RFC-ID>:C-<NAME> --stdin <<'EOF'
clause text here
EOF
# ADR drafting
govctl adr new "<title>" # Create ADR
govctl adr set <ADR-ID> context "..." --stdin
govctl adr set <ADR-ID> decision "..." --stdin
govctl adr set <ADR-ID> consequences "..." --stdin
govctl adr add <ADR-ID> alternatives "Option: Description"
govctl adr add <ADR-ID> refs RFC-0001
# Validation
govctl check # Validate all artifacts
/gov[[artifact-id]] syntax when referencing artifacts (e.g., [[RFC-0001]], [[RFC-0001:C-FOO]]) — in content fields AND code commentsaccept, finalize, advance, and bump belong to /spec or /gov/commitBefore discussing, understand what already exists:
govctl status
govctl rfc list
govctl adr list
Based on $ARGUMENTS, identify RFCs and ADRs that might be relevant:
Read relevant artifacts to understand existing constraints and decisions.
Read gov/config.toml to understand project-specific settings that may affect the design.
Parse $ARGUMENTS and classify:
| Type | Indicator | Output |
|---|---|---|
| New capability | "How should X work?", "Design Y feature" | RFC |
| Design choice | "Should we use A or B?", "Decide between..." | ADR |
| Clarification | "What does RFC-NNNN mean by...?" | Discussion only (no artifact) |
| RFC clarification | "Clarify RFC-NNNN", "Tighten clause wording" | RFC update (spec-only) |
| Amendment | "RFC-NNNN should change because..." | RFC amendment |
| Deprecation | "Deprecate X", "Remove Y behavior" | RFC amendment |
| Both | Complex feature with architectural decisions | RFC + ADR(s) |
Use the authority test when drafting:
If requirements are clear: Proceed to Phase 2.
If requirements are ambiguous: Ask clarifying questions before proceeding.
Questions to consider:
Do not invent requirements. If something is unspecified, ask.
For complex topics, explore the design space:
If the decision is high-risk (2+ competing options with non-obvious trade-offs, irreversible change, or cross-cutting impact), follow the decision-analysis skill for a structured premortem/backcast analysis. The analysis output maps directly to ADR fields — see the skill's "Output → ADR Mapping" section.
Document this exploration — it becomes the ADR context/alternatives or RFC rationale.
For structure, templates, and quality guidelines, follow the rfc-writer skill.
govctl rfc new "<title>"
govctl clause new <RFC-ID>:C-<NAME> "<title>" -s "<section>" -k <kind>
govctl clause edit <RFC-ID>:C-<NAME> --stdin <<'EOF'
clause text
EOF
For structure, templates, and quality guidelines, follow the adr-writer skill.
govctl adr new "<title>"
govctl adr set <ADR-ID> context --stdin <<'EOF' ... EOF
govctl adr set <ADR-ID> decision --stdin <<'EOF' ... EOF
govctl adr set <ADR-ID> consequences --stdin <<'EOF' ... EOF
govctl adr add <ADR-ID> alternatives "Option: Description"
govctl adr add <ADR-ID> refs RFC-NNNN
When existing RFC needs modification:
# Edit the clause content
govctl clause edit <RFC-ID>:C-<NAME> --stdin <<'EOF'
Updated specification text.
EOF
# The RFC version may need bumping during /spec or /gov handoff
# Do NOT bump version in /discuss — handoff owns lifecycle operations
Note: Amendments to normative RFCs require careful consideration. Document the rationale for the change.
Clarification-only RFC updates that do not require implementation should hand off to /spec.
Behavior-changing amendments, including feature deprecations or removals, should hand off to /gov.
After creating artifacts:
govctl check
Fix any validation errors before proceeding.
Invoke the appropriate reviewer agent on each draft artifact:
Address Critical issues before handoff.
If draft artifacts should be recorded, use /commit with docs(rfc): draft <RFC-ID> for <summary> or docs(adr): draft <ADR-ID> for <summary>.
Present the discussion results:
=== DISCUSSION COMPLETE ===
Topic: $ARGUMENTS
Artifacts created:
- RFC-NNNN: <title> (draft, spec phase)
- ADR-NNNN: <title> (proposed)
Key decisions:
- <summary of main design choices>
Open questions:
- <any unresolved issues>
Related artifacts referenced:
- RFC-XXXX: <title>
- ADR-YYYY: <title>
Prompt the user for next action:
Ready to proceed?
Options:
1. /gov "<summary>" — Start governed implementation workflow
- Creates work item
- Finalizes RFC (with permission)
- Implements, tests, completes
2. /spec "<summary>" — Maintain governance artifacts without implementation
- Accepts ADRs with permission
- Clarifies or amends RFCs without code changes
- Validates and renders governance output
3. Continue discussing — Refine the drafts further
- Ask follow-up questions
- Add more clauses or detail
4. Pause — Save drafts, return later
- Drafts can be recorded with `/commit` and resumed later
If the only follow-up is standalone non-behavioral cleanup unrelated to the drafted RFC/ADR (for example, wording-only docs cleanup), `/quick` may be used separately. Do not use `/quick` to implement behavior from these drafts.
Use [[artifact-id]] syntax for inline references in content fields:
# Good - expands to clickable link when rendered
context = "Per [[RFC-0001]], all RFCs must have a summary clause."
# Also good for clauses
decision = "Follow [[RFC-0001:C-SUMMARY]] structure."
# Bad - plain text, not linked
context = "Per RFC-0001, all RFCs must have a summary clause."
Also use in source code comments for implementation traceability:
// Implements [[RFC-0001:C-VALIDATION]]
fn validate() { ... }
// Per [[ADR-0005]], we chose X over Y
This enables govctl check to validate all references exist and are not deprecated.
For RFC 2119 keywords and clause conventions, see the rfc-writer skill. For ADR structure and field conventions, see the adr-writer skill.
govctl check)BEGIN DISCUSSION NOW.