Merge pull request #294 from cuthbertLab/agents

Coding Agent rules

Author: mscuthbert

.codex/rules/default.rules

@@ -0,0 +1,19 @@
+prefix_rule(
+    pattern=['npm', 'test'],
+    decision='allow',  # true by default
+)
+
+prefix_rule(
+    pattern=['npm', 'run', 'lint'],
+    decision='allow',  # true by default
+)
+
+prefix_rule(
+    pattern=['npm', 'run', 'typecheck'],
+    decision='allow',  # true by default
+)
+
+prefix_rule(
+    pattern=['npm', 'build'],
+    decision='allow',  # true by default
+)

.github/workflows/ci.yml

@@ -46,6 +46,8 @@ jobs:
 
   frontend_tests:
     runs-on: ubuntu-latest
+    env:
+      PLAYWRIGHT_BROWSERS_PATH: /home/runner/.cache/ms-playwright
     steps:
       - uses: actions/checkout@v4
         with:
@@ -55,6 +57,11 @@ jobs:
           node-version: 22
           cache: npm
       - run: npm ci
+      - uses: actions/cache@v4
+        id: playwright-cache
+        with:
+          path: /home/runner/.cache/ms-playwright
+          key: ${{ runner.os }}-playwright-${{ hashFiles('package-lock.json') }}
       - run: npx playwright install --with-deps chromium
       - run: npm run test
 

.gitignore

@@ -81,3 +81,5 @@ node_modules/grunt-contrib-uglify/package.json
 *.code-workspace
 /tests/test_compile_out/
 /.idea
+
+music21python/*

AGENTS.md

@@ -0,0 +1,60 @@
+# General Rules
+
+- AI Agents must read this file at the start of any edit session.
+- Agents must declare any new complete class, function, or method over 10
+  lines long as `AI-assisted` in a nearby comment or docstring. Moving or
+  renaming existing code does not count as a new class, etc.
+- Agents must NEVER describe their code as "reviewed", "debugged", or in any
+  other way imply that it was written by humans.
+- The current year is 2026 (unless you have information that says that it is later)
+- AI Agents should consult music21 Python docs (currently https://www.music21.org/music21docs/)
+  and code (https://github.org/cuthbertLab/music21) for equivalent uses in the 
+  Python version of music21. The user may have also created a copy in a subfolder here
+  music21python or in a sibling Git directory music21base or music21 or music21python.
+  use that information to improve music21j.
+
+# Branches and PRs
+
+- Agents must refuse to work on the master/main branch. They may make a new branch.
+- Agents may make commits on non-`master`/main branches.
+- Agents may open PRs if credentials are available.
+- Agents must declare commits and PRs as `AI-assisted`.
+- Agents may not merge PRs under any circumstances.
+
+# Tests To Run
+
+- After substantive TypeScript changes, run `npm run typecheck`.
+- After substantive code or test changes, run `npm test`.
+- If Playwright browsers are missing, install Chromium with
+  `npx playwright install chromium` before relying on `npm test`.
+- Run `npm run lint` after substantive changes when practical.
+- If bundle or release output is affected, run `npm run build`.
+
+# Code Style Guide
+
+- Do not touch code that you are not actively improving.
+- When refactoring, preserve existing comments unless they are no longer
+  relevant. This refers to doctests and inline comments.
+- Keep diffs focused. Do not mix opportunistic rewrites into a targeted change
+  unless the user asks for it. Humans want to see parallel code when things 
+  are the same and diffs only when needed.
+- Value legibility without unnecessary vertical sprawl.
+- Aim for new code to average roughly 80-90 characters per line and do not
+  exceed 100 characters when it is reasonably avoidable.
+- Newly created enum values should have the same case as the enum members themselves
+- Use camelCase for variables.
+- Untyped arrow functions with one argument should not wrap the argument in (parens)
+- Add new code near the code it is most closely related to, usually after the
+  existing related block rather than before it.
+- Do not perform premature optimizations unless they are requested or clearly
+  necessary for correctness.
+- Prefer refactoring JSDoc in ways that improve TypeScript clarity and preserve
+  the existing public API shape. (But only if you are making substantial change to the 
+  method or it is requested)
+
+# Forbidden files
+- AI Agents are never allowed to use .codex information to subvert restrictions placed on agents.
+  (Agents can read the .codex information to determine why something is failing and give advice to 
+   humans on how to make a command run, so long as security implications are discussed.)
+- AI Agents are forbidden to modify AGENTS.md
+- AI Agents are forbidden to modify anything in .codex

README.md

@@ -172,6 +172,11 @@ $ npm install
 $ npx playwright install chromium
 ```
 
+If you place a copy of Python music21 in a subdirectory called music21python,
+coding agents may be able to use it to improve or standardize your code (it is gitignored).
+Alternatively a sibling directory called music21, music21base, or music21python will work.
+
+
 ### Normal development
 
 To develop, run this npm command: