# Nextcraft — ROADMAP.md

## Overview

**Milestone v0.2** — AI Tutor Architecture: The six AI tutor agents (Coach, Tutor, Lab, Assessor, Proctor, Mentor) as real LLM-backed services in a new `apps/ai-service` Python FastAPI application, wired into the existing v0.1 learner surface with streaming responses. Provider-agnostic LLM layer (ollama-cloud default). Lab/Assessor/Proctor operate on mock engine inputs — their real engines are v0.3+.

**Prior milestone:** v0.1 (nextcraft-ui-prototype) — complete, shipped as v0.1.0, founder-agreed (D-013).

**Milestone type:** Feature (new AI service + real agent capabilities)
**Tag line:** v0.1.x (patches on the v0.1 line; milestone release as v0.2.0)
**Branch:** milestone/v0.2-ai-tutor-architecture

---

## Phase List

| # | Name | Status | Depends On | Requirements | Success Criteria |
|---|------|--------|------------|--------------|------------------|
| 0 | Pre-execution | complete | — | — | Specification, clarify, research, plan complete; .ciagent/ files updated for v0.2 |
| 1 | AI service scaffolding | complete | 0 | REQ-2-001, REQ-2-002, REQ-2-003 | apps/ai-service runs (uvicorn), health endpoint responds, provider-agnostic LLM client with 3 providers (ollama-cloud/local/mock), SSE streaming verified, pytest suite passes with mock provider, turbo scripts wired |
| 2 | Agent framework | complete | 1 | REQ-2-004 | Base agent contract, session/state store, prompt templates, streaming pipeline, structured outputs; all tested |
| 3 | Coach + Tutor agents | complete | 2 | REQ-2-005, REQ-2-006 | Coach (pacing/motivation/retrieval practice) and Tutor (concept delivery/Socratic questioning) fully implemented with system prompts, tested against mock provider, wired to chat endpoint |
| 4 | Lab + Assessor agents | complete | 2 | REQ-2-007, REQ-2-008 | Lab consumes simulated sandbox telemetry (mock); Assessor applies rubrics to pre-baked artifacts/defense transcripts (mock); both tested |
| 5 | Proctor + Mentor agents | complete | 2 | REQ-2-009, REQ-2-010 | Proctor produces integrity signals + coaching interventions from mock telemetry; Mentor generates long-horizon career narrative; both tested |
| 6 | Learner surface integration | complete | 3, 4, 5 | REQ-2-011, REQ-2-012 | Learner chat streams real responses; agent routing works; byte viewer/sandbox/assessment mockups surface agent outputs; error/loading states; pnpm build + typecheck pass |
| 7 | Final review + ship | complete | 6 | — | Code review clean; audit passes; milestone tagged v0.2.0; release created on Gitea |

---

## Phase Details

### Phase 0: Pre-execution

**Goal:** Establish v0.2 specification, clarify ambiguities, research AI service architecture, create detailed plans.

**Stages:** SPECIFY → CLARIFY → RESEARCH → PLAN → GRILL → SHIP

**Deliverables:**
- Updated .ciagent/config.json, PROJECT.md, REQUIREMENTS.md, ROADMAP.md, ARCHITECTURE.md, PERSONAS.md, PLAN.md

**Success criteria:** All .ciagent/ files updated for v0.2; phase 0 shipped as v0.1.1.

---

### Phase 1: AI Service Scaffolding

**Goal:** Stand up apps/ai-service with the provider-agnostic LLM layer and SSE streaming.

**Requirements:** REQ-2-001, REQ-2-002, REQ-2-003

**Key deliverables:**
- apps/ai-service: FastAPI app, pydantic-settings, uvicorn, /health, CORS for localhost
- llm package: provider interface + ollama-cloud/local/mock providers; key resolution from .ciagent/.env.secrets via env
- SSE streaming: /v1/chat/stream endpoint streaming provider deltas
- pytest suite with mock provider; root scripts: ai:dev, ai:test; turbo integration

**Success criteria:**
- `python -m uvicorn` starts the service; /health returns 200
- Provider unit tests pass (mock); ollama-cloud integration probe works (manual)
- SSE stream delivers tokens to an HTTP client

---

### Phase 2: Agent Framework

**Goal:** Build the shared framework all six agents use.

**Requirements:** REQ-2-004

