Immutable. This exact content is served forever at /api/v1/blob/89fb6b1a77f304a6.
# bernstein - CLAUDE.md <!-- AUTO-GENERATED by `bernstein agents-md sync` - DO NOT edit by hand. Source: 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 40+ 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.