nextcraft/.ciagent/ROADMAP.md

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.