nextcraft/.ciagent/PROJECT.md

Nextcraft — PROJECT.md

What This Is

Nextcraft is an AI-native outcome school where graduates prove what they can build — not what they can write. It credentials verifiable skill for a post-AI labor market, rejects legacy degree structures, and trains the workforce of tomorrow through hands-on competency stacks assessed entirely by AI tutors. The marketplace is the symbiotic second surface: employers meet AI-credentialed talent through an automated, algorithmically-matched job board that runs without human headcount.

Single guiding outcome: ≥1,000 learners placed in AI-orchestration roles via the Nextcraft marketplace within 36 months of launch, verified by CIRR-style third-party audit.

---

Current Milestone: v0.3 — Credential Engines

Scope: Replace v0.2's mock engine inputs with real credential engines. Build the sandbox fabric (sandboxed IDE / design tool / simulation), the live in-environment build-telemetry pipeline, the process-trace grading engine, per-learner variant task generation, and the oral/voice defense with AI examiner. Lab/Assessor/Proctor agents move from mock inputs to real engine inputs; the six tutor agents operate on authentic telemetry and artifacts.

Status of v0.2: Complete and shipped (v0.2.0). Six AI tutor agents live over mockengine inputs (D-015).

Deferred from earlier plan: REQ-F-017 (identity verification + 16+/18+ age-gating) is explicitly deferred to a later milestone per founder directive. Age-gating remains the v0.1-style visual flow mockup; no real KYC backend is built in v0.3.

Tech stack: v0.1 TS monorepo (pnpm/turborepo, Next.js) + v0.2 Python FastAPI ai-service + new credential-engine services (sandbox fabric orchestrator, telemetry ingest, grading engine) in Python/TypeScript as determined at RESEARCH.

---

Requirements (Validated)

The following requirements have been validated during specification and are locked for milestone v0.3 (REQ-F-007..010 and REQ-F-021 activated from the deferred pool; REQ-F-017 deferred per founder directive):

1. Sandbox fabric — sandboxed IDE, design tool, and simulation environments with isolated execution and lifecycle management (REQ-F-021)
2. Live build telemetry — in-environment capture of process events (keystrokes, commands, file diffs, run/test results) streamed to ai-service (REQ-F-010)
3. Process-trace grading engine — grade artifacts from their process traces, not just final output (REQ-F-007); feeds the Assessor agent real inputs
4. Variant task generation — per-learner task variants so no two learners receive identical prompts (REQ-F-008)
5. Oral/voice defense — AI examiner conducts spoken defense of submitted work (REQ-F-009); feeds the Proctor/Mentor agents
6. Agent re-grounding — Lab/Assessor/Proctor consume real engine inputs (telemetry, traces, defenses) instead of v0.2 mocks
7. Learner surface integration — wire the v0.1 sandbox + assessment mockups to the real engines (build/run in-browser, live telemetry, live defense)

v0.2 Requirements (Complete)

All 12 v0.2 requirements (REQ-2-001..012) are complete and shipped as v0.2.0. See REQUIREMENTS.md traceability matrix.

v0.1 Requirements (Complete)

All 28 v0.1 requirements (REQ-001..028) are complete and shipped as v0.1.0. See REQUIREMENTS.md traceability matrix.

Clarified Assumptions (v0.3 CLARIFY stage, full autonomy — auto-resolved)

