Metadata-Version: 2.5
Name: governed-agent-sdlc
Version: 0.1.0
Summary: A governed, cross-platform SDLC toolkit for AI coding agents.
Author: Governed Agent SDLC Contributors
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown

<div align="center">

# Governed Agent SDLC

**Ship with agents. Keep humans in control.**

[![Validate](https://github.com/vannt-dev/governed-agent-sdlc/actions/workflows/validate.yml/badge.svg)](https://github.com/vannt-dev/governed-agent-sdlc/actions/workflows/validate.yml)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-0b7771)](https://www.python.org/)
[![MIT License](https://img.shields.io/badge/License-MIT-f06f4f.svg)](LICENSE)

[Project website](https://vannt-dev.github.io/governed-agent-sdlc/) · [Architecture](docs/architecture.md) · [Workflow](docs/workflow.md) · [Adoption guide](docs/adoption.md)

</div>

Governed Agent SDLC is a cross-platform toolkit for AI coding agents. It separates a
tool-neutral workflow kernel from project profiles and vendor adapters, so the same approval,
security, artifact, review, and QA rules can be applied to different technology stacks.

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.

> **MVP status:** the core workflow, Claude Code adapter, deterministic safety hooks, and
> cross-platform validation are available. Package publication and additional vendor adapters are
> intentionally future work.

## 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`, `validate`, `doctor`, and artifact commands.
- Claude Code agent generation and safety hooks.
- Stack profiles for generic repositories, Python, .NET, and Nuxt.
- Cross-platform tests and reusable GitHub Actions.

## Quick start

Requires Python 3.11 or newer. From this repository:

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

Initialize another project:

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

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

Create and move a governed artifact:

```bash
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.

## Project manifest

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

```toml
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.
- `docs/agent/` holds project artifacts, not hidden agent memory.

See [Architecture](docs/architecture.md), [Workflow](docs/workflow.md), and
[Adopting Governed Agent SDLC](docs/adoption.md).

## Maturity

Version 0.1.0 is an MVP. Claude Code is the first adapter. Codex and other adapters should consume
the same core contracts rather than introduce parallel policy files.

## License

MIT. See [LICENSE](LICENSE).
