Standards and conventions for spec-driven software development. This project defines how we run projects — the workflow, spec structure, principles, and quality rules that apply regardless of tech stack.

govern adds a spec-driven pipeline that your AI agent walks for you. You describe a feature in plain English; the agent produces the spec, plan, and tasks in a consistent shape. The surface area you learn is small — a handful of verb-named slash commands (/specify, /clarify, /plan, /implement, /review, /analyze) that map to things you already do: write a ticket, surface unknowns, sketch an approach, build it, audit it, check your work.

The payoff is that ambiguity gets caught upstream of code, and every feature lands with a written record of why it's built the way it is.

• framework/ — Everything that ships to adopting projects
  • constitution.md — Guiding principles, development pipeline, spec lifecycle, quality standards. Authoritative.
  • framework/rules/ — Domain rule sets adopted by reference
    • security-backend.md — Enforceable backend security rules (RFC 2119)
    • security-frontend.md — Enforceable frontend security rules (RFC 2119)
  • framework/templates/ — Starter files customized per project, split by consumer
    • templates/spec/ — Templates consumed during the pipeline (spec, plan, tasks, data-model, research, scenario)
    • templates/project/ — Project document templates consumed during adoption (agents.md, claude-md.md, system.md, errors.md, events.md, project-readme.md, gitignore, inbox.md)
  • framework/commands/ — Slash command sources for the operational commands
  • framework/workflows/ — Tech-stack-specific workflow files (lint, test, format, migrate) plus registry.json mapping stack selections to workflows
  • framework/bootstrap/ — The govern.md installer plus per-agent permission files (configure/{agent}.md)
• docs/introduction.md — Long-form pitch for spec-driven development. The constitution is authoritative for normative rules.
• specs/ — Feature specs for govern itself (dogfooding the pipeline)
• scripts/ — Maintenance scripts (e.g., regenerate .claude/commands/gov/ from framework/commands/)

govern uses its own spec-driven pipeline to develop itself.

See specs/README.md for cross-cutting decisions and deferred work.

