Agent instructionsScan: pass
AGENTS.md with Nested Packages
Root AGENTS.md for a monorepo plus a per-package AGENTS.md template, with a precedence note that matches how agents resolve nested files.
Add a trust badge to your README
[](https://waxmark.app/items/agents-md-with-nested-packages/scan)
# {{PROJECT_NAME}} monorepo
Workspace managed by {{PM}}. Apps in `apps/`, shared libraries in `packages/`. Run every command from the repo root unless a package's own `AGENTS.md` says otherwise.
## Precedence
- This file applies everywhere in the repository.
- Each `apps/*` and `packages/*` directory may contain its own `AGENTS.md`. When you edit a file, the closest `AGENTS.md` up the directory tree from that file takes precedence over this one for anything the two disagree on.
- Nested files add detail; they do not repeat this file. If a nested file is silent on a topic, this file's rule stands.
- Instructions the user gives in chat override every `AGENTS.md`.
## Map
| Path | Package | Owner notes |
|------|---------|-------------|
| `apps/{{WEB_APP}}` | `@{{SCOPE}}/{{WEB_APP}}` | Deployable web app; has its own `AGENTS.md` |
| `apps/{{API_APP}}` | `@{{SCOPE}}/{{API_APP}}` | Deployable API; has its own `AGENTS.md` |
| `packages/ui` | `@{{SCOPE}}/ui` | Shared components |
| `packages/config` | `@{{SCOPE}}/config` | Shared tsconfig / lint config; rarely changes |
## Commands (repo root)
```sh
{{PM}} install # install all workspaces
{{PM}} turbo run build lint typecheck test # everything
{{PM}} turbo run test --filter=@{{SCOPE}}/ui # one package
{{PM}} turbo run test --filter='...[origin/main]' # only what changed vs main
{{PM}} --filter @{{SCOPE}}/{{WEB_APP}} dev # dev server for one app
```
Definition of done: `{{PM}} turbo run lint typecheck test --filter='...[origin/main]'` exits 0. Paste the summary line.
## Cross-package rules
- Import internal packages by name (`@{{SCOPE}}/ui`), never by relative path across a package boundary, and never from another package's `src/`.
- Code used by one app stays in that app. Code used by two or more apps moves to `packages/`.
- Internal dependencies are declared with `"workspace:*"`.
- Shared config is extended, not copied.
- Any change to a package in `packages/` is a change to every consumer: run the dependents' tests (`--filter=...@{{SCOPE}}/<pkg>`).
## Git
- Branch from `main`. One package or one concern per PR where possible; title prefixed with the package name, for example `ui: add Toast variant`.
- Changes to `packages/*` need a changeset (`{{PM}} changeset`) committed alongside.
## Ask before
Deleting a package, changing a package's public exports, editing `turbo.json` or the workspace file, or adding a root-level dependency.
---
## Template: `packages/{{PACKAGE_NAME}}/AGENTS.md`
Copy this into each package and fill it in. Keep it under 40 lines.
```markdown
# @{{SCOPE}}/{{PACKAGE_NAME}}
{{PACKAGE_PURPOSE}}. Consumers: `apps/{{WEB_APP}}`, `apps/{{API_APP}}`.
The root `AGENTS.md` applies; this file adds package-specific rules.
## Commands (from repo root)
- Test: `{{PM}} turbo run test --filter=@{{SCOPE}}/{{PACKAGE_NAME}}`
- Test dependents too: `{{PM}} turbo run test --filter=...@{{SCOPE}}/{{PACKAGE_NAME}}`
- Build: `{{PM}} turbo run build --filter=@{{SCOPE}}/{{PACKAGE_NAME}}`
## Layout
- `src/index.ts` is the only public entry point. Anything not exported there is private.
- Tests next to source as `*.test.ts`.
## Rules specific to this package
- (example) Components accept `className` and forward refs.
- (example) No runtime dependency on `react-dom`; this package is also used in React Native.
## Gotchas
- (example) `build` must run before dependents can typecheck; turbo handles the order, do not run `tsc` here directly.
```