centralize guides and rails under mosaic with runtime compatibility links

templates/agent/AGENTS.md.template

@@ -0,0 +1,72 @@
+# ${PROJECT_NAME} — Agent Context
+
+> Patterns, gotchas, and orchestrator integration for AI agents working on this project.
+> **Update this file** when you discover reusable patterns or non-obvious requirements.
+
+## Codebase Patterns
+
+<!-- Add project-specific patterns as you discover them -->
+<!-- Examples: -->
+<!-- - Use `httpx.AsyncClient` for external HTTP calls -->
+<!-- - All routes require authentication via `Depends(get_current_user)` -->
+<!-- - Config is loaded from environment variables via `settings.py` -->
+
+## Common Gotchas
+
+<!-- Add things that trip up agents -->
+<!-- Examples: -->
+<!-- - Remember to run migrations after schema changes -->
+<!-- - Frontend env vars need NEXT_PUBLIC_ prefix -->
+<!-- - Tests require a running PostgreSQL instance -->
+
+## Quality Gates
+
+**All must pass before any commit:**
+
+```bash
+${QUALITY_GATES}
+```
+
+## Orchestrator Integration
+
+### Task Prefix
+Use `${TASK_PREFIX}` as the prefix for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).
+
+### Package/Directory Names
+<!-- List key directories the orchestrator needs to know about -->
+
+| Directory | Purpose |
+|-----------|---------|
+| `${SOURCE_DIR}/` | Main source code |
+| `tests/` | Test files |
+| `docs/scratchpads/` | Working documents |
+
+### Worker Checklist
+When completing an orchestrated task:
+1. Read the finding details from the report
+2. Implement the fix following existing code patterns
+3. Run quality gates (ALL must pass)
+4. Commit with: `git commit -m "fix({finding_id}): brief description"`
+5. Report result as JSON to orchestrator
+
+### Post-Coding Review
+After implementing changes, the orchestrator will run:
+1. **Codex code review** — `~/.mosaic/rails/codex/codex-code-review.sh --uncommitted`
+2. **Codex security review** — `~/.mosaic/rails/codex/codex-security-review.sh --uncommitted`
+3. If blockers/critical findings: remediation task created
+4. If clean: task marked done
+
+## Directory-Specific Context
+
+<!-- Add sub-AGENTS.md files in subdirectories if needed -->
+<!-- Example: -->
+<!-- - `src/api/AGENTS.md` — API-specific patterns -->
+<!-- - `src/components/AGENTS.md` — Component conventions -->
+
+## Testing Approaches
+
+<!-- Document how tests should be written for this project -->
+<!-- Examples: -->
+<!-- - Unit tests use pytest with fixtures in conftest.py -->
+<!-- - Integration tests require DATABASE_URL env var -->
+<!-- - E2E tests use Playwright -->