govctl 0.18.0

Project governance CLI for RFC, ADR, and Work Item management
govctl-0.18.0 is not a library.

govctl is a governance-as-code CLI for teams using AI to build software seriously.

It gives AI-assisted development a control plane that lives in your repo:

  • RFCs say what must be true
  • ADRs record why a design was chosen
  • Work items track execution and acceptance criteria
  • Verification guards enforce executable completion gates
  • Conformance cases map reusable acceptance scenarios to versioned RFC requirements and guards

The point is not bureaucracy. The point is that AI-generated changes become reviewable, traceable, and phase-gated.

Why govctl

Most AI coding tools optimize for generation. govctl optimizes for delivery.

Without explicit governance, teams drift into the same pattern:

  • ideas jump straight into implementation
  • decisions live in chat history instead of artifacts
  • code and specs diverge silently
  • "done" means "the agent stopped typing", not "the work passed verification"

govctl closes that gap by making governed artifacts, lifecycle, and verification part of the normal workflow.

Without govctl:
  prompt -> code -> drift -> arguments

With govctl:
  RFC / ADR -> work item -> guarded implementation -> stable history

What Makes It Different

1. Spec-first by default

govctl is built around the idea that implementation follows governed artifacts.

In practice, that means:

  • RFCs describe externally relevant behavior and constraints
  • ADRs record design choices and trade-offs
  • work items execute against those artifacts
  • verification guards and lifecycle gates decide when work is actually done

Instead of treating prompts as the source of truth, the source of truth becomes governed artifacts in the repository.

2. Artifacts are the control plane

govctl does not hide governance behind a web app or an MCP server.

Artifacts live in gov/ as TOML files with schema headers, references, and stable CLI access. That means:

  • changes are diffable
  • decisions are reviewable in PRs
  • agents can operate against files and commands you already understand

3. One CLI agents can reliably operate

The CLI is the operating surface for agents:

  • list, show, get, edit
  • resource-specific lifecycle verbs like adr accept, rfc advance, rfc supersede, and work move
  • path-first mutation through edit
  • explicit help text designed to act as a reliable command contract

Clauses remain first-class govctl clause resources even though their IDs and storage are scoped by an RFC.

This matters because agent workflows get better when the interface is stable, local, and inspectable.

4. Works in brownfield repositories

This is not only for greenfield projects.

For existing repositories, the /migrate workflow helps you adopt governance incrementally: discover undocumented decisions, backfill ADRs, and establish governed artifacts without restarting the project.

Quick Start

CLI

# Install from source
cargo install govctl

# Or install a prebuilt binary (faster, skips compilation)
cargo binstall govctl

govctl init
govctl status

To update an existing installation:

govctl self-update

Then create your first governed artifacts:

govctl rfc new "Caching Strategy"
govctl adr new "Choose cache backend"
govctl work new --active "implement caching"

Agent workflow

Initialize governance, then install or load the agent workflows for your tool:

  • /discuss <topic> to draft RFCs and ADRs
  • /gov <task> to execute governed implementation
  • /quick <task> for intentionally small changes
  • /commit to record work with governance checks

Check that the target agent runtime is ready, then install the bundled integration:

govctl agent doctor claude
govctl agent install claude

For Codex:

govctl agent doctor codex
govctl agent install codex

Use govctl agent update <claude|codex|all> after upgrading govctl, then start a new agent session. Both clients receive skills and hooks through their native plugin mechanism. Claude also loads its Markdown reviewer agents from the plugin; Codex receives standalone read-only TOML reviewer roles. Runtime-specific hooks add compact context only in governed projects and advise, rather than block, direct governance-artifact edits.

A concrete example

govctl rfc new "Verification Guard Policy"
govctl clause new RFC-0015:C-GUARD-REQUIREMENTS "Required guards" -s "Verification" -k normative
govctl adr new "Require clippy on parser refactors"
govctl work new --active "add parser lint guard"

Core Capabilities

Canonical artifact operations

Agents and humans work through a stable CLI contract.

Read the exact field you need:

govctl rfc get RFC-0001 status

For precise artifact mutation, govctl provides a canonical path-first interface:

govctl adr edit ADR-0038 decision --set --stdin
govctl work edit WI-2026-01-17-001 acceptance_criteria[0] --tick done
govctl clause edit RFC-0002:C-CRUD-VERBS text --set --stdin

This is not the product's identity. It is the low-level tool agents use to update governed artifacts precisely and consistently.

Project-wide search

Use govctl search to find governed artifacts across RFCs, clauses, ADRs, work items, guards, and Conformance Cases:

govctl search cache
govctl search RFC-0002 --output json
govctl search migration --type rfc --type adr --tag cli -n 5
govctl search cache --type conformance

Search uses a disposable local index under .govctl/. The TOML artifacts remain the source of truth, and --reindex forces a fresh rebuild when needed.

Execution loops and dependencies

Work items can declare hard execution dependencies with depends_on; keep informational links in refs.

govctl work edit WI-2026-01-17-002 depends_on --add WI-2026-01-17-001
govctl check

For multi-work-item implementation batches, use a generated local loop ID and record round evidence in .govctl/loops/ instead of work item notes:

govctl loop list open
govctl loop start WI-2026-01-17-001 WI-2026-01-17-002
govctl loop run <LOOP-ID>

Verification guards

Guards are executable checks that run when work reaches completion gates.

Define reusable project defaults in gov/config.toml:

[verification]
enabled = true
default_guards = ["GUARD-GOVCTL-CHECK"]

Keep expensive or domain-specific checks out of the universal default set and require them on affected work items. You can also waive a guard with an explicit reason. See:

Requirement traceability

Conformance Cases provide a stable, non-normative link from a versioned RFC Clause to a project-owned scenario and reusable Guards:

govctl conformance new "Cache expiry" \
  --path tests/conformance/cache.toml \
  --selector cache-expiry \
  --requirement RFC-0012:C-CACHE-EXPIRY@1.2.0 \
  --guard GUARD-CACHE-CONFORMANCE
govctl conformance trace RFC-0012

They declare traceability; they do not execute tests or override RFC authority. See Conformance Cases.

Brownfield adoption vs format migration

These are related, but different:

  • /migrate workflow — adopt govctl in an existing repository by discovering decisions, backfilling ADRs, and introducing governance incrementally
  • govctl migrate command — upgrade existing TOML govctl artifacts to the current on-disk format and schema

For format upgrades:

govctl migrate
govctl check

Schema version 3 is the minimum supported repository format. Schema version 5 uses project .gitignore files plus .govignore for source-scan exclusions and re-inclusions; govctl migrate upgrades supported repositories. Use a compatible earlier govctl version for repositories below schema 3. Legacy RFC and clause JSON storage is rejected explicitly.

Interactive TUI

govctl tui

Open the read-only cockpit for project overview, artifact browsing, search, loop-state inspection with dependency DAG context, guards, releases, tags, and govctl check diagnostics. Mutation remains owned by CLI commands.

Who This Is For

  • Teams using Claude Code, Codex, Cursor, or similar agents for real product work
  • Projects that want AI assistance without losing reviewability
  • Brownfield repositories that need governance without a rewrite
  • Engineers who want specs, decisions, and work tracking to live in the repo

Documentation

Community

Contributing

govctl is intentionally opinionated:

  • features start with governed artifacts, not implementation-first
  • RFCs and ADRs are part of the product, not side documentation
  • verification and lifecycle are core behavior, not optional extras

If that matches how you want AI-assisted development to work, contributions are welcome.

License

MIT

Star History

"Discipline is not the opposite of creativity. It is the foundation."