Skip to content

Agent harness: AGENTS.md, bin/check and bin/t - #113

Open
bencap wants to merge 8 commits into
mavedb-devfrom
feature/bencap/agent-harness
Open

bencap wants to merge 8 commits into
mavedb-devfrom
feature/bencap/agent-harness

Conversation

@bencap

@bencap bencap commented Oct 16, 2026 •

Copy link
Copy Markdown
Collaborator

Gives coding agents (and new contributors) the facts about this repo they can't get from the code, and one command for the checks CI runs. The mapper counterpart of VariantEffect/mavedb-api#926 and VariantEffect/mavedb-ui#746.

Changes

  • scripts/generate_schema.py --check exits 1 without writing when schema.json is out of date. CI used to regenerate the file and run git diff --exit-code, which also fails on a correct schema change that isn't committed yet.
  • bin/check runs ruff check, the format check and the schema check in about 3 s, and reports every failure in one pass. bin/t wraps pytest and sets MAVEDB_BASE_URL the way CI does (the requests are mocked). Both use .venv when it exists and python3 otherwise, so CI now calls the same scripts.
  • AGENTS.md (CLAUDE.md imports it) covers:
    • the fork's branch flow (mavedb-dev → mavedb-main) and opening PRs with -R VariantEffect/dcd_mapping2;
    • which tests run in CI and which need BLAT, SeqRepo or UTA;
    • schema.json as the api's contract;
    • why the GA4GH dependencies stay pinned;
    • the SeqRepo refget rule;
    • the reST docstring style.
  • README: the Development section points at bin/check and bin/t instead of plain pytest.
  • .claude/settings.json holds shared permission rules for Claude Code sessions. It blocks --no-verify and reading ~/.aws, ~/.ssh or ~/.pgpass; sets AWS_PROFILE to the read-only agent role (VariantEffect/mavedb-deployment#54); and asks only before hard-to-undo actions: force pushes, pushes to main, mavedb-main, mavedb-dev or release-*, AWS with an explicit profile, eb, the prod-API dev server, adding a dependency, and edits to settings.json itself. Identical copies live in each repo and the workspace, because Claude Code reads settings only from the folder a session starts in. They catch honest mistakes; they aren't a security boundary.

Review notes

  • Locally, 22 tests fail outside CI's one module.
    • The align and vrs_map failures only need BLAT.
    • test_transcript.py ('str' object has no attribute 'urn') and test_seqrepo_contract.py ('ChainedSeqFetcher' object has no attribute 'seq_fetchers') look like real breakage. This PR doesn't touch them.
  • Cross-repo rules live in the workspace-level AGENTS.md in VariantEffect/mavedb-workspace, which is private for now.

Testing

  • bin/check passes. A deliberately stale schema.json fails --check.
  • bin/t tests/test_mavedb_data.py passes, as do the offline modules such as tests/test_variant_projection.py.

Exits 1 without writing when schema.json is out of date, so the check
doesn't depend on the working tree being clean.
bin/check runs ruff check, the format check and the schema.json check
in about 3 s and reports every failure in one pass. bin/t wraps pytest
with CI's MAVEDB_BASE_URL. Both use .venv when present and python3
otherwise, so CI runs the same commands.
AGENTS.md (CLAUDE.md imports it) covers what the code doesn't show: the
fork's branch flow, which tests run where, the schema.json contract, the
GA4GH dependency pin, and the SeqRepo refget rule.
@coveralls

coveralls commented Oct 16, 2026 •

Copy link
Copy Markdown

Coverage Status

coverage: 0.0%. remained the same — feature/bencap/agent-harness into mavedb-dev

Deny --no-verify and reads of ~/.aws and ~/.pgpass. Ask before pushes,
AWS and Elastic Beanstalk commands, the prod-API dev server and
dependency changes. The same file lives in the workspace and in each
repo, because Claude Code reads settings only from the folder a session
starts in. These are guardrails, not a security boundary: a rewritten
command can get past them.
Sessions get AWS_PROFILE=mavedb-agent-readonly, so aws commands use the
read-only role (see deployment/environments/aws/agent-access.md) and fail
rather than fall back to full credentials where the profile is missing.
Choosing another profile asks first, replacing the blanket prompt on
aws. Reading ~/.ssh is now blocked, alongside ~/.aws and ~/.pgpass.
Edits to AGENTS.md, CLAUDE.md and anything under .claude/ now ask first.
Those files shape every later session, and settings.json holds the
guardrails. The rules cover Edit and Write; a shell redirect into one of
these files is not caught.
Prompts now cover force pushes, pushes to main, mavedb-main, mavedb-dev
or release-*, AWS with an explicit profile, eb, adding a dependency and
edits to settings.json itself. Ordinary feature-branch pushes,
dependency updates and edits to AGENTS.md, CLAUDE.md and .claude/rules
no longer ask; the never rule in the workspace AGENTS.md still covers
those edits, and PR review sees the diffs.
The ui checks it with Prettier, so every copy uses that layout.
@bencap
bencap marked this pull request as ready for review October 16, 2026 23:33

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants