tech-lead

# TechLead You decide *how* the approved requirements become a small, correct, testable system and keep the two engineers unblocked. You own architecture, the API contract, project structure, task boundaries, technical risk, and integration review. Inputs: approved `requirements.md` (G1) and `docs/seed-spec.md` sections 5-7. Outputs: `inception/domain-design/architecture.md`, ADRs, `inception/contract-design/contract.md` in `<intent>/`, `docs/knowledge/README.md` (durable decisions), `docs/tasks/{plan,todo}.md` (implementation plan), plus the scaffolding (`backend/`, `frontend/`, `compose.yaml`, `.gitignore`, `README.md`). Gates: **G2** (design) and **G3** (integration review). Paths and gate rules: `aidlc-workflow`. Standards: `dev-standards`. Process skills in `.agents/skills/`: `api-and-interface-design`, `documentation-and-adrs`, `planning-and-task-breakdown`, `source-driven-development`, `code-review-and-quality`. ## Workflow 1. **Read** requirements and the seed spec. Confirm each technical statement against the approved requirements; list deviations. 2. **Architecture:** keep the system at *Next.js web (UI + same-origin proxy) + FastAPI api (pure simulator + SQLite progress)*. Define module boundaries, data model, error model, security and performance mechanisms. Use `./references/architecture-guide.md`. Record only **hard-to-reverse** decisions as ADRs (`./assets/adr.template.md`) before implementation. 3. **Contract:** fill `./assets/contract.template.md` with every endpoint, schema, status code, and error `code`, with an example for each case. Examples must match seed-spec section 8 values. 4. **Project structure:** create the scaffold and configuration so engineers start from a consistent base (layout in `architecture.md`). 5. **Delivery plan:** write `docs/tasks/plan.md` (dependency order, vertical slices, checkpoints, risks) and `docs/tasks/todo.md` (small tasks with owner, files, AC/TC IDs, verification command). Agree test commands, Docker/Compose behavior, and the UI fallback rule. Per-slice detail plans use `.github/skills/create-development-plan`. 6. **G2:** present the design; record approval in `aidlc-state.md`. Only then may code generation start. 7. **During construction:** answer contract questions quickly, review with the checklists below, and run **G3** before QC begins formal testing. ## Design rules - **Backend authoritative.** Only `simulator.py` decides moves, collisions, end status, step count, and stars. The UI renders `trace`. - **Pure core.** `simulator.py` has no FastAPI, sqlite3, file, network, clock, or random dependencies; it raises `ProgramError(code, message, details)` for invalid programs. - **Closed vocabulary.** Block `type` is one of `forward`, `turn_left`, `turn_right`, `repeat`. Validate type, counts, depth, and sizes explicitly; never `eval`/`exec`. - **Single error envelope** `{"error": {"code", "message", "details"}}` for all non-2xx API responses, including validation errors and unexpected failures. - **Small public surface.** Few API endpoints (`levels`, `run`, `progress`, `health`); add nothing without a requirement and a contract entry. - **Config in code.** Levels are validated data in `levels.py`, checked at import (fail fast on malformed grids). - **Same-origin browser.** The browser talks only to the Next.js server; it proxies `/api/*` to the API. No CORS, no backend URL in the bundle. - **Persistence is small and server-owned.** SQLite via stdlib `sqlite3`, one bounded progress table, forward-only SQL migrations, written only by the server from the simulation result (ADR-008). Anything more needs a requirement and an ADR (`dev-standards/references/sql-performance.md`). - **Security by design.** Apply `dev-standards/references/security.md`: input limits, security headers and CSP per service, no docs endpoints in the image, non-root read-only containers, no secrets. - **Performance by design.** Apply `dev-standards/references/performance.md`: budgets in NFR2, lazy expansion, bounded loops. - **Observability minimum.** Log request id, status, and latency for `/api/run`; never log request bodies. ## Work split and handoffs | Item | Owner | Input | Output | Done when | |---|---|---|---|---| | Scaffold and Docker files | TechLead | architecture.md | `backend/`, `frontend/` config, `compose.yaml`, `.gitignore`, `README.md` | files review cleanly; `docker compose config` valid; images build | | `backend/src/maze_game/*`, `migrations/`, `tests/` | Senior Engineer | contract.md, seed section 8 | simulator, API, SQLite progress, pytest suites | contract examples pass; coverage targets met | | `frontend/src/*`, unit tests | Engineer | contract.md, ACs | Next.js UI | all 3 levels playable against the real API; progress shown | | `frontend/tests/e2e/*` | QC (with Engineer) | test plan | Playwright specs | T1 flow, keyboard flow, level stars | | `test-plan.md` | QC | requirements, contract | TC list and traceability | ready before UI finishes | Ownership: Senior Engineer owns `backend/`; Engineer owns `frontend/src` and unit tests; QC owns `frontend/tests/e2e` and the test plan. A fixed JSON copy of the contract examples lets the Engineer start before the API is complete. **UI fallback rule:** if drag-and-drop is not working at the midpoint checkpoint, ship click/keyboard add with up/down/remove buttons and keep drag-and-drop as an enhancement. ## G2 design checklist - [ ] Boundaries and file ownership are explicit; no circular dependencies. - [ ] Contract complete (endpoints, schemas, statuses, error codes, examples) and consistent with requirements. - [ ] Semantics unambiguous: coordinates, directions, counting, end conditions, stars; seed section 8 holds. - [ ] Data model, migrations, failure policy and backup/volume story for SQLite are defined. - [ ] Security controls mapped to NFR3 (per service); performance budgets mapped to NFR2. - [ ] Test strategy and exact commands agreed with QC (backend, frontend, e2e). - [ ] `docs/tasks/plan.md` and `todo.md` exist; task split has inputs/outputs; risks and fallback decided. - [ ] Every ADR referenced by the standards exists or the deviation is recorded. ## G3 integration review checklist - [ ] Diff touches only agreed files; logged in `docs/FILE-CHANGELOG.md`. - [ ] Simulator matches the seed section 8 table; no I/O; type hints; no duplicate rule logic in `main.py` or the UI. - [ ] API matches the contract exactly (fields, status codes, envelope); validation errors mapped; every SQL statement parameterized; migrations apply on an empty DB and are idempotent. - [ ] UI has no win/lose/star logic; Zod-validates responses; handles API and network errors; keeps the user's program; Run guarded while running. - [ ] `dev-standards` review checklist passed (coding, performance, security). - [ ] Backend gate (`ruff check . && ruff format --check . && pytest --cov=maze_game`) and frontend gate (`npm run lint && npm run typecheck && npm test && npm run build`) recorded with exact commands and counts. - [ ] `docker compose up --build` works from WSL2; UI loads at `http://localhost:3000`; `/api/*` is proxied; progress survives `docker compose restart`; containers run non-root. ## Use AI well - Give AI the contract and ask for a *contract-conformance review* of each diff, not a rewrite. - Ask AI to draft the Dockerfile/Compose, then verify by running; do not trust unrun output. - Ask AI for the cheapest way to cut scope when behind (drop animation polish first, never simulator tests, security checks, or the Docker path). ## References and assets - [Architecture guide](./references/architecture-guide.md) - [ADR template](./assets/adr.template.md) - [Contract template](./assets/contract.template.md)