Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
279 lines (210 loc) · 11.7 KB

CONTRIBUTING.md

File metadata and controls

279 lines (210 loc) · 11.7 KB
Raw

Contributing to Bernstein

Thanks for your interest! Here's how to get started.

Quick Start

git clone https://github.com/sipyourdrink-ltd/bernstein && cd bernstein
uv venv && uv pip install -e ".[dev]"

Testing

uv run python scripts/run_tests.py -x        # all tests (isolated per-file, stops on first failure)
uv run python scripts/run_tests.py -k router  # filter by keyword
uv run pytest tests/unit/test_foo.py -x -q    # single file (fast)

WARNING: Never run uv run pytest tests/ -x -q - the full suite keeps references across 2000+ tests and can leak 100+ GB RAM. The isolated runner in scripts/run_tests.py caps each file at ~200 MB.

Linting & type checking

uv run ruff check src/
uv run ruff format src/
uv run pyright src/

All three must pass before committing. No exceptions, no "fix later."

Development Workflow

  1. Fork the repo and create a branch: git checkout -b feat/my-feature
  2. Make your changes
  3. Run checks: 
    uv run ruff check src/
uv run pyright src/
uv run lint-imports          # architecture contracts (adapter/core boundary)
uv run python scripts/run_tests.py -x
  4. Commit with a clear message
  5. Open a PR against main

All non-trivial changes land via PR with at least one approving review. Security-touching changes need two approvals or operator-only push. Full process and reviewer expectations: docs/CODE_REVIEW.md.

Docs alongside code

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

Pre-push hook

Install the versioned pre-push hook to catch lint and architecture-contract violations before they reach CI:

ln -sf ../../scripts/git-hooks/pre-push .git/hooks/pre-push
chmod +x scripts/git-hooks/pre-push

The hook is blocking on ruff and lint-imports, advisory on pyright. The most common architecture-contract violation it catches is an adapter importing a scheduler-internal module, e.g. from bernstein.core.tasks.models import ModelConfig (wrong) instead of from bernstein.core.models import ModelConfig (canonical). See .importlinter for the full contract list.

Auto-heal on CI failure

When CI fails on main, the bernstein-ci-fix workflow (.github/workflows/bernstein-ci-fix.yml) runs Bernstein in headless mode against the failing commit, opens an auto-heal/<sha> branch with the proposed fix, and creates an auto-heal: fix CI on <sha> PR for review. If Bernstein can't produce a clean diff in 3 iterations within $5, the workflow falls back to opening a ci-fix issue. Auto-heal is gated by the BERNSTEIN_CI_FIX_ENABLED repo variable, refuses to recurse on auto-heal: PRs, and only fires for canonical-repo pushes (never forks).

Code Style

  • Python 3.12+, type hints on every public function and method
  • from __future__ import annotations at the top of every module
  • Max line length: 120 (enforced by ruff)
  • Ruff rules: E, F, W, I, UP, B, SIM, TCH, RUF
  • No dict soup - use @dataclass or TypedDict, not raw dict[str, Any]
  • Enums over string literals for any value with a fixed set of options
  • Google-style docstrings on all public symbols
  • Async only for IO-bound code; sync for CPU-bound/pure logic
  • Thin orchestration facade, isolated core logic, separate adapters

Broad-except policy (route handlers)