The govern runtime is an optional deterministic execution layer for slash commands. It parses the prose Instructions section of each framework/commands/*.md file directly and dispatches the mechanical work (reading specs, walking tasks, checking dependencies, atomic checkbox updates, gate handshakes) in native Rust instead of having the LLM do it in slow tokens. The LLM is invoked only at named extension points (assessSpecQuality, writeCode, writeSpecBody) where semantic judgment actually matters.

The markdown-only path remains a first-class path per constitution §runtime-boundary. When the runtime is absent, the LLM walks the same prose as today.

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.2.1"
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 `gvrn` binary lands away
# from the caller's working 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}"

Pre-built binaries are published for aarch64-apple-darwin, x86_64-apple-darwin, x86_64-unknown-linux-gnu, and aarch64-unknown-linux-gnu. A Windows binary may also be present when cross-compilation succeeds.

Install if you adopt govern and run slash commands frequently — the wall-clock saving on /gov:analyze and /gov:implement is significant. Skip if you only invoke the pipeline occasionally; the markdown-only path is faithful to the same semantics, just slower.

If a runtime process crashes mid-procedure, re-run the slash command — the runtime reads state from your markdown and resumes from the next incomplete step. State-modifying primitives use filesystem-atomic writes (tempfile + rename), so crashes leave coherent markdown. On Windows the rename semantics are weaker; clean up any orphaned tempfile in the spec directory with a manual rm if you observe one.

For brownfield projects, install the govern command and run it — no clone required. Once adopted, use /specify with a sparse description to initialize skeleton specs for existing features (sparse acceptance criteria are valid for brownfield use), and let them gain precision incrementally through bug fixes, enhancements, and clarification.

govern operates a live-on-main model — the snippets below fetch the latest from main. Tagged releases (v0.1.0, etc.) mark milestones for changelogs and release notes, not pinning targets. Adopters who want to lock individual files they've customized use .govern.toml (see Configuring .govern.toml below).

mkdir -p .claude/commands
curl -fsSL https://raw.githubusercontent.com/stonean/govern/main/framework/bootstrap/govern.md \
  > .claude/commands/govern.md

Then run /govern {project-name}.

mkdir -p .augment/commands
curl -fsSL https://raw.githubusercontent.com/stonean/govern/main/framework/bootstrap/govern.md \
  > .augment/commands/govern.md

Then run /govern {project-name}.

The command fetches govern files, scaffolds the spec directory, installs slash commands, and displays next steps. It is idempotent — safe to run again to pick up new govern files.

The same govern.md supports every CLI listed above. Use whichever curl snippet matches the agent you want to start with — adopting additional agents later does not require a second curl. Re-run /govern --add-agent from any adopted agent to pick up the others, and the unified file scaffolds them alongside the existing setup.

Adoption installs a full set of slash commands that operationalize the pipeline. All commands are verb-named and session-aware — use /target to switch to an existing feature; /specify creates a new feature and sets it as the session target automatically (accepting both greenfield-rich and brownfield-sparse input).

/review blocks the spec from reaching done while any MUST violation is unresolved. When a violation is intentional — internal-only endpoint, framework-version constraint, etc. — record a waiver explicitly rather than silencing the gate:

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

The waiver appends a record to the spec's review.waivers frontmatter list (rule, file, reason, waived-at, waived-by). It is anchored to the rule ID and file path: if the file is renamed or the rule no longer fires there, the waiver expires on the next /review run and the finding re-blocks.

The waiver list is open-schema — organizations that require additional fields (e.g., co-waived-by, approved-by-team, ticket) can layer them on without govern erroring on the unknown keys, then gate those fields in their own CI. See specs/020-code-review/data-model.md for the full schema and expiry rules.

The fastest path is /govern (see Adopting in an Existing Project above) — it scaffolds a working setup into a fresh repo. The manual steps below are listed for reference or for agents that don't yet support /govern.

mkdir my-project && cd my-project
git init

Copy these files from govern into your project root:

Open AGENTS.md and replace every placeholder section:

• Tech Stack — list your languages, frameworks, databases, and versions
• Commands — define dev, build, test, lint (or your equivalents)
• Project Structure — map out your directory layout
• Code Style — show idiomatic patterns with code examples
• Testing — define test types, file placement, and tooling conventions
• Gotchas — document framework quirks and non-obvious behavior
• Boundaries — define what agents must never do without asking

Create a CLAUDE.md (or equivalent for your agent) that imports the constitution and agent rules:

@import constitution.md
@import AGENTS.md

mkdir specs

Write specs/system.md describing your architecture — server lifecycle, request flow, shared infrastructure, and module pattern. Add specs/errors.md and specs/events.md if your project uses structured errors or event-driven communication.

Run /specify to create a numbered feature directory with a spec from template. The command accepts both rich (greenfield) and sparse (brownfield) input — richness scales with the description. Every spec uses the same artifact set (spec.md, plan.md, tasks.md).

Alternatively, create one manually:

mkdir specs/000-skeleton
cp /path/to/govern/framework/templates/spec/spec.md specs/000-skeleton/spec.md

Follow the pipeline defined in constitution.md:

1. Spec — resolve all open questions, update status to clarified
2. Plan — run /plan to create plan.md (technical decisions, affected files) and tasks.md (ordered work items) in one step. If the feature involves persistence, also add data-model.md. Updates spec status to planned
3. Implement — follow the tasks list, update spec status to in-progress
4. Review — run /review to audit the code against rules; resolve MUST violations or record waivers. The done transition is gated by review.blocking: false
5. Done — /implement completes the in-progress → done transition when the review gate passes

Run /analyze any time to audit a feature's artifacts; it is not a pipeline gate, but it is the recommended check before starting /implement and before the final /review.

The govern framework includes enforceable security rules for backend and frontend code, distributed via /govern. Rules use RFC 2119 language: MUST/MUST NOT are blocking violations, SHOULD/SHOULD NOT are advisory warnings.

• framework/rules/security-backend.md — Authentication, authorization, input validation, data protection, API security, logging, dependency management, and error handling
• framework/rules/security-frontend.md — XSS prevention, CSRF protection, secure storage, authentication handling, content security, and dependency management

Projects can reference these rules in their AGENTS.md or validate command to enforce security standards during development.

Spec-pipeline templates (consumed by an agent during the pipeline):

Project-scaffolding templates (consumed once at adoption):

Bugs are unwritten scenarios. The govern framework treats every bug as evidence that a spec is missing, ambiguous, or violated.

When a bug is reported, follow 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. Scenarios live in specs/NNN-feature/scenarios/slug.md and capture edge cases, bug fixes, and detailed behavior. Each scenario gets a linked task in the parent spec's tasks.md. Scenarios can be targeted directly with /target feature/scenario-slug for focused work.

For brownfield projects, specs/inbox.md is a temporary inbox. Items are recorded with /log and groomed into specs or scenarios with /groom. The goal is for the inbox to eventually be empty.

/govern installs a local pre-commit hook (.githooks/pre-commit) that keeps generated artifacts (currently the spec dependencies: frontmatter) in sync on every commit. For contributors who never installed the hook locally, govern ships a GitHub Actions template at framework/templates/ci/adopter-generators.yml. Copy it into your project at .github/workflows/govern-generators.yml to fail PRs when generators are out of sync. The template is not auto-installed because that would require detecting which CI platform you use (GHA vs. GitLab vs. Buildkite), which is beyond /govern's scope.

Projects that were bootstrapped with /govern or adopted govern manually can pull the latest govern files by running /govern again. It uses three strategies to decide how each file is handled:

The .gitignore uses a merge strategy — govern patterns are appended below a # govern marker if the marker is not already present.

Re-running /govern always pulls from main — the project does not pin to a specific tag. To track a tag instead, edit the https://raw.githubusercontent.com/.../main/ URL inside your installed govern.md to point at the tag (e.g., v0.1.0). Most adopters won't need to — the per-file pinning below is finer-grained and usually the right tool.

.govern.toml is the project's optional configuration and persisted-decisions file. Create it at your project root only if you need one of the behaviors below — /govern runs without it just fine.

If your project has customized a file that govern normally overwrites (update strategy), pin it:

[pinned]
# Files listed here use 'skip' instead of 'update'.
# Use destination paths (after placeholder resolution).
files = [
  ".claude/commands/myapp/implement.md",
  "constitution.md",
]

Any file listed in pinned.files is treated as skip instead of update when /govern runs. Pinned files are reported in the post-scaffolding summary.

When /govern offers a workflow category (Linting, Formatting, Testing, Migrations, Code Review, Deployment), the prompt has three options: Yes, scaffold all in this category, Skip this run, or Skip and don't ask again. Picking the third option records the decline here:

[workflows]
declined_categories = ["Linting"]

Categories listed are matched case-insensitively against the canonical category list. /govern won't prompt for them on subsequent runs and reports suppressed (workflow): {Category} (declined in .govern.toml) in the summary. To re-enable the prompt for a category, remove it from the array (or delete the [workflows] section, or delete the file).

For the full schema — allowed values, unrecognized-entry handling, and future sections — see specs/019-config-decisions/data-model.md.

If you prefer not to use /govern, govern is a reference, not a dependency. Review the govern changelog or diff, decide which changes apply to your project, and update your copies at your own pace.

govern currently distributes to two AI coding agents:

• Claude Code — .claude/ paths, /govern and /gov:* commands
• Auggie — .augment/ paths, /govern command variant

Adding a new agent is a single registry row plus an agent-specific framework/bootstrap/configure/{key}.md permission file — see framework/bootstrap/govern.md for the full rules.

govern artifacts are plain markdown with YAML frontmatter, so any markdown viewer or PKM tool can browse them. Pick whichever fits your workflow:

• GitHub — push specs/ and browse inline; relative links resolve natively, no tooling required
• Obsidian — point at the repo and open; graph view and backlinks out of the box
• Logseq — open-source PKM with a similar graph model
• Foam — VS Code extension for markdown knowledge graphs
• Quartz — publish a static graph-style site; see Quartz's docs for setup
• MkDocs — static documentation site generator
• Plain cat, GitHub PR review, or any markdown editor — no viewer required

The principle is that artifacts stay portable and source-of-truth markdown, with structured viewers as derived views (see constitution.md).

All .md files must pass npx markdownlint-cli2 using the project config. See constitution.md for the full rule set.