centralize guides and rails under mosaic with runtime compatibility links

2026-02-17 11:39:52 -06:00
parent a1c2efef1c
commit 4eac2c76e6
85 changed files with 10785 additions and 0 deletions
--- a/templates/agent/CLAUDE.md.template
+++ b/templates/agent/CLAUDE.md.template
@@ -0,0 +1,151 @@
+# ${PROJECT_NAME} — Claude Code Instructions
+
+> **Project:** ${PROJECT_DESCRIPTION}
+> **Repository:** ${REPO_URL}
+
+## Session Protocol
+
+### Starting a Session
+```bash
+git pull --rebase
+```
+
+### Ending a Session
+```bash
+git pull --rebase
+git add -A
+git commit -m "feat: <what changed>"
+git push
+```
+
+## 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` |
+| Code review | `~/.mosaic/guides/code-review.md` |
+| Frontend development | `~/.mosaic/guides/frontend.md` |
+| Backend/API development | `~/.mosaic/guides/backend.md` |
+| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
+| Infrastructure/DevOps | `~/.mosaic/guides/infrastructure.md` |
+| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
+
+## Technology Stack
+
+| Layer | Technology |
+|-------|------------|
+| **Frontend** | ${FRONTEND_STACK} |
+| **Backend** | ${BACKEND_STACK} |
+| **Database** | ${DATABASE_STACK} |
+| **Testing** | ${TESTING_STACK} |
+| **Deployment** | ${DEPLOYMENT_STACK} |
+
+## Repository Structure
+
+```
+${PROJECT_DIR}/
+├── CLAUDE.md              # This file
+├── AGENTS.md              # Agent-specific patterns and gotchas
+├── docs/
+│   ├── scratchpads/       # Per-issue working documents
+│   └── templates/         # Project templates (if any)
+├── ${SOURCE_DIR}/         # Application source code
+├── tests/                 # Test files
+└── ${CONFIG_FILES}        # Configuration files
+```
+
+## Development Workflow
+
+### Branch Strategy
+- `main` — Production-ready code
+- `develop` — Integration branch (if applicable)
+- `feat/<name>` — Feature branches
+- `fix/<name>` — Bug fix branches
+
+### Building
+```bash
+${BUILD_COMMAND}
+```
+
+### Testing
+```bash
+${TEST_COMMAND}
+```
+
+### Linting
+```bash
+${LINT_COMMAND}
+```
+
+### Type Checking
+```bash
+${TYPECHECK_COMMAND}
+```
+
+## Quality Gates
+
+**All must pass before committing:**
+
+```bash
+${QUALITY_GATES}
+```
+
+## Issue Tracking
+
+All work is tracked as issues in the project's git repository.
+
+### Workflow
+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
+
+### Labels
+Use consistent labels: `epic`, `feature`, `bug`, `task`, `documentation`, `security`, `breaking`
+
+### Commits
+```
+<type>(#issue): Brief description
+
+Detailed explanation if needed.
+
+Fixes #123
+```
+Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
+
+## Code Review
+
+### Independent Review (Automated)
+After completing code changes, run independent reviews:
+
+```bash
+# Code quality review (Codex)
+~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
+
+# Security review (Codex)
+~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
+```
+
+**Fallback:** If Codex is unavailable, use Claude's built-in review skills.
+
+### Review Checklist
+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