Skip to content

docs(agents): add AGENTS.md with repo conventions for coding agents - #446

Open
pjdoland wants to merge 2 commits into
plmbr:mainfrom
pjdoland:docs/agents-md
Open

pjdoland wants to merge 2 commits into
plmbr:mainfrom
pjdoland:docs/agents-md

Conversation

@pjdoland

@pjdoland pjdoland commented Sep 15, 2026

Copy link
Copy Markdown
Collaborator

Summary

Coding agents (Claude Code, Codex, Cursor, and others) now read repository instruction files automatically. This adds one for Notebook Intelligence so agents pick up conventions the repo already follows, most of which CONTRIBUTING.md and in-code comments describe for people.

Solution

  • AGENTS.md holds the rules, in three short sections:
    • Before pushing: pytest tests/ -q, jlpm tsc --noEmit, jlpm lint:check, and jlpm jest, plus a note to run jlpm lint to auto-fix formatting problems.
    • JavaScript tooling: use jlpm for frontend commands, leave packageManager out of package.json, and regenerate yarn.lock with jlpm install and confirm jlpm install --immutable passes.
    • Code conventions: follow the seven-place checklist above FEATURE_POLICY_SPEC in extension.py when adding an admin policy, and import icons from src/icons.ts.
  • CLAUDE.md is a single @AGENTS.md line, so Claude Code imports the same file and there is only one place to maintain.
  • CONTRIBUTING.md gets a one-sentence pointer to AGENTS.md next to its existing note about lockfile changes.

The packageManager note explains the mechanism: jlpm (Yarn 3.5.0) ignores the field, but a lockfile written by a different Yarn version gets a different TypeScript builtin patch hash, and CI's immutable install rejects it with YN0028.

Testing

  • prettier --check passes on AGENTS.md, CLAUDE.md, and CONTRIBUTING.md.
  • Checked each rule against the repo: jlpm --version reports 3.5.0; the jupyterlab/maintainer-tools base-setup action only enables corepack when packageManager is present; CI runs pytest tests/ -q, jlpm run lint:check, and jlpm test; the FEATURE_POLICY_SPEC comment lists the seven policy touchpoints; and no file under src/ imports react-icons directly.
  • Documentation only; no code or test changes.

Risks / follow-ups

None expected. The files only affect tools that read them, and more rules can be added as they prove useful.

Coding agents read repository instruction files automatically, so this
gives them the conventions the repo already follows: the checks to run
before pushing, jlpm-only frontend tooling (no packageManager pin, and
lockfiles regenerated with jlpm), the seven-place admin policy
checklist, and importing icons from src/icons.ts.

CLAUDE.md imports AGENTS.md so there is one file to maintain, and
CONTRIBUTING.md points to it next to the existing lockfile note.
@pjdoland pjdoland added the documentation Improvements or additions to documentation label Sep 15, 2026
An agent that hits a Prettier failure in lint:check may reformat by hand
or reach for a global prettier. jlpm lint applies the repo's own
formatter, including to Markdown.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant