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.4 — Distribution & Bootstrap CLI

Scope (founder directive, 2026-09-12): Streamline installing Nextcraft. Ship a bootstrap CLI with a single-liner install script, and publish release binaries on an ongoing basis for every release going forward. The previously-named v0.4 seams (real server STT/TTS, KYC/identity, design/simulation sandbox environments, exec-telemetry seq-lease) are re-scoped to v0.5.

Deliverables: (1) nextcraft CLI — doctor (prerequisite checks), bootstrap (deps + venv + env from templates + key validation), verify (health check), dev (thin passthrough to scripts/dev.sh); (2) one-liner install script downloading the linux x64 binary from the latest Gitea release; (3) binary build + checksum + release-asset pipeline wired into every ship; (4) install/quickstart documentation.

Status of v0.3: Complete and shipped (v0.2.8). Credential engines live: namespace-isolated sandbox fabric, live build telemetry, process-trace grading, seeded variants, oral defense; real learner build/defense/grading surfaces.

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 + age-gating KYC), real server STT/TTS, design/simulation sandbox environments, and the exec-telemetry seq-lease are all deferred to v0.5. Age-gating remains the v0.1-style visual flow mockup.

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 are locked for milestone v0.4 (Distribution & Bootstrap CLI) per the founder directive of 2026-09-12:

1. Bootstrap CLI — nextcraft executable with doctor / bootstrap / verify / dev commands covering prerequisite checks, monorepo bootstrap, health verification, and dev-server orchestration (REQ-4-001, REQ-4-002)
2. One-liner install — curl | bash style install script fetching the linux x64 binary from the latest Gitea release with checksum verification (REQ-4-003)
3. Ongoing release binaries — every release from v0.4 onward ships a linux x64 CLI binary + checksum as release assets (REQ-4-004)
4. Install documentation — README quickstart + CLI reference so a fresh clone reaches a running dev stack in one command (REQ-4-005)

v0.3 Requirements (Complete)

All 8 v0.3 requirements (REQ-3-001..008) are complete and shipped as v0.2.8. 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.4 CLARIFY stage, full autonomy — auto-resolved)

#	Ambiguity	Resolution	Confidence
A-201	CLI language/toolchain for the binary?	Probe-driven at RESEARCH — Go → Rust → Node SEA → Python zipapp fallback chain; spec stays toolchain-agnostic so PLAN locks the probe-verified toolchain	0.70
A-202	Does bootstrap replace scripts/bootstrap.sh?	No — reuse it. CLI wraps existing scripts/bootstrap.sh + scripts/dev.sh via subprocess; zero orchestration logic duplicated in the CLI (thin passthrough pattern)	0.85
A-203	Where does the one-liner fetch the binary?	Gitea latest-release API (/repos/{owner}/{repo}/releases/latest) → download nextcraft-linux-x64 + .sha256 asset; repo raw serves install.sh as the stable URL	0.80
A-204	Install target + PATH?	~/.local/bin (XDG-style, no sudo), PATH hint printed when missing; --dest override flag	0.85
A-205	Binary "ongoing releases" scope?	Every ship from v0.4 onward attaches nextcraft-linux-x64 + sha256 sidecar to the Gitea release — the ship workflow gains an asset step; retroactive binaries for old releases NOT required	0.90
A-206	No binary available yet / non-linux?	Graceful degradation: install script prints source-bootstrap instructions (git clone + scripts/bootstrap.sh) — never a hard fail	0.88
A-207	Checksum trust root?	sha256 sidecar shipped as a release asset next to the binary (same release, same channel); script verifies download against it. Signature/PKI out of scope for v0.4 (single forge, TLS transport)	0.75
A-208	Which prerequisites does doctor check?	node ≥18, pnpm ≥8, python3 ≥3.11, git, unshare availability (sandbox fabric needs it) — versions from the existing bootstrap tooling, not invented	0.85
A-209	Does dev manage multiple processes?	No. Thin passthrough to scripts/dev.sh only — the CLI stays bootstrap-scoped (D-016); orchestration remains in dev.sh	0.82
A-210	.env.secrets handling by bootstrap?	Template copy only for .env.example → .env; secrets NEVER generated, NEVER committed; bootstrap validates presence of optional keys and warns (not blocks) when missing — mock-first providers keep the stack runnable	0.90

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?	Run/Test buttons executing in the namespace sandbox + HTTP file-tree/CRUD + read-only exec-output panel (CUT-2/G-8 — the interactive xterm.js shell relay is deferred to v0.4; @xterm/* is not a v0.3 dependency). No full Monaco LSP in v0.3 — a code editor with syntax highlight (existing) 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 namespace sandbox.	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+
D-016	v0.4 = Distribution & Bootstrap CLI (founder directive supersedes previously-named v0.4 seams)	Founder directive 2026-09-12: focus this milestone on streamlining install, a bootstrap CLI with a one-liner install script, ongoing release binaries. Real server STT/TTS, KYC, design/simulation envs, seq-lease move to v0.5.	Milestone scope locked at SPECIFY; binary = CLI-only, linux x64

---

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.