bootstrap/templates/agent/SPEC.md

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 ~/.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 ~/.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 ~/.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