agent-navigation-sop

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:

1. Directory scan: ls -la at root, count top-level directories
2. Monorepo check: Look for packages/, workspaces/, apps/, multiple package.json
3. Dependency count: Scan package.json, pyproject.toml, go.mod, Cargo.toml
4. 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
  • .cursorrules file
  • .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):

1. Identify repetitive tasks in the codebase
2. Suggest skills that would benefit agents working here
3. 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