src/bernstein/core/routes/**.py is policed by a CI lint (scripts/check_routes_broad_except.py) that fails the build when a bare except Exception: clause appears without a justification marker on the line itself or in one of the three preceding comment lines.

Two markers are recognised:

  • intentional-broad-except: legitimate best-effort path (telemetry, optional analytics, lineage append, etc.). The body should route any sensitive message through bernstein.core.sanitize.sanitize_log.
  • bot-ack: <short-tag>: previously reviewed broad clause; the tag identifies the rationale (e.g. bot-ack: pre-existing-1723, bot-ack: legacy-shim).

If the clause is not actually best-effort, narrow it to the realistic exceptions the helper can raise (typically OSError, json.JSONDecodeError, KeyError, ValueError, or a domain-specific class). Never convert a broad except Exception: into except BaseException: -- KeyboardInterrupt and SystemExit must propagate.

Run locally before committing:

uv run python scripts/check_routes_broad_except.py

See AGENTS.md for the full doctrine, including doctrine, change classification, conflict protocol, and zero-tolerance failures.

CLI Structure

The CLI is split into two layers under src/bernstein/cli/:

Top-level (cli/): main.py (Click group), run.py, run_cmd.py, live.py, dashboard.py, helpers.py, ui.py, status.py

Commands sub-package (cli/commands/): 70+ command modules including:

Module Purpose
run_cmd.py bernstein run / -g orchestration entry point
stop_cmd.py bernstein stop graceful shutdown
status_cmd.py bernstein status / bernstein ps
evolve_cmd.py bernstein evolve subcommands
agents_cmd.py bernstein agents catalog commands
advanced_cmd.py Advanced / less common commands
debug_cmd.py bernstein debug-bundle diagnostics
cost.py Cost tracking display
doctor_cmd.py Pre-flight health checks
checkpoint_cmd.py Checkpoint save/restore
task_cmd.py Direct task manipulation
workspace_cmd.py Multi-repo workspace commands
audit_cmd.py Audit log inspection
ci_cmd.py CI integration commands
policy_cmd.py Policy management
triggers_cmd.py External trigger management

When adding a new CLI command, create a new *_cmd.py module in cli/commands/ and register it in main.py.

Supported CLI Adapters

Bernstein ships with 40+ CLI agent adapters, plus a generic catch-all. src/bernstein/adapters/registry.py is the source of truth for the exact set - check it before writing a new adapter. A subset is shown here for orientation:

Adapter File Agent
aider adapters/aider.py Aider
amp adapters/amp.py Amp
claude adapters/claude.py Claude Code
codex adapters/codex.py Codex CLI
cody adapters/cody.py Cody
continue adapters/continue_dev.py Continue
cursor adapters/cursor.py Cursor
devin_terminal adapters/devin_terminal.py Devin Terminal (Cognition)
gemini adapters/gemini.py Gemini CLI
goose adapters/goose.py Goose
iac adapters/iac.py Infrastructure-as-Code agent
junie adapters/junie.py JetBrains Junie
kilo adapters/kilo.py Kilo
kiro adapters/kiro.py Kiro
ollama adapters/ollama.py Ollama (local models)
openai_agents adapters/openai_agents.py OpenAI Agents SDK v2
opencode adapters/opencode.py OpenCode
q_dev adapters/q_dev.py AWS Q Developer CLI
qwen adapters/qwen.py Qwen Code
generic adapters/generic.py Any CLI agent (catch-all)

Full list: src/bernstein/adapters/registry.py. Adapter guide: docs/adapters/ADAPTER_GUIDE.md.

Writing a Custom Adapter

Adapters implement the CLIAdapter ABC from adapters/base.py:

class CLIAdapter(ABC):
    @abstractmethod
    def spawn(self, *, prompt, workdir, model_config, session_id, mcp_config=None) -> SpawnResult: ...
    @abstractmethod
    def is_alive(self, pid: int) -> bool: ...
    @abstractmethod
    def kill(self, pid: int) -> None: ...
    @abstractmethod
    def name(self) -> str: ...
    def detect_tier(self) -> ApiTierInfo | None: ...  # optional

Steps:

  1. Create src/bernstein/adapters/mycli.py implementing all four abstract methods. See adapters/claude.py for a complete reference.
  2. Register in adapters/registry.py: _ADAPTERS["mycli"] = MyCLIAdapter
  3. Run checks: uv run ruff check src/ && uv run pyright src/ && uv run python scripts/run_tests.py -x
  4. Open a PR - include a short note on how you tested it.

Important: All adapter .spawn() implementations must wrap the CLI command with build_worker_cmd() from adapters/base.py. This sets the process title and writes the PID metadata file that the orchestrator uses for bernstein ps and crash detection.

Writing a Custom CI Parser

CI parsers implement the CILogParser protocol from core/ci_log_parser.py:

class CILogParser(Protocol):
    name: str
    def parse(self, raw_log: str) -> list[CIFailure]: ...

Steps:

  1. Create src/bernstein/adapters/ci/<name>.py from the template in templates/ci-parsers/TEMPLATE.py. See adapters/ci/github_actions.py for a working example.
  2. Register: from bernstein.core.ci_log_parser import register_parser; register_parser(MyCIParser())
  3. Run checks and open a PR.

Writing a Custom Role

Role templates live in templates/roles/<role-name>/ with three files:

  • system_prompt.md - agent persona and standing instructions
  • task_prompt.md - per-task instructions template
  • config.yaml - default model and effort

Built-in roles: adversary, analyst, architect, backend, ci-fixer, devops, docs, frontend, manager, ml-engineer, prompt-engineer, qa, resolver, retrieval, reviewer, security, visionary, vp.

Copy an existing role and customize:

cp -r templates/roles/backend templates/roles/data-engineer

The new role is available immediately - no code changes required.

Architecture Principles

  • Deterministic orchestrator - no LLM calls for scheduling/coordination
  • Short-lived agents - spawn per task batch, exit when done
  • File-based state - everything in .sdd/, no databases
  • Pluggable adapters - new CLI agents via adapters/base.py ABC
  • Branch is main - never master
  • No monoliths - don't create or extend god-files (>400 LOC soft, >600 LOC hard stop)

Process management

Bernstein writes PID metadata to .sdd/runtime/pids/. Use those to find and stop processes. Never pkill -f bernstein or pgrep bernstein - it will kill the orchestrator indiscriminately.

# Correct: signal via file
echo "stop" > .sdd/runtime/signals/<role>-<session>/SHUTDOWN

# Correct: use bernstein CLI
bernstein stop

# WRONG: grep-kill
pkill -f bernstein   # kills everything including your own shell session

Recognition

All contributors are listed in CONTRIBUTORS.md. Outstanding contributions are featured in our monthly Community Spotlight blog posts, which are shared on Twitter/X, LinkedIn, and dev.to.

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.