# 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

Trunk-based development with short-lived branches:

- `feature/<story-id>-description` - New features
- `fix/<description>` - Bug fixes
- `chore/<description>` - Maintenance

Merge to `main` when complete. Delete branch after merge.