rutherford-mcp-server AGENTS.md

AGENTS.md

Guidance for coding agents working in this repository, and the canonical home for it. Written to the AGENTS.md convention so any agent finds the same contract rather than each one needing a file named after its vendor.

CLAUDE.md still exists, because Claude Code reads that name and not this one; it imports this file and holds nothing of its own. Anything that belongs to every agent belongs here.

Humans want CONTRIBUTING.md, which covers the same ground at more length and adds the review and pull-request expectations.

Commands

uv sync                       # install deps (project + dev group) into .venv
uv run ruff check .           # lint
uv run ruff format .          # format (write)
uv run ruff format --check .  # format check (CI mode)
uv run mypy                   # type-check (strict)
uv run python scripts/check_license_headers.py   # license-header check
uv run pytest                 # unit tests only (integration deselected by default)
uv run pytest -m integration  # local-only suite that drives real ACP agents

A justfile wraps these. just check is the pre-push gate: it runs scripts/gate.py, which executes every stage in order (lint, format-check, license-check, typecheck, tests, the per-file coverage floor, the entrypoint smoke check, and the build), streams their output, and stops at the first failure. just test-integration drives the real agents. Run a single test file with uv run pytest tests/test_session.py.

If you are an agent, read the verdict rather than the prose. The gate writes .tmp/gate-report.toon, which names the stage that failed instead of leaving you to parse output meant for a human:

schema: 1
head: <sha>
dirty: false          # true means uncommitted edits were in the tree, so `head` alone does not describe what ran
verdict: pass         # or fail
failed_stage: null    # the stage name when verdict is fail
stages[8,]{name,ok,seconds,exit_code}:
  lint,true,0.08,0
  ...