agent-navigation-sop

<overview>

Standard operating procedure for generating AGENTS.md files optimized for AI agent consumption.

</overview> <workflow> <phase name="complexity-assessment">

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> <phase name="analysis-method">

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> <phase name="information-gathering">

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> <phase name="generate-output">

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> <phase name="skill-recommendations">

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

</phase> </workflow> <rules>

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

</rules> <constraints>

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.

</constraints> <guidelines>

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

</guidelines>