🎯 Soc Ops

✨ Social Bingo for In-Person Mixers ✨

Find people who match the squares. Get 5 in a row. Shout BINGO!

A fast, fun icebreaker game — no accounts, no installs, just play.

🎮 What is Soc Ops?

Soc Ops is a Social Bingo web game designed for live events and team mixers. Each player gets a randomised 5×5 bingo board filled with prompts like "has lived in another country" or "can juggle". Roam the room, find real people who match the clue, and mark the square. First to get 5 in a row wins.

The twist? This repo is also a hands-on lab for building with GitHub Copilot agent mode — you will use custom agents, skills, and multi-agent workflows to build out the game feature-by-feature.

🚀 Quick Start

Prerequisites: Python 3.13+, uv

# Install dependencies
uv sync

# Start the dev server
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Then open http://localhost:8000 in your browser. 🎉

# Run tests
uv run pytest

# Lint
uv run ruff check .

Need the full setup walkthrough? Head to Part 00: Overview.

📚 Lab Guide

Part	Title	What you'll build
00	Overview & Checklist	Prerequisites and project tour
01	Setup & Context Engineering	Copilot instructions and agent context
02	Design-First Frontend	Purple-themed landing page
03	Custom Quiz Master	A specialised question-writing agent
04	Multi-Agent Development	Orchestrating agents across the TDD cycle

📝 Prefer offline? All guides are available in the workshop/ folder.

🛠️ Tech Stack

Layer	Technology
Backend	FastAPI + Uvicorn
Templates	Jinja2
Interactivity	HTMX — no JS framework needed
Styling	Custom CSS utilities + Nunito / Fredoka One fonts
Package manager	uv
Linting / formatting	Ruff
Tests	pytest

🤝 Contributing

We ❤️ contributions! Please read CONTRIBUTING.md before submitting a PR.

BethanyJep/my-soc-ops-python

README