# ${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 | `~/.config/mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
| Code review | `~/.config/mosaic/guides/code-review.md` |
| QA/Testing | `~/.config/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
~/.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.

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