Skip to content

Accelerated-Innovation/governed-ai-delivery

BranchesTags

Repository files navigation

govkit — Governed AI Delivery

PyPI version Python 3.11+ License Publish

AI coding agents are powerful — but without constraints, they drift. They invent architecture, skip tests, ignore NFRs, and make decisions that belong to your team. govkit puts the agent inside a governed system where your architecture contracts, acceptance criteria, and evaluation thresholds are the source of truth, not the agent's training data.

pip install govkit
govkit apply --agent claude-code --target .
govkit calibrate

Install govkit, apply it to your project, then calibrate the defaults to match your repo. From there the governance workflow your team follows is what keeps the agent aligned — every feature, every time.

govkit works with any project language — Python, C#, Java, Go, TypeScript, or anything else. It copies Markdown specs, YAML configs, and Gherkin feature files into your project directory. Python is a dev-machine tool requirement only; it is not added as a project dependency.

Get started in 4 steps

You need Python 3.11+ on your machine (govkit is a dev tool, never a project dependency) and an AI coding agent — Claude Code, GitHub Copilot, or OpenAI Codex. govkit ships the governance configuration; you bring the agent.

Work top to bottom. Steps 1–2 install governance; steps 3–4 make it govern your project, not a generic one.

1. Install govkit

pip install govkit

2. Apply it to your project

From your project root:

govkit apply --agent claude-code --target .

govkit detects your stack (language, framework, CI), scaffolds the agent rules + architecture contracts, and writes a .govkit/ marker recording your configuration. Prefer to set everything explicitly, or use a different agent/type/level? See Choose your options.

3. Calibrate the defaults to your repo

Important

This step is not optional. The files govkit installs are sound generic defaults — and your agent treats them as law. If you skip calibration, the agent governs your project against someone else's architecture decisions.

govkit calibrate

govkit calibrate walks you through a 9-step review — installed configuration, tech stack, architecture boundaries, API/query conventions, testing + BDD policy, agent guidance, rules, CI gates, and skill context. For each step it shows the installed default next to what it detected in your repo, then you confirm or modify. Prefer to review with the team first? govkit calibrate --non-interactive writes a GOVKIT_CALIBRATION_CHECKLIST.md todo file instead.

💡 Let the agent help — but you decide. You can ask the agent to draft edits — "update TECH_STACK.md to match our pyproject.toml" or "align BOUNDARIES.md with our actual folder layout" — pointing it at evidence you already have (dependency manifests, existing code). You confirm every change. These files are the source of truth that governs the agent; don't let it invent its own guardrails from its training data — that's the exact drift govkit exists to prevent.

4. Commit your governance baseline

git add .govkit .claude/ docs/ governance/ ci/
git commit -m "chore: add govkit governance baseline"

For Copilot, stage .github/ instead of .claude/; for Codex, stage AGENTS.md and .agents/. govkit installs its governance into those agent-owned locations and does not create a top-level CLAUDE.md / copilot-instructions.md, so your own instruction file (if any) stays out of this commit.

You're ready to build. See The feature lifecycle for how you drive the agent through a feature, and run govkit doctor once you have source code (and in CI) to catch governance that has drifted out of sync with your repo.

Upgrading later? pip install --upgrade govkit && govkit upgrade --target . refreshes the files govkit owns without touching the contracts you've customized. See Keeping contracts up to date.

Choose your options

Each govkit apply configures one project shape. Pick one value per flag:

Flag Options Pick this if…
--agent claude-code · copilot · codex …matches the AI tool your team uses
--type api · cli · ui-react · ui-angular · data …describes this repo (or subdir) — backend service, CLI, React/Angular UI, or governed data project
--level 3 · 4 · 5 …3 governed foundations (default) · 4 spec-driven delivery · 5 GenAI operations — see Maturity Levels
--ci github · azure …your CI platform
--stack python-fastapi · dotnet-aspnet · java-spring-boot · nodejs-fastify · go-gin · python-dbt · databricks-lakehouse …backend/data only; auto-detected, defaults by type (python-fastapi for api / cli, python-dbt for data). See Switching Tech Stacks

Running govkit apply with no --type/--ci/--stack flags prompts interactively and auto-detects sensible defaults from your repo, including python-dbt from dbt_project.yml and databricks-lakehouse from databricks.yml / databricks.yaml. A .govkit marker records every choice so later commands (calibrate, validate, upgrade, doctor) need no re-specification.

Full example commands for every combination 
# Level 3: Governed AI Delivery (Foundations) — agent rules + architecture docs only (default)
govkit apply --agent claude-code --level 3 --type api --ci github --target .

# Level 4: Spec-Driven Add-On — adds the features/ directory and 5-artifact contract
govkit apply --agent claude-code --level 4 --type api --ci github --target .

# Level 5: GenAI Operations plus provider-neutral LLM application contracts
govkit apply --agent claude-code --level 5 --type api --ci github --target .
govkit extension add llm-application --target .

# Python CLI tool + Azure DevOps
govkit apply --agent copilot --type cli --ci azure --target .

# React UI project (L4)
govkit apply --agent copilot --level 4 --type ui-react --ci github --target .

# Angular UI project (L4) on OpenAI Codex
govkit apply --agent codex --level 4 --type ui-angular --ci github --target .

# Data project (L4) — dbt-layered, python-dbt stack inferred from dbt_project.yml
govkit apply --agent claude-code --level 4 --type data --ci github --target .

# Pick a non-default backend stack
govkit apply --agent claude-code --level 4 --type api --ci github --stack dotnet-aspnet --target .

Fullstack-in-one-repo is supported via the monorepo pattern — one govkit apply per subdirectory. There is no --type fullstack.