**Key deliverables:**
- BaseAgent contract: system prompt, message history, streaming completion, structured output
- Session/state store: in-memory per-learner session with message history
- Prompt management: per-agent system prompt templates with learner context injection
- Streaming pipeline: agent → provider → SSE with agent identification
- Structured outputs: JSON-schema outputs for Assessor rubric scores, Proctor signals

**Success criteria:**
- BaseAgent unit tests pass
- Session store tested (create/append/persist in-memory)
- Structured output parsing tested against mock provider

---

### Phase 3: Coach + Tutor Agents

**Goal:** Implement the two learner-facing conversational agents.

**Requirements:** REQ-2-005, REQ-2-006

**Key deliverables:**
- Coach agent: pacing guidance, motivation, retrieval practice prompts; distinct persona
- Tutor agent: concept delivery, Socratic questioning, worked examples
- Agent registry: route chat messages to the correct agent by context/selection
- Per-agent system prompts with competency-stack context injection from packages/mock-data

**Success criteria:**
- Both agents produce distinct, on-persona responses (verified against mock + ollama-cloud)
- Agent routing tested
- Both agents exposed via the chat streaming endpoint

---

### Phase 4: Lab + Assessor Agents

**Goal:** Implement the two build/assessment agents over mock engine inputs.

**Requirements:** REQ-2-007, REQ-2-008

**Key deliverables:**
- Lab agent: consumes simulated sandbox telemetry (mock event streams), produces in-flow feedback
- Assessor agent: applies rubrics to pre-baked artifacts and defense transcripts, returns structured scores + feedback
- Mock engine inputs: simulated telemetry generator, pre-baked artifact corpus in packages/mock-data
- Endpoints: /v1/lab/feedback, /v1/assessment/evaluate

**Success criteria:**
- Lab produces relevant feedback for mock telemetry scenarios
- Assessor returns structured rubric scores (JSON) for pre-baked artifacts
- Both tested against mock provider

---

### Phase 5: Proctor + Mentor Agents

**Goal:** Implement the integrity and narrative agents.

**Requirements:** REQ-2-009, REQ-2-010

**Key deliverables:**
- Proctor agent: integrity signals from mock telemetry (tab switches, idle time, paste events), coaching interventions
- Mentor agent: long-horizon career narrative, competency-stack progression guidance
- Endpoints: /v1/proctor/signals, /v1/mentor/narrative

**Success criteria:**
- Proctor produces classified signals with recommended interventions for mock scenarios
- Mentor produces coherent career-narrative responses
- Both tested against mock provider

---

### Phase 6: Learner Surface Integration

**Goal:** Wire the v0.1 learner surface to the real AI service.

**Requirements:** REQ-2-011, REQ-2-012

**Key deliverables:**
- Learner dashboard chat: real streaming via SSE, agent switcher (Coach/Tutor), error/loading states
- Byte tutorial viewer: Tutor concept explanations
- Build sandbox: Lab feedback panel fed by mock telemetry + Lab agent
- Assessment mockup: Assessor rubric output display, Proctor integrity banner
- Mentor panel on learner dashboard

**Success criteria:**
- Streaming chat works end-to-end with ai-service running
- All four learner surfaces surface agent outputs
- Graceful degradation when ai-service is down (error states, not crashes)
- `pnpm build` and `pnpm typecheck` pass

---

### Phase 7: Final Review + Ship

**Goal:** Code review, audit, milestone release.

**Key deliverables:**
- Multi-persona code review (correctness, testing, security, performance, maintainability)
- Project health audit (reconstruction test, .ciagent/ file discipline, branch hygiene, commit discipline)
- Milestone ship: merge milestone → main, tag v0.2.0, create Gitea release

**Success criteria:**
- Code review: P0 fixes applied, P1+ documented
- Audit: all checks pass, project state reconstructable from git log
- Ship: v0.2.0 tagged, milestone branch merged to main, Gitea release created — **release note explicitly states Lab/Assessor/Proctor operate on mock engine inputs (real engines v0.3+)** (G-5); dead `aiTutorResponses` export disposed of (G-5)
- All 12 v0.2 requirements marked complete

---

## v0.1 (Complete — Shipped as v0.1.0)

UI/UX Prototype: High-fidelity interactive prototype of all four Nextcraft surfaces. 7 phases (P0 + P1-P6 execution + P7 final). All 28 requirements complete. Tags v0.0.1–v0.0.7, milestone release v0.1.0.