bernstein - 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 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.