chore: consolidate new foundation and archive v1 (#1495)

2026-09-07 12:32:57 -05:00
parent 9a5fbdbda7 5d27700026
commit 127a54fdff
3511 changed files with 727899 additions and 10 deletions
@@ -0,0 +1,75 @@
+# 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 |