{{monorepo-name}}

AI Agent Instructions - Monorepo router. Copy to monorepo root as AGENTS.md and commit to version control.

Overview

{{One sentence describing what this monorepo contains}}

Discovery -> Activation -> Execution

Use this flow for context loading:

1. Discovery (always loaded)
2. Root topology, subproject routing, global boundaries
3. Activation (load only if task needs it)
4. Subproject AGENTS.md + relevant @docs/ references
5. Execution (load before running commands)
6. Command catalogs from workspace/subproject docs when they exist (for example @docs/scripts.md)

Structure

{{monorepo-name}}/
├── {{subproject-dir-1}}/
│   ├── {{subproject-1}}/    # {{description}}
│   ├── {{subproject-2}}/    # {{description}}
│   └── {{subproject-3}}/    # {{description}}
├── {{subproject-dir-2}}/
│   ├── {{subproject-4}}/    # {{description}}
│   └── {{subproject-5}}/    # {{description}}
├── {{shared-dir}}/          # {{description, e.g., shared config, IaC}}
└── docs/                    # Cross-project documentation

Subproject Overview (what each does):

Subproject	Purpose	Tech
{{path/name}}	{{description}}	{{stack}}
{{path/name}}	{{description}}	{{stack}}
{{path/name}}	{{description}}	{{stack}}

Commands

• Workspace package manager: {{package-manager}}

{{package-manager}} install   # Install all workspace dependencies
{{package-manager}} build     # Build all packages
{{package-manager}} test      # Run all tests
{{package-manager}} lint      # Lint all packages

• If the workspace maintains a detailed command catalog, reference it here (for example @docs/scripts.md)
• If subprojects maintain command docs, define those in each subproject's AGENTS.md
• Do not invent commands; prefer verified entries only

Task Mode Routing

Task Mode	Load by Default	Command Docs
Research / Design / Plan	Root AGENTS.md + relevant subproject AGENTS.md + topic docs	Skip unless user asks
Implement / Fix	Relevant subproject AGENTS.md + topic docs	Load relevant workspace/subproject command docs (if they exist)
Verify / Release	Relevant subproject + CI/release docs	Load relevant workspace/subproject command docs (if they exist)

Subproject Routing

Read the AGENTS.md in the relevant subproject before working there:

Working On	Read First
{{subproject-1 description}}	@{{path}}/AGENTS.md
{{subproject-2 description}}	@{{path}}/AGENTS.md
{{subproject-3 description}}	@{{path}}/AGENTS.md

Cross-Cutting Concerns

Topic	Read
{{topic, e.g., Git workflow}}	@docs/{{doc-name}}.md
{{topic, e.g., CI/CD}}	@docs/{{doc-name}}.md
Workspace commands	@docs/scripts.md (if this doc exists)

Global Boundaries

Always

• Run affected tests before committing
• Follow subproject-specific patterns (read its AGENTS.md)
• Use workspace dependencies, not external duplicates
• If command docs exist, use verified commands from those docs when executing tasks

Ask First

• Adding new subprojects
• Cross-subproject breaking changes
• Shared dependency version bumps
• Running destructive commands (reset/drop/force operations)

Never

• Commit secrets or .env files
• Modify another subproject without reading its AGENTS.md
• Push directly to main branch