Spec-driven development for AI coding agents. Describe a feature in plain English; your agent turns it into a spec, a plan, tasks, and reviewed code — and every feature lands with a written record of why it was built the way it is.

govern is tech-stack agnostic, ships as plain markdown, and works with Claude Code, Auggie, and Antigravity. There's nothing to compile and no dependency to add — you install a single command into your project and drive the rest through a handful of verb-named slash commands.

AI agents are fast, but left to their own devices they're inconsistent: they guess at ambiguous requirements, lose the reasoning behind a change as soon as the chat scrolls away, and reinvent structure on every task. govern puts a thin, opinionated pipeline in front of the agent so that:

• Ambiguity is caught upstream of code. Open questions get resolved in the spec, not discovered halfway through implementation.
• Every feature carries its "why." The spec is a living document that stays accurate after the code ships — not a ticket that gets buried when it closes.
• The surface area is small. A few commands map to things you already do: write a ticket, surface unknowns, sketch an approach, build it, audit it.
• Artifacts stay portable. Everything is markdown with YAML frontmatter — readable in GitHub, Obsidian, or cat, with no proprietary format to escape.

Install govern into any project:

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/stonean/govern/main/install.sh | sh

This installs the /govern bootstrap command for Claude Code — see Installing per agent to target Auggie or Antigravity instead. Then, in your agent, run:

/govern my-project

That one command scaffolds the specs/ directory, installs the full set of slash commands, wires up the constitution and agent rules, and prints your next steps. It's idempotent — safe to re-run any time to pull the latest govern files.

Now build your first feature by walking it through the pipeline:

/specify   add user login with email and password
/clarify              # resolve open questions the spec surfaced
/plan                 # technical decisions, affected files, tasks
/implement            # work the tasks; code gets written here
/review               # audit the code against the rules

Each command advances the feature one step and leaves a durable artifact behind. That's the whole loop.

Every feature moves through one pipeline. The status on each spec tracks where it is:

draft ──/clarify──▶ clarified ──/plan──▶ planned ──/implement──▶ in-progress ──/implement──▶ done

• Spec (/specify, /clarify) — define what the feature does and why, with concrete acceptance criteria and a list of open questions. No open questions may remain before planning.
• Plan (/plan) — turn the spec into technical decisions, affected files, and an ordered task list. Persistence-heavy features also get a data model.
• Implement (/implement) — work the tasks; this is where code is written. Status moves to in-progress, then done once the review gate passes.
• Review (/review) — audit the implementation against the framework's rules (security, reuse, quality, efficiency, simplicity). Blocking violations keep the feature out of done until they're fixed or explicitly waived.

/analyze can run at any time to check a feature's artifacts against each other — it's a safety check, not a gate.

You don't have to start at draft. A brownfield feature can enter with a sparse sketch spec and gain precision as you touch the code; a done feature reopens automatically when a bug or change request surfaces. See docs/introduction.md for the full mental model, and framework/constitution.md for the authoritative rules.

Adoption installs a full set of verb-named, session-aware commands. Use /target to switch the working feature; /specify creates one and targets it automatically.

govern operates a live-on-main model — the installer fetches the latest from main. Omit the agent to install for Claude Code, or name it explicitly.

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/stonean/govern/main/install.sh | sh

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/stonean/govern/main/install.sh | sh -s -- auggie

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/stonean/govern/main/install.sh | sh -s -- antigravity

Then run /govern {project-name}. The installer creates the right directory for your agent and drops the bootstrap command in place — for Antigravity it's wrapped as a skill under .agents/skills/govern/, since Antigravity discovers dir-form skills rather than verbatim command files. It's safe to re-run. (agy, the Antigravity CLI command name, works in place of antigravity.)

The same bootstrap supports every agent, so re-run /govern --add-agent from any adopted agent later to add others. You don't need to wire the optional runtime by hand — once the gvrn binary is on your PATH, /govern registers it automatically on its next run (see The optional runtime).

You don't need to clone govern or rewrite history to adopt it. Install the command, run /govern, then let specs accrete naturally:

• Use /specify with a sparse description to stub a skeleton spec for an existing feature — sparse acceptance criteria are valid here.
• Let those specs gain precision incrementally through bug fixes, enhancements, and /clarify.
• Drop raw items into specs/inbox.md with /log without breaking flow, and route them later with /groom.

Adoption spreads by feature area, not in a big bang. The goal is for inbox.md to eventually disappear.

govern treats every bug as evidence that a spec is missing, ambiguous, or violated. When one surfaces, follow the decision tree in order:

1. No spec exists — write the spec first, then fix the code.
2. Spec is ambiguous — fix the spec, then fix the implementation.
3. Spec is clear, implementation is wrong — add a scenario, then fix the code.

A scenario is a spec at a lower level of abstraction — same format, same discipline. Scenarios live in specs/NNN-feature/scenarios/slug.md, each gets a linked task in the parent spec, and any can be targeted directly with /target feature/scenario-slug.

The govern runtime (gvrn) is an optional deterministic execution layer. It parses the prose of each command and runs the mechanical work (reading specs, walking tasks, checking dependencies, atomic checkbox updates, gate handshakes) in native Rust instead of slow LLM tokens — invoking the model only where semantic judgment actually matters (assessSpecQuality, writeCode, writeSpecBody).

