Raw view: AGENTS.md with Nested Packages

No invisible, zero-width, or bidi-control characters detected.

# {{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.
```