Govctl
Governance-as-code for AI-assisted software development
Install / Use
/learn @govctl-org/GovctlREADME
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 14: Tests pass, govctl rfc advance RFC-0015 stable
How It Works
govctl enforces phase discipline on software development:
┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ SPEC │ ──► │ IMPL │ ──► │ TEST │ ──► │ STABLE │
└─────────┘ └──────────┘ └──────────┘ └──────────┘
│ │ │ │
▼ ▼ ▼ ▼
RFC must Code must Tests must Bug fixes
be normative match spec pass gates only
Three artifact types, one lifecycle:
- RFCs -- Specifications that must exist before implementation
- ADRs -- Architectural decisions with explicit trade-offs
- Work Items -- Tracked tasks with acceptance criteria and verification guards
All artifacts are TOML files in gov/, validated by JSON schemas, and rendered to markdown in docs/. govctl governs itself by its own rules -- this repository is the first proof.
Quick Start
Claude Code Plugin
/plugin marketplace add govctl-org/govctl
/plugin install govctl@govctl
/govctl:init
The plugin provides workflow skills, reviewer agents, and enforcement hooks out of the box.
CLI
cargo install govctl
govctl init
govctl init creates the governance structure and installs AI agent skills into .claude/.
For complete documentation, see the User Guide.
AI Agent Integration
govctl is built for AI-native development. Install the Claude Code plugin or run govctl init to get workflow skills that any Claude Code / Cursor / Codex agent can invoke:
| Skill | Purpose |
| ------------------ | --------------------------------------------------------------------------------------- |
| /gov <task> | Complete governed workflow: work item, RFC/ADR, implement, test, done |
| /migrate | Adopt govctl in an existing project: discover decisions, backfill ADRs, annotate source |
| /discuss <topic> | Design discussion: explore options, draft RFC or ADR |
| /commit | Smart commit: VCS detection, govctl checks, work item journal updates |
| /quick <task> | Fast path for trivial changes (skip governance ceremony) |
The plugin also includes enforcement hooks: govctl status runs at session start for context, govctl check runs at session end as a gate.
Every govctl operation is a single CLI call. No MCP server needed -- the CLI is the universal interface. Every shell-capable agent already speaks it.
Features
Verification Guards
Guards are executable completion checks that run when a work item moves to done. Define them in gov/guard/:
[govctl]
id = "GUARD-CARGO-TEST"
title = "cargo test passes"
[check]
command = "cargo test"
timeout_secs = 300
Configure which guards are required in gov/config.toml:
[verification]
default_guards = ["GUARD-GOVCTL-CHECK", "GUARD-CARGO-TEST"]
Brownfield Adoption
govctl is designed for existing projects. The /migrate skill systematically backfills governance:
- Discover undocumented architectural decisions in your codebase
- Backfill ADRs for each decision with context, rationale, and alternatives
- Annotate source files with
[[ADR-NNNN]]references for traceability
No existing files are modified without confirmation. The gov/ directory is additive.
Schema Migration
When upgrading govctl to a version that changes the artifact file format:
govctl migrate
Upgrades all governance files to the current schema version -- adding #:schema headers, converting legacy JSON to TOML, normalizing metadata layout. Changes are staged, backed up, and committed atomically with rollback on failure.
Interactive TUI
govctl tui
Browse RFCs, ADRs, and work items with styled markdown rendering. Included by default.
Keymap: 1/2/3 switch lists, j/k navigate, Enter open, / filter, Ctrl+d/Ctrl+u page, ? help.
Who This Is For
- Teams frustrated by AI "code now, think later" patterns
- Existing projects that need to retroactively establish governance
- 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.
Community
- Discord -- Questions, discussions, feedback
- GitHub Issues -- Bug reports and feature requests
- GitHub Discussions -- Design conversations
Contributing
govctl has an opinionated workflow. Before contributing:
- Read the governance RFC to understand the model
- All features require an RFC before implementation
- 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
<a href="https://star-history.com/#govctl-org/govctl&Date"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=govctl-org/govctl&type=Date&theme=dark" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=govctl-org/govctl&type=Date" /> <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=govctl-org/govctl&type=Date" /> </picture> </a>License
MIT
"Discipline is not the opposite of creativity. It is the foundation."
Related Skills
node-connect
326.5kDiagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps
frontend-design
80.4kCreate distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
openai-whisper-api
326.5kTranscribe audio via OpenAI Audio Transcriptions API (Whisper).
commit-push-pr
80.4kCommit, push, and open a PR
