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 -->

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

templates/agent/SPEC.md

@@ -0,0 +1,74 @@
+# Agent Configuration Specification v1.0
+
+> Defines what "well-configured" means for AI agent development across all coding projects.
+
+## CLAUDE.md — Required Sections
+
+### Tier 1 (Required — blocks audit pass)
+
+1. **Conditional Documentation Loading** — Table linking to `~/.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 |
+|-------|---------------|
+| CLAUDE.md exists | File present at project root |
+| AGENTS.md exists | File present at project root |
+| Conditional loading | CLAUDE.md contains `agent-guides` or `Conditional` + `Loading` |
+| Quality gates | CLAUDE.md 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 `~/.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 |

templates/agent/fragments/campsite-rule.md

@@ -0,0 +1,18 @@
+## Campsite Rule (MANDATORY)
+
+If you modify a line containing a policy violation, you MUST either:
+1. **Fix the violation properly** in the same change, OR
+2. **Flag it as a deferred item** with documented rationale
+
+**"It was already there" is NEVER an acceptable justification** for perpetuating a violation in code you touched. Touching it makes it yours.
+
+Examples of violations you must fix when you touch the line:
+- `as unknown as Type` double assertions — use type guards instead
+- `any` types — narrow to `unknown` with validation or define a proper interface
+- Missing error handling — add it if you're modifying the surrounding code
+- Suppressed linting rules (`// eslint-disable`) — fix the underlying issue
+
+If the proper fix is too large for the current scope, you MUST:
+- Create a TODO comment with issue reference: `// TODO(#123): Replace double assertion with type guard`
+- Document the deferral in your PR/commit description
+- Never silently carry the violation forward

templates/agent/fragments/code-review.md

@@ -0,0 +1,14 @@
+## Code Review
+
+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.
+See `~/.mosaic/guides/code-review.md` for the full review checklist.

templates/agent/fragments/commit-format.md

@@ -0,0 +1,11 @@
+## Commits
+
+```
+<type>(#issue): Brief description
+
+Detailed explanation if needed.
+
+Fixes #123
+```
+
+Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`

templates/agent/fragments/conditional-loading.md

@@ -0,0 +1,17 @@
+## Conditional Documentation Loading
+
+**Read the relevant guide before starting work:**
+
+| Task Type | Guide |
+|-----------|-------|
+| Bootstrapping a new project | `~/.mosaic/guides/bootstrap.md` |
+| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
+| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
+| Frontend development | `~/.mosaic/guides/frontend.md` |
+| Backend/API development | `~/.mosaic/guides/backend.md` |
+| TypeScript strict typing | `~/.mosaic/guides/typescript.md` |
+| Code review | `~/.mosaic/guides/code-review.md` |
+| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
+| Infrastructure/DevOps | `~/.mosaic/guides/infrastructure.md` |
+| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
+| Secrets management (Vault) | `~/.mosaic/guides/vault-secrets.md` |

templates/agent/fragments/multi-agent.md

@@ -0,0 +1,6 @@
+## 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

templates/agent/fragments/secrets.md

@@ -0,0 +1,10 @@
+## 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)
+```
+
+Ensure `.gitignore` includes `.env*` (except `.env.example`).

templates/agent/projects/django/AGENTS.md.template

