Skip to main content

Governed Agent SDLC

Ship with agents. Keep humans in control.

Validate PyPI PyPI downloads Python 3.11+ MIT License Official vannt-dev build

Project website · Architecture · Workflow · CLI reference · Adoption guide

Governed Agent SDLC keeps one workflow policy for four AI coding agents: Claude Code, Codex, OpenCode and Antigravity. The roles, artifact lifecycle, approval rules and protected areas live in a tool-neutral core and one project manifest, and agentkit generate turns them into each agent's own configuration; none of them keeps a parallel policy file. Stack profiles supply each stack's commands and exclusions. Maturity says which guards each agent enforces.

Human approvals can be checked against GitHub. With [review].approval_mode = "github" (or --approval-mode github on an artifact transition), agentkit artifact transition ... approved and agentkit review approve accept an approval only when its evidence is a pull request review (or, for an artifact, an issue or pull request comment) in this repository, written by a human owner, member or collaborator, as looked up through gh. In the default local mode an approval is recorded as given and marked unverified.

The project is intentionally human-in-the-loop. It helps agents work predictably; it does not grant an AI permission to approve, merge, release, or retrieve credentials.

Alpha status: the core workflow, the Claude Code, Codex, OpenCode and Antigravity adapters, deterministic safety hooks, cross-platform validation, and PyPI Trusted Publishing are available. Interfaces may still evolve before 1.0.

What is included

  • Six tool-neutral roles: architect, planner, developer, reviewer, QA, and publisher.
  • A structured artifact lifecycle with explicit approval evidence and supersession.
  • A TOML project manifest for repository layout, profiles, commands, and protected areas.
  • A dependency-free Python CLI: init, generate, update-hooks, upgrade, validate, doctor, and artifact commands.
  • Claude Code agent generation and safety hooks.
  • Native Codex project configuration and governed role generation.
  • OpenCode subagents with a guard plugin, and Antigravity agents with a guard hook (OpenCode adapter, Antigravity adapter).
  • Stack profiles for generic repositories, Python, .NET, Nuxt, Node.js and TypeScript, Java (Spring Boot on Maven), Flutter, Go, Rust, Kotlin (Gradle), and PHP (Composer).
  • Cross-platform tests and reusable GitHub Actions.

Quick start

Requires Python 3.11 or newer. Install the published package:

python -m pip install governed-agent-sdlc
agentkit --version
agentkit doctor

Upgrade an existing installation to this release:

python -m pip install --upgrade governed-agent-sdlc==0.9.0
agentkit --version
agentkit upgrade --dry-run
agentkit upgrade
agentkit doctor

Version 0.9.0 adds agentkit upgrade, which brings the guards under hooks/ and the files of every adapter in use up to what the installed version writes, guards first, and replaces running update-hooks and generate <adapter> --force by hand. agentkit doctor now reports those files and exits 1 when one is outdated or missing. Upgrading the Python package does not change a project, so run upgrade after it, and commit .agent/generated.json with the files. A project set up by 0.8.0 or earlier has no record of what was generated, so a file that differs from what this version writes, such as a guard edited by hand, is reported as of unknown origin and kept. If doctor lists one, run agentkit upgrade --force to replace it and re-apply any edits of your own (git diff shows them); from then on the record tells an older file from an edited one. See release notes for the full changes.

For local development:

python -m pip install -e .
agentkit doctor
agentkit validate
python -m unittest discover -s tests -v

Initialize another project:

agentkit init ../my-project --name my-project --adapter claude-code
cd ../my-project
agentkit doctor

Use --format json with validate, doctor, generation, migration, and artifact inspection commands for automation. Preview additive initialization or adapter generation with --dry-run.

Initialization is additive: existing AGENTS.md, manifest, core policy, hook, and adapter files are not overwritten. A fresh project receives the stack profiles and a minimal AGENTS.md so generated roles always have the instructions they reference.

agentkit doctor also compares the guards under hooks/ and the files of each adapter in use with what the installed version writes, and exits 1 when one is outdated or missing, so CI can catch a project left behind by a package upgrade; a file that differs without a record only warns. agentkit upgrade rewrites those files and keeps the ones edited by hand unless --force is given; --dry-run shows what it would change. Generated files are recorded by hash in .agent/generated.json; commit it with them. See the CLI reference.

Name the stack when you initialize, and the manifest starts with its profile and its commands instead of the generic one:

agentkit init my-service --profile java
agentkit init my-app --profile flutter --profile node   # several: the first to name a command wins

