centralize guides and rails under mosaic with runtime compatibility links

templates/agent/projects/python-fastapi/AGENTS.md.template

@@ -0,0 +1,43 @@
+# ${PROJECT_NAME} — Agent Context
+
+> Patterns, gotchas, and guidelines for AI agents working on this project.
+> **Update this file** when you discover reusable patterns or non-obvious requirements.
+
+## Codebase Patterns
+
+- Use Pydantic models for all request/response validation
+- Use dependency injection (`Depends()`) for shared resources
+- Use `httpx.AsyncClient` for external HTTP calls
+- Use `BackgroundTasks` for fire-and-forget operations
+- Structured logging with `structlog` or `logging`
+<!-- Add project-specific patterns as you discover them -->
+
+## Common Gotchas
+
+- Always run `uv sync` after pulling — dependencies may have changed
+- Database migrations must be run before tests that use the DB
+- Async tests need `@pytest.mark.asyncio` decorator
+<!-- Add project-specific gotchas -->
+
+## Quality Gates
+
+**All must pass before any commit:**
+
+```bash
+uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy src/ && uv run pytest --cov
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `pyproject.toml` | Project configuration, dependencies |
+| `src/${PROJECT_SLUG}/main.py` | Application entry point |
+<!-- Add project-specific key files -->
+
+## Testing Approaches
+
+- Unit tests: pytest with fixtures in `conftest.py`
+- API tests: `httpx.AsyncClient` with `TestClient`
+- Coverage minimum: 85%
+<!-- Document project-specific testing patterns -->

templates/agent/projects/python-fastapi/CLAUDE.md.template

@@ -0,0 +1,135 @@
+# ${PROJECT_NAME} — Claude Code Instructions
+
+> **Project:** ${PROJECT_DESCRIPTION}
+> **Repository:** ${REPO_URL}
+
+## Conditional Documentation Loading
+
+**Read the relevant guide before starting work:**
+
+| Task Type | Guide |
+|-----------|-------|
+| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
+| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
+| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
+| Backend/API development | `~/.mosaic/guides/backend.md` |
+| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
+| Code review | `~/.mosaic/guides/code-review.md` |
+| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
+| Infrastructure/DevOps | `~/.mosaic/guides/infrastructure.md` |
+| Secrets management (Vault) | `~/.mosaic/guides/vault-secrets.md` |
+
+## Technology Stack
+
+| Layer | Technology |
+|-------|------------|
+| **Backend** | FastAPI |
+| **Language** | Python 3.11+ |
+| **Database** | ${DATABASE_STACK} |
+| **Testing** | pytest + httpx |
+| **Linting** | ruff |
+| **Type Checking** | mypy (strict) |
+| **Security** | bandit + pip-audit |
+| **Package Manager** | uv |
+| **Deployment** | ${DEPLOYMENT_STACK} |
+
+## Repository Structure
+
+```
+${PROJECT_DIR}/
+├── CLAUDE.md              # This file
+├── AGENTS.md              # Agent-specific patterns and gotchas
+├── src/                   # Source code
+│   └── ${PROJECT_SLUG}/   # Main package
+├── tests/                 # Test files
+├── docs/
+│   └── scratchpads/       # Per-issue working documents
+├── pyproject.toml         # Project configuration
+└── .env.example           # Environment template
+```
+
+## Development Workflow
+
+### Setup
+```bash
+uv sync --all-extras
+```
+
+### Running
+```bash
+uv run uvicorn ${PROJECT_SLUG}.main:app --reload --port 8000
+```
+
+### Testing
+```bash
+uv run pytest                    # Run all tests
+uv run pytest --cov              # With coverage (85% min)
+```
+
+### Linting & Type Checking
+```bash
+uv run ruff check src/ tests/   # Lint
+uv run ruff format --check src/  # Format check
+uv run mypy src/                 # Type check
+```
+
+### Security
+```bash
+uv run bandit -r src/            # SAST scanning
+uv run pip-audit                 # Dependency vulnerabilities
+```
+
+## Quality Gates
+
+**All must pass before committing:**
+
+```bash
+uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy src/ && uv run pytest --cov
+```
+
+## Issue Tracking
+
+All work is tracked as issues in the project's git repository.
+
+1. Check for assigned issues before starting work
+2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
+3. Reference issues in commits: `Fixes #123` or `Refs #123`
+4. Close issues only after successful testing
+
+## Commits
+
+```
+<type>(#issue): Brief description
+
+Detailed explanation if needed.
+
+Fixes #123
+```
+Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
+
+## Code Review
+
+After completing code changes, run independent reviews:
+
+```bash
+~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
+```
+
+See `~/.mosaic/guides/code-review.md` for the full review checklist.
+
+## Secrets Management
+
+**NEVER hardcode secrets.** Use `.env` files (gitignored) or a secrets manager.
+
+```bash
+# .env.example is committed (with placeholders)
+# .env is NOT committed (contains real values)
+```
+
+## Multi-Agent Coordination
+
+When multiple agents work on this project:
+1. `git pull --rebase` before editing
+2. `git pull --rebase` before pushing
+3. If conflicts, **alert the user** — don't auto-resolve data conflicts