agentleFS
iTwiniTwin/itwinjs-core/AGENTS.md

itwinjs-core

AGENTS.md742 starsChanged 4 months agoMITView on GitHub

Read only the references relevant to the task: When editing docs/changehistory/NextVersion.md: Before committing work that will be pushed, apply only the checks required by the final diff:

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository6 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

17 rules. About 0 are common, 9 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read only the references relevant to the task:

    line 5
  2. Distinctive:

    Do not push, create pull requests, or update GitHub issues unless asked.

    line 19
  3. Distinctive:

    Use non-interactive Git. Do not discard changes without explicit approval.

    line 20
  4. Very specific:

    Use rush from the repository root and rushx in a package.

    line 21
  5. Very specific:

    Use relative imports within a package.

    line 22
  6. Very specific:

    Import Node.js built-ins with the node: prefix (node:fs, node:path), not bare specifiers.

    line 23
  7. Very specific:

    Keep backend and native dependencies out of core/common and core/frontend.

    line 24
  8. Distinctive:

    Do not change an existing exported API or RPC signature without a compatibility plan.

    line 26
  9. Very specific:

    Keep private implementation in src/internal/.

    line 27
  10. Distinctive:

    Check the release tag and API report before changing an exported symbol.

    line 31
  11. Very specific:

    Do not break a @public API outside a major-version migration plan.

    line 32
  12. Very specific:

    Do not hand-write dates in @deprecated tags.

    line 34
  13. Distinctive:

    Before committing work that will be pushed, apply only the checks required by the final diff:

    line 46
  14. Distinctive:

    Commit intentional API reports and change files with the implementation.

    line 57
  15. Distinctive:

    Treat a runtime or logical behavior change as breaking even when existing consumer code still compiles.

    line 58
  16. Distinctive:

    If a required check is blocked, state the command and blocker.

    line 59
  17. Very specific:

    Do not commit .only tests.

    line 60

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

iTwin.js Core Agent Instructions

Read the source of truth

Read only the references relevant to the task:

NeedSource
Setup, Rush commands, contribution and PR workflowCONTRIBUTING.md
Package scripts, test runner, local conventionsAffected package's package.json, tests, and configuration
Project graph and publish statusrush.json
Public API contractcommon/api/<package>.api.md API report
Lockstep version policycommon/config/rush/version-policies.json
CI behavior.github/workflows/ and common/config/azure-pipelines/

Boundaries

  • Change only files relevant to the task. Preserve unrelated changes.
  • Do not push, create pull requests, or update GitHub issues unless asked.
  • Use non-interactive Git. Do not discard changes without explicit approval.
  • Use rush from the repository root and rushx in a package. Do not use npm install, pnpm install, or edit pnpm-lock.yaml directly.
  • Use relative imports within a package. Do not self-import through @itwin/*.
  • Import Node.js built-ins with the node: prefix (node:fs, node:path), not bare specifiers.
  • Keep backend and native dependencies out of core/common and core/frontend.
  • Frontend code uses IModelConnection and its managers, not new direct RPC clients.
  • Do not change an existing exported API or RPC signature without a compatibility plan.
  • Keep private implementation in src/internal/. Cross-package internals belong in the owning package's src/internal/cross-package.ts.

Public APIs

  • Check the release tag and API report before changing an exported symbol.
  • Do not break a @public API outside a major-version migration plan. Prefer an additive API and deprecation.
  • Give every new export a release tag.
  • Do not hand-write dates in @deprecated tags.

Change notes

When editing docs/changehistory/NextVersion.md:

  • List the allowed ## sections with node .github/workflows/automation-scripts/check-nextversion.mjs --sections. Add each entry as a ### heading under the section it belongs to, reusing that section when it already exists, and add it to the table of contents.
  • If the table of contents is missing, create it below # NextVersion and before the first ## section, following past release notes such as docs/changehistory/5.14.0.md. Use a nested Markdown list of heading links: NextVersion at the top level, ## sections indented two spaces, ### entries indented four spaces, and deeper headings nested accordingly. Include all existing headings in document order, not just the entry being added. A passing validator does not excuse a missing table of contents.
  • Done when node .github/workflows/automation-scripts/check-nextversion.mjs passes. It checks the whole file, so fix any problems already there in the same change, and tell the user what you fixed and why, since it is outside the task you were given.

Before remote work

Before committing work that will be pushed, apply only the checks required by the final diff:

Final diff includesRequired before push
Production codeTargeted build, tests, and affected-package lint
Exported API, entry point, or release tagrush clean && rush build && rush extract-api; review API report changes
Published packageRush change file with "type": "none"; use an empty comment when behavior is unchanged
Breaking API or behavior change, or significant featureMigration guidance in docs/changehistory/NextVersion.md
External dependency manifestrush check and the Rush update flow
Documentation extract or package docsRelevant rushx docs build when available
  • Commit intentional API reports and change files with the implementation.
  • Treat a runtime or logical behavior change as breaking even when existing consumer code still compiles.
  • If a required check is blocked, state the command and blocker.
  • Do not commit .only tests.

Manual offline tests

AI assistants require network access and cannot work while this machine is offline. Do not launch or supervise a test requiring machine-wide disconnection through assistant tools. While still online, give the operator the complete commands, expected results, cancellation steps, and manual network-restoration instructions, then end your turn before disconnection. Resume work only after the operator confirms networking is restored. For Vertical CRS acceptance, follow the Vertical CRS testing guide.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.