#	Ambiguity	Resolution	Confidence
A-101	Sandbox isolation technology?	unshare user+mount+pid+net namespace subprocess isolation per sandbox (probe-verified: in-ns uid=0, network fully isolated with 0 interfaces, writes land in an isolated bind-mounted workdir; proc-remount is not permitted in this context but is not required). No Docker/Podman/VMs — none present on the box; no sudo. A SandboxBackend protocol keeps a future containerd swap possible. Falls back further to a plain chroot-free subprocess with a cwd-jail if userns ever unavailable (tested path is userns).	0.8
A-102	Sandbox scope in v0.3?	Coding IDE only (web terminal + file tree + run/test). The "design tool" and "simulation" environments specified in REQ-F-021 are deferred to v0.4 — a single real build environment is enough to prove the credential pipeline end-to-end (telemetry → trace → grade → defense).	0.75
A-103	Live in-browser build UX?	WebSocket xterm.js terminal attached to the bwrap sandbox shell + HTTP file-tree/CRUD + run/test buttons. No full Monaco LSP in v0.3 — a code editor with syntax highlight (existing) + real shell is sufficient and far cheaper.	0.72
A-104	Telemetry transport?	WebSocket from sandbox to a new ingestion endpoint on ai-service for live events; SQLite-backed ordered event log (ai_service/telemetry/) gives durability + at-least-once delivery + replay. Events carry monotonic seq per (learner,task) so gaps are detectable.	0.8
A-105	Where do traces live?	SQLite (ai_service data dir), introducing the first real persistence. SQLModel/SQLAlchemy for typed access. Chosen over Postgres because solo-founder + single box + low write volume; the TraceStore protocol is Postgres-migration-ready like SessionStore was.	0.75
A-106	Process-trace grading model?	LLM-based grader: structure the trace into a compact timeline digest (command categories, error/fix cycles, idle gaps, test passes) → Assessor-style rubric prompt → structured score via existing D-020 JSON defense. Deterministic features (test pass/fail, edit count) computed in code, not left to the LLM.	0.7
A-107	Variant generation mechanism?	Parameterized task templates + LLM instantiation, seeded per learner. Generator fills typed parameter slots (scenario, constraints, data) from a template library; variant seed + parameters persisted to SQLite for grading fairness and proctoring cross-check. Difficulty normalized by template-level rubric anchors.	0.72
A-108	Voice defense — STT/TTS providers?	Provider-agnostic, mock-first like the LLM layer (D-014). Real path: browser MediaRecorder → audio to ai-service → OpenAI-compatible /audio/transcriptions (Whisper STT) and /audio/speech (TTS) against ollama-cloud or a compatible endpoint; fallbacks: browser SpeechRecognition/speechSynthesis when no server keys. VoiceProvider protocol + deterministic mock (returns canned transcript) so tests never call a voice API.	0.62
A-109	Defense dialogue shape?	Reuse BaseAgent: an Examiner agent (seventh agent) streams examiner questions over the existing SSE pipeline; integrity signals (long pauses, off-scope answers, reading-from-notes cadence) emitted alongside the transcript to Proctor.	0.8
A-110	KYC / age-gating in v0.3?	Deferred per founder directive. No real identity backend. Age-gating stays the v0.1 visual flow mockup. Personas omit a security-engineer; security review via verifier + Phase 7 secrets-hygiene checklist. Abuse control is NOT deferred with KYC (G-5): v0.3 ships per-learner sandbox caps (AI_SANDBOX_MAX_PER_LEARNER), a global create-rate cap, and a server-side learner_id allowlist (AI_LEARNER_ALLOWLIST) so the unauthenticated surface cannot exhaust shared NPROC/disk. Documented in the release note.	0.98
A-111	New services vs extend ai-service?	Extend ai-service, don't fork new Python apps. Telemetry ingestion, trace grading, variant generation, voice, and sandbox orchestration all live as new modules in apps/ai-service (they share the LLM provider pool + config + session infra). Only the in-sandbox capture agent is a separate tiny Python process shipped into the bwrap environment.	0.82
A-112	Sandbox on a single dev/school box — capacity?	v0.3 targets 1–5 concurrent sandboxes (founder + pilot learners). No horizontal scaling, no queue. Concurrency guard returns 503 when full. Scaling is post-MVP.	0.8

Clarified Assumptions (v0.2 CLARIFY stage, full autonomy — auto-resolved)

