GitHub - govctl-org/govctl: Opinionated CLI tool to enforce RFC-driven AI coding

4 min read Original article ↗

govctl logo

govctl

CI Crates.io License: MIT Discord governed by govctl

Opinionated governance CLI for RFC-driven AI-assisted software development.

The Problem

AI-assisted coding is powerful but undisciplined:

  • Phase skipping: Jumping from idea to implementation without specification
  • Documentation drift: Specs and code diverge silently
  • No enforceable governance: "Best practices" become optional suggestions

The result: faster typing, slower thinking, unmaintainable systems.

Without govctl

Day 1:  "Let's add caching!"
Day 2:  AI generates 500 lines of Redis integration
Day 7:  "Wait, did we agree on Redis or Memcached?"
Day 14: Half the team implements one, half the other
Day 30: Two incompatible caching layers, no spec, nobody knows why

With govctl

Day 1:  govctl rfc new "Caching Strategy"
Day 2:  RFC-0015 defines: Redis, TTL policy, invalidation rules
Day 3:  govctl rfc advance RFC-0015 impl
Day 7:  Implementation complete, traceable to spec
Day 10: govctl rfc advance RFC-0015 test
Day 14: Tests pass, govctl rfc advance RFC-0015 stable

What govctl Is

govctl enforces phase discipline on software development:

  1. RFC is the source of truth — No implementation without specification
  2. Phases are enforced — Each phase has explicit gates and invariants
  3. Governance is executable — Rules are checked, not suggested
  4. Work is traceable — Tasks link back to the specs that authorized them

govctl manages three artifact types:

  • RFCs — Specifications that must exist before implementation
  • ADRs — Architectural decisions with explicit consequences
  • Work Items — Tracked tasks tied to governance artifacts
┌─────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  SPEC   │ ──► │   IMPL   │ ──► │   TEST   │ ──► │  STABLE  │
└─────────┘     └──────────┘     └──────────┘     └──────────┘
     │                │                │                │
     ▼                ▼                ▼                ▼
  RFC must         Code must       Tests must       Bug fixes
  be normative     match spec      pass gates       only

govctl governs itself by its own rules. This repository is the first proof.

Who This Is For

✅ Teams frustrated by AI "code now, think later" patterns ✅ Projects where specifications drift from implementations ✅ Organizations needing audit trails for AI-generated code ✅ Developers who believe discipline enables velocity

❌ Not for "move fast and break things" workflows ❌ Not for projects without review processes

Quick Start

# Install
cargo install govctl

# Or with TUI dashboard
cargo install govctl --features tui

# Initialize project
govctl init

# Create your first RFC
govctl rfc new "Feature Title"

# Validate
govctl check

Optionally, show the project is governed by govctl:

[![governed by govctl](https://img.shields.io/badge/governed%20by-govctl-6366F1)](https://github.com/govctl-org/govctl)

For complete documentation, see the User Guide.

TUI Dashboard

Run the TUI with govctl tui (requires --features tui when installing from source).

Keymap highlights:

  • 1/r, 2/a, 3/w to switch lists from the dashboard
  • j/k or arrows to move; Enter to open; Esc to go back
  • / to filter lists by ID/title/status; Enter to accept; Esc clears filter
  • g/G jump to top/bottom; n/p step through matches when filtered
  • ? toggles help; q quits

What govctl Is NOT

  • Not a code generator — govctl doesn't write code; it ensures code follows specs
  • Not a documentation editor — govctl enforces structure, not style
  • Not about "faster coding" — govctl is about correct coding
  • Not a framework — govctl is a constraint system
  • Not a general issue tracker — Work items exist to trace work back to specs, not to replace Jira

Why No MCP?

govctl doesn't need a dedicated MCP (Model Context Protocol) integration because the CLI itself is the tool.

Modern AI coding agents (Claude, Cursor, Codex, etc.) can already invoke shell commands. Every govctl operation is a single CLI call. MCP would add complexity without adding capability.

The CLI is the universal interface. Every shell-capable agent already speaks it.

For Claude/Cursor users: govctl init installs a /gov <task> command — a complete governed workflow in one invocation.

Contributing

govctl has an opinionated workflow. Before contributing:

  1. Read the governance RFC to understand the model
  2. All features require an RFC before implementation
  3. Phase gates are enforced — this is the point, not bureaucracy

This workflow isn't for everyone, and that's okay. If you thrive in structured, spec-driven development, we'd welcome your contributions.

Star History

Star History Chart

License

MIT

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