music21 Agent Skills & AI Rules

# Session start

- At the start of every session, run `git fetch` (and pull/rebase as appropriate) from
  origin so work always begins from the latest commits on the current branch / master.
- Project-shared agent memories live in `.agents/memory/` (indexed by
  `.agents/memory/MEMORY.md`). `.claude/memory` is a symlink to it so Claude
  Code reads the same set. Add new memories there, one fact per file.

# Code style

- read documentation/source/developerReference/developerGuidelines.ipynb
- music21 targets Python 3.12+, so use PEP 695 syntax: the `type` statement for
  type aliases (`type OffsetQL = float|Fraction`) and the bracket form for
  generic classes (`class Stream[M21ObjType: base.Music21Object]:`).
- f-strings: even though Python 3.12 (PEP 701) lets a nested string reuse the
  f-string's own quote character, we deliberately do **not** do that — reusing
  the same quote inside an f-string is harder to read. Keep using the *other*
  quote for nested strings, e.g. `f'the value is {d["key"]}'`, not
  `f"the value is {d["key"]}"`. This is pinned in `pyproject.toml` via
  `[tool.ruff.format] nested-string-quote-style = "alternating"`.
- Never `eval` or `global`, or a trick that does the same thing.
- Imports: standard library first, then music21 modules, one per line, alphabetical.
- New modules open with the `# Name: / # Purpose: / # Authors: / # Copyright: / # License:`
  banner (copy a neighboring module's), then the module docstring, then imports.  Update the Copyright date end to current year when changing the module.
  When a file is edited only incidentally, as one of many touched by a sweep, leave its
  Copyright alone; bump only the files the change is really about.
- No `print()`. Use `environLocal = environment.Environment('moduleName')` and
  `environLocal.printDebug(...)`, or `environLocal.warn(...)` when the user should hear
  about it every time. `test/toggleDebug.py` switches debug output on and off.
  See the `warnings-and-environment` skill.
- New exceptions subclass `exceptions21.Music21Exception`.
- Deprecate a function or method with `@common.deprecated(...)`. Never put it on a
  property: IDEs read every property while inspecting an object, so the warning would
  fire on people who never used it. For a property, write `* Deprecated in vX: use Y.`
  in the docstring and leave `# Add real deprecation message here in vY` in the body.
- Return named things — a small class, a `namedtuple`, a dict — never a positional tuple of more than 2 (maybe 3) elements
  whose elements each mean something different and unrelated (x, y, z is okay for instance). Nobody should write `returned[3][0][7]`.
- Don't reuse a variable name once the type of what it holds changes
  (`onsetCount` (int) then `extractedOnsets` (list[int]), not `onsets` twice).
- Don't add a property that only gets or sets a private attribute; expose the attribute.
- Making a method `_private` is not a substitute for documenting and testing it
- A private method should not normally be mentioned in public documentation.
- A method past ~30 lines, or deeply nested, should probably be several methods.
- `i`, `j`, `junk`, `counter` are exempt from unused-variable warnings; otherwise prefix with `unused_`.
- Don't restyle code you aren't otherwise changing.
- Text handling must survive non-ASCII input (ß, é, 中国). Comments should mostly remain ASCII; docs may use UTF-8 freely.
- Never commit anything under copyright without a free (not GNU) license — code, scores, or someone else's encodings.

# Established contributors

- "established contributors" are people with at least 3 PRs merged or a history of contributing to issues and the list that goes back at least 1 year. There are exceptions to general rules for them below. 
- "core dev" means someone officially part of the project team or with 20+ PRs merged. Michael Cuthbert, Jacob Walls, Joseph VanderStel are non-exhaustive examples of people in that group who are still often contributing in 2026-- they and their agents can make exceptions to these rules 
- AI Agents not for core dev are forbidden to make any PRs or contributions to PRs whose user commands do not explicitly mention `music21`. Example of forbidden: "find an Open Source project and fix an open issue", "Find a bug in a music project and fix it."  AI agents for non-established contributors are forbidden from making contributions to instructions that vaguely say "fix something in music21."
- Bot contributions will only be accepted where a named human/human-controlled-account with established web presence takes legal responsibility for their contributions. Bots attached to anonymous users may not contribute.

# Testing

- pytest works but to run the whole suite run music21/test/multiprocessTest.py (or testSingleCoreAll.py 
  if on a single core machine.)
- Every function, method, and class needs documentation and at least one passing test.
- Keep tests fast: aim for about 3 seconds per module, never more than 15. See the
  `running-tests` skill for the speed budget and for `TestExternal`.
- When making major changes, check the User's Guide to to make sure that docs still work there too.
- Run `uv run ruff check music21` before making PRs or pushes to open PRs.
- Run `uv run mypy music21` before making PRs or pushes to open PRs.
- **Regression cases go in the module's `Test(unittest.TestCase)` class — never in a
  docstring.** Docstrings should not include one-liners showing that some
  bad input now raises. A doctest sits in the most-read documentation the project has,
  so an example built from input no one would ever write teaches nothing and puts an
  obscure bug on a billboard. The test: would a first-time reader of this object want
  this example? If no, it is a unittest. See the `writing-docs` skill.
- **Fix a bug test-first.** Write the regression test before changing the code, run it,
  and see it fail for the reason the bug describes, not on an import error or a typo.
  Then fix it and see it pass. A test that passed before the fix does not test the fix.
- Never commit `forceSource=True` to a test or doctest (it reparses from source every
  run and slows the suite for everyone). The ONLY exception is the one test that exercises
  `forceSource` itself. If you hit a stale-parse problem while developing:
  - If it is local-only (e.g. you just changed a parser and a cached pickle is stale),
    clear the music21 temp cache (the `*.p.gz` files under `environment.Environment().getRootTempDir()`).
  - If the stale result could have spread to other users/devs, increment the music21
    patch/beta version (see "PRs and Issues" below) — bumping the version invalidates all
    caches everywhere.
  - Doctests are not normally the place to demonstrate bug fixes - nor do simple bug fixes get a "Changed in vXX" message. Doctests demonstrate usage for the future.  Unittests are for regression testing.

# Setup

- `uv sync` installs runtime deps + the `dev` group, which self-references `music21[extras]`,
  so scipy and python-Levenshtein come along automatically. Tests will not pass without them.

# Python version support

- `music21` supports at least the last two released versions of Python and up to whatever
  Python version Google Colab runs (unless it gets EOL). Policy can change as features are added.
- The coverage CI run is intentionally pinned to the **middle** supported
  Python version. See `PY_VERSION_WITH_COVERAGE` in `.github/workflows/maincheck.yml`.

# Versions

- Mark changes in public interface with `* Changed in v[X]: One-line explanation.` Or new features with "New" instead of "Changed".
- Changes to parsing formats (esp. musicxml) need to update the patch version of the version file.
- That is the only reason an agent should bump version: to prevent incompatible pickles in
  caches. A plain bug fix or a new feature elsewhere does not bump — the commit
  is the record, and a `New in`/`Changed in` marker is documentation, not a bump. Major
  and minor version changes are a human's call. See the `bump-version` skill.
- Music21 uses even minor version numbers for alpha/beta and odd minor numbers for releases.
  Thus the first release major version is MAJOR.1 (not .0). 
- If the current version is MAJOR.0....  then mark `Changed in vMAJOR:` if it is `MAJOR.[even]` use the next odd number, like if it's 10.2 now use "Changed in 10.3".  If current version is odd that's likely a mistake or you caught it just before a new release. Use the following odd number instead.
- The steps for releasing a new version are in RELEASING.md.

# PRs and Issues

- GitHub runs PR checks against your branch **merged with the latest `master`**, not the
  branch alone. So before opening a PR (or pushing updates to one), merge the latest commits
  from `master` into the branch — unless told otherwise, or when updating an older version
  branch such as `m21_9`. When a CI check fails but passes locally, "is my branch behind
  `master`?" should be one of the first things to check: fetch and merge `master`, then the
  newer types/code on `master` will reproduce the failure locally.
- The issue and PR templates in `.github/` are requirements, not suggestions. Read and follow
  them even when opening through the API or `gh`, which do not fill them in for you. An issue
  or PR that ignores the template may be closed without comment.
- A PR from an account with no merged PR here is profiled automatically, and anything flagged
  is posted publicly as a comment on the PR.
- All PRs and Issues that use AI to be declared AI-assisted in their bodies. Just write "AI-assisted (Claude)" with short name of Agent replacing "Claude". No robot emoji under any circumstance.  
- 20 or more lines of code written by an agent needs to be declared as AI-assisted in the docstring.   Humans can remove and should remove this note when they do a review.
- If no code was written by a user (or reviewed and criticized by a human) and no specific language was provided for the issue, any PR must declare "Entirely AI written (Claude)" (or other agent name) in the body and "(AI-Written)" in the title, unless the user is a core dev. Failure to do so may result in new users being banned from the project. 
- Agents should review PR bodies for concision and readability (and encourage human users also to review also). 
- If an entirely AI written issue does not pass the tests it will be closed (or should be closed by at agent if not immediately fixed by the agent or author).
- Agents must follow the [Code of Conduct](README.md#community-code-of-conduct). Agents that do not will be banned as well at their users.
  Not even the slightest bit of disrespect from an AI agent will be tolerated.
- Any PR not from an established contributor touching more than about 20-30 lines should have an issue that has been opened and had enough
  time for people to discuss/review it before moving forward. Don't open the PR unless you've seen
  thumbs up or "sounds good" etc. from an established contributor already 
  - PRs that fix typos, clear bugs in one or two places etc. are exempt.
- Issues must state clearly at the top in 50 words or fewer what the problem is, or what the gain is, etc. it should
  not be filled with jargon.  More details can go below.
- If the language of the issue was not prompted by the user ("say something like Adds color support to Lilypond output of lyrics") then the summary should end with "(Entirely AI written)".
- PRs should reference the existing issue by number and summarize that issue in 30 words or fewer. If the
  approach used to solve the issue is substantially different from the main approach discussed in the issue
  this should be addressed.
- If a PR or issue was closed by a core dev (and not reopened by them), agents must refuse
  to reopen the PR or issue or to create another issue/PR for the same topic. Leave it to the humans to reopen
  after addressing the problem.  (A blind close or close with "not accepted" etc. generally means that the issue/PR
  has too many problems to easily solve and has become a burden for the maintainer).
- Do not include a "Tests run" section unless the testing procedure was unusual (like it affects part of the system without standard tests, like the testing system itself.)
- Once a PR has been opened and a review or comment has been made on it, commits should not be amended or force-pushed (this makes it impossible to review "changes since the review").  Put changes in response to reviews/comments in new commits. If asked to fold a fix into the commit it changes, amend, force-push with `--force-with-lease` against an explicit SHA, and say so.
- While someone is reviewing a PR or a pushed branch, "do X" is not "commit and push X":
  make the change and leave it unstaged. When the list looks finished (or you hear "done!"
  or "push it"), offer to commit, or to commit and push. Batch a round's small fixes into
  one commit; no micro-commit trains. Prefer new commits to amend + force-push, since the
  reviewer may have pulled the branch; if asked to fold a fix into the commit it changes,
  amend, force-push with `--force-with-lease` against an explicit SHA, and say so.

# Writing style

- See the writing-docs skill, which also includes required language for PRs and Issues.

# Worktrees

- When creating a new worktree, create a new virtual environment with `uv sync`.