agentic repository readiness

• repository root and every package: AGENTS.md + CLAUDE.md.
• AGENTS.md owns the instructions; CLAUDE.md only points to the sibling AGENTS.md, never duplicates it.
• an instruction file owns only its directory tree:
  • root file: repository-wide rules + table of contents.
  • package file: that package's purpose, boundaries, commands, local conventions.
  • nested file: only rules narrower than its parent can own.
• root contract is a router, not a knowledge base: durable law links to its standards corpus, repeatable mechanics link to their procedure, package commands stay with the package. when a correction grows into several conditions, examples, or commands, move it to that owner and keep only the trigger and link.

• mindset: read first, then code. before changing a scoped file, an agent reads the nearest AGENTS.md, the target file heading, the owning specification, and the directly related code — then states the intended boundary and verifies the changed behavior.
• this prevents treating a directory listing, prompt fragment, or single call site as the whole system.
• consequences of skipping the contract read:
  • edits without knowing ownership or invariants — read-only caches, generated artifacts, coordination boundaries get modified.
  • concurrent agents make conflicting assumptions about the same subsystem.
  • features built from one file's local logic violate stability guarantees or ownership boundaries.
  • completion claimed while unrelated work breaks elsewhere.
  • with concurrent agents, the contract is the only shared authority preventing silent conflicts; without it, every agent rediscovers the same constraints from scattered comments and never establishes common ground.

• an agent that edits without a scoped contract learns the system from a directory listing and one call site, then makes ownership and invariant decisions on that partial map: editing generated artifacts, crossing boundaries that need coordination, claiming completion over broken neighbors.
• a small read-first AGENTS.md per scope makes the shared authority explicit before the first edit.
• invariant protected: scope, ownership, and verification boundary are stated before code changes.

AGENTS.md                 # repository contract and table of contents
CLAUDE.md                 # read AGENTS.md first
apps/
  frontend/
    AGENTS.md             # frontend-only contract
    CLAUDE.md             # read AGENTS.md first
packages/
  base/
    AGENTS.md             # base-package-only contract
    CLAUDE.md             # read AGENTS.md first

• root table of contents links to each package instruction file, the specification index, domain glossary, architecture decisions, commands, and deployment owner. a navigation map, not a second copy of package rules.
• temporary probes, downloaded inputs, generated intermediates, logs, caches, one-off scripts stay outside the repository unless an approved product artifact. the machine-level contract names the exact temporary root; project instructions do not invent another scratch location.

• use exact paths and commands.
• remove stale instructions in the same forward-only change that replaces them.
• a generic policy an agent cannot turn into the next correct action is not a useful instruction.

read and follow the sibling `AGENTS.md` before inspecting or editing this
scope. it is the complete instruction contract for this directory tree.

• one AGENTS.md reference in plain text. it is a repository entry file in Markdown, not a corpus document — it does not link into the published collection.

bad

AGENTS.md (bloated):

# Monorepo

... 200 lines covering everything ...

Frontend section:
- Color tokens: primary=#2563eb, secondary=#6366f1
- tailwind config in apps/frontend/tailwind.config.ts
- Next.js version must match apps/frontend/package.json
- dev server: pnpm --filter frontend dev
- build output: apps/frontend/.next

Database section:
- migrations in apps/backend/drizzle/migrations
- run: drizzle-kit generate then wrangler d1 migrations apply
- schema tables: users, orders, payments
- Drizzle ORM, D1 database, TypeORM for legacy

Deployment section:
- frontend: vercel deploy from main
- backend: wrangler publish from apps/backend
- database: migrate production with [command]
- ...

• a frontend agent must read database and deployment sections it does not own; seeing apps/backend/drizzle/migrations, it cannot tell whether a backend script runs them or a separate command is required.
• a migration-bug agent reads "drizzle-kit generate then wrangler d1" in the root, then the backend package's actual process — two instructions now own conflicting authority.
• a third agent adds a tool and updates the root without checking the backend package's dependency on it — hidden incompatibility.

good

AGENTS.md (root contract, ~80 lines):

# Monorepo

Repository purpose, source-of-truth order, links to standards and procedures.

Workspace Map:
| Package       | Role                       | Contract                                           |
| ------------- | -------------------------- | -------------------------------------------------- |
| apps/frontend | SSR Next.js web app        | [apps/frontend/AGENTS.md](apps/frontend/AGENTS.md) |
| apps/backend  | Cloudflare Worker API      | [apps/backend/AGENTS.md](apps/backend/AGENTS.md)   |
| packages/base | Shared types and contracts | [packages/base/AGENTS.md](packages/base/AGENTS.md) |

Commands:
root coordinates the task graph:
pnpm install && turbo run generate format build lint typecheck

each package runs its own lifecycle scripts; see the package contract.

Standards:
project standards at /workspace/project; this project applies guru standards per [AGENTS.md](CLAUDE.md).

apps/frontend/AGENTS.md (self-contained):

# Frontend (Next.js App)

Purpose: SSR public web experience on localhost:20000, deployed via OpenNext.

Local Commands:
- pnpm --filter @scope/frontend dev
- pnpm --filter @scope/frontend build
- pnpm --filter @scope/frontend lint

Tailwind and Design Tokens:
semantic-token system at src/tokens; see [design.mdx](../../docs/content/domains/design.mdx).

Dependencies:
see apps/frontend/package.json; root manages only turbo and the workspace.

apps/backend/AGENTS.md (self-contained):

# Backend (Cloudflare Worker + D1)

Purpose: Hono API worker, deployed to worker.example.com

Migrations:
migrations live in src/infra/drizzle-orm/migrations.
pnpm --filter @scope/backend generate # outputs openapi.json
wrangler d1 migrations apply --local

see [backend.mdx](../../docs/content/domains/backend.mdx#database-migrations) for schema authority.

• a frontend-bug agent reads only apps/frontend/AGENTS.md and knows its scope; backend dependencies name their owner.
• a backend agent sees the exact invocation, not a generic summary.
• the root file is a map, not a second copy of package knowledge.

1. every repository root and package has both files.
2. each CLAUDE.md points only to its sibling AGENTS.md.
3. a package contract read without the root explains that package only.
4. every root-table-of-contents link resolves to its owner.
5. before editing, the read-first sequence is possible from the scoped instructions alone.

specification-first · code file headings · layered source organization · compounding engineering · verification evidence · navigable folder structure