From 0c564aa3eb8524df7d2666da7911e49bc96c6dd2 Mon Sep 17 00:00:00 2001
From: Alex Rubinsteyn <alex.rubinsteyn@gmail.com>
Date: Sat, 18 Apr 2026 09:35:45 -0400
Subject: [PATCH] Add AGENTS.md and bump to 3.13.2

Adds AGENTS.md so coding agents don't need to be re-told the repo
workflow every session.
---
 AGENTS.md            | 75 ++++++++++++++++++++++++++++++++++++++++++++
 mhctools/__init__.py |  2 +-
 2 files changed, 76 insertions(+), 1 deletion(-)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9cbc135
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,75 @@
+# AGENTS.md — mhctools
+
+Guide for coding agents working in this repo. Read this before touching code.
+
+---
+
+## Golden Rules
+
+1. **Never commit to `main`.** Always `git checkout -b <feature-branch>` before editing. Land via PR.
+2. **Every PR bumps the version.** Even doc-only PRs — at minimum a patch bump. `deploy.sh <version>` handles the bump + commit + push.
+3. **"Done" means merged AND deployed to PyPI** — never stop at merge. After a PR merges, run `./deploy.sh` from a clean main. Skipping deploy = task not done.
+4. **File problems as issues, don't silently work around them.** If you hit a bug here or in a sibling openvax/pirl-unc repo, open a GitHub issue on the correct repo and link it from the PR.
+5. **After a PR ships, look for the next block of work.** Read open issues across the relevant openvax repos, group by dependency + urgency. Prefer *foundational* changes that unblock multiple downstream improvements; otherwise chain the smallest independent improvements.
+
+---
+
+## Before Completing Any Task
+
+Before telling the user a change is "complete":
+
+1. **`./lint.sh`** — must pass
+2. **`./test.sh`** — must pass
+3. For a PR: **CI must be green on GitHub**, then merge, then **`./deploy.sh`**.
+
+`deploy.sh` gates on lint + test, refuses to run off `main`/`master`, and refuses a dirty tree — don't work around these. If deploy fails, fix the root cause.
+
+## Scripts
+
+- `./develop.sh` — editable install (dev mode)
+- `./lint.sh` — ruff check
+- `./test.sh` — pytest (with coverage where configured)
+- `./deploy.sh [version]` — lint → test → optional version bump → build → twine upload → tag → push
+
+## Code Style
+
+- Python 3.9+
+- Lint: ruff (config in `pyproject.toml`)
+- Docstrings: numpy style
+- Bugfixes include a regression test where feasible
+- mhctools wraps external predictors (mhcflurry, netMHCpan, etc.) — keep predictor adapters thin; push generic logic upstream into topiary when possible.
+
+---
+
+## Workflow Orchestration
+
+### 1. Upfront Planning
+- For any non-trivial task (3+ steps or architectural): write a short spec first. If something goes sideways, STOP and re-plan — don't keep pushing.
+
+### 2. Verification Before Done
+- Never claim complete without proof: tests green, CI green, PyPI version live.
+
+### 3. Autonomous Bug Fixing
+- Given a bug report: just fix it. Point at logs/errors/failing tests and resolve them without hand-holding.
+
+### 4. Demand Elegance (Balanced)
+- For non-trivial changes pause and ask "is there a more elegant way?" — skip for trivial fixes.
+- Treat workarounds as bugs, not new abstractions. Rip out legacy paths decisively rather than accumulating special cases.
+
+### 5. Issue Triage After Each Ship
+- Close superseded/outdated issues as you notice them.
+- New problems mid-task → file as issues (on the right repo, even if it's not this one), don't bury.
+
+---
+
+## Core Principles
+
+- **Simplicity first.** Minimal diffs, minimal abstractions.
+- **No laziness.** Find root causes; no temporary fixes, no empty-category fudges.
+- **Minimal blast radius.** Touch only what the task requires.
+
+## Scientific Domain Knowledge
+
+- If a change touches immunology/genomics semantics, check primary sources (papers, UniProt, GenBank) before edits.
+- If the code expresses a scientific model at odds with your understanding, flag it — don't silently "fix" it into something wrong.
+- Use `mhcgnomes` for MHC allele parsing. Never `startswith("HLA-")` or other string hacks — alleles aren't always human.
diff --git a/mhctools/__init__.py b/mhctools/__init__.py
index a6d1293..9589544 100644
--- a/mhctools/__init__.py
+++ b/mhctools/__init__.py
@@ -63,7 +63,7 @@ def __getattr__(name):
     raise AttributeError(
         "module %r has no attribute %r" % (__name__, name))
 
-__version__ = "3.13.1"
+__version__ = "3.13.2"
 
 __all__ = [
     "Prediction",