Metadata-Version: 2.4
Name: agenraci
Version: 0.1.0a0
Summary: Who's allowed to do what, and who's accountable, on a team of humans and AI agents: a machine-checkable RACI charter + linter.
Author: AgenRACI contributors
License: MIT
Project-URL: Homepage, https://github.com/jing-ny/agenraci
Project-URL: Repository, https://github.com/jing-ny/agenraci
Project-URL: Issues, https://github.com/jing-ny/agenraci/issues
Keywords: ai-agents,raci,governance,rbac,accountability,charter
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.6
Requires-Dist: typer>=0.12
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# AgenRACI — who's allowed to do what, and who's accountable, on a team of humans and AI agents

[![CI](https://github.com/jing-ny/agenraci/actions/workflows/ci.yml/badge.svg)](https://github.com/jing-ny/agenraci/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/agenraci.svg)](https://pypi.org/project/agenraci/)
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> When an AI agent does something on your team — ships code, sends a message,
> spends money — and no human pressed the button, **who is accountable?**
> AgenRACI is one plain-language file that answers that up front, for every kind
> of action: who may do it, who signs off, and who owns the outcome.

For decades, teams have used **RACI** — a simple chart of who is *Responsible,
Accountable, Consulted, and Informed* for each kind of work. RACI quietly assumes
a person starts every task. AI agents break that assumption: they can act on
their own, but someone human must still answer for what they do.

**AgenRACI brings RACI into the age of AI agents.** You write one file — a
*charter* — that lists, for each type of action on your team:

- who **does** it (Responsible),
- who is **accountable** (exactly one person or role),
- who must be **consulted** or kept **informed**,
- who has to **approve** it first, and
- what happens if the one who should act is **unavailable**.

A built-in checker reads the charter and flags the gaps before they bite: an
action with no one accountable, two people who both think they're in charge, or
an approval step that could quietly stall forever.

```bash
pip install agenraci
agenraci init                    # writes a commented charter.yaml to edit
agenraci validate charter.yaml   # check it holds together
```

Cloned the repo instead? Validate a bundled example directly:
`agenraci validate examples/sprout/charter.yaml`.

Prefer to try it without installing? A **paste-and-check playground** runs the
real checker in your browser (nothing uploaded) — see
[`docs/playground/`](docs/playground/).

New here? Start with the essay: [**Why AgenRACI**](docs/why-agenraci.md) — the
accountability gap, why classic RACI breaks under agentic AI, and how this fits
ISO/IEC 42001 and the EU AI Act.

## See it catch a gap

A charter where two roles both think they're accountable for shipping code — the
checker catches it (rule **R1**), and the one-line fix passes:

![AgenRACI catching a two-accountable conflict, then passing once fixed](docs/demo/demo.gif)

```text
$ agenraci validate docs/demo/charter-broken.yaml
✗ R1 single accountable
    - A2_ship_code: has 2 accountable roles (builder, reviewer) — exactly one is required.
FAIL — 1 issue(s) found.

$ agenraci validate docs/demo/charter-fixed.yaml
✓ R1 single accountable
PASS — charter is a valid operating constitution.
```

Full walkthrough + a recordable GIF script: [`docs/demo/`](docs/demo/).

## What AgenRACI is (and isn't) yet

**Today, AgenRACI helps you write the charter and checks that it holds together.**
You get:

- a clear format for the charter file,
- an automatic checker that catches gaps, conflicts, and approval steps that could
  deadlock,
- a worked example and a blank template to start from.

**AgenRACI does not run your team — yet.** It doesn't (today) intercept actions or
enforce approvals at the moment they happen. Tools like LangGraph, CrewAI, and
HumanLayer already handle *running* agents and pausing them for sign-off. AgenRACI
sits one level up and answers what they don't: *on this specific team, who is
allowed to do what, and who breaks a tie.* Turning the charter into live, enforced
approvals is the next milestone on the roadmap — not a claim about today.

## The gap we fill

Today, RACI is mostly applied at the *governance* level — the boardroom and
compliance question of "who answers for the AI system as a whole" (the concern
behind standards like ISO/IEC 42001 and the EU AI Act). What's missing is the
*operating* level: a precise, machine-checkable charter for the day-to-day, where
the AI agents themselves hold real roles and the rules can be verified by a tool
instead of living in a slide deck. That everyday accountability — for the exact
moment an agent acts on its own — is what AgenRACI covers.

## The core model (three independent questions)

Most "who does what" confusion comes from mixing up three different questions.
AgenRACI keeps them separate:

| Question        | What it asks                      | Example |
|-----------------|-----------------------------------|---------|
| **Function**    | What do you *do*?                 | Orchestrate, Build, Advise, Investigate, Review, Watch |
| **Permission**  | What may you *touch*?             | `edit_code`, `merge`, `deploy`, `spend`, … granted **or explicitly denied** |
| **Authority**   | Whose call *wins* in a conflict?  | Each action's `accountable`, plus gate `escalate_to` for timeouts |

The proof they're separate: a **domain expert can be _accountable_ for a fact,
_denied_ the right to touch code, yet able to _block_ a merge on correctness
grounds** — all at once, none implying the others.

### Roles are defined once; members are assigned

You don't rewrite the rules for every agent. Define a small **set of roles**
(orchestrator, engineer, domain expert, researcher, reviewer, monitor) once, then
*assign* humans and agents to them. Adding an agent is a one-line appointment, not
a new rulebook.

### One accountable per action — no gaps, no turf wars

List the **types of action** in your project (not individual tasks), and require
each to have exactly one accountable role. Nobody accountable = a gap; two people
accountable = a turf war. The checker catches both.

### Escape hatches so the rules never deadlock

People aren't always online — and neither are agents. So every approval step must
say what happens on timeout (`block`, `escalate to someone`, or, only for
explicitly low-risk actions, `proceed`), and must have a `break_glass` emergency
path. Any blocked-but-confident actor gets a `suggestion_route` so their input
isn't silently dropped. `proceed` on timeout is a guarded opt-in — allowed only on
an action explicitly marked low-risk — so "low risk" can never become a quiet
backdoor for an agent to act unsupervised.

## The checker (v0.1)

| Rule | Checks |
|------|--------|
| **R1** | single accountable — every action type has exactly one `accountable` |
| **R2** | coverage — no unused permissions; no action uses an undeclared permission |
| **R3** | no contradiction — no role both grants and denies the same permission |
| **R4** | gate completeness — every approval step has a timeout rule + emergency path; every blocking `deny` has a `suggestion_route` |
| **R5** | low-risk gating — `proceed` on timeout only on an action marked low-risk |
| **R6** | acyclic authority — gate `escalate_to` timeouts never form a loop, so a decision can't escalate forever without anyone able to settle it |

## CLI

```bash
agenraci init [path]                             # write a commented starter charter (default: charter.yaml)
agenraci validate <charter.yaml> [more.yaml...]  # parse + check, with a per-rule report
agenraci validate --explain <charter.yaml>       # ...and a plain-language fix under each failure
agenraci compile --target humanlayer <charter>   # placeholder in v0.1
agenraci compile --target langgraph  <charter>   # placeholder in v0.1
```

## Keep the charter honest in CI

A charter only protects you if it stays valid as it changes. Two ways to enforce
that automatically:

**GitHub Action** — fail a PR that breaks the charter:

```yaml
# .github/workflows/charter.yml
on: [push, pull_request]
jobs:
  charter:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jing-ny/agenraci@v0.1.0
        with:
          charter: charter.yaml      # a path, or a glob like 'governance/*.yaml'
```

**pre-commit hook** — catch it before it's even committed:

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/jing-ny/agenraci
    rev: v0.1.0
    hooks:
      - id: agenraci-validate        # checks staged charter.yaml / charter.yml files
```

`agenraci validate` takes one or more paths, so a single call checks every
charter in the repo and exits non-zero if any fails.

## Repository layout

```
agenraci/
├── README.md            # this file
├── SPEC.md              # the three questions, RACI rules, file format, checker rules
├── agenraci/            # the Python package (schema, checker, cli, connectors,
│                        #   and the starter template `agenraci init` writes)
├── governance/          # AgenRACI's own charter — the project governs itself
├── examples/autopilot/    # ★ flagship: an autonomous coding team (1 human + 4 agents)
├── examples/hello-world/  # the smallest meaningful charter (1 human + 1 agent)
├── examples/blog/         # one step up: a gate + separation of powers (1 human + 2 agents)
├── examples/sprout/       # a complete worked example (2 humans + 6 agents)
├── examples/relay/        # an all-agent worked example (5 agents, 0 humans)
└── tests/                 # one test per rule + known-good / known-bad charters
```

## Roadmap

- **v0.1 — write it and check it.** The charter format, the checker (R1–R6) with
  `validate --explain` plain-language fixes, worked examples (the Autopilot
  flagship + others), a template, a GitHub Action, and a pre-commit hook. ← you are here
- **v0.2 — first live connector.** A working HumanLayer connector that turns a
  charter into real approval gates, plus a richer authority graph beyond gate
  `escalate_to` edges (standing veto relations).
- **v0.3 — LangGraph connector** + a small web view that renders the chart so
  non-engineers can read it.
- **v0.4 — author ergonomics.** Inline checker findings in an editor, and a
  reference mode that explains any rule on demand.

## FAQ

**Isn't this just RBAC?**
No. Permission ("what may you touch") is only *one* of AgenRACI's three axes.
Role-based access control answers that one question and stops there. AgenRACI also
separates **Function** (what you do) and **Authority** (whose call wins in a
conflict), and — the part RBAC has no concept of — it centers a single
**accountable** owner for each *type* of action. RBAC can tell you an agent is
allowed to call `deploy`; it can't tell you who answers for the deploy, who had to
sign off first, or what should happen if that approver goes dark. A charter can be
denied a permission yet still be accountable for the outcome — those are different
axes, and conflating them is exactly the gap AgenRACI exists to close.

**Why not just use HumanLayer / LangGraph / CrewAI?**
Use them — they're solving a different layer. Those frameworks *run* agents and can
pause them to wait for a human sign-off. AgenRACI sits one level up: it's the file
that says, *for this specific team*, who is allowed to do what, who owns each
outcome, and who breaks a tie — independent of which runtime you use. The charter
is framework-agnostic on purpose. Turning a charter into the live gates those tools
enforce (starting with a HumanLayer connector) is on the roadmap; today AgenRACI
defines and checks the rules those runtimes would enforce.

**Is this vaporware?**
No. v0.1 *writes and checks* a charter today: a real file format, an automatic
checker with rules R1–R6, worked examples, and a template — all of which you
can run from a clone of this repo (`pip install -e .` then
`agenraci validate examples/sprout/charter.yaml`). What it does
*not* do yet is intercept actions or enforce approvals at runtime; that's stated
plainly in [What AgenRACI is (and isn't) yet](#what-agenraci-is-and-isnt-yet)
above and tracked on the roadmap, not dressed up as a current capability.

## License

MIT — see [LICENSE](LICENSE).
