# Agent Configuration Specification v1.0

> Defines what "well-configured" means for AI agent development across all coding projects.

## CLAUDE.md — Required Sections

### Tier 1 (Required — blocks audit pass)

1. **Conditional Documentation Loading** — Table linking to `~/.config/mosaic/guides/`
2. **Quality Gates** — Bash commands that must pass before commit (build, test, lint, typecheck)
3. **Build/Test/Lint commands** — How to build, test, and lint the project

### Tier 2 (Recommended — logged as warning)

4. Technology Stack table
5. Repository Structure tree
6. Commit format reference
7. Secrets management note
8. Multi-agent coordination note
9. **Campsite Rule** — "Touching it makes it yours" policy for code violations

### Tier 3 (Optional — nice to have)

10. Code Review section (Codex commands)
11. Issue Tracking workflow
12. Session Protocol (start/end)

## AGENTS.md — Required Sections

### Tier 1 (Required)

1. **Codebase Patterns** — At least one entry or placeholder with instructive comments
2. **Common Gotchas** — At least one entry or placeholder with instructive comments
3. **Quality Gates** — Duplicated for quick agent reference

### Tier 2 (Recommended)

4. Key Files table
5. Testing Approaches section

## Monorepo Sub-AGENTS.md

Required in any directory under `apps/`, `packages/`, `services/`, or `plugins/`
that contains its own `package.json` or `pyproject.toml`.

Minimum content:
1. Purpose (one line)
2. Patterns (at least placeholder)
3. Gotchas (at least placeholder)

## Detection Markers

The `agent-lint.sh` tool checks for these markers:

| Check | Pass Criteria |
|-------|---------------|
| CLAUDE.md exists | File present at project root |
| AGENTS.md exists | File present at project root |
| Conditional context/loading | CLAUDE.md contains `~/.config/mosaic/guides` or `Conditional` + `Loading/Context` |
| Quality gates | CLAUDE.md contains `Quality Gates` or quality commands (test, lint, typecheck) |
| Monorepo sub-agents | Each app/package dir with own manifest has AGENTS.md |

## Fragment Sources

Shared sections are maintained in `~/.config/mosaic/templates/agent/fragments/`:

| Fragment | Injects Section |
|----------|----------------|
| `conditional-loading.md` | Conditional Documentation Loading table |
| `commit-format.md` | Commit format convention |
| `secrets.md` | Secrets management note |
| `multi-agent.md` | Multi-agent coordination protocol |
| `code-review.md` | Code review commands |
| `campsite-rule.md` | Campsite Rule — fix violations you touch |