# Nextcraft — ROADMAP.md

## Overview

**Milestone v0.1** — UI/UX Prototype: High-fidelity interactive prototype of all four Nextcraft surfaces (Learner, Marketplace, Employer Dashboard, Admin) with realistic mock data, shared component library, responsive layouts, and navigation flows. No backend, no business logic.

**Milestone type:** Feature (includes new UI features)
**Tag line:** v0.0.x (patches on the v0.0 line; milestone release as v0.1.0)
**Branch:** milestone/v0.1-nextcraft-ui-prototype

---

## Phase List

| # | Name | Status | Depends On | Requirements | Success Criteria |
|---|------|--------|------------|--------------|------------------|
| 0 | Pre-execution | complete | — | — | Specification, clarify, research, plan complete; .ciagent/ files created |
| 1 | Project scaffolding | complete | 0 | REQ-001, REQ-002, REQ-003, REQ-004, REQ-005 | Monorepo builds; dev server starts; component library has all primitives; mock data typed; routing works between route groups |
| 2 | Learner surface UI | complete | 1 | REQ-006, REQ-007, REQ-008, REQ-009, REQ-010, REQ-011, REQ-012 | All 7 learner pages render with mock data; navigation between pages works; responsive at mobile/tablet/desktop |
| 3 | Marketplace surface UI | complete | 1 | REQ-013, REQ-014, REQ-015, REQ-016, REQ-017 | All 5 marketplace pages render with mock data; search/filter UI interactive (client-side); job board listing displays mock jobs |
| 4 | Employer dashboard UI | complete | 1 | REQ-018, REQ-019, REQ-020, REQ-021 | All 4 employer pages render with mock data; talent search displays mock candidates; candidate profile shows artifact gallery + process trace |
| 5 | Admin surface UI | complete | 1 | REQ-022, REQ-023, REQ-024, REQ-025 | All 4 admin pages render with mock data; competency graph viewer renders interactive graph; moderation queue displays mock flagged content |
| 6 | Polish + integration | complete | 2, 3, 4, 5 | REQ-026, REQ-027, REQ-028 | Cross-surface navigation works; visual consistency audit passes; dark mode toggle functional; Storybook documents all components |
| 7 | Final review + ship | in_progress | 6 | — | Code review clean; audit passes; milestone tagged v0.1.0; release created on Gitea |

---

## Phase Details

### Phase 0: Pre-execution

**Goal:** Establish project specification, clarify ambiguities, research tech stack, create detailed plans.

**Stages:** SPECIFY → CLARIFY → RESEARCH → PLAN → (GRILL optional) → SHIP

**Deliverables:**
- .ciagent/config.json
- .ciagent/PROJECT.md
- .ciagent/REQUIREMENTS.md
- .ciagent/ARCHITECTURE.md
- .ciagent/ROADMAP.md
- .ciagent/CHECKPOINT.json

**Success criteria:** All .ciagent/ files created; initial commit with ---ci--- block; phase 0 shipped as v0.0.1.

---

### Phase 1: Project Scaffolding

**Goal:** Set up the monorepo, component library, mock data layer, routing, and responsive system.

**Requirements:** REQ-001, REQ-002, REQ-003, REQ-004, REQ-005

**Key deliverables:**
- pnpm-workspace.yaml + turbo.json + root package.json
- apps/web Next.js app with App Router
- packages/ui with design tokens + all primitives (Button, Input, Card, Badge, Avatar, Dialog, Tabs, Progress, Tooltip, Skeleton, Toast)
- packages/mock-data with typed mock data for all domains
- packages/types with shared TypeScript type definitions
- Route groups: (learner), (marketplace), (employer), (admin)
- Responsive layout system with breakpoints
- Root layout with theme provider

**Success criteria:**
- `pnpm dev` starts the Next.js dev server
- `pnpm build` succeeds without errors
- `pnpm typecheck` passes
- All primitive components exist and are importable
- Mock data is typed and importable
- Navigation between route groups works (even if pages are placeholders)

---

### Phase 2: Learner Surface UI

**Goal:** Build all 7 learner surface pages with realistic mock data and interactive elements.

**Requirements:** REQ-006, REQ-007, REQ-008, REQ-009, REQ-010, REQ-011, REQ-012

