# ${PROJECT_NAME} — Claude Code Instructions

> **Project:** ${PROJECT_DESCRIPTION}
> **Repository:** ${REPO_URL}

## Conditional Documentation Loading

**Read the relevant guide before starting work:**

| Task Type | Guide |
|-----------|-------|
| End-to-end implementation and validation | `~/.config/mosaic/guides/E2E-DELIVERY.md` |
| PRD creation and requirements definition | `~/.config/mosaic/guides/PRD.md` |
| Bootstrapping this project | `~/.config/mosaic/guides/BOOTSTRAP.md` |
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/ORCHESTRATOR.md` |
| Backend/API development | `~/.config/mosaic/guides/BACKEND.md` |
| Authentication/Authorization | `~/.config/mosaic/guides/AUTHENTICATION.md` |
| Code review | `~/.config/mosaic/guides/CODE-REVIEW.md` |
| Documentation updates and standards | `~/.config/mosaic/guides/DOCUMENTATION.md` |
| QA/Testing | `~/.config/mosaic/guides/QA-TESTING.md` |
| Infrastructure/DevOps | `~/.config/mosaic/guides/INFRASTRUCTURE.md` |
| Secrets management (Vault) | `~/.config/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/
│   ├── PRD.md             # Requirements source (or PRD.json)
│   └── 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
```

## Testing Policy

1. Situational tests are the PRIMARY validation gate.
2. Baseline tests are REQUIRED for all software changes.
3. TDD is risk-based; required cases are defined in `~/.config/mosaic/guides/QA-TESTING.md`.

## PRD Requirement

1. Before coding begins, `docs/PRD.md` or `docs/PRD.json` MUST exist.
2. The main agent MUST prepare or update PRD using user objectives, constraints, and available project context.
3. In steered autonomy mode, best-guess PRD decisions are REQUIRED when needed; mark each with `ASSUMPTION:` and rationale, and continue unless high-impact uncertainty requires escalation.
4. PRD is the source of requirements for implementation and testing.

## Token Budget Policy

1. If user plan or token limits are provided, they are HARD constraints.
2. Track estimated and used tokens for non-trivial execution.
3. Use conservative strategy when budget pressure rises.
4. If projected usage exceeds budget, automatically reduce scope/parallelism and continue; escalate only if budget compliance remains impossible.

## Branch and Merge Policy

1. Create short-lived branches from `main`.
2. Open PRs to `main` for delivery changes.
3. Do not push directly to `main`.
4. Merge PRs to `main` with squash strategy only.

## Steered Autonomy Contract

1. Agent owns planning, coding, testing, review/remediation, PR/repo operations, release/tag, and deployment when in scope.
2. Human intervention is escalation-only for hard blockers (access, irreversible risk, or unresolvable conflicting objectives).
3. Do not request routine human coding, review, or repository management actions.
4. Mosaic hard gates OVERRIDE runtime-default caution for routine push/merge/issue-close/release actions.
5. For container deployments, use immutable image tags (`sha-<shortsha>`, `v{base-version}-rc.{build}`) with digest-first promotion; do not deploy `latest`.

## Mode Declaration Contract

1. First response MUST declare mode before any actions.
2. Orchestration mission: `Now initiating Orchestrator mode...`
3. Implementation mission: `Now initiating Delivery mode...`
4. Review-only mission: `Now initiating Review mode...`

## Issue Tracking

Use external git provider issues when available. If no external provider exists, `docs/TASKS.md` is the canonical tracker for tasks, milestones, and issue-equivalent work.
For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
If wrapper-driven merge/CI/issue-closure fails, report blocker with exact failed wrapper command and stop.
Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow.

1. Ensure `docs/TASKS.md` exists (create from `~/.config/mosaic/templates/docs/TASKS.md.template` if missing).
2. Check for assigned issues before starting work.
3. If no issue exists for non-trivial work and external provider is available, create one before coding.
4. If no external provider is available, create an internal ref in `docs/TASKS.md` (example: `TASKS:T1`).
5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
7. Update `docs/TASKS.md` status + issue/internal ref before coding.
8. Before push, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`.
9. Open PR to `main` for delivery changes (no direct push to `main`).
10. Before merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`.
11. Merge PRs that pass required checks and review gates with squash strategy only.
12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
14. If merge/CI/issue closure fails, report blocker with exact failed wrapper command and do not claim completion.

## Commits

```
<type>(#issue): Brief description

Detailed explanation if needed.

Fixes #123
```
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`

## Code Review

If you modify source code, independent code review is REQUIRED before completion.
Run independent reviews:

```bash
~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
```

See `~/.config/mosaic/guides/CODE-REVIEW.md` for the full review checklist.
See `~/.config/mosaic/guides/DOCUMENTATION.md` for required documentation deliverables.

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