agent-navigation-sop

Generate AGENTS.md for AI agent navigation. Covers build/test commands, coding conventions, task routing, and codebase structure...

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 -la at root, count top-level directories
Monorepo check: Look for packages/, workspaces/, apps/, multiple package.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
- .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):

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

Generate AGENTS.md for AI agent navigation. Covers build/test commands, coding conventions, task routing, and codebase structure...

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 -la at root, count top-level directories
Monorepo check: Look for packages/, workspaces/, apps/, multiple package.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
- .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):

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

About

SKILL.md

agent-navigation-sop

About

SKILL.md

Phase 1: Complexity Assessment (MANDATORY)

Phase 2: Analysis Method

Phase 3: Information Gathering

Phase 4: AGENTS.md Generation

Phase 5: Skill Recommendations (Full Mode Only)

CRITICAL: Long-Running Processes

Requirements

MUST

SHOULD

MUST NOT

Quality Checklist

About

SKILL.md

About

SKILL.md

Phase 1: Complexity Assessment (MANDATORY)

Phase 2: Analysis Method

Phase 3: Information Gathering

Phase 4: AGENTS.md Generation

Phase 5: Skill Recommendations (Full Mode Only)

CRITICAL: Long-Running Processes

Requirements

MUST

SHOULD

MUST NOT

Quality Checklist