The profiles are generic, python, dotnet, nuxt, node, java, flutter, go, rust, kotlin and php. The commands a profile gives are a starting point written into [commands] of the manifest: a Gradle project replaces the Maven ones of java, and flutter names no build because which artefact to build is the project's to say. kotlin runs ./gradlew check, which runs ktlint or detekt only when the build applies them, and php names composer validate and PHPUnit; a project using PHPStan or PHP CS Fixer adds those commands. The go format check is a POSIX shell line, because gofmt -l lists files without failing.

Create and move a governed artifact:

agentkit artifact new spec add-search
agentkit artifact transition docs/agent/specs/<file>.md awaiting_approval
agentkit artifact transition docs/agent/specs/<file>.md approved \
  --approved-by "github:maintainer" \
  --evidence "https://github.com/org/repo/issues/123#issuecomment-..."

An agent must never supply approval metadata for itself. The human supplies the actor and durable evidence, and CI validates that the fields exist. By default ([review].approval_mode = "local", as for review approve) the approval is recorded as given and marked verification = "unverified". With approval_mode = "github", or --approval-mode github on the command, the CLI checks through gh that the review or comment URL is in this repository and was written by a human collaborator, and records that login (github:LOGIN) as the approver; see artifact approval verification.

Project manifest

agentkit.toml or .agent/project.toml is the source of truth:

version = 1
protected_areas = ["authentication", "database-schema", "billing"]

[project]
name = "commerce"
topology = "monorepo"

[[repositories]]
id = "backend"
path = "services/api"
profiles = ["dotnet"]

[[repositories]]
id = "frontend"
path = "apps/web"
profiles = ["nuxt"]

[workflow]
require_spec = true
require_plan = true
require_review = true
require_qa = true

Repository paths are resolved from the manifest and must remain inside the project root. No machine or user-specific absolute path belongs in committed configuration.

Validation is strict and dependency-free. It rejects unsupported manifest versions and topology, missing workflow flags, invalid field types, duplicate repository identities or paths, escaping repository paths, and profile capabilities that are not provided by profiles/, adapters/, or the repository's GitHub integration.

Artifact validation also checks kind-specific parent gates, approval history for approved/active/ completed/superseded states, repository and protected-area references, timestamps, supersession, and metadata types. Artifact creation refuses filename collisions. Transitions made through the CLI are restricted to Markdown files below the active project's docs/agent/ directory.

Design boundaries

  • core/ is vendor-neutral and is the only source of workflow meaning.
  • profiles/ contain stack-specific commands and exclusions.
  • adapters/ and generated tool files translate the core; they do not redefine it.
  • hooks/ enforce deterministic safety rules. Prompts explain behavior but are not security controls.
  • Hook input is fail-closed: malformed input is denied, as are credential paths/environment dumps, force pushes, and direct protected-branch refspecs.
  • Hooks also hold the workflow: a role is spawned only from artifacts that passed their gate, and a role that does not own a task file may change only its completion evidence.
  • docs/agent/ holds project artifacts, not hidden agent memory.

See Architecture, Workflow, and Adopting Governed Agent SDLC.

Maturity

The project is an alpha. Claude Code, Codex, OpenCode and Antigravity consume the same core contracts rather than introducing parallel policy files. The credential and git guards hold on all four; the role write scope and the role gate are enforced on Claude Code only, because only its hook input says which role is acting.

See CHANGELOG.md for release history and upgrade notes.

License

MIT. See LICENSE.

Metadata

Release files for governed-agent-sdlc 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for governed-agent-sdlc 0.9.0
File Size Uploaded Provenance Actions
governed_agent_sdlc-0.9.0.tar.gz 211.7 kB With provenance Details for governed_agent_sdlc-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for governed-agent-sdlc 0.9.0
File Interpreter ABI Platform Actions
governed_agent_sdlc-0.9.0-py3-none-any.whl Python 3 none any Details for governed_agent_sdlc-0.9.0-py3-none-any.whl

Total release size: 315.3 kB

Release files / governed_agent_sdlc-0.9.0.tar.gz

Download URL governed_agent_sdlc-0.9.0.tar.gz
Size 211.7 kB
Tags Source
SHA-256 checksum
How to use checksums
b5e77e2ce18d599e6d241df49f5e028acbec029751e3c4092ad7699300544399
BLAKE2b-256 checksum
How to use checksums
01a86cd3ebb00e5dec5bdc13ca2b6a2008614e978a608e3bc20c273628cad249
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / governed_agent_sdlc-0.9.0-py3-none-any.whl

Download URL governed_agent_sdlc-0.9.0-py3-none-any.whl
Size 103.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cff94c0f67d3a6c64adc800a6f0d208021bd0487823c31133a294b62067aaf9a
BLAKE2b-256 checksum
How to use checksums
3cebb9c83a40f87b210aa49b39213d8509ff333f94b2f4f173b123584e7a13d0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for governed-agent-sdlc 0.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for governed_agent_sdlc-0.9.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page