AI agent documentation
This repository is set up so AI coding agents can discover project context, build and test commands, and tool-specific configuration.
The single source of truth is AGENTS.md at the repo root: layout, build/test and provider-service requirements, conventions, multi-agent workflow, and issue-tracking rules. Tool-specific files layer on top of it:
| Tool | What to use |
|---|---|
| Claude Code | CLAUDE.md (thin entry point → AGENTS.md). Task agents in .claude/agents/, skills in .claude/skills/, shared hook scripts in eng/agent-hooks/, settings in .claude/settings.json. |
| Codex | Reads AGENTS.md natively. Agent role definitions in .codex/agents/*.toml, configuration in .codex/config.toml, hooks in .codex/hooks.json. |
| GitHub Copilot | .github/copilot-instructions.md (thin pointer → AGENTS.md). |
| Other tools (Zed, ChatGPT, etc.) | AGENTS.md directly. |
Multi-agent setup
Three specialized roles are defined for both Claude Code (.claude/agents/*.md) and Codex (.codex/agents/*.toml):
| Agent | Role |
|---|---|
| engineer | Implements features, fixes bugs, refactors code |
| qa-engineer | Writes tests, validates changes, checks coverage |
| reviewer | Reviews code for correctness, style, architecture |
Isolation model
The lead session owns isolation: it creates a worktree and branch per task and dispatches agents into that prepared workspace. Agents verify their workspace (git status, git branch --show-current) before making changes and never touch the user’s main checkout. Coordination happens via branches and pull requests, not shared files. See AGENTS.md § “Multi-agent workflow”.
Guardrails
- Protected files (
VERSION,.github/,Directory.Build.props,Directory.Packages.props,nuget.config,.claude/,.codex/): a PreToolUse hook blocks direct edits and tells the agent to ask the user first. This is advisory, not a security boundary. Self-test:bash eng/agent-hooks/hooks.test.sh. - Build feedback: install the git pre-push hook with
eng/install-hooks.sh; it runs the fast local gate before pushes. Agent-time per-edit builds are intentionally not used. - Permissions:
.claude/settings.jsonpre-approves the repository test runner and common development commands (dotnet,git,gh, etc.) so agents can work without manual approval prompts.