---
name: agents-md-generator
description: Generate hierarchical AGENTS.md structures for codebases. Use when user asks to create AGENTS.md files, analyze codebase for AI agent documentation, set up AI-friendly project documentation, or generate context files for AI coding assistants. Triggers on "create AGENTS.md", "generate agents", "analyze codebase for AI", "AI documentation setup", "hierarchical agents".
---

# AGENTS.md Generator

Generate hierarchical AGENTS.md structures optimized for AI coding agents with minimal token usage.

## Core Principles

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

## Workflow

### 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
4. **Build system**: pnpm/npm/yarn workspaces? Turborepo?
5. **Testing setup**: Jest, Vitest, Playwright, pytest?
6. **Key patterns**: Organization, conventions, examples

### Phase 2: Root AGENTS.md

Create lightweight root (~100-200 lines):

```markdown
# Project Name

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

## Root Setup Commands
[5-10 lines: install, build all, typecheck all, test all]

## Universal Conventions
[5-10 lines: code style, commit format, branch strategy]

## JIT Index
- 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)

## Definition of Done
[3-5 lines: what must pass before PR]
```

### Phase 3: Sub-Folder AGENTS.md

For each major package, create detailed AGENTS.md with:
- Package Identity
- Setup & Run commands
- Patterns & Conventions (with real file examples)
- Key Files
- JIT Index Hints
- Common Gotchas
- Pre-PR Checks

## Quality Checklist

- [ ] 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