# Sneaky Klaus

A self-hosted Secret Santa organization application.

## Project Documentation

- `docs/PROJECT_OVERVIEW.md` - Product vision and scope
- `docs/BACKLOG.md` - User stories with acceptance criteria
- `docs/decisions/` - Architecture Decision Records
- `docs/designs/vX.Y.Z/` - Design documents (versioned)

## Workflow

This project uses a two-agent workflow coordinated by the main agent:

1. **Architect** (`.claude/agents/architect.md`) - Designs systems, produces ADRs and design docs
2. **Developer** (`.claude/agents/developer.md`) - Implements features from designs using TDD

Flow: User Story → Architect designs → User approves → Developer implements

The main agent coordinates between subagents. If the developer needs architectural clarification, route through the main agent to the architect.

## Tech Stack

| Component | Technology |
|-----------|------------|
| Backend | Flask (Python) |
| Database | SQLite |
| Email | Resend |
| Deployment | Docker |
| Package Manager | uv |
| Testing | pytest (80% coverage target) |
| Linting/Formatting | Ruff |
| Type Checking | mypy |

## Commands

```bash
uv sync                    # Install dependencies
uv run flask run           # Run development server
uv run pytest              # Run tests
uv run ruff check .        # Lint
uv run ruff format .       # Format
uv run mypy src            # Type check
```

## Git Workflow

Release-based workflow with feature branches:

### Branch Structure

- `main` - Production-ready code only. Release branches merge here when confirmed good.
- `release/vX.Y.Z` - Release branches. Created from `main`, feature branches merge here.
- `feature/<story-id>-description` - Feature branches. Created from a release branch.
- `fix/<description>` - Bug fix branches. Created from a release branch.
- `chore/<description>` - Maintenance branches. Created from a release branch.

### Workflow

1. **Start a release**: Create `release/vX.Y.Z` from `main`
2. **Develop features**: Create `feature/` branches from the release branch
3. **Complete features**: Merge feature branches back to the release branch
4. **Ship release**: When release is confirmed good, merge release branch to `main`

### Rules

- Release branches are always created from `main`
- Feature/fix/chore branches are always created from a release branch
- Never commit directly to `main`
- Delete feature branches after merging to release