Files

T

ducoterra f84c6ebaef Scaffold project and author 14-phase roadmap

Browser co-op kitchen game: FastAPI + native WebSockets, server-authoritative
20 Hz simulation, in-memory anonymous lobbies, data-driven YAML levels, Canvas 2D
vanilla ES-module client with locally authored SVG art and no external CDNs.

.agents/PLAN.md records the LOCKED decisions; .agents/user_stories/ holds the 12
flow contracts; .agents/phases/todo/ breaks them into 14 sequential, test-gated
phases (71 task files), each leaving the app launchable and the suite green.

LLM-Generated: true

2026-10-05 17:05:56 -04:00

2.8 KiB

Raw Blame History

Phase 01 — Runnable service scaffold

Story: US-01_create_anonymous_lobby (partial — landing surface only) Context: .agents/PLAN.md §4 (app/static/HTTP boundary), A1, A2, A12, A17, A18, A20

Objective

Turn the empty repository into a launchable FastAPI service that serves the client shell, exposes /healthz, enforces the no-external-asset rule, and has its quality toolchain wired end to end. Nothing about gameplay exists yet; the app must still boot, serve, and pass every check.

Dependencies

none (first phase; pyproject.toml, Containerfile, compose.yaml, README.md, AGENTS.md, .agents/PLAN.md already exist in the repo)

Tasks

01_lock_toolchain_and_packages.md — deps resolve, uv sync clean, test tree + markers, first passing test
02_config_and_debugpy.md — typed env config, .env.example, debugpy bootstrap
03_fastapi_app_and_static_shell.md — app factory, CLI entry point, static shell page, security headers
04_no_cdn_guard_and_docs.md — no-external-asset test, header tests, README/AGENTS verified

Testing & Quality

Unit: config parsing/defaults/overrides; static asset scan finds zero external URLs; security headers present; /healthz returns 200 with a JSON body.
Integration: app boots through create_app() and serves / and /static/*.
Coverage: >90% on new/modified code (config.py and server/app.py fully covered).
The phase is "Complete" only when the entire project test suite passes 100% (every test in the project, not just this phase's).
Gate commands, all green: uv run ruff check ., uv run pyright, uv run pytest.

Documentation & Consistency

The final pass reviews README.md and AGENTS.md in full against the project as it will stand after this phase — fixing every inconsistency found, including pre-existing ones not caused by this phase (e.g. commands or variable names that drifted from config.py).
Tasks update README.md/AGENTS.md immediately when their own changes are user-visible (setup, commands, configuration, features, conventions).

Completion Criteria

uv sync --extra dev succeeds and uv.lock is committed
uv run undercooked --host 127.0.0.1 --port 8000 & then curl -fsS http://127.0.0.1:8000/healthz → {"status":"ok"}; curl -fsS http://127.0.0.1:8000/ → the shell HTML
DEBUGPY=1 uv run undercooked opens port 5678 and still serves /healthz
uv run pytest -q → 100% passing, coverage ≥ 90%
uv run ruff check . and uv run pyright → zero errors
no file under app/static/ references an external URL (test-enforced)
README.md and AGENTS.md are accurate and consistent with the whole project (verified in the final pass)
no behavior change in completed phases (n/a — first phase)

2.8 KiB Raw Blame History