gzkit
GovZero Kit: A Development Covenant for Human-AI Collaboration
Documentation Release Notes Roadmap
gzkit is cognitive infrastructure for extended human-AI collaboration-a protocol that preserves human intent across agent context boundaries, gives agents constraints to reason against, creates verification loops both parties trust, and reserves final judgment for humans.
Why gzkit?
Modern AI-assisted development faces a structural problem: agents are powerful but context-bound. They drift without constraints, forget across sessions, and can't distinguish between "should do" and "could do." Humans provide intent and judgment but can't scale execution.
gzkit bridges this gap by formalizing the collaboration:
| Role | Human | Agent |
|---|---|---|
| Intent | Originates | Interprets, clarifies |
| Constraints | Defines, enforces | Operates within, flags violations |
| Exploration | Guides | Executes, surfaces options |
| Judgment | Final authority | Proposes, explains tradeoffs |
| Memory | Long-term, cross-project | Session-bound, needs scaffolding |
| Verification | Attests | Generates evidence |
Three Concerns
gzkit spans three distinct but interrelated concerns:
| Concern | Purpose | Primary Audience |
|---|---|---|
| Specification | Invariants, constraints, acceptance criteria | Agent (grounding) |
| Methodology | Phases, workflows, checkpoints | Process (structure) |
| Governance | Authority, attestation, audit | Human (oversight) |
Specification is agent-native: explicit constraints, declarative intent, immutable canon.
Methodology is process-native: phases, gates, verification loops.
Governance is human-native: attestation rituals, authority boundaries, audit ceremonies.
All three are necessary. Specification without governance drifts. Governance without methodology is theater. Methodology without specification is arbitrary.
Boundary
gzkit is a governance meta-harness for governed human-AI work. It does not run agents: a vendor harness turns a model into an agent, and gzkit operates one tier up, wrapping agent harnesses such as Codex, Claude Code, Copilot, and adjacent tools with deterministic governance surfaces, evidence capture, gate enforcement, and human attestation.
gzkit is not a generic framework that asks humans to assemble arbitrary agent chains. It ships an opinionated covenant for deciding whether agent work is justified, verified, and complete. If gzkit grows a machine-readable workflow specification surface, its canonical form is JSON that describes gzkit stages, gate prerequisites, evidence requirements, and ledger events. Workflow specification should make the covenant more executable, not replace it with a YAML-style automation DSL.
The Covenant
gzkit implements a development covenant-a binding agreement between human and agent:
- Human defines intent through canon, ADRs, and acceptance criteria
- Agent operates within constraints and flags potential violations
- Verification is mutual through tests, checks, and evidence
- Human attests completion after observing artifacts
- Artifacts survive sessions preserving intent across context boundaries. Gzkit operates as a constitutional framework for human‑agent collaboration: humans serve as the Legislature (defining intent, constraints, and final judgment), agents act as the Executive (executing within bounds and generating evidence), and tests/BDD function as the Judiciary (verifying compliance and enforcing the constitution).
This is not "AI governance" in the compliance sense. It's a protocol for productive partnership.
Lineage
gzkit evolved from:
- GitHub spec-kit - the
constitute → specify → plan → implement → analyzephase model - GovZero - governance framework developed in AirlineOps through ~100 work items of iterative learning
- Claude Code conventions - CLAUDE.md patterns for agent-native constraint specification
See docs/lineage.md for full heritage.
Five Gates
Work flows through five gates, adapted by lane (Lite or Heavy):
| Gate | Name | Purpose |
|---|---|---|
| 1 | ADR | Record intent and tradeoffs before implementation |
| 2 | TDD | Red-Green-Refactor: tests derived from spec, not implementation |
| 3 | Docs | Ensure documentation describes actual behavior |
| 4 | BDD | Verify external contracts through acceptance tests |
| 5 | Human | Human observes artifacts and attests completion |
Lite lane (internal changes): Gates 1, 2
Heavy lane (external contracts): Gates 1, 2, 3, 4, 5
Workflow Lifecycle
DEFINE PLAN BUILD VERIFY ATTEST RELEASE
┌──────┐ ┌──────┐ ┌──────────┐ ┌──────┐ ┌──────┐ ┌──────────┐
│Design│───▶│ ADR │───▶│ Pipeline │───▶│Gates │───▶│Human │───▶│ Closeout │
│ PRD │ │ OBPI │ │ TDD Impl │ │Check │ │Attest│ │ Release │
└──────┘ └──────┘ └──────────┘ └──────┘ └──────┘ └──────────┘
gz-design gz-adr- gz-obpi- gz-check gz-adr- gz-patch-
gz-prd create pipeline gz-gates closeout- release
gz-obpi- gz-obpi- gz-validate ceremony
specify simplify
Skill Catalog
| Category | Skills |
|---|---|
| ADR Lifecycle | gz-adr-create, gz-adr-evaluate, gz-adr-promote, gz-adr-status, gz-design, gz-plan |
| ADR Operations | gz-adr-emit-receipt, gz-adr-map, gz-adr-sync |
| ADR Audit & Closeout | gz-adr-audit, gz-adr-closeout-ceremony, gz-patch-release |
| OBPI Pipeline | gz-obpi-lock, gz-obpi-pipeline, gz-obpi-sync, gz-obpi-simplify, gz-obpi-specify, gz-plan-audit |
| Governance Infrastructure | gz-constitute, gz-implement, gz-init, gz-prd, gz-state, gz-status, gz-validate |
| Agent & Repository | git-sync, gz-agent-sync, gz-check-config-paths, gz-migrate-semver, gz-session-handoff, gz-skill-review, gz-tidy |
| Code Quality | gz-check, gz-chore-runner, gz-cli-audit |
| Routing | gz-how |
For details on any skill, read its SKILL.md in .gzkit/skills/<skill-name>/.
Installation
# Using uv (recommended)
uv tool install py-gzkit
# Or pip
pip install py-gzkit
Quick Start
# Initialize gzkit in a project
gz init
# Create a new ADR
gz plan create feature --title "Feature description"
# Check gate status
gz status
# Run verification
gz check
Configuration
gzkit uses .gzkit.json for project configuration:
{
"mode": "lite",
"paths": {
"canon": "docs/canon",
"adrs": "docs/adr",
"specs": "docs/specs"
}
}
Documentation
- Charter - The covenant itself
- Lineage - Heritage from spec-kit and GovZero
- Concepts - The three concerns explained
- Genesis - Origin story and founding conversation
Philosophy
Governance is verification, not celebration.
gzkit treats governance as executable documentation. All state lives in Markdown, validated by a Python CLI. The meta-harness is human-centric, auditable, and version-controlled.
Prompts are code. Constraints are first-class. Human attestation is the final gate.
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for py-gzkit 0.34.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| py_gzkit-0.34.9.tar.gz | 95.2 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| py_gzkit-0.34.9-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 98.2 MB
Release files / py_gzkit-0.34.9.tar.gz
| Download URL | py_gzkit-0.34.9.tar.gz |
|---|---|
| Size | 95.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6beebccb57692f2b0a1a2ce568af38e12cdfcd7136a7053680926c4966c94776
|
|
BLAKE2b-256 checksum How to use checksums |
e8ed23b0ab6b8ffa2f0b066893f30af48e6757ca51889e8c63a9205f6c92efd9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 11, 2026.
Transparency logRelease files / py_gzkit-0.34.9-py3-none-any.whl
| Download URL | py_gzkit-0.34.9-py3-none-any.whl |
|---|---|
| Size | 3.0 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2de31b7d804a1d0a18b53b2fd06b0f58dfee51265adf9df1342c261d9ba06aa4
|
|
BLAKE2b-256 checksum How to use checksums |
70f8c6dc53de517a12f6c146cb759311ed478b3f74b3658f73069833a459498f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 11, 2026.
Transparency log