#	Ambiguity	Resolution	Confidence
A-001	Where does the ai-service live in the monorepo?	apps/ai-service — pnpm-workspace ignores Python; it integrates via root package.json scripts (ai:dev, ai:test), not as a pnpm package. Turbo gets passthrough tasks.	0.95
A-002	How does the Next.js client talk to ai-service?	Direct fetch to http://localhost:8420 (configurable via NEXT_PUBLIC_AI_SERVICE_URL) with SSE parsing. No Next.js API-route proxy in v0.2 — client components talk straight to the service.	0.85
A-003	Session persistence?	In-memory dict keyed by session ID (v0.2 has no DB). Sessions lost on restart — acceptable for this milestone; store interface is DB-migration-ready.	0.9
A-004	Port for ai-service?	8420 (avoids common dev-port collisions with 3000/8000; documented in .env.example).	0.8
A-005	Which ollama-cloud model?	Default gemma4:31b (probe-verified); configurable via AI_TUTOR_MODEL env. Model choice is a config, not code.	0.85
A-006	Streaming format?	SSE with data: JSON lines (OpenAI-compatible delta objects), terminated by data: [DONE]. Matches the provider contract, so the provider layer passes deltas through unchanged.	0.9
A-007	Agent routing in the chat UI?	Explicit agent switcher (Coach/Tutor) in the learner chat; Byte viewer always uses Tutor; sandbox uses Lab; assessment uses Assessor+Proctor; dashboard Mentor panel. No autonomous routing in v0.2.	0.9
A-008	Auth between web and ai-service?	None in v0.2 (local dev surface). CORS limited to localhost origins. Real auth is v0.3+ with identity work.	0.85
A-009	Python tooling?	python3 -m venv + pip (venv is the only available mechanism in this environment; no uv). Pydantic v2, FastAPI, uvicorn, pytest — all PyPI-reachable (verified).	0.9
A-010	What happens when the LLM provider is unreachable?	Streaming endpoints return an error event; the UI shows error states with retry. Mock provider guarantees tests never call the cloud.	0.9

Requirements (Active — Future Milestones)

The following remain deferred beyond v0.3 and will be activated in subsequent milestones:

• Identity verification and age-gating logic (16+/18+) — the real KYC backend (deferred from v0.3 per founder directive; visual flow already exists in v0.1)
• Competency graph engine and adaptive pathways
• Marketplace job aggregation pipeline (3M+ jobs from 120K companies)
• AI-powered tagging, semantic vector search, company enrichment
• AI resume parsing and job matching
• SEO-optimized programmatic pages
• Payment processing and subscription management
• Human tutor marketplace (third-party course creation)
• B2B employer network functionality
• CIRR-style placement tracking and audit

Requirements (Out of Scope — Per Vision Doctrine)

• Traditional accreditation — not sought, not pursued, not revisited
• Under-16 learners — excluded; AI school floor is 16+
• Marketplace for under-18 — excluded; marketplace is 18+ with verified identity
• Human tutors in the core school — excluded; humans exist only in the open marketplace
• Graded written exams without process trace — excluded
• Legacy job titles in curriculum — excluded
• Junk advertising — excluded

---

Constraints

1. MAJOR 0 until MVP — all versions remain v0.x until the MVP is released and agreed upon by the founder
2. No business logic in v0.1 — pure UI/UX prototype with mock data only
3. High-fidelity interactive — clickable navigation, realistic content, hover states, form inputs (non-functional), responsive breakpoints, loading states (mock)
4. All data mocked — no real API calls, no database, no authentication logic
5. Shared design system — all 4 surfaces use a unified component library with surface-specific theming via CSS variables
6. TypeScript monorepo — pnpm workspaces + turborepo for build orchestration
7. Next.js App Router — route groups for each surface: (learner), (marketplace), (employer), (admin)
8. Solo founder constraint — Phase 1 is build-only with no headcount; the prototype must be producible by a solo developer with AI assistance
9. No traditional accreditation — proprietary credential replaces degrees
10. AI-first architecture — AI tutors are the primary human-facing layer (in future milestones)

---

Key Decisions

