centralize guides and rails under mosaic with runtime compatibility links

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

@@ -0,0 +1,39 @@
+# ${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
+
+- All public APIs must have type hints and docstrings
+- Zero or minimal runtime dependencies — be conservative adding deps
+- Exports defined in `__init__.py`
+<!-- Add project-specific patterns as you discover them -->
+
+## Common Gotchas
+
+- Always run `uv sync` after pulling — dependencies may have changed
+- Ensure backward compatibility — this is a library consumed by other projects
+<!-- 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, build |
+| `src/${PROJECT_SLUG}/__init__.py` | Public API exports |
+<!-- Add project-specific key files -->
+
+## Testing Approaches
+
+- Unit tests: pytest with fixtures in `conftest.py`
+- Coverage minimum: 85%
+<!-- Document project-specific testing patterns -->

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

@@ -0,0 +1,120 @@
+# ${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` |
+| Code review | `~/.mosaic/guides/code-review.md` |
+| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
+
+## Technology Stack
+
+| Layer | Technology |
+|-------|------------|
+| **Language** | Python 3.11+ |
+| **Testing** | pytest |
+| **Linting** | ruff |
+| **Type Checking** | mypy (strict) |
+| **Package Manager** | uv |
+| **Build** | ${BUILD_SYSTEM} |
+
+## Repository Structure
+
+```
+${PROJECT_DIR}/
+├── CLAUDE.md              # This file
+├── AGENTS.md              # Agent-specific patterns and gotchas
+├── src/
+│   └── ${PROJECT_SLUG}/   # Main package
+├── tests/                 # Test files
+├── docs/
+│   └── scratchpads/       # Per-issue working documents
+└── pyproject.toml         # Project configuration
+```
+
+## Development Workflow
+
+### Setup
+```bash
+uv sync --all-extras
+```
+
+### 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
+```
+
+## 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
+```
+
+## Library Conventions
+
+- Zero or minimal runtime dependencies
+- All public APIs must have type hints
+- All public functions must have docstrings
+- Exports defined in `__init__.py`
+- Versioning via `pyproject.toml`
+
+## 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.
+
+## 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