AGENTS.md

1# AGENTS.md
2 
3This is the context file for *this* repository -- the one about context engineering. `CLAUDE.md` is symlinked to this file for Claude Code compatibility. For usage notes and an overview of what's here, read the [README](README.md).
4 
5## What This Project Is
6 
7A public companion repo to [Rethinking Team Topologies for AI-Augmented Development](https://brianfending.substack.com/p/rethinking-team-topologies-for-ai). Working examples of context file structures (single-file, context directory, cascading, agents) alongside reference copies of the context-setup plugin (which has since moved!). Patterns you understand are here, IDE helpers you can install from [ordovera/ordovera-plugins](https://github.com/ordovera/ordovera-plugins).
8 
9## Structure
10 
11- `examples/` -- All patterns and templates, organized by complexity level
12  - `single-file/` -- Four single-file AGENTS.md examples at different complexity levels
13  - `directory/` -- Full context directory with six template files
14  - `cascading-files/` -- Global, project, and subdirectory cascading examples
15  - `agents/` -- Agent-as-workflow pattern with two example agents and shared config
16  - `agent-teams/` -- Multi-agent teams with optional Jira integration (activation, team structure, phases, templates)
17- `examples/claude-config/` -- Working skills and hooks configuration (copy to `.claude/`)
18- `plugins/` -- Reference copies of Claude Code plugins (install from [ordovera/ordovera-plugins](https://github.com/ordovera/ordovera-plugins) instead)
19  - `context-setup/` -- Scaffold, audit, align, optimize MCP tools, usage diagnostics, and upgrade context files
20- `evolution.md` -- What changed since the June 2025 article
21 
22## Standards
23 
24- No emojis, no decorative symbols
25- kebab-case filenames
26- Direct, practitioner voice -- not academic, not marketing
27- Conventional commits (feat/fix/docs/etc)
28- All markdown must pass markdownlint (MD013 disabled for line length)
29- Example files use `[bracket]` placeholders -- no fictional companies or products
30 
31## Navigation
32 
33Read different files depending on the task:
34 
35- Adding or editing examples: read the target directory's `README.md` first, then the existing examples for the pattern
36- Understanding the repo's purpose and framing: `README.md`
37- Understanding what changed since the article: `evolution.md`
38- Understanding cross-agent coordination: `examples/agents/README.md` and `examples/agents/shared-config.json`
39- Setting up agent teams with Jira: `examples/agent-teams/README.md`
40- Setting up skills and hooks via copy: `examples/claude-config/README.md`
41- Installing skills via plugin: install from [ordovera/ordovera-plugins](https://github.com/ordovera/ordovera-plugins); local `plugins/context-setup/` is a reference copy
42 
43## File Format Convention
44 
45Every example file follows the same structure:
46 
471. **Title and intro** -- what this example is, when to use it (2-3 sentences)
482. **Fenced template** -- the actual AGENTS.md content the reader would copy, wrapped in backtick fences
493. **Notes section** -- explains why the template is structured this way, when to graduate to something more complex
50 
51Files containing nested markdown code blocks use 4-backtick outer fences (`` ```` ``) to avoid parsing issues. Template content uses `[bracket]` placeholders describing the *kind* of content that belongs there.
52 
53## Do NOT
54 
55- Add fictional company names, product names, or branded examples
56- Add application code -- this is a documentation-only repo
57- Modify example templates without updating the corresponding README if structure changes
58- Add new top-level sections without updating the root README file tree
59