@@ -0,0 +1,79 @@
+# ${PROJECT_NAME} — Agent Context
+
+> Guidelines for AI agents working on this Django project.
+> **Update this file** when you discover reusable patterns or non-obvious requirements.
+
+## Codebase Patterns
+
+- **Django project:** Standard Django project layout
+- **Database:** PostgreSQL with Django ORM
+- **API:** Django REST Framework for REST endpoints
+- **Tasks:** Celery for background/async tasks
+- **Config:** Environment variables via `.env` / `python-dotenv`
+
+## Common Gotchas
+
+- **Run migrations** after model changes: `python manage.py makemigrations && python manage.py migrate`
+- **Import order matters:** Django setup must happen before model imports
+- **Celery tasks** must be importable from `tasks.py` in each app
+- **Settings module:** Check `DJANGO_SETTINGS_MODULE` environment variable
+- **Test database:** Tests use a separate database — check `TEST` config in settings
+- **Static files:** Run `collectstatic` before deployment
+
+## Context Management
+
+| Strategy | When |
+|----------|------|
+| **Spawn sub-agents** | Isolated coding tasks, research |
+| **Batch operations** | Group related operations |
+| **Check existing patterns** | Before writing new code |
+| **Minimize re-reading** | Don't re-read files you just wrote |
+
+## Quality Gates
+
+**All must pass before any commit:**
+
+```bash
+ruff check . && mypy . && pytest tests/
+```
+
+## Orchestrator Integration
+
+### Task Prefix
+Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).
+
+### Worker Checklist
+1. Read the finding details from the report
+2. Implement the fix following existing patterns
+3. Run quality gates (ALL must pass)
+4. Commit: `git commit -m "fix({finding_id}): brief description"`
+5. Push: `git push origin {branch}`
+6. Report result as JSON
+
+### 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
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `CLAUDE.md` | Project overview and conventions |
+| `pyproject.toml` | Python dependencies and tool config |
+| `${SOURCE_DIR}/manage.py` | Django management entry point |
+| `.env.example` | Required environment variables |
+
+## Testing Approaches
+
+- Unit tests: `pytest` with fixtures in `conftest.py`
+- API tests: DRF's `APITestCase` or pytest with `api_client` fixture
+- Database tests: Use `@pytest.mark.django_db` decorator
+- Mocking: `unittest.mock.patch` for external services
+- Minimum 85% coverage for new code
+
+---
+
+_Model-agnostic. Works for Claude, Codex, GPT, Llama, etc._

templates/agent/projects/django/CLAUDE.md.template

