Skill

spec

Maintains governance artifacts like ADRs and RFCs without code changes: accept/refine ADRs, clarify/amend RFCs, update docs/checks/renders using govctl.

Bash

Git

Markdown

documentation

git-workflow

npx claudepluginhub govctl-org/govctl --plugin govctl

Tool Access

This skill is limited to using the following tools:

ReadWriteEditBashGlobGrepTodoWrite

Preview

Maintain governance artifacts for: `$ARGUMENTS`

SKILL.md

Similar Skills

gov

103

Executes governed implementation workflow using govctl CLI: creates/manages work items, RFC/ADR checks, phase gates, testing, and closure. For non-trivial changes needing tracking.

7 tools

govctl

rfc

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.

godmode

rfc

Manages architecture RFCs: create populated drafts from conversation and docs context, review existing, list all, update sections, transition status.

5 files

doc

Stats

Parent Repo Stars103

Parent Repo Forks7

Last CommitApr 4, 2026

Actions

View Source View Plugin View on GitHub View README

Help us improve

Share bugs, ideas, or general feedback.

/spec - Governance Artifact Maintenance

Maintain governance artifacts for: $ARGUMENTS

Use this workflow for spec-only governance work: refine or accept ADRs, clarify or amend RFCs, update artifact references, and validate/render governance output without implementing code.

Outputs: Updated governance artifacts, completed artifact review, and validated rendered governance state.

Artifact roles: RFCs define obligations, ADRs explain decisions, and work items track execution. /spec only maintains the first two.

Critical Rules

Artifact-only scope. Do not write implementation code in this workflow.
No work item by default. This workflow is for governance maintenance, not implementation tracking.
Ask permission before lifecycle-owned verbs: govctl adr accept, govctl adr reject, govctl adr supersede, govctl rfc finalize, and govctl rfc bump.
Do not advance RFC phase out of spec here. Hand off to /gov when implementation-bearing work begins.
Clarification-only RFC updates must not silently change behavior. If behavior changes, stop and route through /discuss and /gov.
Never edit governed files directly. Use govctl verbs only.
Validate with govctl check, and run govctl render when rendered docs should change.
Use /commit for raw VCS operations. This workflow defines what to record, not how to invoke VCS directly.
Do not let RFCs absorb implementation structure or let ADRs absorb work-item execution details. Preserve artifact roles while editing.

Quick Reference

govctl status
govctl rfc list
govctl rfc show <RFC-ID>
govctl adr list
govctl adr show <ADR-ID>

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: ..."
govctl adr accept <ADR-ID>

govctl clause edit <RFC-ID>:C-<NAME> --stdin <<'EOF' ... EOF
govctl rfc bump <RFC-ID> --patch -m "Clarify clause wording"
govctl rfc finalize <RFC-ID> normative

govctl check
govctl render

Workflow

1. Classify the task

Choose the narrowest fit:

ADR maintenance: refine a proposed ADR, add alternatives/refs, or accept it
RFC clarification: tighten wording or fill specification gaps without changing behavior
RFC amendment: change normative requirements without implementing them yet
Governance-only cleanup: fix artifact references, rendering output, or metadata

If the task requires implementation, testing implementation behavior, or phase advancement beyond spec, stop and use /gov.

2. Gather context

govctl status
govctl rfc list
govctl adr list

Then read the relevant artifacts:

govctl rfc show <RFC-ID>
govctl adr show <ADR-ID>

For artifact editing conventions, follow the appropriate writer skill:

RFC changes -> rfc-writer
ADR changes -> adr-writer

3. Edit the artifacts

Use govctl verbs only.

For ADR work:

Refine context, decision, consequences, alternatives, and refs
If the ADR is ready to become authoritative, ask permission before govctl adr accept <ADR-ID>

For RFC work:

Edit clauses with govctl clause edit
If the RFC is draft and ready to become normative, ask permission before govctl rfc finalize <RFC-ID> normative
If amending an existing normative RFC, ask permission before govctl rfc bump

Semver guidance for RFC amendments:

--patch: clarification or wording fix with no behavioral change
--minor: additive requirement or newly specified behavior
--major: breaking or incompatible requirement change

Every RFC bump must include a changelog summary via -m.

4. Review and validate

Run the appropriate reviewer before finalizing artifact state:

RFC changes -> rfc-reviewer
ADR changes -> adr-reviewer

Then validate:

govctl check
govctl render

Fix validation or reviewer issues before recording the result.

5. Record the result

Spec-only governance commits may be recorded without a work item.

Use commit types that reflect artifact maintenance:

docs(rfc): RFC drafting, clarification, or amendment
docs(adr): ADR drafting or acceptance preparation
chore(gov): governance metadata, refs, render output, or config cleanup

Use /commit to record those changes.

If the task grows into implementation work, stop here and hand off to /gov.

Handoff Rules

Use /discuss when the design itself is still unresolved
Use /gov when code or tests must change
Use /quick only for standalone non-behavioral cleanup outside governance artifacts

Examples

Accept a reviewed ADR

Read the ADR with govctl adr show <ADR-ID>
Run adr-reviewer
Fix issues
Ask permission, then run govctl adr accept <ADR-ID>
Run govctl check

Clarify an RFC without changing behavior

Edit the clause text with govctl clause edit
Run rfc-reviewer
Ask permission, then run govctl rfc bump <RFC-ID> --patch -m "Clarify wording"
Run govctl check and govctl render

Prepare a deprecation plan without implementation

Update the RFC language to mark the behavior deprecated
Record the rationale and migration guidance
Review and validate the artifact changes
Hand off to /gov for actual implementation or removal work