AGENTS.md · sipyourdrink-ltd/bernstein

Sections

1. Overview
2. Module map
3. Directory context files
4. Build & test
5. Setup
6. Architecture (entry points)
7. Git workflow
8. Agent roles
9. Documentation duty

First lines (shown under the repo's Apache-2.0 license)

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