@@ -0,0 +1,168 @@
+# ${PROJECT_NAME} — Claude Code Instructions
+
+> **${PROJECT_DESCRIPTION}**
+
+## Conditional Documentation Loading
+
+| When working on... | Load this guide |
+|---|---|
+| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
+| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.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 |
+|-------|------------|
+| **Backend** | Django / Django REST Framework |
+| **Database** | PostgreSQL |
+| **Task Queue** | Celery + Redis/Valkey |
+| **Testing** | pytest + pytest-django |
+| **Linting** | ruff |
+| **Type Checking** | mypy |
+| **Deployment** | Docker + docker-compose |
+
+## Repository Structure
+
+```
+${PROJECT_DIR}/
+├── CLAUDE.md              # This file
+├── AGENTS.md              # Agent-specific patterns and gotchas
+├── ${SOURCE_DIR}/         # Django project root
+│   ├── manage.py
+│   ├── ${PROJECT_SLUG}/   # Django settings module
+│   │   ├── settings.py
+│   │   ├── urls.py
+│   │   └── wsgi.py
+│   └── apps/              # Django applications
+├── tests/                 # Test files
+├── docs/
+│   ├── scratchpads/       # Per-issue working documents
+│   └── templates/         # Project templates
+├── pyproject.toml         # Python project configuration
+├── .env.example
+└── README.md
+```
+
+## Development Workflow
+
+### Branch Strategy
+- `main` — Production-ready code
+- `develop` — Integration branch (if used)
+- `feat/<name>` — Feature branches
+- `fix/<name>` — Bug fix branches
+
+### Starting Work
+```bash
+git pull --rebase
+uv sync                        # or pip install -e ".[dev]"
+```
+
+### Building / Running
+```bash
+python manage.py runserver     # Development server
+python manage.py migrate       # Apply migrations
+python manage.py shell          # Django shell
+```
+
+### Testing
+```bash
+pytest tests/                  # Run all tests
+pytest tests/ -x               # Stop on first failure
+pytest tests/ --cov            # With coverage
+```
+
+### Linting & Type Checking
+```bash
+ruff check .                   # Lint
+ruff format .                  # Format
+mypy .                         # Type check
+```
+
+## Quality Gates
+
+**All must pass before committing:**
+
+```bash
+ruff check . && mypy . && pytest tests/
+```
+
+## Django Conventions
+
+### Models
+- All tunable parameters stored in the database with `get_effective_*()` fallback patterns
+- Always create migrations for model changes: `python manage.py makemigrations`
+- Include migrations in commits
+- Use `models.TextChoices` or `models.IntegerChoices` for enum-like fields
+
+### Views / API
+- Use Django REST Framework for API endpoints
+- Use serializers for validation
+- Use ViewSets for standard CRUD
+- Use permissions classes for authorization
+
+### Management Commands
+- Place in `<app>/management/commands/`
+- Use `self.stdout.write()` for output
+- Handle interrupts gracefully
+
+## Database
+
+### Migration Workflow
+```bash
+# Create migration after model changes
+python manage.py makemigrations <app_name>
+
+# Apply migrations
+python manage.py migrate
+
+# Check for missing migrations
+python manage.py makemigrations --check
+```
+
+### Rules
+- Always create migrations for schema changes
+- Include migrations in commits
+- Use `RunPython` for data migrations
+- Use transactions for multi-table operations
+
+## 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
+```
+
+## Issue Tracking
+
+### 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 after successful testing
+
+### Commits
+```
+<type>(#issue): Brief description
+
+Fixes #123
+```
+Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
+
+## Secrets Management
+
+**NEVER hardcode secrets.**
+
+```bash
+# .env.example is committed (with placeholders)
+# .env is NOT committed (contains real values)
+# Load via python-dotenv or django-environ
+```

templates/agent/projects/nestjs-nextjs/AGENTS.md.template

@@ -0,0 +1,91 @@
+# ${PROJECT_NAME} — Agent Context
+
+> Guidelines for AI agents working on this NestJS + Next.js monorepo.
+> **Update this file** when you discover reusable patterns or non-obvious requirements.
+
+## Codebase Patterns
+
+- **Monorepo structure:** pnpm workspaces + TurboRepo
+  - `apps/api/` — NestJS backend
+  - `apps/web/` — Next.js frontend
+  - `packages/shared/` — Shared types and utilities
+- **Database:** Prisma ORM — schema at `apps/api/prisma/schema.prisma`
+- **Auth:** Configured in `apps/api/src/auth/`
+- **API:** RESTful with DTOs for validation
+
+## Common Gotchas
+
+- **Always run `pnpm install`** after pulling — lockfile changes frequently
+- **Prisma generate** after schema changes: `pnpm --filter api prisma generate`
+- **Environment variables:** Frontend vars need `NEXT_PUBLIC_` prefix
+- **Import paths:** Use `@shared/` alias for shared package imports
+- **Tests require running database:** Set `DATABASE_URL` in `.env.test`
+- **TurboRepo caching:** Run `pnpm clean` if builds behave unexpectedly
+
+## Context Management
+
+Context = tokens = cost. Be smart.
+
+| Strategy | When |
+|----------|------|
+| **Spawn sub-agents** | Isolated coding tasks, research |
+| **Batch operations** | Group related API calls |
+| **Check existing patterns** | Before writing new code |
+| **Minimize re-reading** | Don't re-read files you just wrote |
+
+## Quality Gates
+
+**All must pass before any commit:**
+
+```bash
+pnpm typecheck && pnpm lint && pnpm test
+```
+
+## Orchestrator Integration
+
+### Task Prefix
+Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).
+
+### Worker Checklist
+1. Read the finding details from the report
+2. Implement the fix following existing patterns
+3. Run quality gates (ALL must pass)
+4. Commit: `git commit -m "fix({finding_id}): brief description"`
+5. Push: `git push origin {branch}`
+6. Report result as JSON
+
+### 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
+
+## Workflow (Non-Negotiable)
+
+```
+1. Branch    → git checkout -b feature/XX-description
+2. Code      → TDD: write test (RED), implement (GREEN), refactor
+3. Test      → pnpm test (must pass)
+4. Push      → git push origin feature/XX-description
+5. PR        → Create PR to develop (not main)
+6. Review    → Wait for approval or self-merge if authorized
+7. Close     → Close related issues
+```
+
+**Never merge directly to develop without a PR.**
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `CLAUDE.md` | Project overview and conventions |
+| `apps/api/prisma/schema.prisma` | Database schema |
+| `apps/api/src/` | Backend source |
+| `apps/web/app/` | Frontend pages |
+| `packages/shared/` | Shared types |
+| `.env.example` | Required environment variables |
+
+---
+
+_Model-agnostic. Works for Claude, Codex, GPT, Llama, etc._

templates/agent/projects/nestjs-nextjs/CLAUDE.md.template

@@ -0,0 +1,200 @@
+# ${PROJECT_NAME} — Claude Code Instructions
+
+> **${PROJECT_DESCRIPTION}**
+
+## Conditional Documentation Loading
+
+| When working on... | Load this guide |
+|---|---|
+| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
+| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
+| Frontend development | `~/.mosaic/guides/frontend.md` |
+| Backend/API development | `~/.mosaic/guides/backend.md` |
+| Code review | `~/.mosaic/guides/code-review.md` |
+| TypeScript strict typing | `~/.mosaic/guides/typescript.md` |
+| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
+| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
+
+## Technology Stack
+
+| Layer | Technology |
+|-------|------------|
+| **Frontend** | Next.js + React + TailwindCSS + Shadcn/ui |
+| **Backend** | NestJS + Prisma ORM |
+| **Database** | PostgreSQL |
+| **Testing** | Vitest + Playwright |
+| **Monorepo** | pnpm workspaces + TurboRepo |
+| **Deployment** | Docker + docker-compose |
+
+## Repository Structure
+
+```
+${PROJECT_DIR}/
+├── CLAUDE.md              # This file
+├── AGENTS.md              # Agent-specific patterns and gotchas
+├── apps/
+│   ├── api/               # NestJS backend
+│   │   ├── src/
+│   │   ├── prisma/
+│   │   │   └── schema.prisma
+│   │   └── Dockerfile
+│   └── web/               # Next.js frontend
+│       ├── app/
+│       ├── components/
+│       └── Dockerfile
+├── packages/
+│   ├── shared/            # Shared types, utilities
+│   ├── ui/                # Shared UI components
+│   └── config/            # Shared configuration
+├── docs/
+│   ├── scratchpads/       # Per-issue working documents
+│   └── templates/         # Project templates
+├── tests/                 # Integration/E2E tests
+├── docker/                # Docker configuration
+├── .env.example
+├── turbo.json
+├── pnpm-workspace.yaml
+└── README.md
+```
+
+## Development Workflow
+
+### Branch Strategy
+- `main` — Stable releases only
+- `develop` — Active development (default working branch)
+- `feature/*` — Feature branches from develop
+- `fix/*` — Bug fix branches
+
+### Starting Work
+```bash
+git checkout develop
+git pull --rebase
+pnpm install
+```
+
+### Building
+```bash
+pnpm build                    # Build all packages
+pnpm --filter api build       # Build API only
+pnpm --filter web build       # Build web only
+```
+
+### Testing
+```bash
+pnpm test                     # Run all tests
+pnpm test:unit                # Unit tests (Vitest)
+pnpm test:e2e                 # E2E tests (Playwright)
+pnpm test:coverage            # Coverage report
+```
+
+### Linting & Type Checking
+```bash
+pnpm lint                     # ESLint
+pnpm typecheck                # TypeScript type checking
+pnpm format                   # Prettier formatting
+```
+
+## Quality Gates
+
+**All must pass before committing:**
+
+```bash
+pnpm typecheck && pnpm lint && pnpm test
+```
+
+## API Conventions
+
+### NestJS Patterns
+- Controllers handle HTTP, Services handle business logic
+- Use DTOs with `class-validator` for request validation
+- Use Guards for authentication/authorization
+- Use Interceptors for response transformation
+- Use Prisma for database access (no raw SQL)
+
+### REST API Standards
+- `GET /resource` — List (with pagination)
+- `GET /resource/:id` — Get single
+- `POST /resource` — Create
+- `PATCH /resource/:id` — Update
+- `DELETE /resource/:id` — Delete
+- Return proper HTTP status codes (201 Created, 204 No Content, etc.)
+
+## Frontend Conventions
+
+### Next.js Patterns
+- Use App Router (`app/` directory)
+- Server Components by default, `'use client'` only when needed
+- Use Shadcn/ui components — don't create custom UI primitives
+- Use TailwindCSS for styling — no CSS modules or styled-components
+
+### Component Structure
+```
+components/
+├── ui/          # Shadcn/ui components (auto-generated)
+├── layout/      # Layout components (header, sidebar, etc.)
+├── forms/       # Form components
+└── features/    # Feature-specific components
+```
+
+## Database
+
+### Prisma Workflow
+```bash
+# Generate client after schema changes
+pnpm --filter api prisma generate
+
+# Create migration
+pnpm --filter api prisma migrate dev --name description
+
+# Apply migrations
+pnpm --filter api prisma migrate deploy
+
+# Reset database (dev only)
+pnpm --filter api prisma migrate reset
+```
+
+### Rules
+- Always create migrations for schema changes
+- Include migrations in commits
+- Never use raw SQL — use Prisma client
+- Use transactions for multi-table operations
+
+## 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
+```
+
+## Issue Tracking
+
+### 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 after successful testing
+
+### Commits
+```
+<type>(#issue): Brief description
+
+Fixes #123
+```
+Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
+
+## Secrets Management
+
+**NEVER hardcode secrets.**
+
+```bash
+# .env.example is committed (with placeholders)
+# .env is NOT committed (contains real values)
+```
+
+Required environment variables are documented in `.env.example`.

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

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

templates/agent/projects/typescript/AGENTS.md.template

@@ -0,0 +1,41 @@
+# ${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
+
+- TypeScript strict mode enabled — no `any`, no implicit types
+- See `~/.mosaic/guides/typescript.md` for mandatory TypeScript rules
+<!-- Add project-specific patterns as you discover them -->
+
+## Common Gotchas
+
+<!-- Add things that trip up agents -->
+<!-- Examples: -->
+<!-- - Frontend env vars need NEXT_PUBLIC_ prefix -->
+<!-- - Tests require specific setup (describe in Testing section) -->
+
+## Quality Gates
+
+**All must pass before any commit:**
+
+```bash
+${QUALITY_GATES}
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `tsconfig.json` | TypeScript configuration |
+| `package.json` | Dependencies and scripts |
+<!-- Add project-specific key files -->
+
+## Testing Approaches
+
+<!-- Document how tests should be written for this project -->
+<!-- Examples: -->
+<!-- - Unit tests use Vitest with fixtures -->
+<!-- - Component tests use React Testing Library -->
+<!-- - E2E tests use Playwright -->

templates/agent/projects/typescript/CLAUDE.md.template

@@ -0,0 +1,119 @@
+# ${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` |
+| Frontend development | `~/.mosaic/guides/frontend.md` |
+| TypeScript strict typing | `~/.mosaic/guides/typescript.md` |
+| Code review | `~/.mosaic/guides/code-review.md` |
+| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
+
+## Technology Stack
+
+| Layer | Technology |
+|-------|------------|
+| **Language** | TypeScript (strict mode) |
+| **Framework** | ${FRAMEWORK} |
+| **Testing** | ${TESTING_STACK} |
+| **Linting** | ESLint + Prettier |
+| **Package Manager** | ${PACKAGE_MANAGER} |
+| **Deployment** | ${DEPLOYMENT_STACK} |
+
+## Repository Structure
+
+```
+${PROJECT_DIR}/
+├── CLAUDE.md              # This file
+├── AGENTS.md              # Agent-specific patterns and gotchas
+├── src/                   # Source code
+├── tests/                 # Test files
+├── docs/
+│   └── scratchpads/       # Per-issue working documents
+└── ${CONFIG_FILES}        # Configuration files
+```
+
+## Development Workflow
+
+### Building
+```bash
+${BUILD_COMMAND}
+```
+
+### Testing
+```bash
+${TEST_COMMAND}
+```
+
+### Linting & Type Checking
+```bash
+${LINT_COMMAND}
+${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.
+
+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
+# 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.
+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

templates/agent/qa-remediation-actions.md

@@ -0,0 +1,233 @@
+---
+file_path: {full_path}
+file_name: {sanitized_name}
+remediation_report: {FileName}_remediation_needed.md
+timestamp_start: {ISO_timestamp}
+timestamp_end: {ISO_timestamp}
+iteration: {current_iteration}
+status: {planning|researching|executing|validating|completed|failed}
+success_metrics:
+  typescript: {pass|fail|not_applicable}
+  eslint: {pass|fail|not_applicable}
+  prettier: {pass|fail|not_applicable}
+  security: {pass|fail|not_applicable}
+---
+
+# Remediation Actions: {file_name}
+
+## Planning Phase
+**Start Time**: {timestamp}  
+**Status**: {in_progress|completed}
+
+### Sequential Thinking Analysis
+```
+Thought 1: Analyzing reported issues - {analysis}
+Thought 2: Determining fix priority - {priority reasoning}
+Thought 3: Identifying dependencies - {dependency analysis}
+Thought 4: Planning execution order - {order rationale}
+Thought 5: Estimating complexity - {complexity assessment}
+Thought 6: Validation approach - {how to verify success}
+Total Thoughts: {n}
+Decision: {chosen approach}
+```
+
+### Issues Prioritization
+1. **Critical**: {issues that block compilation/execution}
+2. **High**: {issues affecting functionality}
+3. **Medium**: {code quality issues}
+4. **Low**: {style/formatting issues}
+
+## Research Phase
+**Start Time**: {timestamp}  
+**Status**: {in_progress|completed}
+
+### Context7 Documentation Retrieved
+```javascript
+// Query 1: TypeScript best practices
+await mcp__context7__get_library_docs({
+  context7CompatibleLibraryID: "/microsoft/TypeScript",
+  topic: "{specific topic}",
+  tokens: 3000
+});
+// Result: {summary of findings}
+
+// Query 2: ESLint rules
+await mcp__context7__get_library_docs({
+  context7CompatibleLibraryID: "/eslint/eslint",
+  topic: "{specific rules}",
+  tokens: 2000
+});
+// Result: {summary of findings}
+
+// Query 3: Framework patterns
+await mcp__context7__get_library_docs({
+  context7CompatibleLibraryID: "{framework library}",
+  topic: "{specific patterns}",
+  tokens: 2500
+});
+// Result: {summary of findings}
+```
+
+### Relevant Patterns Identified
+- **Pattern 1**: {description and application}
+- **Pattern 2**: {description and application}
+- **Best Practice**: {relevant best practice from docs}
+
+## Action Plan
+**Generated**: {timestamp}  
+**Total Actions**: {count}
+
+### Planned Actions
+1. [ ] **Fix TypeScript interface issue**
+   - **Issue**: Property 'onClick' missing from ButtonProps
+   - **Solution**: Add optional onClick property with proper typing
+   - **Rationale**: Maintains backward compatibility while fixing type error
+   - **Rollback**: Remove property if breaks existing usage
+   - **Estimated Impact**: Low risk, improves type safety
+
+2. [ ] **Resolve ESLint violations**
+   - **Issue**: no-unused-vars on line 45
+   - **Solution**: Remove unused import or implement usage
+   - **Rationale**: Clean code practice, reduces bundle size
+   - **Rollback**: Re-add if functionality needed
+   - **Estimated Impact**: No functional change
+
+3. [ ] **Apply Prettier formatting**
+   - **Issue**: Inconsistent formatting throughout file
+   - **Solution**: Run prettier --write
+   - **Rationale**: Maintains code style consistency
+   - **Rollback**: Not needed (formatting only)
+   - **Estimated Impact**: No functional change
+
+## Execution Phase
+**Start Time**: {timestamp}  
+**Status**: {in_progress|completed}
+
+### Actions Taken
+
+#### Action 1: Fix TypeScript interface issue
+**Timestamp**: {ISO timestamp}  
+**Tool Used**: Edit  
+**Target**: Lines 10-15 of ButtonProps interface  
+**Change Applied**:
+```typescript
+// Before
+interface ButtonProps {
+  label: string;
+  disabled?: boolean;
+}
+
+// After
+interface ButtonProps {
+  label: string;
+  disabled?: boolean;
+  onClick?: React.MouseEventHandler<HTMLButtonElement>;
+}
+```
+**Result**: ✅ Success - TypeScript compilation now passes  
+**Side Effects**: None observed  
+**Status**: [x] Completed
+
+#### Action 2: Resolve ESLint violations
+**Timestamp**: {ISO timestamp}  
+**Tool Used**: MultiEdit  
+**Target**: Multiple locations with violations  
+**Changes Applied**:
+- Removed unused import on line 3
+- Fixed missing dependency in useEffect on line 67
+- Added missing return type on line 89
+**Result**: ✅ Success - ESLint now reports 0 errors  
+**Side Effects**: None  
+**Status**: [x] Completed
+
+#### Action 3: Apply Prettier formatting
+**Timestamp**: {ISO timestamp}  
+**Tool Used**: Bash  
+**Command**: `npx prettier --write {file_path}`  
+**Result**: ✅ Success - File formatted  
+**Lines Changed**: 47  
+**Status**: [x] Completed
+
+### Unexpected Issues Encountered
+{Any issues that arose during execution}
+
+### Adjustments Made
+{Any deviations from the original plan and why}
+
+## Validation Phase
+**Start Time**: {timestamp}  
+**Status**: {in_progress|completed}
+
+### Re-run QA Checks
+
+#### TypeScript Validation
+```bash
+npx tsc --noEmit {file_path}
+```
+**Result**: ✅ PASS - No errors  
+**Details**: Compilation successful, all types resolved
+
+#### ESLint Validation
+```bash
+npx eslint {file_path}
+```
+**Result**: ✅ PASS - 0 errors, 2 warnings  
+**Warnings**: 
+- Line 34: Prefer const over let (prefer-const)
+- Line 78: Missing explicit return type (explicit-function-return-type)
+
+#### Prettier Validation
+```bash
+npx prettier --check {file_path}
+```
+**Result**: ✅ PASS - File formatted correctly
+
+#### Security Scan
+```bash
+# Security check command
+```
+**Result**: ✅ PASS - No vulnerabilities detected
+
+### Overall Validation Status
+- **All Critical Issues**: ✅ Resolved
+- **All High Issues**: ✅ Resolved
+- **Medium Issues**: ⚠️ 2 warnings remain (non-blocking)
+- **Low Issues**: ✅ Resolved
+
+## Next Steps
+
+### If Successful (All Pass)
+- [x] Move reports to done/
+- [x] Archive after 7 days
+- [x] Log success metrics
+
+### If Failed (Issues Remain)
+- [ ] Check iteration count: {current}/5
+- [ ] If < 5: Plan next iteration approach
+- [ ] If >= 5: Escalate with detailed analysis
+
+### Next Iteration Planning (If Needed)
+**Remaining Issues**: {list}  
+**New Approach**: {different strategy based on learnings}  
+**Sequential Thinking**:
+```
+Thought 1: Why did previous approach fail?
+Thought 2: What alternative solutions exist?
+Thought 3: Which approach has highest success probability?
+Decision: {new approach}
+```
+
+## Summary
+**Total Execution Time**: {duration}  
+**Actions Completed**: {n}/{total}  
+**Success Rate**: {percentage}  
+**Final Status**: {completed|needs_iteration|escalated}
+
+## Lessons Learned
+{Any insights that could help future remediation}
+
+---
+*Generated by Auto-Remediation Agent*  
+*Start: {ISO timestamp}*  
+*End: {ISO timestamp}*  
+*Agent Version: 1.0.0*

templates/agent/qa-remediation-needed.md

@@ -0,0 +1,117 @@
+---
+file_path: {full_path}
+file_name: {sanitized_name}
+epic_association: {E.XXXX-name or "general"}
+epic_exists: {true|false|created}
+timestamp: {YYYYMMDD-HHMM}
+iteration: {1-5}
+max_iterations: 5
+tool_triggered: {Edit|MultiEdit|Write}
+severity: {CRITICAL|HIGH|MEDIUM|LOW}
+status: pending
+error_context: {any errors during creation}
+---
+
+# Remediation Needed: {file_name}
+
+## Environment Context
+- **Epic Status**: {existing|created|general}
+- **Report Location**: {full path to this report}
+- **Previous Iterations**: {list if any}
+- **Project Type**: {React Frontend|NestJS Backend|Node.js Library}
+
+## Issues Detected
+
+### TypeScript Compilation
+**Status**: ❌ FAILED | ✅ PASSED  
+**Errors Found**: {count}
+
+```typescript
+// Error details with line numbers
+{specific errors}
+```
+
+**Context7 Documentation**:
+- {relevant TypeScript docs retrieved}
+
+### ESLint Violations
+**Status**: ❌ ERRORS | ⚠️ WARNINGS | ✅ CLEAN  
+**Issues Found**: {count}
+
+```javascript
+// Violation details with rule names
+{specific violations}
+```
+
+**Context7 Documentation**:
+- {relevant ESLint rule docs}
+
+### Prettier Formatting
+**Status**: ❌ NEEDS FORMATTING | ✅ FORMATTED  
+**Changes Required**: {yes|no}
+
+```diff
+// Formatting differences
+- {original}
++ {formatted}
+```
+
+### Security Issues
+**Status**: ❌ VULNERABILITIES | ✅ SECURE  
+**Critical Issues**: {count}
+
+- {list of security concerns}
+
+## Recommended Fixes
+
+### Priority 1: Critical (Must Fix)
+1. **{Issue}**: {specific fix with code example}
+   - Rationale: {why this fix}
+   - Context7 Reference: {documentation link/content}
+
+### Priority 2: High (Should Fix)
+1. **{Issue}**: {specific fix}
+   - Rationale: {reasoning}
+   - Auto-fixable: {yes|no}
+
+### Priority 3: Medium (Consider Fixing)
+1. **{Issue}**: {improvement suggestion}
+   - Impact: {what this improves}
+
+## Sequential Thinking Analysis
+```
+Thought 1: {initial analysis}
+Thought 2: {problem identification}
+Thought 3: {solution approach}
+Thought 4: {validation strategy}
+Decision: {recommended approach}
+```
+
+## Auto-Fix Availability
+- **TypeScript**: {percentage auto-fixable}
+- **ESLint**: {percentage auto-fixable with --fix}
+- **Prettier**: ✅ 100% auto-fixable
+- **Overall**: {percentage requiring manual intervention}
+
+## Execution Plan
+1. [ ] Apply Prettier formatting
+2. [ ] Run ESLint with --fix flag
+3. [ ] Fix TypeScript compilation errors
+4. [ ] Address security vulnerabilities
+5. [ ] Re-run validation suite
+
+## Risk Assessment
+- **Breaking Changes**: {none|low|medium|high}
+- **Side Effects**: {list potential impacts}
+- **Dependencies**: {any new dependencies needed}
+
+## Manual Actions Required
+{If any issues cannot be auto-fixed, list specific manual interventions needed}
+
+## Notes
+{Additional context, warnings, or information}
+
+---
+*Generated by Universal QA Agent*  
+*Timestamp: {ISO timestamp}*  
+*Agent Version: 1.0.0*

templates/agent/sub-agents.md.template

@@ -0,0 +1,17 @@
+# ${DIRECTORY_NAME} — Agent Context
+
+> ${DIRECTORY_PURPOSE}
+
+## Patterns
+
+<!-- Add module-specific patterns as you discover them -->
+
+## Gotchas
+
+<!-- Add things that trip up agents in this module -->
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+<!-- Add important files in this directory -->