Metadata-Version: 2.4
Name: agentcharter
Version: 0.0.1a0
Summary: Agent-neutral policy-engineering framework
Author: Open Coder AI
License: Apache-2.0
Project-URL: Homepage, https://github.com/open-coder-ai/agentcharter
Project-URL: Repository, https://github.com/open-coder-ai/agentcharter
Project-URL: Issues, https://github.com/open-coder-ai/agentcharter/issues
Project-URL: Documentation, https://github.com/open-coder-ai/agentcharter/blob/main/docs/README.md
Keywords: ai,agents,governance,policy,guardrails,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: jsonschema<5,>=4.18
Requires-Dist: referencing<0.38,>=0.35
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-bdd>=8.0; extra == "dev"
Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
Provides-Extra: build
Requires-Dist: build>=1.0; extra == "build"
Requires-Dist: pyinstaller>=6.0; extra == "build"
Dynamic: license-file

<div align="center">

# ⚓ Agent Charter

### Governance-as-code for AI coding agents. Write it once — enforce it everywhere.

Turn your team's rules into **deterministic guardrails** that every AI coding agent — Claude Code, Copilot, Cursor, Codex, Gemini, Aider — actually obeys. Not prose it can ignore. Real enforcement, on git hooks, CI, and each agent's native controls.

<!-- 🎬 Hero demo — render docs/assets/demo.tape with `vhs`, then uncomment:
<img src="docs/assets/demo.gif" alt="agentcharter init, then a blocked commit to main and a successful feature-branch commit" width="760">
-->

