spec

name	spec
description	Maintain governance artifacts without implementation work. Use when: (1) Accepting or refining ADRs, (2) Clarifying or amending RFCs without code changes, (3) Governance-only docs/check/render updates
allowed-tools	Read, Write, Edit, Bash, Glob, Grep, TodoWrite
argument-hint	<artifact-maintenance-task>

/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

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

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 add <ADR-ID> alternatives "Option: ..."
govctl adr add <ADR-ID> alternatives "Other option: ..." --reject-reason "Why it was not chosen"
govctl adr tick <ADR-ID> alternatives --at 1 -s rejected
govctl adr tick <ADR-ID> alternatives --at 0 -s accepted
govctl adr set <ADR-ID> decision --stdin <<'EOF' ... EOF
govctl adr set <ADR-ID> consequences --stdin <<'EOF' ... EOF
govctl adr accept <ADR-ID>

govctl clause edit <RFC-ID>:C-<NAME> text --stdin <<'EOF' ... EOF
govctl rfc bump <RFC-ID> --patch -m "Clarify clause wording"
govctl rfc get <RFC-ID> changelog
govctl rfc edit <RFC-ID> changelog.summary --set "Clarify current version"
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>

Before editing a normative RFC, inspect its current phase. The phase determines whether the edit remains in the current version candidate or must be released as a new version.

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, alternatives, decision, consequences, 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, do not bump it; when ready, ask permission before govctl rfc finalize <RFC-ID> normative
• If a normative RFC is in spec, edit the current version candidate directly; do not bump it again for those edits
• If a normative RFC is in impl, test, or stable, an RFC or Clause edit creates an unversioned amendment; after review, ask permission before using govctl rfc bump to release it as the next version in spec
• If the RFC is deprecated, do not edit or version-bump it
• Use govctl rfc edit <RFC-ID> changelog.* for current-version changelog corrections; these do not change version, phase, or the sealed content signature

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 version-changing RFC bump must include a changelog summary via -m. --change without a bump level is changelog-only and cannot release an RFC or Clause content amendment.

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

1. Read the ADR with govctl adr show <ADR-ID>
2. Run adr-reviewer
3. Fix issues
4. Ask permission, then run govctl adr accept <ADR-ID>
5. Run govctl check

Clarify an RFC without changing behavior

1. Inspect the RFC phase with govctl rfc show <RFC-ID>
2. Edit the clause text with govctl clause edit
3. Run rfc-reviewer
4. For a draft RFC, keep the version and finalize when ready; for a normative RFC already in spec, keep the current version; for a normative RFC in impl, test, or stable, ask permission, then run govctl rfc bump <RFC-ID> --patch -m "Clarify wording"
5. Run govctl check and govctl render

Prepare a deprecation plan without implementation

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