75 lines
2.6 KiB
Markdown
75 lines
2.6 KiB
Markdown
# 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 |
|