# Agent Configuration Specification v1.0

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

## Runtime Context File — 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                                                                                |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| Runtime context file exists | `CLAUDE.md` or `RUNTIME.md` present at project root                                          |
| AGENTS.md exists            | File present at project root                                                                 |
| Conditional context/loading | Runtime context file contains `~/.config/mosaic/guides` or `Conditional` + `Loading/Context` |
| Quality gates               | Runtime context file 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 |
