# Spec

> Maintain RFC and ADR artifacts without implementation work

- Skill: `govctl-org/spec` (Agent Skill)
- Install (CLI): `npx skillmds@latest add govctl-org/spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/govctl-org/spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: govctl-org (https://skillmd.com/u/govctl-org)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/govctl-org/spec

---


# Specification Maintenance

Maintain governance artifacts for `$ARGUMENTS` without implementing code or
creating execution work.

## Operational Baseline

### Discovery

Establish artifact and lifecycle state first:

```bash
govctl status
govctl search <topic>
govctl rfc list
govctl adr list
```

Read the current projection with the resource `show` command and use `--history`
only when obsolete content matters. Use `govctl <resource> --help` for current
authoring and lifecycle syntax. In the govctl repository itself, invoke the
development binary as `cargo run --quiet --`.

### Hard Stops

- This workflow is artifact-only. Do not write implementation code, create Work
  Items, or advance an RFC beyond `spec`.
- RFCs own obligations; ADRs own design rationale. Do not put implementation
  plans into either artifact.
- Use canonical govctl resource commands rather than editing `gov/` files.
  Clause operations use the root `govctl clause` namespace.
- Obtain user authorization before lifecycle-owned or destructive artifact
  operations, including acceptance/rejection, finalization, version changes,
  deprecation, supersession, and deletion, unless already granted.
- Stop when a clarification changes behavior, design remains unresolved, or the
  task requires implementation. Route those cases to `discuss` or `gov`.
- Stop lifecycle mutation when authoritative phase, signature baseline, or
  required recovery state cannot be established.

## Decision Policy

### Classify The Change

| Change                                          | Path                                             |
| ----------------------------------------------- | ------------------------------------------------ |
| Clarify an obligation without changing behavior | Edit and review the RFC                          |
| Change, add, deprecate, or remove behavior      | Amend the RFC, then hand implementation to `gov` |
| Refine rationale or alternatives                | Edit and review the ADR                          |
| Resolve an open design question                 | Hand off to `discuss`                            |
| Fix governance metadata or references           | Edit the owning artifact                         |

Follow `rfc-writer` or `adr-writer` for artifact quality. Use `rfc-reviewer`
for RFCs, `adr-reviewer` for ADRs, and `wi-reviewer` for Work Items before
treating substantively changed content as ready for a lifecycle transition.

### Respect Candidate Boundaries

Inspect the RFC and its governing lifecycle clauses before editing:

- Draft RFC content remains in its initial candidate and is finalized rather
  than version-bumped.
- A normative RFC already in `spec` remains open for current-candidate
  authoring; do not bump merely to retarget that candidate.
- Editing sealed content after `spec` creates an amendment that needs an
  authorized version-changing bump before later phase progression.
- A post-`spec` RFC without a trustworthy sealed baseline requires the
  documented migration or version-control restoration path, not an inferred
  bump.
- Deprecated RFC content is historical and is not edited or version-bumped.

Clause `since` and version assignment are lifecycle-owned. Use the Clause
lifecycle surface rather than rewriting history. Current-version changelog
corrections use the canonical changelog edit path and do not replace a content
amendment or lifecycle bump.

### Validate And Hand Off

Run `govctl check` after substantive artifact edits and render affected
projections. Resolve structural diagnostics and critical reviewer findings
before requesting a lifecycle transition.

Use:

- `discuss` when the decision remains open;
- `gov` when code or implementation tests are required;
- `quick` only for unrelated non-behavioral cleanup outside governance
  artifacts; and
- `commit` for raw VCS operations.

## Completion Evidence

Spec maintenance is complete when:

- the artifact stays within its authority boundary;
- lifecycle state and required authorization are explicit;
- the artifact's named reviewer has no unresolved critical finding;
- `govctl check` passes and affected projections are current; and
- the final response identifies changed artifacts, lifecycle state, review
  result, and the correct next workflow.

Leave unapproved artifacts in their existing draft/proposed lifecycle state.