Specialist context files loaded on demand by AI coding agents. The orchestration entry point is AGENTS.md in the repo root — read that first. It tells you when to load each of these.

.agents/
├── rules/        ← checklists and constraints for specific kinds of work
├── personas/     ← role and voice presets to adopt
└── workflows/    ← multi-step procedures for recurring tasks

Each subdirectory has its own README.md listing the files inside and what they're for. The authoritative routing tables — when to load each file — live in AGENTS.md, not here.

The three categories are deliberately different shapes. Putting a file in the wrong one is the most common failure mode of this system.

If a file mixes two of these, split it. A persona that contains a checklist belongs partly in personas/ (the voice) and partly in rules/ (the checklist), with the persona referencing the rule.

1. Decide which subdirectory (rules/, personas/, workflows/).
2. Create the file there.
3. Add a row to the matching table in AGENTS.md describing when to load it.
4. Update the subdirectory's README.md if you want a longer description.
5. Keep it focused — if it grows past ~200 lines, split it.

• These files are read by AI agents. Write for that audience: direct, structured, no marketing voice.
• Checklists with [ ] boxes are intentional — agents and humans both work better with them.
• Examples are concrete. Abstract advice without examples gets misapplied.
• Cross-reference, don't duplicate. If you find yourself repeating something from another file, link instead.