hierarchical-agents

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:

1. Repository type (monorepo, multi-package, simple)
2. Technology stack (languages, frameworks, tools)
3. Major directories (apps, services, packages)
4. Build system and testing setup
5. 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:

1. Project Snapshot (3-5 lines)
   • Repo type
   • Primary tech stack
   • Note about sub-package AGENTS.md files
2. Root Setup Commands (5-10 lines)
   • Install dependencies, build all, typecheck all, test all
3. Universal Conventions (5-10 lines)
   • Code style (TypeScript strict? Prettier? ESLint?)
   • Commit format (Conventional Commits?)
   • Branch strategy
   • PR requirements
4. Implementation Rules (2-3 lines) — see example below
5. Development Workflow (5-7 lines) — see example below
6. Security & Secrets (3-5 lines)
   • Never commit tokens
   • Where secrets go (.env patterns)
   • PII handling
7. JIT Index - Directory Map (10-20 lines) — see example below
   • Reference files by path, not content
   • Provide search commands that agents can execute
8. Acceptance Criteria (3-5 lines)
   • Pre-PR checklist
   • What must pass

Example Implementation Rules:

## Implementation Rules

Before adding ANY external dependency (gems, npm packages, GitHub Actions, Docker images, APIs, CDN links):
- Use WebSearch to verify the latest stable version BEFORE implementation
- Never trust training data for version numbers

Example JIT Index:

## JIT Index (what to open, not what to paste)

### 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)
- Shared packages: `packages/**/` -> [see packages/README.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`

Example Development Workflow:

## Development Workflow

- Before coding -> describe approach -> wait for approval
- Ambiguous requirements -> ask first
- If task touches >3 files -> decompose first
- After coding -> list breakage risks + suggest tests
- Bug fix -> write failing test -> fix until green
- When corrected -> add lesson to .agents/lessons/

Phase 3: Generate Sub-Folder AGENTS.md Files

Sub-folders have MORE detail than root — specific patterns, technology-specific conventions, real file examples from the codebase.

For EACH major package/directory, create detailed AGENTS.md:

1. Package Identity (2-3 lines)
2. Setup & Run (5-10 lines)
3. Patterns & Conventions (10-20 lines) - MOST IMPORTANT
4. Touch Points / Key Files (5-10 lines)
5. JIT Index Hints (5-10 lines)
6. Common Gotchas (3-5 lines)
7. Pre-PR Checks (2-3 lines)

Key: Patterns & Conventions must include real file paths with DO/DON'T examples.

Phase 4: Special Considerations

Adapt templates for specific package types (Design System, Database, API, Testing). See references/generation-process.md for specialized templates.

Directory Structures

Monorepo

AGENTS.md                    # Root (lightweight)
apps/
  web/AGENTS.md             # Frontend details
  api/AGENTS.md             # Backend details
packages/
  ui/AGENTS.md              # Design system details
  shared/AGENTS.md          # Shared code details

Simple Project

AGENTS.md                    # Root (can be more detailed)
src/
  components/AGENTS.md      # Component patterns
  services/AGENTS.md        # Service patterns

Quality Checklist

• Root AGENTS.md is under 200 lines
• Root links to all sub-AGENTS.md files
• Each sub-file has concrete examples (actual file paths)
• Commands are copy-paste ready
• No duplication between root and sub-files
• Every DO has a real file example
• Every DON'T references real anti-pattern
• All paths are relative and verified to exist
• Only major packages/domains have AGENTS.md — not every directory

Maintenance

Update AGENTS.md when:

• Adding new packages or major directories
• Changing build/test commands
• Establishing new conventions
• Refactoring project structure

Related Resources

• references/generation-process.md - Complete step-by-step generation process with templates