The markdown-only path stays first-class per constitution §runtime-boundary: when the runtime is absent, the agent walks the same prose. Install it if you run the pipeline frequently — the wall-clock saving on /analyze and /implement is significant; skip it if you only use the pipeline occasionally.

Download the pre-built binary for your platform from the latest release and verify the checksum:

# Example for aarch64-apple-darwin; substitute your target triple.
VERSION="0.11.3"
TARGET="aarch64-apple-darwin"
ARCHIVE="gvrn-${TARGET}.tar.gz"
BASE="https://github.com/stonean/govern/releases/download/gvrn-v${VERSION}"

# Work in a scratch tempdir so the extracted binary lands away from your tree.
tmp="$(mktemp -d)" && cd "${tmp}"

curl -LO "${BASE}/${ARCHIVE}"
curl -LO "${BASE}/${ARCHIVE}.sha256"
shasum -a 256 -c "${ARCHIVE}.sha256"
tar xzf "${ARCHIVE}"
sudo install -m 0755 gvrn /usr/local/bin/gvrn
gvrn --version

# Clean up.
cd - >/dev/null && rm -rf "${tmp}"

Binaries are published for aarch64-apple-darwin, x86_64-apple-darwin, x86_64-unknown-linux-gnu, and aarch64-unknown-linux-gnu (a Windows binary appears when cross-compilation succeeds). If a runtime process crashes mid-procedure, just re-run the command — state lives in your markdown, and writes are filesystem-atomic, so the runtime resumes from the next incomplete step.

You install the binary; you don't register the server yourself. The next time you run /govern after gvrn is on your PATH, the bootstrap detects it, writes the per-agent MCP config (.mcp.json for Claude-style agents, .agents/mcp_config.json for Antigravity) and the matching tool permissions, then asks you to start a fresh session so the runtime loads. From that session on, the pipeline takes the deterministic path. The writes are additive — an existing MCP config keeps its other servers, and a gvrn entry that's already present is left untouched. If /govern can't find the binary, it stays on the markdown path and reminds you that installing gvrn cuts token use.

.govern.toml is an optional project file — /govern runs fine without it. Create it only if you need one of these behaviors:

• [pinned] — list destination paths govern should never overwrite, even files it normally updates (e.g. a customized constitution.md).
• [workflows] — record workflow categories you've declined so /govern stops offering them.

[pinned]
files = ["constitution.md"]

[workflows]
declined_categories = ["Linting"]

For the full schema, see specs/019-config-decisions/data-model.md.

Re-run /govern to pull the latest framework files. Each file is handled by one of three strategies:

.gitignore uses a merge strategy — govern patterns are appended below a # govern marker. Pin individual files you've customized with [pinned] in .govern.toml (above). govern is a reference, not a runtime dependency: if you'd rather not use /govern, diff the repo and apply changes at your own pace.

govern ships enforceable security rules using RFC 2119 language — MUST/MUST NOT are blocking, SHOULD/SHOULD NOT are advisory. /review loads the rule files that match your detected stack.

• framework/rules/security-backend.md — auth, input validation, data protection, API security, logging, dependencies, error handling
• framework/rules/security-frontend.md — XSS, CSRF, secure storage, auth handling, content security, dependencies

When a MUST violation is intentional, record a waiver instead of silencing the gate:

/review --waive <rule-id> --reason "<text>"

Waivers are anchored to the rule ID and file path — if the file is renamed or the rule stops firing there, the waiver expires and the finding re-blocks. The waiver schema is open, so organizations can layer on their own required fields. See specs/020-code-review/data-model.md.

govern artifacts are plain markdown with YAML frontmatter, so any markdown viewer or PKM tool can browse them:

• GitHub — push specs/ and browse inline; relative links resolve natively
• Obsidian, Logseq, Foam — graph view and backlinks out of the box
• Quartz or MkDocs — publish a static site
• Plain cat, a GitHub PR review, or any markdown editor — no viewer required

Artifacts stay the portable source of truth; structured viewers are derived views (see constitution §text-first-artifacts).

This repo is the source for everything govern ships, plus its own dogfooded specs.

• framework/ — everything that ships to adopting projects
  • constitution.md — guiding principles, pipeline, spec lifecycle, quality standards (authoritative)
  • rules/ — domain rule sets adopted by reference
  • templates/ — starter files for specs and project scaffolding
  • commands/ — slash command sources
  • workflows/ — tech-stack-specific lint/test/format/migrate workflows plus registry.json
  • bootstrap/ — the govern.md installer and per-agent permission files
• install.sh — the curl … | sh installer that places the /govern bootstrap command for your agent
• docs/introduction.md — the long-form pitch for spec-driven development
• runtime/ — the optional gvrn deterministic runtime (Rust)
• specs/ — govern's own feature specs; it develops itself with its own pipeline. See specs/README.md for cross-cutting decisions and deferred work.
• scripts/ — maintenance and generator scripts

govern currently distributes to three AI coding agents: Claude Code (.claude/ paths), Auggie (.augment/ paths), and Antigravity (.agents/ paths, installed as a skill). Adding another is a single registry row plus a permission file — see framework/bootstrap/govern.md.

All .md files must pass npx markdownlint-cli2 using the project config; see constitution §markdown-standards for the rule set. govern dogfoods its own pipeline — changes to the framework go through the same /specify → /plan → /implement → /review loop, recorded under specs/.

MIT