diff --git a/documentation/ai-context/99-current-task.md b/documentation/ai-context/99-current-task-blueprint.md similarity index 72% rename from documentation/ai-context/99-current-task.md rename to documentation/ai-context/99-current-task-blueprint.md index cd28365..9bc1325 100644 --- a/documentation/ai-context/99-current-task.md +++ b/documentation/ai-context/99-current-task-blueprint.md @@ -34,6 +34,7 @@ Example: "Implement guest play flow so users can try a 3-round quiz without crea [List files you've identified. The LLM may ask for additional ones.] Example: + - `apps/api/src/controllers/gameController.ts` — needs guest variant - `apps/api/src/middleware/authMiddleware.ts` — needs optional auth path - `packages/shared/src/schemas/game.ts` — needs GuestGameRequestSchema @@ -43,20 +44,24 @@ Example: ## Constraints & Requirements **Must have:** + - [ ] - [ ] **Nice to have:** + - [ ] - [ ] **Must NOT break:** + - [ ] Existing auth flow (logged-in users still work normally) - [ ] WebSocket protocol (if applicable) - [ ] Database schema (additive changes only unless migration planned) - [ ] Zod schemas in `packages/shared` (no silent drift) **Known blockers or open questions:** + - [ ] --- @@ -80,17 +85,18 @@ After the task is complete, ask the LLM: The LLM should check: -| File | Check if... | -|------|-------------| -| `documentation/STATUS.md` | Task changes what's working or what's blocked | -| `documentation/BACKLOG.md` | Task completes a backlog item or creates a new one | -| `documentation/DECISIONS.md` | Task involved choosing between alternatives with long-term consequences | -| `documentation/ARCHITECTURE.md` | Task changes monorepo structure, data flow, or layer boundaries | -| `documentation/ai-context/*.md` | Task changes schemas, endpoints, protocol, or pipeline stages | -| `packages/shared/src/schemas/*.ts` | Task changes request/response shapes or WS message types | -| `README.md` | Task changes quickstart steps, stack, or current status | +| File | Check if... | +| ---------------------------------- | ----------------------------------------------------------------------- | +| `documentation/STATUS.md` | Task changes what's working or what's blocked | +| `documentation/BACKLOG.md` | Task completes a backlog item or creates a new one | +| `documentation/DECISIONS.md` | Task involved choosing between alternatives with long-term consequences | +| `documentation/ARCHITECTURE.md` | Task changes monorepo structure, data flow, or layer boundaries | +| `documentation/ai-context/*.md` | Task changes schemas, endpoints, protocol, or pipeline stages | +| `packages/shared/src/schemas/*.ts` | Task changes request/response shapes or WS message types | +| `README.md` | Task changes quickstart steps, stack, or current status | **Expected output format:** + ``` - FILE: [filename] — REASON: [what changed and why the doc needs updating] ``` diff --git a/documentation/ai-context/99-current-task.md b/documentation/ai-context/99-current-task.md new file mode 100644 index 0000000..24a16eb --- /dev/null +++ b/documentation/ai-context/99-current-task.md @@ -0,0 +1,78 @@ +# 99 — Current Task + +## Task Description + +Implement guest play flow so users can try a 3-round singleplayer quiz without creating an account. After completing the quiz, optionally prompt them to sign up to save progress. + +## Context + +**Which parts of the codebase does this touch?** + +- [x] Frontend (`apps/web/`) +- [x] Backend API (`apps/api/`) +- [ ] Database schema (`packages/db/`) — no schema changes needed +- [x] Shared schemas (`packages/shared/`) — may need GuestGameRequestSchema +- [ ] WebSocket protocol (`apps/api/src/ws/`) — not touched (guest play is singleplayer only) +- [ ] Data pipeline (`data-pipeline/`) +- [ ] Infrastructure / deployment (`docker-compose.yml`, Caddyfile, etc.) +- [x] Documentation + +**Relevant files I already know about:** + +- `apps/api/src/middleware/authMiddleware.ts` — needs optional auth path +- `apps/api/src/controllers/gameController.ts` — needs guest variant of start/answer +- `apps/api/src/services/gameService.ts` — may need guest session logic +- `apps/api/src/routes/gameRouter.ts` — route definitions +- `apps/web/src/routes/play.tsx` — singleplayer route +- `apps/web/src/components/game/GameSetup.tsx` — start quiz UI +- `packages/shared/src/schemas/game.ts` — request/response schemas +- `apps/web/src/components/auth/AuthModal.tsx` — post-game auth prompt + +## Constraints & Requirements + +**Must have:** + +- [ ] Guest users can start and complete a singleplayer quiz (3 or 10 rounds) +- [ ] No login required to reach `/play` or call `POST /api/v1/game/start` +- [ ] Server-side answer evaluation still works (correct answer never sent to frontend) +- [ ] Guest sessions are ephemeral (no database storage of guest progress) +- [ ] After quiz completion, show a friendly "Save your progress?" prompt with auth options + +**Nice to have:** + +- [ ] Guest sessions stored in-memory with a TTL (e.g., 24h) so refreshing the page doesn't lose the current quiz +- [ ] Post-game prompt includes a "Continue as guest" option to play again without signing up + +**Must NOT break:** + +- [x] Existing auth flow (logged-in users still work normally) +- [x] WebSocket protocol (if applicable) +- [x] Database schema (additive changes only unless migration planned) +- [x] Zod schemas in `packages/shared` (no silent drift) + +**Known blockers or open questions:** + +- [ ] Should guest sessions use the same `GameSessionStore` interface with a guest flag, or a separate store? +- [ ] Should the post-game auth prompt be a modal or a redirect to a dedicated page? + +## Definition of Done + +- [ ] Code implemented and tested +- [ ] No TypeScript errors (`pnpm typecheck` passes) +- [ ] Tests pass (`pnpm test`) +- [ ] Manual verification in dev environment (both logged-in and guest flows) +- [ ] Commit message follows convention +- [ ] Feature branch merged to main + +## Post-Work Checklist + +After the task is complete, ask the LLM: + +> "Review the post-work checklist in prompts/meta.md. Which documentation files need updates based on what we just changed?" + +Expected doc updates: + +- `documentation/STATUS.md` — Guest play is now live +- `documentation/ai-context/03-api-contract.md` — New guest endpoint or schema changes +- `packages/shared/src/schemas/game.ts` — If GuestGameRequestSchema added +- `README.md` — Quickstart may mention guest play