What gets installed

After applying, your project contains artifacts appropriate to the shape you picked.

Backend shape (--type api or --type cli):

your-project/
├── .claude/rules/govkit/        — governance.md + layer rules
│   └── governance.md, api.md, services.md, ports.md, adapters.md, security.md, repo-scope.md
├── .claude/skills/              — govkit skills, all govkit- prefixed
│   └── govkit-architecture-preflight/, govkit-spec-planning/, govkit-implementation-plan/, govkit-adr-author/
├── docs/backend/
│   ├── architecture/   — ARCH_CONTRACT, API_CONVENTIONS, TECH_STACK, etc.
│   └── evaluation/     — eval_criteria.md, scoring rubrics
├── features/           — created empty at L4+; scaffold your first feature with govkit init
├── governance/backend/schemas/   — eval_criteria.schema.json
└── ci/github/ (or azure/)        — l3-quality-gate.yml + L4/L5 gates

govkit does not create or overwrite a top-level CLAUDE.md / .github/copilot-instructions.md. Its governance loads from the govkit/ namespace above (Claude Code and Copilot both auto-load those directories), so your own instruction file is left untouched. Copilot's equivalents live under .github/instructions/govkit/ (rules) and .github/skills/govkit-* (skills). Codex has no rules directory, so its governance installs as a managed block inside AGENTS.md — at the root and per layer (api/AGENTS.md, services/AGENTS.md, …) — fenced by <!-- BEGIN/END GOVKIT GOVERNANCE --> and preserving whatever you wrote around it; Codex skills go under .agents/skills/govkit-*.

UI shape (--type ui-react or --type ui-angular):

your-project/
├── .claude/rules/govkit/
│   ├── governance.md         — root UI governance (loads every session)
│   ├── governance-src.md     — UI layer rules, path-scoped to src/** (Claude Code)
│   └── repo-scope.md, test-first.md (L4+), spec-compliance.md (L4+)
├── .claude/skills/
│   └── govkit-ui-architecture-preflight/, govkit-ui-spec-planning/, govkit-ui-implementation-plan/, govkit-ui-adr-author/
├── docs/ui/
│   ├── architecture/   — MVVM_CONTRACT, ACCESSIBILITY_STANDARDS, react|angular subdirs
│   └── evaluation/     — eval_criteria.md, scoring rubrics
├── governance/ui/      — schemas, templates
└── ci/github/ (or azure/)  — l3-ui-quality-gate.yml + L4/L5 UI gates

As with the backend shape, no top-level CLAUDE.md / copilot-instructions.md is created. Copilot installs the same content under .github/instructions/govkit/ (with applyTo: globs, src/**-scoped for the layer rules); Codex uses managed blocks in AGENTS.md at the root and under src/.

Backend installs ship no UI artifacts; UI installs ship no backend artifacts. The CI dispatch is type-aware: backend types get l3-quality-gate.yml, UI types get l3-ui-quality-gate.yml. For fullstack monorepos, run one govkit apply per app subdirectory — see the monorepo pattern.

Starter templates and worked examples are bundled inside the govkit package, not copied into your project by govkit apply. Use govkit init <feature-name> to scaffold a new feature from the appropriate starter, or run govkit list to see what is available.

Commands

Command What it does
govkit apply Install / scaffold governance into your project. Detects your stack, writes the .govkit marker.
govkit calibrate Guided 9-step review to make the installed generic defaults match your repo. --non-interactive writes a checklist file; --only <step> revisits one decision.
govkit doctor Read-only governance-fit checks (rule globs resolve, CI/stack/language match, stale baselines, extension manifests). Run once you have source code, and in CI. Monorepo-aware.
govkit validate Level-aware per-feature compliance check (artifact existence, Gherkin structure, NFR coverage, eval-criteria schema, prediction thresholds). No-op at L3.
govkit init <feature> Scaffold a new feature folder from the appropriate starter (L4+).
govkit stack stack list shows bundled tech-stack overlays; stack apply <id> swaps the stack on an existing install.
govkit extension extension list shows bundled extension packs; extension add <id> --target <path> copies one into your project's extensions/<id>/.
govkit upgrade Refresh the files govkit owns (contracts, CI gates, templates) to a new version without touching the files you own.
govkit list List available agents and starter templates.

govkit doctor and govkit validate cover different surfaces: doctor checks whether the installed governance still fits the repo; validate checks whether your features meet the governed contract. Both are designed to run in CI.

Maturity Levels

govkit supports three operating levels in an additive ladder. Each level commits the team to a different way of working, not just a different artifact count. The boundary between L3 and L4 sits at the most meaningful place: whether the team adopts a features/ directory model and per-feature spec contracts.

Level Name What it ships What the team commits to
Level 3 Governed AI Delivery (Foundations) Agent rules, architecture contracts under docs/*/architecture/, /govkit-adr-author skill, lean CI gate (commit-format + import-linter + sonar/snyk). No features/ directory, no per-feature artifacts. "Our AI agents follow our architecture contracts." Lowest-friction entry; no project-structure change required.
Level 4 Spec-Driven Add-On Adds the features/<name>/ 5-artifact contract (acceptance.feature, nfrs.md, eval_criteria.yaml, plan.md, architecture_preflight.md), feature-coupled skills (/govkit-spec-planning, /govkit-architecture-preflight, /govkit-implementation-plan), test-first + spec-compliance rules (binding), governance CI jobs, and per-feature evaluation prediction (FIRST + 7 Virtues, average ≥ 4.0). "We adopt spec-first, test-first feature delivery on top of L3." govkit init becomes meaningful here.
Level 5 GenAI Operations LLM-specific NFRs, evaluation and safety gates, extension-aware coding-agent rules, and optional implementation-profile CI templates. Add llm-application for provider-neutral gateway, evaluation, observability, and model-guardrail contracts; add skill-oriented-agent-architecture for agent runtime and skills. "Our model-backed features are governed (routing, evaluation, telemetry, safety)." Builds on L4.

