CIAgent
88a1dab810
---ci--- phase: 7 milestone: v0.2 status: complete requirements: covered: [REQ-2-001, REQ-2-002, REQ-2-003, REQ-2-004, REQ-2-005, REQ-2-006, REQ-2-007, REQ-2-008, REQ-2-009, REQ-2-010, REQ-2-011, REQ-2-012] partial: [] ---/ci--- Milestone v0.2 (ai-tutor-architecture) merged to main. Escalation record (audit remediation, durable): P1 executor delegation failed twice (empty subagent results, zero files created); auto-resolved at full autonomy to inline execution with identical plan fidelity (commit 3271373, reflog-only after phase branch squash-delete).
180 lines
8.2 KiB
Markdown
180 lines
8.2 KiB
Markdown
# 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. |