| name | hierarchical-agents |
| description | Generate hierarchical AGENTS.md structure for codebases to optimize AI agent token usage. Use when creating AGENTS.md files, documenting codebase structure, setting up agent guidance, organizing project documentation for AI tools, implementing JIT indexing, or working with monorepos that need lightweight root guidance with detailed sub-folder documentation. Covers repository analysis, root AGENTS.md generation, sub-folder AGENTS.md creation, and token-efficient documentation patterns. |
Hierarchical Agents Documentation Generator
Purpose
Create a hierarchical AGENTS.md system for codebases that enables AI coding agents to work efficiently with minimal token usage. Generates lightweight root documentation with detailed sub-folder guidance following the "nearest-wins" principle.
When to Use
- Creating AGENTS.md documentation for a new project
- Setting up AI agent guidance for a monorepo
- Optimizing existing documentation for token efficiency
- Implementing JIT (Just-In-Time) indexing patterns
Process
Follow these phases in order. See references/generation-process.md for complete details.
Phase 1: Repository Analysis
Analyze the codebase:
- Repository type (monorepo, multi-package, simple)
- Technology stack (languages, frameworks, tools)
- Major directories (apps, services, packages)
- Build system and testing setup
- Key patterns, conventions, anti-patterns
Output: Structured map of the repository before generating any files.
Phase 2: Generate Root AGENTS.md
Root must be lightweight: ~100-200 lines maximum, universal guidance only. Acts as index and navigation hub. Agents read the closest AGENTS.md to the file being edited — sub-folder files override root (nearest-wins).
Create root file with these sections:
