AGENTS.md#
Cross-agent guidance for this repository. See CLAUDE.md for the full project
overview, architecture, and conventions — this file mirrors the rules that
apply to every coding agent regardless of tool.
Dependency Install#
Run pnpm install before starting any task and again after every merge with
main.
Pre-PR Quality Gate (MANDATORY)#
Before committing, run the narrowest meaningful quality checks for your changes and confirm they pass locally. Before opening a PR or pushing changes intended for review, run the same checks CI runs. If you make post-commit changes, rebase, or merge before pushing to a PR, rerun the relevant checks first.
Use the repo-preferred package manager, scripts, and Nx targets where applicable. Do not commit or push while quality checks are failing unless the user explicitly instructs otherwise; report the exact failing command and failure instead.
The single canonical command is:
pnpm test:pr
This runs the exact target set the PR workflow runs in CI
(nx affected --targets=test:sherif,test:knip,test:docs,test:eslint,test:lib,test:types,test:build,build --exclude=examples/**,testing/**).
If you can't run test:pr (e.g. it's too slow on your machine), at minimum run
each of these and confirm they're green before pushing:
pnpm test:sherif— workspace consistencypnpm test:knip— unused dependenciespnpm test:docs— doc link verificationpnpm test:eslint— lintpnpm test:types— typecheckpnpm test:lib— unit testspnpm test:build— build artifact verificationpnpm build— build all affected packagespnpm --filter @tanstack/ai-e2e test:e2e— E2E suite (mandatory for any behavior change; seetesting/e2e/README.md)
Do not rely on CI as your first signal. Run locally, fix, then push.
Documentation#
When editing docs under docs/:
- No
astype-assertion casts in code samples. Examples must type-check withoutas SomeType— narrowunknownvalues withtypeof/inchecks, type guards, or Standard Schema validation instead. (as constis fine — it's a const assertion, not a type cast.) - Show both sides of the coin. When a doc spans server and client, include snippets for both halves (server endpoint AND client consumption).
- Use the latest model per provider, sourced from each adapter's
model-meta.ts(newestgpt-*,claude-*,gemini-*, …), in example code. - Maintain
addedAt/updatedAton docs entries indocs/config.json. Every page entry carries anaddedAt(ISOYYYY-MM-DD) and, once edited, anupdatedAt. When you touch a docs page, update its entry: add a new entry withaddedAtset to today's date for a new page, or set/refreshupdatedAtto today's date when you make a content change to an existing page (new section, capability, reworked guidance, new examples). Bug fixes don't bump anything — typos, broken links, code-fence languages, formatting, and factual fixes must not touchaddedAtorupdatedAt. - Run
pnpm test:docs(link verification) before pushing.
Everything Else#
For package manager (pnpm@10.17.0), monorepo layout, adapter architecture,
tool system, framework integrations, E2E requirements, and all other
conventions, read CLAUDE.md in this directory.