# ${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 | `~/.config/mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
| Code review | `~/.config/mosaic/guides/code-review.md` |
| Frontend development | `~/.config/mosaic/guides/frontend.md` |
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
| Infrastructure/DevOps | `~/.config/mosaic/guides/infrastructure.md` |
| QA/Testing | `~/.config/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)
~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted

# Security review (Codex)
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
```

**Fallback:** If Codex is unavailable, use Claude's built-in review skills.

### Review Checklist
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.

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