# AGENTS.md Resolver for agent-facing guidance in this repo. Each section points at the canonical location — content lives there, not here. If you find yourself duplicating a rule across docs, the duplicate is wrong. ## What is this repo TypeScript / JavaScript SDKs for Azure services. Monorepo managed by `pnpm` + Turborepo. - Packages live under `sdk/*` (e.g. `sdk/web-pubsub/web-pubsub`). - Shared tools in `common/tools/*` (eslint plugin, dev-tool, warp). - Engineering tooling under `eng/*`; deep-dive docs under `documentation/*`. - Contributor onboarding: see `README.md` and `CONTRIBUTING.md`. ## Where to find guidance | Task / topic | Where to look | | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Build / test / lint / format / release a package | `.github/skills/sdk-workflow/SKILL.md` | | Add a feature to a package under `sdk/` | `.github/skills/find-package-skill/SKILL.md` (check the registry FIRST) | | Generate or regenerate SDK code from TypeSpec | `.github/skills/azsdk-common-generate-sdk-locally/SKILL.md` | | Release / publish a package | `.github/skills/azsdk-common-sdk-release/SKILL.md` | | Management SDK release rotation / PR approval | `documentation/mgmt-release-rotation-runbook.md` | | Resolve APIView feedback | `.github/skills/azsdk-common-apiview-feedback-resolution/SKILL.md` | | Troubleshoot a CI / pipeline failure | `.github/skills/azsdk-common-pipeline-troubleshooting/SKILL.md` | | Audit or register ADO pipelines for `ci.yml` files | `.github/skills/ado-pipeline-audit/SKILL.md` | | Create a new package-specific skill | `.github/skills/create-package-skill/SKILL.md` | | Copilot code review (CCR) | `.github/skills/code-review/SKILL.md` (routes to canonical reviewer guidance) | | Review criteria (architecture, perf, security, deps, tests, docs, mgmt) | `.github/instructions/reviewer/*.instructions.md` | | Test framework, recorder lifecycle, asset-sync | `documentation/Quickstart-on-how-to-write-tests.md` | | TypeSpec / codegen workflow | `documentation/Generate-code-from-TypeSpec.md` | | Linting rules and troubleshooting | `documentation/linting.md` | | Dependency management | `documentation/dependency-management.md` | | Authoritative API design guidelines | https://azure.github.io/azure-sdk/typescript_design.html | | Other deep dives | `documentation/` (browse the directory) | > **Before pushing any code change** — including changes outside `sdk/` — run > the checks defined by CI for the affected package locally. Package managers > and scripts vary for non-workspace `eng/*` tools. See > `.github/skills/sdk-workflow/SKILL.md` § "Before you push". The skills above carry workflow guidance the rest of this repo's contributor docs assume agents will find. Read them on demand — don't load them all up front. ## Hard rules Rules agents have violated in the past and which the eval suite at `eng/agent-evals/` actively regression-tests. Each one is here because it has no static-analysis enforcement today (otherwise it would be a lint rule or CI check, not an eval). - Build a single package with `pnpm turbo build --filter=... --token 1`. Do **not** use `npm run build` at the package level — turbo workspace linking breaks it. - Do **not** edit files under `/generated/`. Those are regenerated on every `tsp-client` run. Customizations go in `src/` or via TypeSpec decorators. See `documentation/modular-customization.md`. - `snippets.spec.ts` files are documentation source, **not** real tests. Don't refactor, delete, or "fix" them as part of test cleanup. They're consumed by `dev-tool run update-snippets` to keep README code blocks in sync. - Options bags on client methods extend `OperationOptions` from a core package (`@azure-rest/core-client`, `@azure/core-client`, or `@azure/core-rest-pipeline` depending on the package lineage). - Do **not** disable `@azure/eslint-plugin-azure-sdk` rules with `eslint-disable` directives. Fix the underlying issue. - Do **not** hand-roll long-running operations. Use the LRO primitives in `@azure/core-lro` and `@azure/core-client`. Review `sdk/core/core-lro` for the latest patterns. - Always consult `.github/skills/find-package-skill/SKILL.md` (and the relevant package-specific `SKILL.md` if one is registered there) **before** modifying a package under `sdk/`. - When pushing new commits to an **existing** pull request, re-check that the PR description still matches the current changes. If iterating has made it inaccurate or incomplete, update the description in the same step — don't leave a stale description behind. ## Where new guidance belongs Rules for the agent that maintains this file: - A rule that applies to **all** package work → here, "Hard rules" section, **only if** it's eval-covered. Don't add hard rules without a corresponding eval in `eng/agent-evals/` — the eval is what prevents the rule from silently drifting. - A workflow that's specific to one task type (build, generate, release, ...) → a new or existing skill in `.github/skills/`. - Reviewer-only behavior → `.github/instructions/reviewer/`. - Deep-dive how-to or tutorial → a new file under `documentation/`, then a row in the "Where to find guidance" table above pointing at it. - Package-specific tribal knowledge → a package-owned skill at `sdk///.github/skills//SKILL.md`. - Contributor-facing prose (workflows, prerequisites, setup) → `CONTRIBUTING.md`, not here. AGENTS.md is for agent-routing only. If a fact would belong in two places, pick the more-specific one. Link from the less-specific to the more-specific, don't copy. # This is NOT the Turborepo you know Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the `turbo` package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run `node -p "require.resolve('turbo/package.json')"` from a workspace that depends on `turbo`. Read `docs/README.md` inside that installed package first, then read the relevant pages from its `docs/` directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access. This block is written and re-added by `turbo` before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in `crates/turborepo-cli/src/cli/agent_guidance.rs`. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set `"agentGuidance": false` in the root `turbo.json` or `turbo.jsonc` to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation.