sneakyklaus/CLAUDE.md

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

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