[![CI](https://github.com/open-coder-ai/agentcharter/actions/workflows/ci.yml/badge.svg)](https://github.com/open-coder-ai/agentcharter/actions/workflows/ci.yml)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
[![Status: Early Access](https://img.shields.io/badge/status-v0.0.1%20early%20access-orange.svg)](#-roadmap)

[Quick Start](#-quick-start-3-commands) · [How it works](#-how-it-works) · [Docs](docs/README.md) · [Contribute](CONTRIBUTING.md) · [Roadmap](#-roadmap)

</div>

---

## 🎯 The Problem & The Solution

Your team now runs **five different AI coding agents**, each with its own config file and its own idea of "the rules." You write "don't force-push to `main`" in a `CLAUDE.md`, a `.cursorrules`, and a `copilot-instructions.md`… and the agent ignores it anyway, because prose is a *suggestion*, not a *control*.

| Without Agent Charter | With Agent Charter |
| :--- | :--- |
| Rules copy-pasted into N agent config files | **One policy**, authored once |
| Prose guidance the agent can ignore | **Deterministic enforcement** (exit-code guards) |
| Different behavior per agent | **Compiled to each agent's native surface** |
| "Did the AI follow policy?" — unknowable | **Per-agent coverage report + evals** |

Agent Charter is a **policy-as-code framework**: you author a rule, hook, or skill once, and it compiles to the *real* enforcement surface of every agent — **git hooks, CI gates, Claude PreToolUse, and `AGENTS.md` rules** — validated and version-locked.

## 🔭 How It Works

<div align="center">
  <img src="docs/assets/architecture.svg" alt="Author a policy once, compile it, and enforce it on every agent's native surface." width="820">
</div>

You author a policy once. The compiler emits the strongest control each agent supports and reports the exact coverage — *enforced*, *enforced-at-commit*, or *advisory* — so you always know where a guarantee holds. Read the full [architecture overview](docs/architecture.md).

## ✨ Key Features

- **✍️ Author once, enforce everywhere** — one policy → git-hook + CI gate + Claude PreToolUse + `AGENTS.md`, across 13 agents including Claude Code, Copilot, Cursor, Codex, Gemini, Aider and Windsurf. The CI gate is opt-in (`agentcharter install-ci`) and [the coverage report only credits it once it is wired up](docs/enforcement-surfaces.md).
- **🛡️ Real guardrails, one command away** — `agentcharter add protect-main-branch` pulls from the [catalog](https://github.com/open-coder-ai/agentcharter-catalog): `block-destructive-commands`, `scan-secrets`, `block-no-verify`, plus advisory rules (`code-safety`, `git-safety`, `token-efficiency`). Installed content is yours to edit.
- **⚙️ Deterministic, not vibes** — gates are declarative and run through a stdlib-only vendored runner; guard scripts are plain bash. No LLM calls, no network, and every policy carries an eval suite replayed against its own mechanism on each build.
- **✅ Trust, but verify** — a validation engine, an artifact registry, a hash-pinned `agentcharter.lock`, and an eval suite (with adversarial cases) for every policy.
- **📊 Coverage you can prove** — `compile` emits a per-agent report: *enforced* / *enforced-at-commit* / *advisory* — the foundation for compliance attestation.
- **📦 Speaks the open packaging standard** — `agentcharter plugin build` emits [Agent Plugins 1.0.0](https://agent-plugins.org) packages, so any conformant client can *read* a policy. None of them can enforce it — that part is ours. [What the badge does and does not mean](docs/agent-plugins.md).
- **🧩 One CLI** — `init`, `add`, `recompile`, `validate`, `eval`, `compile`, `registry`, `plugin`, `verify`, `new`, `refresh`, `install-hooks`, `install-ci`, `install-skills`, `policies`, `disable`, `enable`, `check-matrix`, `compliance`. `agentcharter --help` prints the list from the code, so that one cannot drift.

## 🎯 What it covers today

Agent Charter is a **craft and enforcement framework first, and a security framework second** — and that is worth saying plainly, because the two get marketed as the same thing.

The mechanism is genuinely deterministic: gates block commits, and the coverage report tells you exactly where. But most of the baseline catalog — `yagni`, `token-efficiency`, `context-hygiene`, `agent-discipline`, `memory-discipline` — are coding-discipline and token-economy rules, not security controls. The security-shaped ones are a minority: `scan-secrets`, `protect-main-branch`, `block-destructive-commands`, `block-no-verify`.

Against the OWASP Top 10 for Agentic Applications (ASI01–ASI10), that comes to **3 partial of 10, and 0 fully covered**. You do not have to take our word for it:

```bash
agentcharter compliance report --framework owasp_asi
```

It prints the same table we would, including every `uncovered` row. Closing that gap is the roadmap's priority; overstating it in the meantime would cost more than the gap does.

## 🚀 Quick Start (3 commands)

> **Requires:** Python 3.11+ and git. Installed git hooks need bash at runtime.
> **Early access:** not yet on PyPI — install from source while `v0.0.1` stabilises.

```bash
# 1. Install
pip install git+https://github.com/open-coder-ai/agentcharter

# 2. Scaffold your repo — wiring and authoring skills, no opinions
cd /path/to/your/project
agentcharter init .

# 3. Adopt a policy, compiled and ready
agentcharter add protect-main-branch
agentcharter install-hooks .
```

`init` deliberately installs **no policies**. The framework ships mechanism; policies are content you
choose, and once installed they are **yours to edit** — nothing overwrites them. That is what makes
customisation possible at all.

> **`agentcharter` not found?** Your Python scripts dir may not be on `PATH`. Use `python -m agentcharter …` — it works regardless of PATH.

**Now watch it enforce.**

```bash
git checkout main                     # or master — whichever your default branch is
echo "oops" > hotfix.txt && git add hotfix.txt
git commit -m "quick fix straight to main"
# ❌ Direct commits/pushes to a protected branch (main|master) are blocked.
#    Create a feature branch and open a pull request.
#      - main

git checkout -b feature/x
git commit -m "on a feature branch"   # ✅ allowed
```

That branch list is resolved from the gate, not hard-coded: point
`agentcharter.defaults.protected_branches` at `[main, master, release/*]` and the message says so.

That block came from a **deterministic git hook**, compiled from the same policy that also produced
your agents' native controls. New here? Follow the [Getting Started guide](docs/getting-started.md).

## 📋 Basic Usage Example

Author your own guard and compile it to every agent:

```bash
# Scaffold a new policy (manifest + gate + evals)
agentcharter new policy block-console-log

# Validate every artifact against the spec
agentcharter validate .

# Compile it to each agent's enforcement surface + a coverage report
agentcharter compile block-console-log
```

A policy is just a small, reviewable manifest:

```yaml
# .agents/policies/block-console-log/manifest.yaml
id: block-console-log
name: "No console.log in committed code"
artifact: hook
enforcement: block
effects: [read_only]
description: >
  Block staged JS/TS changes that add console.log — keep debug noise out of main.
```

## 📚 Documentation

Full developer documentation lives in [`docs/`](docs/README.md):

| Guide | What's inside |
| :--- | :--- |
| [Getting Started](docs/getting-started.md) | Install, onboard a repo, author your first policy |
| [Architecture](docs/architecture.md) | The author → compile → enforce model |
| [Core Concepts](docs/concepts.md) | Artifacts, manifests, surfaces, coverage, registry |
| [CLI Reference](docs/cli-reference.md) | Every command, flag, and example |
| [Authoring Policies](docs/authoring-policies.md) | Rules, hooks, skills, subagents |
| [Enforcement Surfaces](docs/enforcement-surfaces.md) | The six surfaces + per-agent coverage matrix |
| [Validation](docs/validation.md) | The validation engine and checks |
| [Registry & Lockfile](docs/registry-and-lockfile.md) | Reproducible, hash-pinned distribution |
| [Evals](docs/evals.md) | Testing policies with adversarial cases |
| [Policies](docs/baseline-policies.md) | What the catalog offers, and how to install and customise it |
| [Adapters](docs/adapters/README.md) | Per-agent wrapper notes |

## 🗺️ Roadmap

We're building in the open. Next up:

- [x] **`agentcharter add <id>`** — install a policy or skill from any catalog, public or private.
- [x] **CI backstop** — `agentcharter install-ci` plus a commit-range gate mode, so a hook skipped with `--no-verify` is still caught on a pull request.
- [ ] **Publish** — PyPI package and signed standalone binaries.
- [ ] **Upgrades** — `agentcharter upgrade`, three-way merge against a pinned `agentcharter.lock`.
- [ ] **Supply-chain & MCP packs** — block hallucinated ("slopsquatted") dependencies and un-approved MCP tools.
- [ ] **Cost & autonomy governance** — token/spend circuit-breakers and human-in-the-loop approval tiers.
- [ ] **Compliance attestation** — `agentcharter attest` mapping controls to NIST AI RMF, ISO 42001 & the EU AI Act.

See the [open issues](https://github.com/open-coder-ai/agentcharter/issues) and [good first issues](https://github.com/open-coder-ai/agentcharter/labels/good%20first%20issue) to jump in.

## 🤝 Contributing

We'd love your help — **code and non-code contributions alike**. Docs fixes, bug reports, and new policy ideas are all first-class. Start with the [Contributing Guide](CONTRIBUTING.md) and look for [`good first issue`](https://github.com/open-coder-ai/agentcharter/labels/good%20first%20issue).

## ⭐ Star History

If Agent Charter saves you from one bad `--force` push, **[drop a star](https://github.com/open-coder-ai/agentcharter)** — it's the single biggest signal that helps other teams find the project and keeps development moving.

<a href="https://star-history.com/#open-coder-ai/agentcharter&Date">
  <img src="https://api.star-history.com/svg?repos=open-coder-ai/agentcharter&type=Date" alt="Star History Chart" width="600">
</a>

## 📄 License

Apache-2.0 — see [LICENSE](LICENSE). Built by and for teams shipping with AI agents.
