Curio/KICKOFF.md

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.