AGENTS.md git:20260930.5f47161A

Immutable. This exact content never changes and is served at /api/v1/blob/8fc4ad4b0767e612.

# bernstein - AGENTS.md
<!-- AUTO-GENERATED by `bernstein agents-md sync` - DO NOT edit by hand. Curated content lives under `.sdd/agents-md/`. -->

## Overview

Bernstein is the open-source governance layer for AI agents. It runs on policy as code: you write the policy - who may do what, what needs approval, what must be recorded - and Bernstein enforces it and produces the verifiable record. A deterministic scheduler - no model in the coordination loop - runs agents in parallel, gates what they produce, and records every step, so a run can be verified after the fact, offline, from the artifacts alone. CLI coding agents work out of the box (Claude Code, Codex, Gemini CLI, and 50 more), and the same layer governs any agent workload: the deliverable can be a diff, a research report, a dataset, or an audit evidence pack. Air-gap install profile included. Apache-2.0.

## Module map

Full per-file map: `docs/sdd/module-map.md` (generated).

| Package       | Purpose / detail |
|---------------|------------------|
| `core/`       | orchestration engine - `src/bernstein/core/` |
| `adapters/`   | CLI agent adapters - `src/bernstein/adapters/AGENTS.md` |
| `agents/`     | agent catalog & discovery - `src/bernstein/agents/` |
| `cli/`        | Click CLI - `src/bernstein/cli/AGENTS.md` |
| `evolution/`  | self-evolution engine - `src/bernstein/evolution/` |
| `eval/`       | evaluation harness - `src/bernstein/eval/` |
| `plugins/`    | plugin system (pluggy) - `src/bernstein/plugins/` |
| `tui/`        | Textual TUI - `src/bernstein/tui/` |
| `github_app/` | GitHub App integration - `src/bernstein/github_app/` |
| `mcp/`        | MCP server - `src/bernstein/mcp/` |
| `benchmark/`  | SWE-bench - `src/bernstein/benchmark/` |

## Directory context files

Per-directory context files for agents working inside a subtree. Each covers: what the directory is for, key files, invariants, and how to test that subtree.

| Path                                         | Covers |
|----------------------------------------------|--------|
| `src/bernstein/adapters/AGENTS.md`           | CLI agent adapters |
| `src/bernstein/cli/AGENTS.md`                | Click CLI |
| `src/bernstein/core/lineage/AGENTS.md`       | Lineage: artifact provenance |
| `src/bernstein/core/orchestration/AGENTS.md` | Orchestration engine |
| `src/bernstein/core/quality/AGENTS.md`       | Quality gates and verification |
| `src/bernstein/core/security/AGENTS.md`      | Security: audit chain, identity, policy |
| `tests/AGENTS.md`                            | Test suite |

## Build & test

```
uv sync                             # install + lock
uv run python scripts/run_tests.py  # tests (isolated per-file runner)
uv run ruff check .                 # lint
uv run ruff format .                # format
uv run mypy src                     # type-check
```

## Setup

1. `uv sync` to install + lock the project.
2. `uv run python -m bernstein --help` (or your equivalent entry point).
3. See [Build & test](#build--test) for the recurring commands.

## Architecture (entry points)

Top-level entry points exposed by the package:

| Command                | Purpose |
|------------------------|---------|
| `bernstein`            | bernstein.cli.main:cli |
| `bernstein-worker`     | bernstein.core.worker:main |
| `bernstein-bench`      | bernstein.eval.bench.bench_cli:bench_group |
| `verify-audit-receipt` | bernstein.core.verifier.audit_receipt_verifier:main |

**Back-compat aliases.** Legacy import paths (e.g. `bernstein.core.orchestrator`) are served by a `sys.meta_path` finder, not by physical shim files. The mechanism lives in `src/bernstein/core/__init__.py` as `_CoreRedirectFinder` driven by the `_REDIRECT_MAP` dict - add new aliases there rather than creating shim modules at the old path.

## Git workflow

Default branch: `main`.

## Agent roles

Bernstein ships agent role prompts under `templates/roles/`. The orchestrator loads them at task-spawn time; you don't write to them manually.

- `adversary`
- `analyst`
- `architect`
- `backend`
- `ci-fixer`
- `devops`
- `docs`
- `frontend`
- `manager`
- `ml-engineer`
- `prompt-engineer`
- `qa`
- `resolver`
- `retrieval`
- `reviewer`
- `security`
- `visionary`
- `vp`

## Documentation duty

Every PR that adds or changes a feature MUST update docs in the same PR:

- User-visible behaviour: update the relevant `README.md` section.
- Operator workflows: update `docs/operations/<area>.md`.
- Public API surface: regenerate `docs/api/` schemas.
- Architecture or new module: update `docs/sdd/` and run `bernstein agents-md sync` so AGENTS.md, CLAUDE.md, `.goosehints`, `CONVENTIONS.md`, and `.cursor/rules/*.mdc` stay aligned.
- New test layer: also update `docs/contributing/testing.md`.

PRs without the matching docs change will be sent back. Docs and code ship together.