nextcraft/.ciagent/REQUIREMENTS.md

Nextcraft — REQUIREMENTS.md

v0.2 Requirements (AI Tutor Architecture)

AI Service Infrastructure

ID	Description	Priority	Phase	Status
REQ-2-001	apps/ai-service scaffolding: Python FastAPI app, pydantic settings, uvicorn, health endpoint, CORS, pytest setup, pnpm/turbo integration scripts	critical	1	complete
REQ-2-002	Provider-agnostic LLM client: OpenAI-compatible provider interface with ollama-cloud (default), local-endpoint, and deterministic mock providers; key resolution from env files	critical	1	complete
REQ-2-003	SSE streaming endpoint plumbing: chat completion streaming from provider through FastAPI to the Next.js client	critical	1	complete
REQ-2-004	Agent framework: base agent contracts, session/state store, prompt management, streaming pipeline, structured output support	critical	2	complete

AI Tutor Agents

ID	Description	Priority	Phase	Status
REQ-2-005	Coach agent (REQ-F-001): pacing, motivation, retrieval practice — full LLM implementation	critical	3	complete
REQ-2-006	Tutor agent (REQ-F-002): concept delivery, Socratic questioning — full LLM implementation	critical	3	complete
REQ-2-007	Lab agent (REQ-F-003): in-flow feedback over simulated sandbox telemetry (mock inputs)	high	4	complete
REQ-2-008	Assessor agent (REQ-F-004): rubric application to pre-baked artifacts and defense transcripts (mock inputs)	high	4	complete
REQ-2-009	Proctor agent (REQ-F-005): integrity signals from mock telemetry, coaching interventions	high	5	complete
REQ-2-010	Mentor agent (REQ-F-006): long-horizon career narrative	high	5	complete

Learner Surface Integration

ID	Description	Priority	Phase	Status
REQ-2-011	Learner chat UI wired to real service: streaming responses, agent routing, error and loading states	critical	6	complete
REQ-2-012	Byte tutorial viewer, build sandbox, and assessment mockups surface Lab/Assessor/Proctor outputs (mock engine inputs)	high	6	complete

---

v0.1 Requirements (Complete)

Infrastructure

ID	Description	Priority	Phase	Status
REQ-001	Monorepo scaffolding: pnpm workspaces, turborepo, Next.js app, TypeScript config, ESLint, Prettier	critical	1	complete
REQ-002	Shared component library: design tokens, Button, Input, Card, Badge, Avatar, Dialog, Navigation, Table, Tabs, Progress, Tooltip, Skeleton, Toast	critical	1	pending
REQ-003	Mock data layer: typed mock data for competency stacks, job listings, candidate profiles, employers, learner progress	critical	1	pending
REQ-004	Routing and navigation: App Router route groups for (learner), (marketplace), (employer), (admin); shared layout components; cross-surface navigation	critical	1	pending
REQ-005	Responsive layout system: mobile, tablet, desktop breakpoints; container components; grid system	high	1	pending

Learner Surface

ID	Description	Priority	Phase	Status
REQ-006	Landing page: hero, value proposition, program highlights, how-it-works (Byte→Build→Demonstrate→Defend), testimonials mockup, CTA to program catalog	critical	2	pending
REQ-007	Program catalog: grid of competency stacks (AI Orchestration Engineer, AI Safety & Governance Lead, Human-AI Product Designer, AI-Augmented Field Operator, Computational Sciences Practitioner); stack cards with role descriptions	critical	2	pending
REQ-008	Competency stack view: selected stack detail with 12-18 competencies listed, progress indicators, microcredential badges, mastery status	critical	2	pending
REQ-009	Learner dashboard: active competencies, progress graph, recent artifacts, upcoming defenses, AI tutor chat mockup, milestone tracker	critical	2	pending
REQ-010	Byte tutorial viewer: 3-7 minute micro-tutorial layout with concept panel, worked example panel, code/design/simulation viewer mockup	high	2	pending
REQ-011	Build sandbox mockup: sandboxed IDE/design tool/simulation UI mockup with toolbar, file explorer, editor area, telemetry sidebar (process capture indicators)	high	2	pending
REQ-012	Assessment/defense mockup: rubric display, AI reviewer panel, oral defense interface (voice/mic mockup), process trace timeline, artifact viewer	high	2	pending

Marketplace Surface

ID	Description	Priority	Phase	Status
REQ-013	Job board listing: searchable grid of AI-era job listings, filter sidebar (skills, seniority, location, salary), result cards with match score	critical	3	pending
REQ-014	Job detail page: full job description, required competencies, employer info, application CTA, related jobs, AI-matched skills breakdown	critical	3	pending
REQ-015	Employer profile: company overview, logo, description, social links, open positions, company culture mockup	high	3	pending
REQ-016	Search/filter UI: semantic search bar, skill tags, category filters, seniority filter, remote/on-site toggle, saved searches mockup	critical	3	pending
REQ-017	Pricing page: job posting packages (single, bundle, enterprise), talent access plans, subscription tiers, feature comparison table	high	3	pending

Employer Dashboard