Start at Level 3 (default) if you want governed AI agents without restructuring your codebase. Move to Level 4 when your team is ready to commit to spec-first feature delivery. Move to Level 5 when shipping LLM-powered features that need governed model routing, evaluation, and safety.

The ladder is additive: L4 ⊃ L3, L5 ⊃ L4. Files installed at lower levels are not replaced by higher levels (with one exception: the govkit governance file — .claude/rules/govkit/governance.md, .github/instructions/govkit/governance.instructions.md, or the managed block in Codex's AGENTS.md — is re-issued at each level so the agent sees the right operating mode).

Level 3 — Governed AI Delivery (Foundations)

Your AI agent operates aligned to your architecture contracts:

  • Reads docs/<area>/architecture/ (ARCH_CONTRACT, BOUNDARIES, TESTING, SECURITY_AUTH_PATTERNS, etc.) on every turn
  • Path-scoped rules trigger when editing files in each layer (api/, services/, ports/, adapters/, security/)
  • ADRs required for any standard extension, override, or boundary change — scaffolded with /govkit-adr-author
  • Test-first is recommended (the binding rule lives at L4)
  • CI quality-gate enforces commit-format, import-linter (architecture boundaries), SonarQube, Snyk
  • No features/ directory is created. govkit init errors at L3 with a pointer to --level 4.
  • govkit validate is a no-op (returns 0 with informational message).

Level 4 — Spec-Driven Add-On

Everything in Level 3, plus:

Every feature lives under features/<name>/ with five required artifacts:

  • Defined with Gherkin acceptance criteria tagged to NFR categories
  • Constrained with fully populated NFRs (no TBD entries permitted)
  • Governed by evaluation criteria validated against a JSON Schema
  • Planned through Architecture Preflight + Spec Planning + Implementation Plan skills
  • Bounded by hexagonal architecture contracts with FIRST + 7 Virtues prediction (average ≥ 4.0)
  • Enforced by governance CI jobs (artifact existence, eval-criteria schema, prediction thresholds, contract compatibility)

Level 5 — GenAI Operations

Everything in Level 4, plus:

  • Install the provider-neutral LLM application contracts:

    govkit extension add llm-application --target .

  • Route model calls through an application-owned port with logical model identities, bounded resilience, data policy, and budgets

  • Apply privacy-aware model telemetry with immutable model, prompt, policy, and configuration provenance

  • Define versioned model-quality, adversarial, retrieval, tool-use, and operational evaluation criteria and blocking evidence

  • Apply risk-based input, context, output, and tool-call controls without treating model output as authority

  • Select concrete gateway, telemetry, evaluation, and guardrail products in TECH_STACK.md or an ADR; bundled product guides and CI gates are optional implementation profiles

  • Install skill-oriented-agent-architecture as a separate extension when the feature uses agents, skills, delegation, or governed agent runtime state

The AI agent operates inside a governed system. Architecture, evaluation, and feature artifacts are the source of truth — not the agent.

Migrating from v0.6.x

The L3 / L4 maturity-model meaning changed in v0.7.0. If your .govkit marker says level: "3" (the v0.6 simpler 3-artifact model), run:

govkit upgrade --migrate-levels --target .

You'll be prompted to choose: migrate your existing 3-artifact features to the new L4 (with stub generation for the two new artifacts), or adopt new-L3 (no features/). See CHANGELOG.md for the full migration guide.

The feature lifecycle

Once govkit is installed and calibrated, here is how you interact with the agent to deliver a feature. This lifecycle applies to every feature, regardless of project type. The commands below use Claude Code; see Agent command equivalents for Copilot and Codex.

Step 1: Create a feature folder

govkit init my_feature --target .

Or specify the starter type explicitly:

govkit init my_feature --starter backend --target .

The command auto-detects your maturity level from .govkit. govkit init requires Level 4 or higher — Level 3 (Foundations) ships agent rules and architecture contracts only and has no features/ directory model. Running govkit init at L3 errors with a pointer to govkit apply --level 4. At L4 the bundled starter has all 5 artifacts; at L5 the starter adds agent_topology.md for multi-agent features.

For Level 4 projects, each starter's eval_criteria.yaml includes mode selection instructions at the top. Set the mode field to match your feature type: llm (LLM generation/retrieval), deterministic (pure logic), or none (configuration artifacts). If the mode is deterministic or none, delete the llm_evaluation section.

Step 2: Write your acceptance criteria

Edit features/my_feature/acceptance.feature with your Gherkin scenarios:

  • Write happy path and failure/edge case scenarios
  • Tag NFR scenarios with @nfr-performance, @nfr-security, etc.
  • Tag E2E scenarios with @e2e (UI projects)
  • Add @contract scenarios if the feature produces shared artifacts

Step 3: Complete your NFRs

Edit features/my_feature/nfrs.md — replace every TBD entry with concrete requirements. The agent will refuse to proceed if any TBD entries remain.

Step 4: Run architecture preflight

Ask the agent to validate your feature against the architecture contracts with /govkit-architecture-preflight my_feature. The agent produces architecture_preflight.md covering boundary analysis, security impact, evaluation impact, and whether an ADR is needed. If an ADR is required, create it next with /govkit-adr-author my_feature.

Step 5: Generate the plan

Ask the agent to create the implementation plan with /govkit-spec-planning my_feature. The agent generates plan.md and eval_criteria.yaml. The plan includes:

  • Increments with deliverables and tests
  • An Evaluation Compliance Summary predicting FIRST and 7 Virtue scores
  • Each increment sized as a single committable unit (~300 lines)

The agent will not proceed if predicted averages are below 4.0.

Step 6: Review the implementation plan

Ask the agent to break the plan into a detailed task checklist with /govkit-implementation-plan my_feature. Review and approve before implementation begins.

Step 7: Implement incrementally

Work through the plan one increment at a time. For each increment:

  1. The agent writes production code respecting architecture boundaries
  2. The agent writes tests (unit, integration, contract as needed)
  3. You review and commit: feat(my_feature): increment 1 — <name>
  4. Move to the next increment

Do not skip increments or combine multiple increments into one commit.

Step 8: Push and merge

Open a PR. CI gates automatically run:

  • Schema validation of eval_criteria.yaml
  • FIRST and 7 Virtue prediction completeness
  • Unit, component, and E2E tests
  • Architecture boundary enforcement
  • Security scan and quality gates
  • Accessibility checks (UI projects)

All gates must pass before merge.

Agent command equivalents

The lifecycle is identical across agents; only the invocation syntax differs.

Step Claude Code Copilot Codex
Architecture preflight /govkit-architecture-preflight my_feature /govkit-architecture-preflight $govkit-architecture-preflight my_feature
Author ADR /govkit-adr-author my_feature /govkit-adr-author $govkit-adr-author my_feature
Spec planning /govkit-spec-planning my_feature /govkit-spec-planning $govkit-spec-planning my_feature
Implementation plan /govkit-implementation-plan my_feature /govkit-implementation-plan $govkit-implementation-plan my_feature

Copilot infers the feature from context rather than taking it as an argument; Codex invokes skills with a $ prefix.

Project Type Details

The 8-step lifecycle above applies to all project types. Key differences by type:

Backend API

Architecture: Hexagonal Architecture — ports and adapters. API routes are the inbound adapter layer. See docs/backend/architecture/API_CONVENTIONS.md.

Layer rules (load automatically when editing files):

  • api.md for **/api/**
  • services.md for **/services/**
  • ports.md for **/ports/**
  • adapters.md for **/adapters/**
  • security.md for **/security/** and **/auth/**

CI gates: ci/github/quality-gate.yml, ci/github/eval-gate.yml (or ci/azure/ for Azure DevOps)

CLI

Architecture: Hexagonal Architecture — CLI commands are the inbound adapter layer (same position as API routes). See docs/backend/architecture/CLI_CONVENTIONS.md.

Layer rules (load automatically):

  • cli.md for **/cli/** and **/commands/**
  • services.md, ports.md, adapters.md, security.md as above

CI gates: Same backend gates — ci/github/quality-gate.yml, ci/github/eval-gate.yml

React UI

Architecture: MVVM with vertical slice feature structure. Layer order is API → ViewModel → View. See docs/ui/architecture/MVVM_CONTRACT.md.

Layer rules (load automatically):

  • components.md for View layer
  • viewmodel.md for hooks and store
  • api.md for API client functions
  • accessibility.md for accessibility concerns

Implementation order: API functions → React Query hooks → Zustand stores → Components → E2E tests

CI gates: ci/github/ui-quality-gate.yml, ci/github/ui-eval-gate.yml

Angular UI

Architecture: MVVM with vertical slice feature structure. Standalone components with OnPush. See docs/ui/architecture/MVVM_CONTRACT.md.

Layer rules: Same as React, with Angular-specific content.

Implementation order: API functions → TanStack Query inject functions → Signal stores → Standalone components → E2E tests

CI gates: ci/github/ui-quality-gate.yml, ci/github/ui-eval-gate.yml

Data

Architecture: governed data delivery — Staging → Intermediate → Marts for dbt projects, or Bronze → Silver → Gold / curated Delta layers for Databricks lakehouse projects. Staging/Bronze cleans source data, Intermediate/Silver holds joins and business logic, and Marts/Gold are the downstream contracts. See docs/data/architecture/BOUNDARIES.md plus the selected stack overlay's layering guidance.

The following layer rules apply to dbt-style repos (python-dbt). For Databricks lakehouse repos, follow the databricks-lakehouse overlay's MODEL_LAYERING.md (Bronze/Silver/Gold) and adjust rule globs if your repo uses src/bronze|silver|gold.

Layer rules (load automatically):

  • staging.md for **/models/staging/**
  • intermediate.md for **/models/intermediate/**
  • marts.md for **/models/marts/**
  • data-quality.md for **/tests/** (dbt schema + singular tests)
  • pii.md for **/models/**, **/macros/**, **/seeds/** (PII tagging + masking)

Stack overlays:

  • python-dbt (dbt-core + Snowflake / BigQuery / Redshift / Postgres adapter, SQLfluff, dbt schema tests, optional dbt-expectations for L4).
  • databricks-lakehouse (Unity Catalog, Delta tables, Databricks Asset Bundles, Jobs, Lakeflow Pipelines, PySpark, SQL, notebooks, and optional Databricks bundle validation).

If both dbt_project.yml and databricks.yml are present, GovKit treats the repo as python-dbt by default because dbt is the project shape. Pass --stack databricks-lakehouse when the repo should use the native Databricks overlay instead.

Databricks skills integration: GovKit governs repo delivery: contracts, acceptance criteria, architecture boundaries, PII handling, lineage expectations, CI gates, ADRs, and human approvals remain the source of truth. Databricks skills provide platform-specific assistant guidance for workspace, CLI, bundle, Unity Catalog, Jobs, Lakeflow, serving, vector search, and notebook workflows. For Databricks-native repos, install those optional skills with:

databricks aitools install

Worked starter: govkit init <feature> --starter data scaffolds a customer_dim_freshness feature with @nfr-freshness / @nfr-quality / @nfr-pii / @nfr-lineage / @nfr-reliability / @nfr-cost Gherkin scenarios.

CI gates: data installs include the common repo-scope governance gate. Stack-specific execution gates (source freshness, dbt test, SQLfluff, Databricks workspace validation) remain conservative and opt-in until configured by the team.

Maturity levels: data projects support Level 3 and Level 4. Level 5 is GenAI Operations for LLM application delivery and does not apply to dbt/data project installs.

Agent support: claude-code, copilot, and codex.

Monorepo (Fullstack) Pattern

Each govkit apply configures one project shape. There is no --type fullstack. Teams that need both backend and UI in a single repo run govkit apply once per subdirectory:

govkit apply --agent claude-code --type api      --level 4 --ci github --target apps/api
govkit apply --agent claude-code --type ui-react --level 4 --ci github --target apps/web

Each subdir becomes a self-contained govkit install — separate .govkit marker, separate features/, separate CI gates. The three agents all support subpath governance natively:

  • Claude Code — recursive .claude/rules/ discovery picks up each subdir's govkit/ rules based on the open file's directory
  • Codex — directory-walk loader concatenates AGENTS.md (govkit's managed block plus your content) from leaf to root
  • Copilot — applyTo: globs in each .github/instructions/govkit/ file (one small post-install adjustment to prefix the app path so globs don't cross app boundaries)

govkit calibrate and govkit doctor are monorepo-aware: run them with no --target from the repo root and they discover every .govkit/ install under the tree and process each app in turn.

For the complete setup — directory layout, CI workflow examples, the Copilot applyTo: prefix tweak, feature governance per app, upgrade flow, and gotchas — see docs/MONOREPO_PATTERN.md.

If your backend and UI live in separate repositories instead of subdirectories of a monorepo, see Multi-Repository Features below — different coordination problem.

Switching Tech Stacks

GovKit ships stack overlays — small bundles of 6 stack-specific architecture docs plus metadata. Pick one at install time with --stack, or swap later with govkit stack apply. Stack overlays apply to backend types (api, cli) and the data type; UI installs ignore --stack. The 6 docs vary per shape:

  • Backend stacks (python-fastapi, dotnet-aspnet, java-spring-boot, nodejs-fastify, go-gin): TECH_STACK.md, API_CONVENTIONS.md, TESTING.md, LAYER_IMPLEMENTATION.md, SECURITY_AUTH_PATTERNS.md, OBSERVABILITY_PORT_CONTRACT.md.
  • Data stacks (python-dbt, databricks-lakehouse): TECH_STACK.md, TESTING.md, MODEL_LAYERING.md, PII_HANDLING.md, LINEAGE_OBSERVABILITY.md, plus stack-specific query or pipeline contracts.

See what's available

govkit stack list

Lists every bundled overlay (id, display name, summary) along with the apply commands.

Pick a stack at install time

govkit apply --agent claude-code --target . --level 4 --type api --ci github \
             --stack dotnet-aspnet

If you omit --stack, govkit detects your stack from the repo and falls back to the type default (python-fastapi for api / cli, python-dbt for data), recording the choice as an assumption in .govkit/marker.json so govkit doctor can warn if it doesn't fit your repo.

Swap stacks on an existing install

govkit stack apply java-spring-boot --target .

Re-applies the new overlay on top of the existing install. Edit-protection respects user changes: any of the 6 stack docs you've modified since the last apply are preserved unless you pass --force (your edits are detected via the govkit:editable header + file mtime vs. the marker's applied_at).

Why only 6 files?

The agent rules and most architecture docs (DESIGN_PRINCIPLES, ARCH_CONTRACT, BOUNDARIES, GHERKIN_CONVENTIONS, ERROR_MAPPING, etc.) are language-agnostic and ship from the baseline. Only these 6 vary per stack:

File What it defines
TECH_STACK.md Languages, versions, approved frameworks
API_CONVENTIONS.md Route patterns and request/response idioms
TESTING.md Test framework, mocking library, BDD tool
LAYER_IMPLEMENTATION.md DI patterns, interface idioms, DTO style
SECURITY_AUTH_PATTERNS.md Auth libraries, token handling, hashing
OBSERVABILITY_PORT_CONTRACT.md Structured logging library, OTel SDK

Bundled stacks

Id Shape Stack
python-fastapi backend Python 3.11+ / FastAPI / pytest (default for api / cli)
dotnet-aspnet backend C# 12 / .NET 8 / ASP.NET Core Minimal APIs / xUnit
java-spring-boot backend Java 21 / Spring Boot 3 / Spring Web MVC / JUnit 5
nodejs-fastify backend Node.js 20 LTS / TypeScript 5 / Fastify 4 / Vitest
go-gin backend Go 1.22+ / Gin / standard library testing + testify
python-dbt data Python 3.11+ / dbt-core (staging → intermediate → marts) / Snowflake | BigQuery | Redshift | Postgres adapter / SQLfluff / dbt schema tests (default for data)
databricks-lakehouse data Databricks Lakehouse / Unity Catalog / Delta tables / Asset Bundles / Jobs / Lakeflow Pipelines / PySpark / SQL

After applying a stack, review the installed files and adapt anything specific to your repo (approved library versions, internal service names, etc.) — govkit calibrate walks you through this. GOVKIT_SETUP_REVIEW.md at the target root lists each stack doc with a one-line review prompt. Consider raising an ADR to document the stack decision.

See cli/stacks/README.md for the complete guide, including how to add new stacks.

Extensions

Govkit ships optional extension packs that layer additional architecture contracts on top of the core kit — currently llm-application, skill-oriented-agent-architecture, and vision-inference. Add one with govkit extension add, or drop the folder in by hand; either way the folder under extensions/<id>/ in your project is the install.

How to add an extension

The quickest path is the bundled-pack command:

govkit extension list                              # see what's bundled
govkit extension add llm-application --target .    # provider-neutral LLM contracts
govkit extension add vision-inference --target .   # copy it into extensions/vision-inference/
govkit extension add skill-oriented-agent-architecture --target .

add copies the pack into your project's extensions/<id>/ and validates it in place. It warns but proceeds if the pack's supported_levels / supported_project_types don't match your .govkit marker, or if a core contract it extends isn't installed yet (e.g. a generative pack's L5 contracts in a non-L5 project). Pass --force to overwrite an existing folder.

Or add one by hand — the folder is the install, so you can vendor any extension, including ones not bundled with govkit:

  1. Create the folder at your project root — a sibling of docs/, governance/, and features/:

    <project>/
├── docs/
├── governance/
├── features/
├── extensions/
│   └── <extension-id>/
│       ├── manifest.yaml
│       ├── README.md
│       ├── docs/
│       └── governance/
└── .govkit

  2. Drop in the extension's files. Copy or vendor the folder into extensions/<id>/; all manifest paths are relative to it.

  3. Re-run govkit apply (or govkit doctor). It scans extensions/*/manifest.yaml and reports each extension it discovers.

  4. Validate it. govkit validate and govkit doctor (checks D013/D014) verify the manifest and flag any undeclared overlap with core contracts (see below).

When extensions/ is absent, govkit behaves exactly as it does without extensions — they are entirely optional.

See extensions/llm-application/, extensions/skill-oriented-agent-architecture/, and extensions/vision-inference/ in this repository for complete reference examples. Install both llm-application and skill-oriented-agent-architecture for an agentic system that invokes language models.

Authoring an extension

Each extension is self-describing: it declares its own id, version, contract_sets, capabilities, and agent guidance in its manifest. Govkit needs no per-extension code.

Minimal manifest (extensions/<id>/manifest.yaml):

id: my-extension
name: My Extension
version: 0.1.0
extension_type: architecture
contract_sets:
  - id: my_contracts
    description: ...
    paths:
      - docs/backend/architecture/MY_CONTRACT.md
    capabilities:
      - my-capability

The extension id must match its folder name and the pattern ^[a-z0-9][a-z0-9-]*$. Every path listed in contract_sets[].paths (and templates[].path) must exist as a file under the extension folder — govkit validate reports missing or out-of-bounds paths.

Resolving overlap with project contracts

When an extension contract covers the same topic as a core GovKit contract or a contract from another installed extension, the manifest declares the relationship explicitly via relates_to:

contract_sets:
  - id: my_contracts
    paths: [docs/backend/architecture/AGENT_EVALUATION_CONTRACT.md]
    relates_to:
      extends:    [extensions/llm-application/docs/backend/architecture/LLM_EVALUATION_CONTRACT.md] # both apply; stricter rule wins
      supersedes: [] # this set replaces the listed contract in scope (requires ADR)
  • relates_to.extends — the extension layers additional constraints on top of the referenced project contract. The agent reads both and applies whichever is stricter on any specific point.
  • relates_to.supersedes — the extension replaces the referenced project contract for rules in its scope. Requires an ADR in the consuming project.

Undeclared overlap is detected. govkit validate and govkit doctor run a filename-token heuristic: if an extension contract shares a topic token with a core contract under docs/backend/architecture/ and relates_to does not declare the relationship, the validator emits a WARN (or FAIL under --strict) asking the extension author to declare the intent. This prevents silent drift when extension authors and core authors update the same topic area independently.

Agent reading order at preflight time. The architecture-preflight skill reads core contracts first, then extension contracts; it prefers extensions only when supersedes is declared. If an applicable extension and a core contract conflict and relates_to does not declare the relationship, the agent halts and requests either a manifest update or an ADR rather than silently picking one.

Multi-Repository Features

If your feature spans multiple repositories (e.g., Auth Service + Client SDK + API Gateway), see:

  • CROSS_REPO_FEATURES.md — Complete guide to planning, implementing, and testing features across repos
  • REPO_SCOPE_ANALYSIS_GUIDANCE.md — How to declare repo ownership in your feature spec
  • features/example-jwt-unification/ — Worked example of a 3-repo JWT authentication feature

The key principle: Every feature must declare which repositories own which parts. This prevents agents from writing code in the wrong repo.

Multi-Repo FAQ

Q: My feature needs changes in Auth Service, API Gateway, and Frontend. Where do I document this? A: In the primary owner repo's features/<feature>/nfrs.md, add a "Repository Scope" section with a table listing each repo, owner team, modules, and contracts. See CROSS_REPO_FEATURES.md#repository-ownership-table.

Q: Can we implement the feature in just one repo and copy code to the others later? A: No — this violates ownership and creates duplication. Each repo implements its own portion against the shared contract. See CROSS_REPO_FEATURES.md#common-pitfalls.

Q: Should we wait for Repo A to finish before Repo B starts? A: No. Each repo implements in parallel using mocks for external dependencies. Only the final integration tests (after all repos merge) verify cross-repo contracts. See CROSS_REPO_FEATURES.md#implementation-stage-parallel.

Q: How do we test a feature that depends on another repo's code? A: Each repo has unit tests (mocking externals) and contract tests (verifying its own implementation). After all repos merge to main, run integration tests to verify end-to-end behavior. See CROSS_REPO_FEATURES.md#testing-strategy.

Q: What if the repos have deployment dependencies (one must be live before the other)? A: Document the order in your nfrs.md "Key Cross-Repo Contracts" section. Ideally, design contracts to be backward-compatible so deployment order is flexible. See CROSS_REPO_FEATURES.md#integration-stage-sequential.

Keeping contracts up to date

When you upgrade govkit, run govkit upgrade to refresh the files that govkit owns — architecture contracts, CI gate pipelines, plan templates — without touching the files your team owns.

pip install --upgrade govkit
govkit upgrade --target .

govkit distinguishes these categories of files:

Category Examples apply upgrade
govkit agent config .claude/rules/govkit/, .github/instructions/govkit/, .claude/skills/govkit-*, Codex's managed AGENTS.md block Overwrite (govkit-owned namespace) Overwrite / refresh
Governed contracts docs/backend/architecture/, governance/backend/templates/, ci/github/ Write once (skip if present) Overwrite
Project artifacts features/starter_*/, your ADRs, filled-in feature files Write once (skip if present) Skip
Your files your own CLAUDE.md / .github/copilot-instructions.md, your content around Codex's AGENTS.md block, your own .claude/rules/*.md or .claude/skills/* Never written or touched Never touched

govkit never overwrites files you authored. Everything govkit installs lives in a namespace it owns — a govkit/ subdirectory under the rules dir, a govkit- prefix on skills, or a fenced managed block inside Codex's AGENTS.md. So your own CLAUDE.md, a rule you named .claude/rules/api.md, or a skill you named spec-planning all coexist with govkit's copies untouched. When you upgrade an install created by an older govkit that did write a top-level CLAUDE.md, upgrade retires that orphan only when it can prove it was govkit's own (byte-identical to the shipped governance, or unmodified since the last apply); if you edited it, it is kept and you're told how to adopt the managed layout.

After upgrading, review the diff and commit:

git diff
git add -p
git commit -m "chore: upgrade govkit governance contracts to vX.Y.Z"

Use --force to re-apply even when the version is already current — useful for resetting a contract file to govkit defaults after an accidental edit:

govkit upgrade --target . --force

Interpreting Validation Failures

When govkit validate --target . reports failures, here's what they mean and how to fix them:

Failure Meaning Fix
acceptance.feature not found Feature folder is missing its Gherkin spec Copy from starter and write scenarios
no Feature: keyword or no Scenario: keyword Gherkin file exists but is malformed Add Feature: header and at least one Scenario: with Given/When/Then
nfrs.md contains TBD entries NFR categories have placeholder values Replace every TBD with a concrete, measurable requirement
eval_criteria.yaml missing or invalid Eval config doesn't match the JSON Schema Check governance/*/schemas/eval_criteria.schema.json for required fields
plan.md missing evaluation_prediction Plan exists but has no prediction block Add the evaluation_prediction YAML block (see worked examples)
predicted FIRST average below 4.0 Predicted test quality is below threshold Revise the plan — improve test strategy or split complex increments
predicted Virtue average below 4.0 Predicted code quality is below threshold Revise the plan — simplify design, reduce complexity, improve separation
NFR tag coverage incomplete Some NFR categories lack corresponding Gherkin tags Add @nfr-<category> tags to relevant scenarios in acceptance.feature

For governance that has drifted out of sync with your repo (rule globs matching nothing, CI/stack mismatches, stale baselines), run govkit doctor — it covers a different surface than validate.

Troubleshooting & FAQ

Q: govkit: command not found after installation A: Ensure your Python scripts directory is on your PATH. Try python -m cli.govkit as a fallback, or reinstall with pip install --user govkit.

Q: govkit apply fails with "no agent found" A: Check that you're using a valid agent name (claude-code, copilot, or codex). Run govkit list to see available agents.

Q: The agent ignores my architecture rules A: Verify the rules files were copied to the correct location (.claude/rules/govkit/, .github/instructions/govkit/, or the nested AGENTS.md managed blocks for Codex). Run govkit doctor — its D001 check flags any rule whose path globs resolve to zero files in your repo, which is the most common cause. (D001 scans the rules directory recursively, so it validates govkit's govkit/ rules and any of your own.) Claude Code loads rules based on the file path you're editing; Codex walks the directory tree from repo root down to the current working directory and concatenates each AGENTS.md it finds.

Q: How do I update to a newer version of govkit? A: Run pip install --upgrade govkit, then govkit upgrade --target . to refresh govkit-owned files without touching your customized contracts. See Keeping contracts up to date.

Q: Can I use govkit on an existing project with existing code? A: Yes. govkit apply copies governance artifacts into your project without modifying existing code. Then run govkit calibrate to align ARCH_CONTRACT.md and the other contracts with your existing architecture rather than the defaults.

Q: What if my architecture doesn't match the Hexagonal defaults? A: Customize the architecture docs after install (calibrate's "Architecture boundaries" step walks you through it). The agent follows whatever BOUNDARIES.md / ARCH_CONTRACT.md say — if your project uses clean or layered architecture, document it there. Consider creating an ADR explaining the architectural choice.

Q: Can I use multiple agents in the same project? A: Yes. Run govkit apply once for each agent. They install to different paths (.claude/, .github/, and AGENTS.md + .agents/ for Codex) and share the same docs/, governance/, and features/ artifacts. All agents read the same architecture contracts.

Q: How do I add a new NFR category? A: Add the category as a ## Heading in your feature's nfrs.md, add corresponding @nfr-<category> tags to acceptance scenarios, and update cli/validate.py's category_to_tag mapping if you want automated tag coverage validation.

Q: The CI pipeline fails because SonarQube/Snyk isn't configured A: These tools are optional. If your team doesn't use them, remove or comment out those jobs from the CI pipeline files. See ci/README.md for details on required secrets.

Q: What does "thresholds_met: false" mean in my plan? A: Your predicted FIRST or Virtue average is below 4.0, or a predicted accessibility violation count is above zero. Revise the plan — simplify the design, improve test strategy, or split large increments before proceeding.

Architecture Reference

The files linked below are installed into your project by govkit apply. Links point to their source in the govkit repository for reference.

Backend (Core — Level 4)

LLM Application Extension (Optional — Level 5)

Skill-Oriented Agent Architecture Extension (Optional — Level 5)

Backend (Optional Product Implementation Guides — Level 5)

These guides map concrete products to the provider-neutral llm-application ports. They are examples, not architecture mandates.

UI (Shared)

React UI

Angular UI

Data (Core — Level 4)

Data (Stack overlay — python-dbt)

Data (Stack overlay — databricks-lakehouse)

Evaluation Reference

Standards (All Levels)

Schemas

UI Evaluation

Evaluation by Level

Level What's Evaluated Tools
L3 Architecture-boundary compliance + commit format + lint/security (codebase-wide; no per-feature artifacts) l3-quality-gate.yml (import-linter + sonar/snyk + commit-format)
L4 L3 + spec completeness, Gherkin structure, NFR coverage, FIRST + 7 Virtue scores, eval_criteria schema govkit validate + quality-gate.yml + eval-gate.yml
L5 L4 + declared model quality, adversarial, retrieval, guardrail, operational, and agent-topology evidence govkit validate plus the configured evaluator/guardrail gates; bundled product-profile gates remain available

Getting Help

License

Copyright 2026 Accelerated Innovation

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Glossary

Term Definition
Agent The AI coding tool (Claude Code, GitHub Copilot, or OpenAI Codex) that reads governance artifacts and generates code
Rule (Claude Code) A path-scoped .md file in .claude/rules/ that loads automatically when editing files matching its path
Skill (Claude Code) A reusable prompt in .claude/skills/ invoked via slash command (e.g., /govkit-architecture-preflight)
Instruction (Copilot) A path-scoped .md file in .github/instructions/ — Copilot equivalent of a rule
Skill (Copilot) A reusable task in .github/skills/ invoked via slash command — open agent skills standard
AGENTS.md (Codex) A markdown instructions file read by Codex. A root AGENTS.md applies globally; nested AGENTS.md files at layer directories scope rules to that subtree via directory walk
Skill (Codex) A SKILL.md under .agents/skills/<name>/ invoked via $skill-name
Marker (.govkit) The marker directory/file written by govkit apply recording agent, level, type, stack, CI, assumptions, and calibration decisions so later commands auto-detect your configuration
govkit calibrate Guided 9-step review that aligns the installed generic defaults with your actual repo and records the decisions in the marker
govkit doctor Read-only governance-fit validator (rule globs, CI/stack/language match, stale baselines, extension manifests); complements govkit validate
govkit validate CLI command that checks all features for governance compliance (artifact completeness, thresholds)
Port An interface defining a contract between layers (inbound ports for API entry, outbound ports for infrastructure)
Adapter An implementation of a port that connects to infrastructure (database, external API, message queue)
Domain Business logic that has no dependencies on frameworks or infrastructure
FIRST Test quality framework — Fast, Isolated, Repeatable, Self-verifying, Timely (scored 1–5)
7 Virtues Code quality framework — Working, Unique, Simple, Clear, Easy, Developed, Brief (scored 1–5)
ADR Architecture Decision Record — documents and gates architectural changes
NFR Non-Functional Requirement — performance, security, availability, etc.
Evaluation Prediction Predicted FIRST and Virtue scores in plan.md — must average >= 4.0 before implementation
Extension An optional, self-describing pack under extensions/<id>/ that layers extra contracts/templates onto the core kit; install with govkit extension add or vendor the folder directly
/govkit-architecture-preflight Agent skill that validates a feature against architecture contracts before planning ($govkit-architecture-preflight in Codex)
/govkit-genai-preflight L5 agent skill that loads the llm-application manifest and validates provider-neutral gateway, observability, guardrail, and evaluation decisions ($govkit-genai-preflight in Codex)
/govkit-eval-suite-planning L5 agent skill that plans versioned evaluation subjects, datasets, oracles, slices, thresholds, and evidence for configured evaluator adapters ($govkit-eval-suite-planning in Codex)
LiteLLM Gateway option documented by the bundled implementation profile; not required by the llm-application contract
OpenLLMetry Model instrumentation option documented by the bundled implementation profile
Langfuse Telemetry and prompt-management option documented by the bundled implementation profile
DeepEval Model-quality evaluator option documented by the bundled implementation profile
Promptfoo Adversarial and regression evaluator option documented by the bundled implementation profile
RAGAS Retrieval evaluator option documented by the bundled implementation profile
NeMo Guardrails Behavioral-safety adapter option documented by the bundled implementation profile
Guardrails AI Structured-output validator option documented by the bundled implementation profile

About

Governed AI Delivery (GovKit) is an open source toolkit for spec-driven, evaluation-aware AI-assisted software delivery.

Topics

open-source evaluation developer-tools governance codex software-delivery github-copilot ai-coding claude-code spec-driven-development spec-kit

Resources

Readme

License

View license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

20 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 9

govkit 0.13.0 Latest
Jun 7, 2026
+ 8 releases

Packages

 
 
 

Contributors

Languages