By name: agent-navigation-sop description: |- Generate AGENTS.md for AI agent navigation. Covers build/test commands, coding conventions, task routing, and codebase structure. Use for /init workflow or when creating agent-readable repository documentation.
Examples: - user: "/init" → full AI navigation AGENTS.md + skill recommendations - user: "/init basic" → minimal AGENTS.md structure only - user: "Create AGENTS.md for this repo" → assess complexity, generate navigation doc - user: "Document codebase for AI agents" → structured AGENTS.md with task routing
Standard operating procedure for generating AGENTS.md files optimized for AI agent consumption.
Phase 1: Complexity Assessment (MANDATORY)
MUST complete before any other action:
- Directory scan:
ls -laat root, count top-level directories - Monorepo check: Look for
packages/,workspaces/,apps/, multiplepackage.json - Dependency count: Scan
package.json,pyproject.toml,go.mod,Cargo.toml - Language detection: Identify primary and secondary languages
Complexity thresholds:
| Indicator | Simple | Complex |
|---|---|---|
| Top-level dirs | ≤10 | >10 |
| Dependencies | ≤50 | >50 |
| Languages | 1 | 2+ |
| Monorepo patterns | None | Present |
Phase 2: Analysis Method
Based on complexity:
- Simple repo: Proceed directly with glob/read tools
- Complex repo: MUST dispatch explore subagent:
Task tool with subagent_type: "explore" Prompt: "Analyze repository structure, build systems, test commands, coding conventions. Return structured summary for AI navigation AGENTS.md. Thoroughness: [quick|medium|very thorough]"
Phase 3: Information Gathering
MUST collect from repo:
- Build commands (
npm run build,make,cargo build, etc.) - Test commands (unit, integration, e2e)
- Lint/format commands
- Type checking commands
- Code generation commands (e.g.,
convex codegen,prisma generate) - Entry points (main files, CLI commands)
- Configuration files (tsconfig, eslint, prettier, etc.)
- Key directories and their purposes
- Coding conventions (from existing code patterns)
- Existing AI rules - check for and incorporate:
.cursor/rules/directory.cursorrulesfile.github/copilot-instructions.md- Any other AI assistant configuration
Phase 4: AGENTS.md Generation
Structure using XML tags:
## Repository Overview
[1-2 sentences: what this repo does]
<instructions>
## Build & Test
- Build: `exact command`
- Test: `exact command`
- Lint: `exact command`
- Typecheck: `exact command`
- Codegen: `exact command` (if applicable)
</instructions>
<rules>
## Process Constraints
- MUST NOT run long-running/blocking processes (dev servers, watch modes)
- Dev servers are USER's responsibility to run in background
- MUST use one-shot verification commands only
## Coding Conventions
- [Pattern observed in codebase]
- [Naming conventions]
- [File organization rules]
</rules>
<routing>
## Task Navigation
| Task | Entry Point | Key Files |
|------|-------------|-----------|
| Add feature | src/features/ | README in dir |
| Fix bug | src/ | Related test file |
</routing>
<context_hints>
## Context Allocation
- **Large/generated**: [files to skip or skim]
- **Legacy zones**: [directories with tech debt]
- **Critical configs**: [files that break everything]
</context_hints>
Phase 5: Skill Recommendations (Full Mode Only)
If running full workflow (not basic):
- Identify repetitive tasks in the codebase
- Suggest skills that would benefit agents working here
- Offer to create skills using
skill-creator
CRITICAL: Long-Running Processes
The generated AGENTS.md MUST include a rule forbidding agents from running blocking processes.
This is not just about what commands to document - the AGENTS.md MUST explicitly instruct agents:
<rules>
## Process Constraints
- MUST NOT run long-running/blocking processes (dev servers, watch modes)
- Dev servers (`npm run dev`, `bun dev`, `convex dev`, etc.) are USER's responsibility
- User will run these in background and make them available to the agent
- MUST use one-shot commands for verification (build, lint, test, typecheck)
</rules>
Commands to document vs avoid:
| MUST NOT Document | Document Instead |
|---|---|
npm run dev |
npm run build |
bun run dev |
npm run lint |
npm start (if blocking) |
npm run typecheck |
convex dev |
convex codegen |
next dev |
next build |
vite / vite dev |
vite build |
tsc --watch |
tsc --noEmit |
jest --watch |
jest / npm test |
Good commands for AGENTS.md:
- One-shot builds:
npm run build,make,cargo build - Linting:
npm run lint,eslint .,oxlint - Type checking:
tsc --noEmit,pyright - Testing:
npm test,pytest,go test ./... - Code generation:
convex codegen,prisma generate,graphql-codegen - Formatting:
prettier --check .,cargo fmt --check
Requirements
MUST
- Assess complexity before choosing analysis method
- Use explore subagent for complex repositories
- Verify all file paths exist before referencing
- Use exact, copy-pasteable commands
- Use RFC 2119 keywords (MUST, SHOULD, MAY) in generated content
- Use XML tags for section boundaries
- Document one-shot verification commands (build, lint, test, typecheck, codegen)
SHOULD
- Incorporate existing AI rules if present
- Keep output ~150 lines for new files
MUST NOT
- Include long-running/blocking processes (dev servers, watch modes)
- Include prose that doesn't change agent behavior
- Reference files/directories without verifying they exist
- Guess at commands - verify against package.json, Makefile, etc.
Quality Checklist
- Complexity assessed FIRST
- Explore subagent used for complex repos
- All paths verified to exist
- Commands are exact (copy-pasteable)
- NO blocking/long-running processes included
- One-shot commands for build/lint/test/typecheck documented
- XML tags used for section boundaries
- RFC 2119 keywords used appropriately
- No prose that doesn't change agent behavior