**Key deliverables:**
- Landing page: hero, value proposition, Byte→Build→Demonstrate→Defend flow, testimonials, CTA
- Program catalog: 5 competency stack cards with role descriptions
- Competency stack view: selected stack with 12-18 competencies, progress indicators, microcredential badges
- Learner dashboard: active competencies, progress graph, recent artifacts, AI tutor chat mockup, milestones
- Byte tutorial viewer: concept panel, worked example, code/design viewer mockup
- Build sandbox mockup: IDE UI with toolbar, file explorer, editor area, telemetry sidebar
- Assessment/defense mockup: rubric display, AI reviewer panel, oral defense interface, process trace timeline

**Success criteria:**
- All 7 pages render with mock data
- Navigation between pages works
- AI tutor chat mockup displays pre-scripted responses
- Responsive at mobile (375px), tablet (768px), desktop (1280px)
- Hover states and interactive elements functional

---

### Phase 3: Marketplace Surface UI

**Goal:** Build all 5 marketplace surface pages with job listings, search, and pricing.

**Requirements:** REQ-013, REQ-014, REQ-015, REQ-016, REQ-017

**Key deliverables:**
- Job board listing: searchable grid of mock AI-era jobs, filter sidebar, match score cards
- Job detail page: full description, required competencies, employer info, AI-matched skills
- Employer profile: company overview, logo, open positions, culture mockup
- Search/filter UI: semantic search bar, skill tags, filters (seniority, remote, salary), saved searches
- Pricing page: job posting packages, talent access plans, feature comparison table

**Success criteria:**
- All 5 pages render with mock data
- Filter sidebar interactive (client-side filtering of mock jobs)
- Job cards display match scores and skill tags
- Pricing table is responsive and readable

---

### Phase 4: Employer Dashboard UI

**Goal:** Build all 4 employer dashboard pages for talent search and posting management.

**Requirements:** REQ-018, REQ-019, REQ-020, REQ-021

**Key deliverables:**
- Dashboard overview: active postings, applicant pipeline, talent matches, analytics charts
- Talent search: searchable candidate database with AI-matched filters, candidate cards
- Candidate profile: artifact gallery, process trace summary, defense transcripts, competency graph, microcredentials
- Posting management: create/edit/delete job postings, status tracking, applicant list, interview pipeline

**Success criteria:**
- All 4 pages render with mock data
- Analytics charts display mock metrics (bar/line/donut charts)
- Candidate cards show competency stacks, microcredentials, defense scores
- Posting management form inputs are interactive (non-functional submit)

---

### Phase 5: Admin Surface UI

**Goal:** Build all 4 admin surface pages including the interactive competency graph viewer.

**Requirements:** REQ-022, REQ-023, REQ-024, REQ-025

**Key deliverables:**
- Admin overview: platform metrics (learners, employers, placements, completion rate, NPS), activity feed, system health
- Learner management: searchable learner table, detail view, progress tracking, credential log
- Competency graph viewer: interactive node/edge graph using react-flow, competency stack nodes, dependency edges
- Marketplace moderation: job posting review queue, employer verification queue, flagged content, moderation tools

**Success criteria:**
- All 4 pages render with mock data
- Competency graph viewer renders an interactive graph with clickable nodes
- Admin table supports sorting and filtering (client-side, mock data)
- Moderation queue displays mock flagged items with approve/reject buttons (non-functional)

---

### Phase 6: Polish + Integration

**Goal:** Ensure cross-surface consistency, responsive quality, and component library documentation.

**Requirements:** REQ-026, REQ-027, REQ-028

**Key deliverables:**
- Cross-surface navigation: role switcher (learner/employer/admin), breadcrumbs, consistent header/footer
- Visual consistency: typography scale, color palette, spacing system, dark mode toggle, WCAG AA contrast
- Storybook: component documentation, prop tables, usage examples for all primitives and composites

**Success criteria:**
- Role switcher navigates between surfaces
- Dark mode toggle works across all surfaces
- All pages pass WCAG AA contrast checks
- Storybook runs and documents all components
- No visual inconsistencies between surfaces

---

### 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.1.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.1.0 tagged, milestone branch merged to main, Gitea release created
- All 28 requirements marked complete