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:

</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:

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>