# 5-Layer AI Agent Instruction Hierarchy — Starter Kit Companion reference kit for **[What Goes Where: Layered AGENTS.md Files and Tiered Model Routing](https://vacuumbreather.com/writing/tiered-ai-agent-hierarchy/)**. The kit addresses two habits: 1. **Flat context bloat:** Stuffing framework rules, PowerShell gotchas, UI design tokens, and old audit notes into one monolithic `AGENTS.md` or `CLAUDE.md` that loads on every turn. The main cost is adherence; in tokens it is a few percent of a long session (the article shows the arithmetic). 2. **Untiered delegation:** Spawning subagents without an explicit `model:` so file searches, test runs, and boilerplate edits quietly inherit your most expensive frontier model. This is where most of the money is. ## File Map ("What Goes Where") | File in This Kit | Target Path in Your Setup | Layer & Load Cadence | |---|---|---| | `GLOBAL_POLICY.md` | `~/.claude/CLAUDE.md` + slim pointer in `~/.copilot/copilot-instructions.md` | **Layer 1 (Global):** Universal engineering, scope, verification, and anti-duplication laws. Written once per machine. | | `WORKSPACE_AGENTS.md` | `~/Projects/Git/AGENTS.md` (multi-repo parent folder) | **Layer 2 (Workspace):** 3-tier model routing matrix, explicit subagent contract, cross-repo isolation, IDE buffer cautions. | | `REPO_AGENTS.md` | `/AGENTS.md` (+ 25-line `.github/copilot-instructions.md` pointer) | **Layer 3 (Repository):** Explicit read order (`../AGENTS.md`), stack lock-in, branch/review mode, protected surfaces, test gates. | | `powershell-iac.instructions.md` | `/.github/instructions/powershell-iac.instructions.md` (Claude Code: `.claude/rules/powershell-iac.md` with `paths:` instead of `applyTo:`) | **Layer 4 (Path-Scoped Rule):** Loaded **only** when touching `**/*.{ps1,psm1,psd1,bicep,tf}` via `applyTo:` frontmatter. Codex has no globs; use a nested `AGENTS.md`. | | `explorer.agent.md` | `/.github/agents/explorer.agent.md` | **Layer 4 (Subagent):** Read-only Tier 3 codebase search & citation mapper. | | `investigator.agent.md` | `/.github/agents/investigator.agent.md` | **Layer 4 (Subagent):** Tier 2 multi-file research, schema/doc verification, and audit pass. | | `builder.agent.md` | `/.github/agents/builder.agent.md` | **Layer 4 (Subagent):** Tier 2 scoped implementation executor working from a tight Tier 1 spec. | | `verifier.agent.md` | `/.github/agents/verifier.agent.md` | **Layer 4 (Subagent):** Tier 3 deterministic linter/test runner (literal exit codes, zero polling loops). | ## Adapting the Model IDs Replace the placeholder model IDs (``, ``, ``, ``) in `WORKSPACE_AGENTS.md` and `*.agent.md` with the exact runtime identifiers exposed by your editor or CLI harness (for example, Claude Opus / Sonnet / Haiku, Gemini Pro / Flash, or GPT / Codex equivalents). Keep **Tier 1** strictly pinned without automatic downgrade fallbacks on safety-critical work.