agent-navigation-sop

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:

Phase 2: Analysis Method

Based on complexity:

• •Simple repo: Proceed directly with glob/read tools
• •Complex repo: MUST dispatch explore subagent:
  code

  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:

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