ID	Decision	Rationale	Outcome
D-001	Milestone v0.1 = UI/UX prototype only, no business logic	Founder directive: validate UX before building backend. Prototype must be agreed upon before proceeding to business logic.	Scope locked to frontend surfaces with mock data
D-002	MAJOR 0 until MVP released	Founder directive: remain on v0.x until MVP is validated. Signals pre-release status.	All tags are v0.x.y until MVP agreement
D-003	TypeScript monorepo (pnpm/turborepo) + Next.js	Unified codebase for all 4 surfaces. Shared component library, types, mock data. Next.js App Router for route-based surface separation. Python AI services deferred to later milestones.	Monorepo structure with apps/web + packages/*
D-004	All 4 surfaces in v0.1 (Learner, Marketplace, Employer, Admin)	Founder selected all 4 surfaces for the prototype. Complete product visualization before any backend work.	24 REQ-IDs covering all surfaces + shared infrastructure
D-005	High-fidelity interactive prototype	Founder selected high-fidelity over wireframes. Realistic mock data, navigation flows, responsive layouts, component library. No backend calls.	Clickable prototype with realistic content
D-006	Release forge = Gitea @ git.coreci.dev, owner=coreci, repo=nextcraft	Founder-provided Gitea instance for release management. Token stored in .ciagent/.env.secrets. Forge migrated 2026-09-12 from git.cloudinit.dev → git.coreci.dev (old host decommissioned; all releases migrated, IDs preserved).	Ship workflow creates tags + releases on Gitea
D-007	Full autonomy for CIAgent pipeline	Founder selected full autonomy. No HITL after clarify. Auto-decide above confidence 0.60. Escalation hooks: deploy, delete_data, merge_to_main.	Rapid autonomous building with kill criteria
D-008	Shared component library in packages/ui/	All surfaces share a unified design system with surface-specific theming via CSS variables. Promotes consistency and reduces duplication.	packages/ui, packages/mock-data, packages/types
D-009	AI tutor UI as chat interface mockup with pre-scripted responses	The learner surface includes an AI tutor chat UI mockup. No real AI backend — pre-scripted responses simulate the Coach and Tutor agents.	Mockup only in v0.1, real agents in future milestone
D-010	Age-gating represented as visual registration flow mockup	16+/18+ age-gating shown as a UI flow with age verification step. No actual verification logic.	Visual mockup only
D-011	Competency graph viewer as interactive static visualization	Admin surface includes a competency graph viewer using react-flow or similar. Mock competency nodes and edges. No real graph data.	Static graph with mock data
D-012	Tech stack: TS monorepo + Python AI services (future)	v0.1 uses TS only. Python FastAPI microservices planned for AI tutor agents and assessment engine in later milestones.	v0.1: TS only. v0.2: TS + Python (apps/ai-service)
D-013	v0.1 prototype founder-agreed; D-001 business-logic gate unlocked	Founder approved starting v0.2 with AI Tutor Architecture, which constitutes agreement of the v0.1 prototype per D-001. Recorded at v0.2 SPECIFY.	Business logic authorized from v0.2 onward
D-014	Provider-agnostic LLM layer; ollama-cloud as initial provider	OpenAI-compatible client abstraction with pluggable providers: ollama-cloud (https://ollama.com/v1, default), local OpenAI-compatible endpoint, deterministic mock (tests/CI). Keys in gitignored .ciagent/.env.secrets, never in code or commits.	apps/ai-service llm package with 3 providers; default=ollama-cloud
D-015	All six agents implemented as real LLM services; engines mocked	Coach/Tutor/Mentor fully real. Lab/Assessor/Proctor are real LLM logic over mock inputs (simulated telemetry, pre-baked artifacts) since sandbox fabric, assessment engine, and identity verification are v0.3+. Consistent with v0.1's mock-data approach.	REQ-F-001..006 complete in v0.2; real engines deferred to v0.3+

---

Context

Nextcraft is being built by a solo founder using the CIAgent v0.7.0 autonomous pipeline. The vision document defines a 36-month, 3-phase roadmap to ≥1,000 placements. The first CIAgent milestone (v0.1) is intentionally scoped to UI/UX only — validating the product vision through interactive prototypes before any backend or business logic investment.

The four surfaces (Learner, Marketplace, Employer Dashboard, Admin) map directly to the four audiences in the vision: learners, employers, marketplace operators, and platform administrators. The prototype will demonstrate the complete user journey across all surfaces with realistic mock data reflecting the AI-era competency stacks, AI-orchestration job listings, and artifact+process trace+oral defense credential model.