AGENTS.md Generation Capability

AGENTS.md

Core Capability

• Function: Analyze repository structure and generate or update a standardized

  AGENTS.md

  document
• Output Format: Markdown file with structured sections
• Character Limit: Dynamic, based on repository LOC (Lines of Code)
• Monorepo Support: Automatically detects monorepo structures and generates hierarchical documentation (Root + Packages)
• Update Support: Refreshes only standard sections in an existing

  AGENTS.md

  , preserving user-defined custom sections

Output Sections

Single Repo / Package Document (5 Sections)

• Overview: 1-2 sentence project description (abstract, no tool/framework lists)
• Folder Structure: Key directories and their contents
• Core Behaviors & Patterns: Logging, error handling, control flow, module structure patterns observed in code
• Conventions: Naming, comments, code style derived from analysis
• Working Agreements: Rules for agent behavior and communication

Monorepo Root Document (3 Sections)

• Overview: 1-2 sentences describing the monorepo's purpose
• Folder Structure: High-level map of apps, packages, and shared configs
• Working Agreements: Common working agreements applicable to all packages

Operation Modes

Generate vs Update

• Generate: Creates a new

  AGENTS.md

  from scratch (default when no

  AGENTS.md

  exists)
• Update: Refreshes standard sections in an existing

  AGENTS.md

  while preserving custom sections. See ./references/update_strategy.md for detailed workflow and section matching rules.

AGENTS.md

Generation Modes (Monorepo)

Tools

• tokei

  : LOC measurement (required)

• rg

  (ripgrep): Content search (preferred)

• grep

  /

  Select-String

  : Content search (fallback per OS)

• sed -n

  /

  Get-Content \| Select-Object

  : Paginated file reading per OS

• tree

  : Directory structure visualization

• find

  : File and directory discovery (Linux / macOS)

• ls

  ,

  pwd

  : Basic directory navigation

Domain Knowledge

• LOC Measurement: Capability to measure repository size and determine character limits. See ./references/loc_measurement.md
• Repository Analysis: Capability to inspect and understand codebase structure. See ./references/read_only_commands.md
• Output Template: Standardized AGENTS.md structure specification. See ./references/agents_md_template.md
• Working Agreements: Agent behavior rules for generated documents. See ./references/working_agreements.md
• Monorepo Detection: Capability to identify monorepo structures. See ./references/monorepo_detection.md
• Monorepo Strategy: Strategy for generating documentation in monorepos. See ./references/monorepo_strategy.md
• Update Strategy: Strategy for updating existing AGENTS.md files with selective section refresh. See ./references/update_strategy.md

Scope Boundaries

• Read-Only Analysis: Supports non-destructive commands for repository inspection
• Output Scope: Produces documentation content only; excludes run/test/build/deploy instructions
• Excluded Inputs: Lock files (

  pnpm-lock.yaml

  ,

  package-lock.json

  ,

  yarn.lock

  , etc.) are outside analysis scope