AGENTS.md template for a Turborepo monorepo

# Monorepo instructions

This repository is a TypeScript monorepo managed with pnpm workspaces and Turborepo. Identify the owning package before editing and preserve package boundaries, task dependencies, and public APIs.

## Start here

- Find the nearest package.json and read its name, scripts, dependencies, and package-level instructions.
- Use workspace filters instead of running every task while iterating.
- Read shared package APIs before copying utilities across workspace boundaries.
- Preserve user changes, pnpm-lock.yaml, workspace configuration, and existing task pipelines.

## Commands

- `pnpm install`: install the workspace from the lockfile.
- `pnpm turbo run dev --filter=<package>`: start the target package and required dependencies.
- `pnpm turbo run test --filter=<package>`: test the target package.
- `pnpm turbo run lint --filter=<package>`: lint the target package.
- `pnpm turbo run typecheck --filter=<package>`: type-check the target package.
- `pnpm turbo run build --filter=<package>...`: build the target package and its dependents.

Replace task names and filters with the scripts defined by this repository.

## Repository map

- `apps/`: deployable applications.
- `packages/`: shared libraries, configuration, and design-system packages.
- `turbo.json`: task graph, inputs, outputs, caching, and environment declarations.
- `pnpm-workspace.yaml`: workspace membership.
- `.changeset/`: release notes and version intent when Changesets is used.

## Monorepo rules

- Make changes in the package that owns the behavior. Do not reach into another package's private source.
- Import through documented package entry points, not relative paths across package boundaries.
- Keep dependency direction acyclic and consistent with existing layers.
- Add a dependency to the narrowest package that needs it; do not add application-only dependencies at the workspace root.
- Update task inputs or outputs only when the produced artifacts or environment requirements actually change.
- Do not disable caching globally to work around a missing task declaration.

## Releases and compatibility

- Preserve public exports unless the task explicitly authorizes a breaking change.
- Add a Changeset for user-visible package changes when the repository's release process requires one.
- Do not modify versions, publish packages, or apply broad lockfile rewrites without explicit scope.
- Note which applications or packages consume a changed public API.

## Testing and validation

- Run filtered checks for the owning package while iterating.
- Before completion, build or test affected dependents using the repository's graph-aware command.
- Verify that generated output directories match turbo.json outputs when build tasks change.
- Fix failures caused by the change; distinguish unrelated failures in the handoff.

## Definition of done

- The owning package and affected dependents build and test successfully.
- Package boundaries, exports, and the task graph remain coherent.
- Required Changesets or release notes are present, but no package was published.
- No unrelated workspace configuration, lockfiles, or user changes were modified.
- The final handoff lists affected packages, commands run, and remaining release risk.