ID	Description	Priority	Phase	Status
REQ-018	Employer dashboard overview: active postings, applicant pipeline, talent matches, analytics mockup (charts, placement stats)	critical	4	pending
REQ-019	Talent search: searchable candidate database with AI-matched filters, candidate cards showing competency stack, microcredentials, artifact count, defense score	critical	4	pending
REQ-020	Candidate profile view: full candidate profile with artifact gallery, process trace summary, oral defense transcripts, competency graph, microcredential verification	high	4	pending
REQ-021	Posting management: create/edit/delete job postings, posting status tracking, applicant list per posting, interview pipeline mockup	high	4	pending

Admin Surface

ID	Description	Priority	Phase	Status
REQ-022	Admin overview: platform metrics (learners, employers, placements, completion rate, NPS), recent activity feed, system health mockup	critical	5	pending
REQ-023	Learner management: searchable learner table, learner detail view, progress tracking, competency completion status, credential issuance log	high	5	pending
REQ-024	Competency graph viewer: interactive visualization of competency stacks and their relationships, node/edge graph using react-flow, stack details on node click	high	5	pending
REQ-025	Marketplace moderation: job posting review queue, employer verification queue, flagged content, content moderation tools mockup	high	5	pending

Polish & Integration

ID	Description	Priority	Phase	Status
REQ-026	Cross-surface navigation: role switcher (learner/employer/admin), breadcrumbs, consistent header/footer across all surfaces	critical	6	pending
REQ-027	Visual consistency audit: typography scale, color palette, spacing system, dark mode toggle, accessibility baseline (WCAG AA contrast)	high	6	pending
REQ-028	Component library finalization: Storybook setup, component documentation, prop tables, usage examples	medium	6	pending

---

v2 Requirements (Future Milestones — Deferred)

Assessment Engine

ID	Description	Priority	Milestone	Status
REQ-F-007	Process-trace grading engine	high	v0.3+	deferred
REQ-F-008	Per-learner variant task generation	high	v0.3+	deferred
REQ-F-009	Oral/voice defense with AI examiner	high	v0.3+	deferred
REQ-F-010	Live in-environment build with telemetry	high	v0.3+	deferred
REQ-F-021	Sandbox fabric: sandboxed IDE, design tool, simulation	high	v0.3+	deferred

Marketplace Engine

ID	Description	Priority	Milestone	Status
REQ-F-011	AI job aggregation pipeline (3M+ jobs from 120K companies)	high	v0.4+	deferred
REQ-F-012	AI-powered tagging (skills, categories, seniority)	high	v0.4+	deferred
REQ-F-013	Semantic vector search for role matching	high	v0.4+	deferred
REQ-F-014	AI company enrichment (logos, descriptions, social links)	medium	v0.4+	deferred
REQ-F-015	AI resume parsing (profile auto-fill)	medium	v0.4+	deferred
REQ-F-016	SEO-optimized programmatic pages	medium	v0.4+	deferred

Platform Infrastructure

ID	Description	Priority	Milestone	Status
REQ-F-017	Identity verification and age-gating (16+/18+) — real KYC backend	high	v0.3+	deferred
REQ-F-018	Payment processing and subscription management	high	v0.3+	deferred
REQ-F-019	Human tutor marketplace (third-party courses)	medium	v0.4+	deferred
REQ-F-020	CIRR-style placement tracking and audit	medium	v0.5+	deferred

---

Out of Scope (Per Vision Doctrine)

Feature	Reason
Traditional accreditation	Not sought, not pursued, not revisited (Principle 4)
Under-16 learners	COPPA avoidance; AI school floor is 16+
Marketplace for under-18	Marketplace restricted to 18+ with verified identity
Human tutors in core school	Humans exist only in open marketplace as third-party sellers
Graded written exams without process trace	Trivially solvable by frontier AI; process-trace + oral defense more valid
Legacy job titles in curriculum	Programs train for AI-era roles, not obsolete ones
Junk advertising	Ad quality enforced algorithmically; relevant ads only

---

Traceability Matrix

v0.2 (current milestone)

Requirement	Phase	Status
REQ-2-001	1	complete
REQ-2-002	complete
REQ-2-003	1	complete
REQ-2-004	complete
REQ-2-005	complete
REQ-2-006	complete
REQ-2-007	complete
REQ-2-008	complete
REQ-2-009	complete
REQ-2-010	complete
REQ-2-011	complete
REQ-2-012	complete

v0.1 (complete)

Requirement	Phase	Status
REQ-001	1	complete
REQ-002	1	complete
REQ-003	1	complete
REQ-004	1	complete
REQ-005	1	complete
REQ-006	2	complete
REQ-007	2	complete
REQ-008	2	complete
REQ-009	2	complete
REQ-010	2	complete
REQ-011	2	complete
REQ-012	2	complete
REQ-013	3	complete
REQ-014	3	complete
REQ-015	3	complete
REQ-016	3	complete
REQ-017	3	complete
REQ-018	4	complete
REQ-019	4	complete
REQ-020	4	complete
REQ-021	4	complete
REQ-022	5	complete
REQ-023	5	complete
REQ-024	5	complete
REQ-025	5	complete
REQ-026	6	complete
REQ-027	6	complete
REQ-028	6	complete