arnaudne
4e38b5a791
Full Next.js App Router application with: - AI-graded lesson checkpoints (BKT/Elo mastery tracking) - Auth.js v5: credentials, Google, GitHub, generic OIDC - Anonymous-session-first with migrate-on-signin - Admin panel: users, blueprints, reports, site settings - Password reset + email verification (nodemailer/SMTP) - Site config: require_auth + signups_enabled flags - server-only guards on all DB/generation/verification modules - PostgreSQL 16 + pgvector, Redis cache, Drizzle ORM - 271 unit tests (Vitest), golden-eval harness, Playwright e2e stubs Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
84 lines
8.6 KiB
Markdown
84 lines
8.6 KiB
Markdown
# Curio — Claude Code Kickoff & Task Plan
|
||
|
||
Two parts: the **kickoff prompt** to paste into Claude Code first, and the **phased tickets** to work through after. Both assume `docs/curio-specification.md` and `CLAUDE.md` are in the repo.
|
||
|
||
---
|
||
|
||
## PART 1 — Kickoff prompt (paste this first)
|
||
|
||
> You are building **Curio**, an AI mastery tutor (TypeScript, single stack). Read `CLAUDE.md` and `docs/curio-specification.md` in full before doing anything — `CLAUDE.md` holds the decided stack, repo structure, and the architectural + design invariants, all non-negotiable.
|
||
>
|
||
> **Do not write feature code yet.** First, produce a plan: propose the initial scaffold (matching the structure in `CLAUDE.md`) — Next.js (App Router, TS) + Tailwind, docker-compose for Postgres+pgvector and Redis, Drizzle schema + migration setup, Vitest, and a stubbed `src/lib/llm/client.ts` wrapping the Vercel AI SDK with generator + grader as distinct configured models, mockable in tests. Include a minimal `src/styles/` design-token file derived from the §7 direction. List the files you'll create and the commands that verify the scaffold runs. **Wait for my approval before implementing.**
|
||
>
|
||
> After I approve the scaffold, we work through the tickets in this plan **one at a time**, in order. For each ticket: plan briefly, implement, write tests, run the suite, then stop and summarize what changed and how to verify it. Do not start the next ticket until I confirm.
|
||
>
|
||
> For any ticket that builds UI, **first run the frontend-design two-pass process** (plan tokens → critique for genericness against the §7 brief → build); do not reach for AI-default looks. Honor every invariant in `CLAUDE.md` — especially: all LLM calls go through `src/lib/llm/client.ts`; contracts are shared Zod schemas; the grader supports `uncertain`/abstention and is biased against false-fail; content carries provenance; the serve path reads the buffer while jobs generate; motion is CSS/View-Transitions only. If a ticket appears to require anything in the "Out of scope" list, stop and ask.
|
||
|
||
**Why this shape:** Claude Code performs best with (1) full context up front, (2) a plan-and-confirm gate before large work, (3) bounded tickets it completes and verifies one at a time, and (4) a fixed set of invariants it can check itself against.
|
||
|
||
---
|
||
|
||
## PART 2 — Tickets (build in order; each is a vertical or testable slice)
|
||
|
||
Format per ticket: **Goal · Scope · Acceptance criteria.** "Done" = acceptance criteria met **and** tests pass **and** invariants upheld.
|
||
|
||
### P0-1 — Scaffold & infra
|
||
- **Goal:** Runnable skeleton.
|
||
- **Scope:** Repo structure per `CLAUDE.md`; Next.js (App Router, TS) + Tailwind; docker-compose (pg+pgvector, redis); Drizzle init + first migration; `/api/health` route handler; `src/lib/llm/client.ts` (Vercel AI SDK) with a **mock provider**; `src/schemas/` bootstrapped with Zod; `src/styles/` design tokens; Vitest + eslint/prettier configured.
|
||
- **Accept:** `docker compose up` + `pnpm dev` start; `/api/health` returns 200; `pnpm test` runs; LLM client is importable and mockable; tokens load in a sample page.
|
||
|
||
### P1-1 — Content model + seeded corpus + retrieval
|
||
- **Goal:** Grounding substrate for one hardcoded topic.
|
||
- **Scope:** Drizzle schema + migrations for `source_chunk`, `concept`, `lesson`, `segment`, `checkpoint`, `misconception`, `job` (see spec §17). Seed a small trusted corpus for ONE topic. pgvector retrieval helper in `src/lib/intent`/`generation`.
|
||
- **Accept:** Given a concept, retrieval returns relevant chunks; migrations run clean up/down; seed script idempotent.
|
||
|
||
### P1-2 — Lesson generation (RAG-grounded)
|
||
- **Goal:** Generate one Lesson for the seeded topic.
|
||
- **Scope:** `src/lib/generation` produces a Lesson = 2–3 segments, each with explanation + one checkpoint + **reference answer + rubric**, grounded in retrieved chunks, storing `source_chunk_ids`. Schema-constrained (Zod) structured output via the AI SDK. Prompts in the registry.
|
||
- **Accept:** Lesson persists with provenance on every segment; rubric + reference answer present per checkpoint; reproducible against a mocked LLM; one real-model smoke test.
|
||
|
||
### P1-3 — Serve + render the reading surface (design-critical)
|
||
- **Goal:** Learner reads a beautiful Lesson and reaches a checkpoint.
|
||
- **Scope:** Route handler returns a Lesson (served from buffer/cache, not generated inline); reading surface renders segments as calm editorial prose with checkpoints punctuating (not peppering); free-text input at each checkpoint. **Run the frontend-design pass first**; implement the §7 direction (reading serif, generous measure, restrained chrome, tokens from `src/styles/`). Cold-start outline is a designed state, not a spinner.
|
||
- **Accept:** Reads like a short article; meets the quality floor (responsive, keyboard focus, reduced-motion, AA contrast); no synchronous generation in the request path (assert via test/log).
|
||
|
||
### P1-4 — Response grading + marginalia (the moat MVP)
|
||
- **Goal:** AI diagnoses a free-text response and the tutor responds in the margin.
|
||
- **Scope:** `src/lib/verification` grader evaluates the response against the **pre-stored rubric + reference answer + misconception library**; returns the §10.3 grader contract (Zod-validated); supports `uncertain` → reveal model answer; biased against false-fail. UI renders **diagnosis-as-marginalia** threaded to the `evidence_span`, with the single View-Transitions motion moment. Persist `response` + `grade`. Wire Langfuse tracing on the call.
|
||
- **Accept:** Correct/partial/misconceived/empty responses each map to sensible verdicts on a mocked grader; `uncertain` triggers reveal; feedback points at the learner's own words; every response→grade is logged with cost/latency.
|
||
|
||
### P1-5 — Golden eval harness (gate the moat)
|
||
- **Goal:** Measure grading quality; prevent regressions.
|
||
- **Scope:** `tests/golden/` with labeled `response → expected verdict` cases for the seeded topic; a runner reporting accuracy, **false-fail rate**, misconception-hit rate; wired into CI (`pnpm test:golden`).
|
||
- **Accept:** Runs against the real grader and prints metrics; CI fails if false-fail rate exceeds the set threshold; adding a case is trivial.
|
||
|
||
> **P1 milestone = MVP hypothesis test:** one topic, generate → read → produce → diagnose-in-the-margin → reveal, with measured grading quality. Validate diagnosis quality (and that the marginalia experience lands) before expanding.
|
||
|
||
### P2-1 — Misconception library quality
|
||
- **Goal:** Diagnosis depth. Generate distinct, real, diagnosable misconceptions per concept; verify them (T2).
|
||
- **Accept:** Golden misconception-hit rate beats a generic-feedback baseline; misconceptions are distinct and source-grounded.
|
||
|
||
### P2-2 — Content verification cascade
|
||
- **Scope:** T0 structural + T1 cheap-model grounding + **blind checkpoint self-solve**; T2 adversarial at promotion. Amortized per blueprint.
|
||
- **Accept:** Bad content (unsupported claim, wrong reference answer) is caught; verification runs once per blueprint, not per serve; golden content-verification metrics tracked.
|
||
|
||
### P3-1 — Mastery + spaced repetition
|
||
- **Scope:** `src/lib/memory`: per-concept mastery (BKT or Elo) updated from grades; spaced-rep schedule; mastery gate on advancement.
|
||
- **Accept:** Mastery moves correctly on repeated outcomes; due-review query returns the right concepts.
|
||
|
||
### P3-2 — Blueprint cache + intent normalization + jobs
|
||
- **Scope:** Structured + embedding intent keying; blueprint lookup; **BullMQ** workers for `generate_next` / `promote_to_blueprint` with **idempotency keys + durable `job` state**; Redis buffer with backpressure; edge rate limiter on cold-start.
|
||
- **Accept:** Equivalent intents collapse to one key; warm serves are cache hits (no generation); cold path promotes into cache async; a retried job never regenerates-and-rebills.
|
||
|
||
### P4 — Roadmap features (only when asked, one at a time)
|
||
Confidence rating before reveal · Socratic follow-up on `partial` · Daily Review · mastery map · source citations · variant-based personalization · accounts. (XP/feed/social/voice/PDF remain out of scope per `CLAUDE.md`.)
|
||
|
||
---
|
||
|
||
## Claude Code workflow tips
|
||
|
||
- Run `/init` once to seed a `CLAUDE.md`, then replace it with the curated one — keeps it accurate to the actual repo.
|
||
- Use **plan mode** for P0-1, any ticket on the grading/verification path, and any UI ticket (pair it with the frontend-design pass).
|
||
- Keep context lean: point it at specific files per ticket rather than the whole tree.
|
||
- After each ticket, run `pnpm test` + `pnpm test:golden` and report metrics before moving on.
|
||
- Treat the golden eval thresholds as the definition of "good enough" — they're how Claude Code knows whether its diagnosis work actually works. |