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