agents-md-generator

1. Root AGENTS.md is LIGHTWEIGHT - Only universal guidance, links to sub-files (~100-200 lines max)
2. Nearest-wins hierarchy - Agents read closest AGENTS.md to file being edited
3. JIT indexing - Provide paths/globs/commands, NOT full content
4. Token efficiency - Small, actionable guidance over encyclopedic docs
5. Sub-folder files have MORE detail - Specific patterns, examples, commands

Phase 1: Repository Analysis

Analyze and report:

1. Repository type: Monorepo, multi-package, or simple?
2. Tech stack: Languages, frameworks, key tools
3. Major directories needing own AGENTS.md:

- Apps (apps/web, apps/api, apps/mobile)

- Services (services/auth, services/transcribe)

- Packages (packages/ui, packages/shared)

- Workers (workers/queue, workers/cron)

1. Build system: pnpm/npm/yarn workspaces? Turborepo? Lerna?
2. Testing setup: Jest, Vitest, Playwright, pytest?
3. Key patterns: Organization, conventions, examples, anti-patterns

Present as structured map before generating files.

Phase 2: Root AGENTS.md

Create lightweight root (~100-200 lines):

```markdown

# Project Name

[3-5 lines: repo type, tech stack, note about sub-AGENTS.md files]

[5-10 lines: install, build all, typecheck all, test all]

[5-10 lines: code style, commit format, branch strategy, PR requirements]

[3-5 lines: never commit tokens, .env patterns, PII handling]

Package Structure

• Web UI: apps/web/ -> [see apps/web/AGENTS.md](apps/web/AGENTS.md)
• API: apps/api/ -> [see apps/api/AGENTS.md](apps/api/AGENTS.md)

Quick Find Commands

• Search function: rg -n "functionName" apps/ packages/
• Find component: rg -n "export.*ComponentName" apps/web/src
• Find API routes: rg -n "export const (GET|POST)" apps/api

[3-5 lines: what must pass before PR]

```

Phase 3: Sub-Folder AGENTS.md

For each major package, create detailed AGENTS.md:

```markdown

# Package Name

[2-3 lines: what it does, primary tech]

[5-10 lines: install, dev, build, test, lint commands]

[10-20 lines - MOST IMPORTANT SECTION]

• File organization rules
• Naming conventions
• Examples with actual file paths:

- DO: Use pattern from src/components/Button.tsx

- DON'T: Class components like src/legacy/OldButton.tsx

- Forms: Copy src/components/forms/ContactForm.tsx

- API calls: See src/hooks/useUser.ts

[5-10 lines: important files to understand package]

• Auth: src/auth/provider.tsx
• API client: src/lib/api.ts
• Types: src/types/index.ts

[5-10 lines: search commands for this package]

• Find component: rg -n "export function .*" src/components
• Find hook: rg -n "export const use" src/hooks
• Find tests: find . -name "*.test.ts"

[3-5 lines if applicable]

• "Auth requires NEXT_PUBLIC_ prefix for client-side"
• "Always use @/ imports for absolute paths"

[2-3 lines: copy-paste command]

pnpm --filter @repo/web typecheck && pnpm --filter @repo/web test

```

Phase 4: Special Templates

#### Design System / UI Package

```markdown

• Components: packages/ui/src/components/**
• Use design tokens from packages/ui/src/tokens.ts
• Component gallery: pnpm --filter @repo/ui storybook
• Examples:

- Buttons: packages/ui/src/components/Button/Button.tsx

- Forms: packages/ui/src/components/Input/Input.tsx

```

#### Database / Data Layer

```markdown

• ORM: Prisma / Drizzle / TypeORM
• Schema: prisma/schema.prisma
• Migrations: pnpm db:migrate
• Connection: via src/lib/db.ts singleton
• NEVER run migrations in tests

```

#### API / Backend Service

```markdown

• REST routes: src/routes/*/.ts
• Auth middleware: src/middleware/auth.ts
• Validation: Zod schemas in src/schemas/**
• Errors: ApiError from src/lib/errors.ts
• Example: src/routes/users/get.ts

```

#### Testing

```markdown

• Unit: *.test.ts colocated
• Integration: tests/integration/**
• E2E: tests/e2e/** (Playwright)
• Single test: pnpm test -- path/to/file.test.ts
• Mocks: src/test/mocks/**

```

Provide files in order:

1. Analysis Summary
2. Root AGENTS.md (complete)
3. Each Sub-Folder AGENTS.md (with file path)

Format:

```

---

File: AGENTS.md (root)

---

[content]

---

File: apps/web/AGENTS.md

---

[content]

```

Before generating, verify:

• [ ] Root AGENTS.md under 200 lines
• [ ] Root links to all sub-AGENTS.md files
• [ ] Each sub-file has concrete examples (actual paths)
• [ ] Commands are copy-paste ready
• [ ] No duplication between root and sub-files
• [ ] JIT hints use actual patterns (ripgrep, find, glob)
• [ ] Every "DO" has real file example
• [ ] Every "DON'T" references real anti-pattern
• [ ] Pre-PR checks are single commands