Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 CIAgent
|
9d530dd4d3 |
@@ -0,0 +1,136 @@
|
||||
# Nextcraft — ARCHITECTURE.md
|
||||
|
||||
## Overview
|
||||
|
||||
Nextcraft v0.1 is a high-fidelity UI/UX prototype built as a TypeScript monorepo using pnpm workspaces and turborepo. The prototype consists of a single Next.js application with route groups for each surface (Learner, Marketplace, Employer Dashboard, Admin), backed by a shared component library, typed mock data layer, and shared types package.
|
||||
|
||||
**No backend, no database, no authentication logic.** All data is static/mock. The architecture is designed to be replaced piece-by-piece with real backend services in future milestones.
|
||||
|
||||
### Confirmed Technology Stack (Research Findings)
|
||||
|
||||
| Technology | Version | Purpose |
|
||||
|------------|---------|---------|
|
||||
| Node.js | v24.15.0 | Runtime |
|
||||
| pnpm | 12.3.4 | Package manager + workspaces |
|
||||
| turborepo | latest | Build orchestration |
|
||||
| Next.js | latest (App Router) | Web application framework |
|
||||
| React | 19+ | UI library |
|
||||
| TypeScript | 5.x | Type system |
|
||||
| Tailwind CSS | v4 | Utility-first CSS framework |
|
||||
| lucide-react | latest | Icon system |
|
||||
| recharts | latest | Charts for employer/admin dashboards |
|
||||
| @xyflow/react (react-flow) | latest | Competency graph viewer in admin surface |
|
||||
| Inter font | via next/font | Typography |
|
||||
| ESLint | via Next.js | Linting |
|
||||
| Prettier | latest | Code formatting |
|
||||
|
||||
### Architecture Decisions from Research
|
||||
|
||||
1. **Next.js App Router with route groups** — `(learner)`, `(marketplace)`, `(employer)`, `(admin)` provide clean URL separation without affecting paths
|
||||
2. **Tailwind CSS v4** — Configured via `@theme` in CSS, no `tailwind.config.js` needed (v4 paradigm shift). Dark mode via `class` strategy.
|
||||
3. **Server components by default** — All pages are server components. Client components only for interactive elements (filters, search, chat, graph viewer, dark mode toggle)
|
||||
4. **Mock data as ES modules** — Typed TS files exported from `packages/mock-data`. No JSON files — all mock data is programmatically generated for richer structure.
|
||||
5. **react-flow (@xyflow/react)** — Confirmed for competency graph viewer. Provides interactive node/edge rendering with built-in controls.
|
||||
6. **recharts** — Confirmed for analytics dashboards. Responsive, composable, integrates well with React server components.
|
||||
7. **pnpm workspaces** — `apps/web` + `packages/ui` + `packages/mock-data` + `packages/types`. Shared deps hoisted.
|
||||
|
||||
---
|
||||
|
||||
## Components
|
||||
|
||||
### apps/web — Next.js Application
|
||||
|
||||
| Component | Description | Boundaries | Depends On |
|
||||
|-----------|-------------|------------|------------|
|
||||
| `app/(learner)/` | Learner surface route group: landing, catalog, competency stack, dashboard, byte viewer, sandbox mockup, assessment mockup | Learner-only routes and layouts | packages/ui, packages/mock-data, packages/types |
|
||||
| `app/(marketplace)/` | Marketplace surface route group: job board, job detail, employer profile, search/filter, pricing | Marketplace-only routes and layouts | packages/ui, packages/mock-data, packages/types |
|
||||
| `app/(employer)/` | Employer dashboard route group: overview, talent search, candidate profile, posting management | Employer-only routes and layouts | packages/ui, packages/mock-data, packages/types |
|
||||
| `app/(admin)/` | Admin surface route group: overview, learner management, competency graph viewer, moderation | Admin-only routes and layouts | packages/ui, packages/mock-data, packages/types |
|
||||
| `app/layout.tsx` | Root layout: theme provider, navigation shell, responsive container | All routes | packages/ui |
|
||||
| `components/` | Surface-specific components (not shared across surfaces) | Per-surface only | packages/ui |
|
||||
|
||||
### packages/ui — Shared Component Library
|
||||
|
||||
| Component | Description | Boundaries | Depends On |
|
||||
|-----------|-------------|------------|------------|
|
||||
| `design-tokens/` | CSS custom properties: color palette, typography scale, spacing system, breakpoints, shadows, radii | Foundation layer — no dependencies | None |
|
||||
| `primitives/` | Button, Input, Card, Badge, Avatar, Dialog, Tabs, Progress, Tooltip, Skeleton, Toast | Atomic UI components | design-tokens |
|
||||
| `composites/` | Navigation, Table, SearchBar, FilterPanel, ChatInterface, GraphViewer, ArtifactCard, CompetencyBadge, JobCard, CandidateCard, MetricCard | Composite components built from primitives | primitives, packages/types |
|
||||
| `layouts/` | Container, Grid, Sidebar, SplitPanel, DashboardLayout | Layout components | primitives, design-tokens |
|
||||
| `theme/` | Theme provider, CSS variable overrides per surface (learner, marketplace, employer, admin) | Theme context | design-tokens |
|
||||
|
||||
### packages/mock-data — Mock Data Layer
|
||||
|
||||
| Component | Description | Boundaries | Depends On |
|
||||
|-----------|-------------|------------|------------|
|
||||
| `competency-stacks.ts` | 5 competency stacks (AI Orchestration Engineer, AI Safety & Governance, Human-AI Product Designer, AI-Augmented Field Operator, Computational Sciences), each with 12-18 competencies | Typed mock data | packages/types |
|
||||
| `jobs.ts` | 20+ mock AI-era job listings with skills, seniority, salary, match scores | Typed mock data | packages/types |
|
||||
| `candidates.ts` | 15+ mock candidate profiles with artifacts, process traces, defense scores, microcredentials | Typed mock data | packages/types |
|
||||
| `employers.ts` | 10+ mock employer profiles with logos, descriptions, open positions | Typed mock data | packages/types |
|
||||
| `learner-progress.ts` | Mock learner progress data: active competencies, completion percentages, recent artifacts | Typed mock data | packages/types |
|
||||
| `ai-tutor-responses.ts` | Pre-scripted AI tutor chat responses for Coach and Tutor agent mockups | Typed mock data | packages/types |
|
||||
|
||||
### packages/types — Shared Types
|
||||
|
||||
| Component | Description | Boundaries | Depends On |
|
||||
|-----------|-------------|------------|------------|
|
||||
| `domain.ts` | Competency, CompetencyStack, Microcredential, Artifact, ProcessTrace, OralDefense, AssessmentRubric | Domain types | None |
|
||||
| `marketplace.ts` | Job, Employer, Candidate, JobPosting, TalentMatch, SearchFilter | Marketplace types | None |
|
||||
| `user.ts` | Learner, Admin, EmployerUser, AgeGroup, Role | User types | None |
|
||||
| `ui.ts` | Component props, theme config, breakpoint definitions | UI types | None |
|
||||
|
||||
---
|
||||
|
||||
## Data Flow
|
||||
|
||||
```
|
||||
[Mock Data Layer] ──typed──> [Shared Types] <──typed──> [UI Components]
|
||||
│ │
|
||||
│ │
|
||||
▼ ▼
|
||||
[Next.js Route Groups] [Surface Components]
|
||||
(learner)/ (marketplace)/ (employer)/ (admin)/
|
||||
│ │ │ │
|
||||
└──────────────────┴─────────────────┴───────────────┘
|
||||
│
|
||||
▼
|
||||
[Root Layout + Theme Provider]
|
||||
│
|
||||
▼
|
||||
[Responsive Navigation Shell]
|
||||
```
|
||||
|
||||
All data flows from the mock data layer through typed imports into Next.js route handlers / server components, which pass data as props to UI components. No client-side data fetching, no API routes, no server actions in v0.1.
|
||||
|
||||
---
|
||||
|
||||
## Build Order
|
||||
|
||||
1. **Monorepo scaffolding** — pnpm-workspace.yaml, turbo.json, tsconfig.json, package.json, Next.js app initialization
|
||||
2. **Shared types** — packages/types with all domain, marketplace, user, and UI type definitions
|
||||
3. **Mock data layer** — packages/mock-data with typed mock data for all surfaces
|
||||
4. **Design tokens** — packages/ui/design-tokens with CSS custom properties
|
||||
5. **UI primitives** — Button, Input, Card, Badge, Avatar, Dialog, Tabs, Progress, Tooltip, Skeleton, Toast
|
||||
6. **Root layout + navigation shell** — Root layout with theme provider, responsive navigation, role switcher
|
||||
7. **UI composites** — Navigation, Table, SearchBar, FilterPanel, ChatInterface, GraphViewer, ArtifactCard, CompetencyBadge, JobCard, CandidateCard, MetricCard
|
||||
8. **Learner surface routes** — Landing, catalog, competency stack, dashboard, byte viewer, sandbox mockup, assessment mockup
|
||||
9. **Marketplace surface routes** — Job board, job detail, employer profile, search/filter, pricing
|
||||
10. **Employer dashboard routes** — Overview, talent search, candidate profile, posting management
|
||||
11. **Admin surface routes** — Overview, learner management, competency graph viewer, moderation
|
||||
12. **Polish + integration** — Cross-surface navigation, responsive QA, visual consistency, Storybook
|
||||
|
||||
---
|
||||
|
||||
## Future Architecture (Post-v0.1, for reference)
|
||||
|
||||
The v0.1 prototype is designed to be replaced piece-by-piece with real backend services:
|
||||
|
||||
- **Mock data → PostgreSQL + Drizzle ORM** — mock data files replaced with database queries via repository layer
|
||||
- **Static routes → Fastify API + Next.js SSR** — API routes replaced with Fastify backend services
|
||||
- **Mock AI tutor → Python FastAPI AI services** — Chat interface mockup replaced with real AI agent microservices
|
||||
- **Mock assessment → Assessment engine** — Assessment mockup replaced with process-trace grading + oral defense engine
|
||||
- **No auth → Identity verification + age-gating** — Registration flow mockup replaced with real KYC and age verification
|
||||
- **No search → Semantic vector search (pgvector)** — Filter UI replaced with vector similarity search
|
||||
- **No payments → Payment processing** — Pricing page replaced with real subscription/payment flows
|
||||
|
||||
The monorepo structure (apps/web + packages/*) is designed to accommodate additional apps (e.g., apps/api, apps/ai-service) in future milestones without restructuring.
|
||||
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"phase": 0,
|
||||
"stage": "plan",
|
||||
"milestone": "v0.1",
|
||||
"phase_role": "pre_execution",
|
||||
"attempts": 0,
|
||||
"updated_at": "2026-09-10T21:40:00Z"
|
||||
}
|
||||
@@ -0,0 +1,124 @@
|
||||
# Nextcraft — PERSONAS.md
|
||||
|
||||
## Persona Roster
|
||||
|
||||
### lead-developer
|
||||
```yaml
|
||||
active: true
|
||||
phase_specific: false
|
||||
reason: Coordinates task decomposition across surfaces, resolves conflicts between frontend and data personas
|
||||
domain: coordination
|
||||
frameworks:
|
||||
- next.js
|
||||
- turborepo
|
||||
- pnpm
|
||||
constraints:
|
||||
- pragmatic
|
||||
- battle-tested defaults
|
||||
- monorepo-architecture
|
||||
territory:
|
||||
- "**/package.json"
|
||||
- "**/turbo.json"
|
||||
- "**/pnpm-workspace.yaml"
|
||||
- "**/tsconfig.json"
|
||||
```
|
||||
|
||||
### frontend-engineer
|
||||
```yaml
|
||||
active: true
|
||||
phase_specific: false
|
||||
reason: Primary persona for v0.1 — all 28 REQ-IDs are UI/frontend work. Owns all page components, layouts, and surface-specific UI.
|
||||
domain: frontend
|
||||
frameworks:
|
||||
- react
|
||||
- next.js
|
||||
- tailwindcss
|
||||
- lucide-react
|
||||
- recharts
|
||||
- react-flow
|
||||
constraints:
|
||||
- component-first
|
||||
- server-components-default
|
||||
- minimal-client-js
|
||||
- mock-data-only
|
||||
- responsive-all-breakpoints
|
||||
- dark-mode-support
|
||||
territory:
|
||||
- "apps/web/**"
|
||||
- "packages/ui/**"
|
||||
- "packages/mock-data/**"
|
||||
- "packages/types/**"
|
||||
```
|
||||
|
||||
### data-engineer
|
||||
```yaml
|
||||
active: true
|
||||
phase_specific: false
|
||||
reason: Owns mock data layer schema and typed definitions. No real database in v0.1, but data structures must be well-typed for future migration.
|
||||
domain: data
|
||||
frameworks:
|
||||
- typescript
|
||||
constraints:
|
||||
- schema-first
|
||||
- type-safe
|
||||
- migration-ready
|
||||
- mock-data-only
|
||||
territory:
|
||||
- "packages/types/**"
|
||||
- "packages/mock-data/**"
|
||||
```
|
||||
|
||||
### backend-engineer
|
||||
```yaml
|
||||
active: false
|
||||
phase_specific: false
|
||||
reason: No backend in v0.1. All data is mock/static. Backend persona deactivated until v0.2+ when API services are needed.
|
||||
domain: backend
|
||||
frameworks: []
|
||||
constraints: []
|
||||
territory: []
|
||||
```
|
||||
|
||||
### security-auditor
|
||||
```yaml
|
||||
active: false
|
||||
phase_specific: false
|
||||
reason: No auth, no API, no real data in v0.1. Security review handled by verifier's STRIDE analysis layer. No dedicated security persona needed for UI prototype.
|
||||
domain: security
|
||||
frameworks: []
|
||||
constraints: []
|
||||
territory: []
|
||||
```
|
||||
|
||||
## Custom Personas
|
||||
|
||||
### design-system-engineer
|
||||
```yaml
|
||||
active: true
|
||||
phase_specific: false
|
||||
reason: Custom persona for v0.1 — owns the shared component library, design tokens, and visual consistency. Combines frontend expertise with design system ownership.
|
||||
domain: frontend
|
||||
frameworks:
|
||||
- tailwindcss
|
||||
- storybook
|
||||
- lucide-react
|
||||
constraints:
|
||||
- design-token-driven
|
||||
- wcag-aa-contrast
|
||||
- dark-mode-required
|
||||
- consistent-across-surfaces
|
||||
territory:
|
||||
- "packages/ui/**"
|
||||
```
|
||||
|
||||
## Phase-Specific Personas
|
||||
|
||||
None for v0.1. All active personas span the entire milestone.
|
||||
|
||||
## Territory Conflict Resolution
|
||||
|
||||
| Conflict | Resolution |
|
||||
|----------|-----------|
|
||||
| frontend-engineer vs data-engineer (packages/types, packages/mock-data) | data-engineer owns type definitions and mock data schema; frontend-engineer consumes them. If changes needed, data-engineer updates types first. |
|
||||
| frontend-engineer vs design-system-engineer (packages/ui) | design-system-engineer owns design tokens and primitive components; frontend-engineer owns composite components and page-level UI. |
|
||||
| lead-developer vs any | lead-developer coordinates only, does not directly modify code files. |
|
||||
@@ -0,0 +1,398 @@
|
||||
# Nextcraft v0.1 — PLAN.md
|
||||
|
||||
## Overview
|
||||
|
||||
This plan covers execution phases 1-6 of milestone v0.1 (UI/UX Prototype). Each phase is a vertical slice that produces a demoable milestone. Phases are ordered by dependency — later phases build on earlier ones.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Project Scaffolding
|
||||
|
||||
**Requirements:** REQ-001, REQ-002, REQ-003, REQ-004, REQ-005
|
||||
**Persona:** design-system-engineer (Wave 1), data-engineer (Wave 1), frontend-engineer (Wave 2)
|
||||
**Goal:** Monorepo builds, dev server starts, component library has all primitives, mock data typed, routing works
|
||||
|
||||
### Wave 1: Foundation (parallel — no shared file conflicts)
|
||||
|
||||
#### Task 1-1-01: Monorepo scaffolding
|
||||
- **Persona:** design-system-engineer
|
||||
- **Files:** `package.json`, `pnpm-workspace.yaml`, `turbo.json`, `tsconfig.json`, `.npmrc`
|
||||
- **Action:** Create root monorepo config. pnpm workspaces pointing to `apps/*` and `packages/*`. Turborepo with build/dev/lint/typecheck pipelines. Root tsconfig with path aliases.
|
||||
- **Verify:** `pnpm install` succeeds; workspace packages detected
|
||||
- **Done:** `pnpm list -r` shows all workspace packages
|
||||
|
||||
#### Task 1-1-02: Shared types package
|
||||
- **Persona:** data-engineer
|
||||
- **Files:** `packages/types/package.json`, `packages/types/tsconfig.json`, `packages/types/domain.ts`, `packages/types/marketplace.ts`, `packages/types/user.ts`, `packages/types/ui.ts`, `packages/types/index.ts`
|
||||
- **Action:** Create all shared TypeScript type definitions: Competency, CompetencyStack, Microcredential, Artifact, ProcessTrace, OralDefense, AssessmentRubric, Job, Employer, Candidate, JobPosting, TalentMatch, SearchFilter, Learner, Admin, EmployerUser, AgeGroup, Role, plus UI types (ComponentProps, ThemeConfig, Breakpoint).
|
||||
- **Verify:** `pnpm typecheck` passes in packages/types
|
||||
- **Done:** All types exported from index.ts; no type errors
|
||||
|
||||
#### Task 1-1-03: Mock data package
|
||||
- **Persona:** data-engineer
|
||||
- **Files:** `packages/mock-data/package.json`, `packages/mock-data/tsconfig.json`, `packages/mock-data/competency-stacks.ts`, `packages/mock-data/jobs.ts`, `packages/mock-data/candidates.ts`, `packages/mock-data/employers.ts`, `packages/mock-data/learner-progress.ts`, `packages/mock-data/ai-tutor-responses.ts`, `packages/mock-data/index.ts`
|
||||
- **Action:** Create typed mock data: 5 competency stacks (AI Orchestration Engineer with 15 competencies, AI Safety & Governance with 14, Human-AI Product Designer with 13, AI-Augmented Field Operator with 12, Computational Sciences with 16). 20+ mock jobs. 15+ mock candidates. 10+ mock employers. Mock learner progress. Pre-scripted AI tutor responses.
|
||||
- **Verify:** All mock data matches types from packages/types; `pnpm typecheck` passes
|
||||
- **Done:** All mock data exported from index.ts; types match
|
||||
|
||||
### Wave 2: UI Foundation (depends on Wave 1)
|
||||
|
||||
#### Task 1-2-01: Next.js app initialization
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/package.json`, `apps/web/tsconfig.json`, `apps/web/next.config.ts`, `apps/web/app/layout.tsx`, `apps/web/app/page.tsx`, `apps/web/app/globals.css`
|
||||
- **Action:** Initialize Next.js app with App Router, TypeScript, Tailwind CSS v4. Configure Inter font via next/font. Set up path aliases to packages. Create root layout with theme provider. Create placeholder home page.
|
||||
- **Verify:** `pnpm dev` starts; `pnpm build` succeeds; page renders at localhost:3000
|
||||
- **Done:** Next.js app runs with Tailwind CSS and Inter font
|
||||
|
||||
#### Task 1-2-02: Design tokens and Tailwind config
|
||||
- **Persona:** design-system-engineer
|
||||
- **Files:** `packages/ui/package.json`, `packages/ui/tsconfig.json`, `packages/ui/src/index.ts`, `packages/ui/src/tokens/index.ts`, `apps/web/app/globals.css` (update)
|
||||
- **Action:** Create packages/ui package. Define design tokens as TypeScript constants and CSS custom properties: color palette (indigo/violet primary, emerald accent, slate neutral, dark mode variants), typography scale (12px-48px), spacing system (4px base), breakpoints (375px, 768px, 1280px), shadows, radii. Configure Tailwind v4 `@theme` with custom colors.
|
||||
- **Verify:** Design tokens importable from packages/ui; Tailwind classes work with custom colors
|
||||
- **Done:** `import { tokens } from '@nextcraft/ui'` works; `bg-primary-500` class works
|
||||
|
||||
#### Task 1-2-03: UI primitives
|
||||
- **Persona:** design-system-engineer
|
||||
- **Files:** `packages/ui/src/primitives/button.tsx`, `packages/ui/src/primitives/input.tsx`, `packages/ui/src/primitives/card.tsx`, `packages/ui/src/primitives/badge.tsx`, `packages/ui/src/primitives/avatar.tsx`, `packages/ui/src/primitives/dialog.tsx`, `packages/ui/src/primitives/tabs.tsx`, `packages/ui/src/primitives/progress.tsx`, `packages/ui/src/primitives/tooltip.tsx`, `packages/ui/src/primitives/skeleton.tsx`, `packages/ui/src/primitives/toast.tsx`, `packages/ui/src/primitives/index.ts`
|
||||
- **Action:** Create all 12 primitive components. Each is a React component with TypeScript props, Tailwind styling, forwardRef, and size variants. Button (primary, secondary, ghost, destructive). Input (text, search, with label). Card (with header, body, footer slots). Badge (default, success, warning, error). Avatar (with image, fallback, sizes). Dialog (modal, with overlay). Tabs (horizontal, with active indicator). Progress (linear, circular). Tooltip (on hover). Skeleton (shimmer). Toast (with variants).
|
||||
- **Verify:** All primitives importable; each renders without error; variants work
|
||||
- **Done:** 12 primitives exported from packages/ui
|
||||
|
||||
#### Task 1-2-04: Layout components
|
||||
- **Persona:** design-system-engineer
|
||||
- **Files:** `packages/ui/src/layouts/container.tsx`, `packages/ui/src/layouts/grid.tsx`, `packages/ui/src/layouts/sidebar.tsx`, `packages/ui/src/layouts/split-panel.tsx`, `packages/ui/src/layouts/dashboard-layout.tsx`, `packages/ui/src/layouts/index.ts`
|
||||
- **Action:** Create layout components. Container (max-width variants: sm, md, lg, xl, full). Grid (responsive cols prop). Sidebar (collapsible, with nav items). SplitPanel (resizable divider). DashboardLayout (sidebar + main content area).
|
||||
- **Verify:** Layout components render; responsive breakpoints work
|
||||
- **Done:** 5 layout components exported
|
||||
|
||||
#### Task 1-2-05: Root layout + navigation shell
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/layout.tsx` (update), `apps/web/components/navigation-shell.tsx`, `apps/web/components/role-switcher.tsx`, `apps/web/components/header.tsx`, `apps/web/components/footer.tsx`
|
||||
- **Action:** Update root layout with theme provider (dark mode toggle), Inter font, responsive navigation shell. Create role switcher (learner/employer/admin toggle in header). Create header with logo, nav links, role switcher, dark mode toggle. Create footer with links.
|
||||
- **Verify:** Dark mode toggle works; role switcher navigates between surfaces; responsive at 375px/768px/1280px
|
||||
- **Done:** Navigation shell renders on all pages; role switcher functional
|
||||
|
||||
#### Task 1-2-06: Route groups with placeholder pages
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(learner)/page.tsx`, `apps/web/app/(learner)/layout.tsx`, `apps/web/app/(marketplace)/page.tsx`, `apps/web/app/(marketplace)/layout.tsx`, `apps/web/app/(employer)/page.tsx`, `apps/web/app/(employer)/layout.tsx`, `apps/web/app/(admin)/page.tsx`, `apps/web/app/(admin)/layout.tsx`
|
||||
- **Action:** Create route groups with layouts for each surface. Each layout has surface-specific navigation. Placeholder pages with surface name and brief description.
|
||||
- **Verify:** Navigation to / (learner), /marketplace, /employer, /admin works
|
||||
- **Done:** 4 route groups with layouts and placeholder pages
|
||||
|
||||
### Must-Haves (Phase 1)
|
||||
- [ ] `pnpm install` succeeds
|
||||
- [ ] `pnpm dev` starts Next.js dev server
|
||||
- [ ] `pnpm build` succeeds
|
||||
- [ ] `pnpm typecheck` passes
|
||||
- [ ] 12 UI primitives importable from `@nextcraft/ui`
|
||||
- [ ] Mock data typed and importable from `@nextcraft/mock-data`
|
||||
- [ ] Types importable from `@nextcraft/types`
|
||||
- [ ] 4 route groups with layouts
|
||||
- [ ] Dark mode toggle works
|
||||
- [ ] Role switcher navigates between surfaces
|
||||
- [ ] Responsive at 375px, 768px, 1280px
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Learner Surface UI
|
||||
|
||||
**Requirements:** REQ-006, REQ-007, REQ-008, REQ-009, REQ-010, REQ-011, REQ-012
|
||||
**Persona:** frontend-engineer
|
||||
**Goal:** All 7 learner pages render with mock data; navigation works; responsive
|
||||
|
||||
### Wave 1: Core learner pages
|
||||
|
||||
#### Task 2-1-01: Landing page
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(learner)/page.tsx`, `apps/web/components/learner/hero.tsx`, `apps/web/components/learner/how-it-works.tsx`, `apps/web/components/learner/program-highlights.tsx`, `apps/web/components/learner/testimonials.tsx`
|
||||
- **Action:** Build landing page with hero section (headline, subheadline, CTA buttons), how-it-works section (Byte→Build→Demonstrate→Defend visual flow), program highlights (3-4 featured competency stacks), testimonials mockup (3 cards with avatar, quote, name, role), CTA to program catalog.
|
||||
- **Verify:** Landing page renders with all sections; CTA links to /catalog
|
||||
- **Done:** Landing page complete
|
||||
|
||||
#### Task 2-1-02: Program catalog
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(learner)/catalog/page.tsx`, `apps/web/components/learner/stack-card.tsx`
|
||||
- **Action:** Build program catalog page. Grid of 5 competency stack cards. Each card: stack name, role description, competency count, estimated duration, microcredential count, "Explore" button linking to stack detail.
|
||||
- **Verify:** 5 stack cards render with mock data; clicking "Explore" navigates to stack detail
|
||||
- **Done:** Catalog page complete
|
||||
|
||||
#### Task 2-1-03: Competency stack view
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(learner)/catalog/[stackId]/page.tsx`, `apps/web/components/learner/competency-list.tsx`, `apps/web/components/learner/competency-item.tsx`, `apps/web/components/learner/microcredential-badge.tsx`
|
||||
- **Action:** Build competency stack detail page. Header with stack name, role, description. List of 12-18 competencies. Each competency: name, description, status (locked/available/in-progress/mastered), microcredential badge, progress bar. Clicking a competency navigates to byte tutorial viewer.
|
||||
- **Verify:** Competencies render with correct status indicators; microcredential badges display
|
||||
- **Done:** Stack detail page complete
|
||||
|
||||
#### Task 2-1-04: Learner dashboard
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(learner)/dashboard/page.tsx`, `apps/web/components/learner/dashboard/active-competencies.tsx`, `apps/web/components/learner/dashboard/progress-graph.tsx`, `apps/web/components/learner/dashboard/recent-artifacts.tsx`, `apps/web/components/learner/dashboard/upcoming-defenses.tsx`, `apps/web/components/learner/dashboard/ai-tutor-chat.tsx`, `apps/web/components/learner/dashboard/milestone-tracker.tsx`
|
||||
- **Action:** Build learner dashboard. Active competencies panel (current stack, progress). Progress graph (recharts area chart showing mastery over time). Recent artifacts (cards with artifact name, type, date). Upcoming defenses (list with competency name, date, status). AI tutor chat mockup (chat interface with pre-scripted responses, message input). Milestone tracker (progress through stack).
|
||||
- **Verify:** Dashboard renders all panels; AI tutor chat displays scripted responses on "send"
|
||||
- **Done:** Dashboard complete
|
||||
|
||||
### Wave 2: Detail views
|
||||
|
||||
#### Task 2-2-01: Byte tutorial viewer
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(learner)/learn/[competencyId]/page.tsx`, `apps/web/components/learner/byte-viewer/concept-panel.tsx`, `apps/web/components/learner/byte-viewer/worked-example.tsx`, `apps/web/components/learner/byte-viewer/viewer-tabs.tsx`
|
||||
- **Action:** Build byte tutorial viewer. Layout: left panel (concept text, 3-7 minute read), right panel (worked example with code/design/simulation viewer mockup). Tabbed viewer (code, design, simulation). Navigation to build sandbox.
|
||||
- **Verify:** Tutorial viewer renders with concept and example panels; tabs switch
|
||||
- **Done:** Byte tutorial viewer complete
|
||||
|
||||
#### Task 2-2-02: Build sandbox mockup
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(learner)/build/[competencyId]/page.tsx`, `apps/web/components/learner/sandbox/toolbar.tsx`, `apps/web/components/learner/sandbox/file-explorer.tsx`, `apps/web/components/learner/sandbox/editor-area.tsx`, `apps/web/components/learner/sandbox/telemetry-sidebar.tsx`
|
||||
- **Action:** Build sandbox mockup IDE UI. Layout: top toolbar (run, save, submit buttons), left sidebar (file explorer tree), center (code editor area with syntax-highlighted mock code), right sidebar (telemetry — process capture indicators showing commits, keystrokes, time spent). No real code execution.
|
||||
- **Verify:** Sandbox UI renders with all panels; toolbar buttons are interactive (non-functional)
|
||||
- **Done:** Build sandbox mockup complete
|
||||
|
||||
#### Task 2-2-03: Assessment/defense mockup
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(learner)/defend/[competencyId]/page.tsx`, `apps/web/components/learner/assessment/rubric-display.tsx`, `apps/web/components/learner/assessment/ai-reviewer-panel.tsx`, `apps/web/components/learner/assessment/oral-defense.tsx`, `apps/web/components/learner/assessment/process-trace.tsx`, `apps/web/components/learner/assessment/artifact-viewer.tsx`
|
||||
- **Action:** Build assessment/defense mockup. Layout: top (artifact viewer — submitted work preview), left (rubric display — competency criteria with checkmarks), right (AI reviewer panel — assessment results), bottom (oral defense interface — mic button mockup, waveform animation, transcript area). Process trace timeline (showing build steps with timestamps).
|
||||
- **Verify:** Assessment mockup renders all panels; mic button has hover state; timeline displays mock events
|
||||
- **Done:** Assessment/defense mockup complete
|
||||
|
||||
### Must-Haves (Phase 2)
|
||||
- [ ] Landing page renders with hero, how-it-works, highlights, testimonials, CTA
|
||||
- [ ] Program catalog shows 5 competency stack cards
|
||||
- [ ] Competency stack view shows 12-18 competencies with status and badges
|
||||
- [ ] Learner dashboard shows all 6 panels including AI tutor chat mockup
|
||||
- [ ] Byte tutorial viewer renders with concept and worked example panels
|
||||
- [ ] Build sandbox mockup renders with toolbar, file explorer, editor, telemetry
|
||||
- [ ] Assessment mockup renders with rubric, AI reviewer, oral defense, process trace
|
||||
- [ ] All pages responsive at 375px, 768px, 1280px
|
||||
- [ ] Navigation between all learner pages works
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Marketplace Surface UI
|
||||
|
||||
**Requirements:** REQ-013, REQ-014, REQ-015, REQ-016, REQ-017
|
||||
**Persona:** frontend-engineer
|
||||
**Goal:** All 5 marketplace pages render with mock data; search/filter interactive
|
||||
|
||||
### Wave 1: Job board + search
|
||||
|
||||
#### Task 3-1-01: Job board listing
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(marketplace)/page.tsx`, `apps/web/components/marketplace/job-card.tsx`, `apps/web/components/marketplace/job-listing-grid.tsx`
|
||||
- **Action:** Build job board listing page. Layout: left sidebar (filters), main area (grid of job cards). Each job card: job title, company name, logo, location, remote badge, salary range, match score (percentage badge), required skills (tag chips), posted date. 20+ mock job listings.
|
||||
- **Verify:** 20+ job cards render; match scores display; skill tags show
|
||||
- **Done:** Job board listing complete
|
||||
|
||||
#### Task 3-1-02: Search/filter UI
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/components/marketplace/filter-sidebar.tsx`, `apps/web/components/marketplace/search-bar.tsx`, `apps/web/components/marketplace/saved-searches.tsx`
|
||||
- **Action:** Build filter sidebar. Semantic search bar at top (with icon, placeholder text). Filters: skills (multi-select chips), seniority (dropdown), location (text input), remote toggle, salary range (min/max inputs). Saved searches mockup section. Client-side filtering of mock jobs using useState.
|
||||
- **Verify:** Typing in search filters jobs; selecting skill filters jobs; toggling remote filters jobs
|
||||
- **Done:** Search/filter UI functional with client-side filtering
|
||||
|
||||
### Wave 2: Detail pages
|
||||
|
||||
#### Task 3-2-01: Job detail page
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(marketplace)/jobs/[jobId]/page.tsx`, `apps/web/components/marketplace/job-detail.tsx`, `apps/web/components/marketplace/skills-breakdown.tsx`, `apps/web/components/marketplace/related-jobs.tsx`
|
||||
- **Action:** Build job detail page. Layout: header (job title, company, location, salary, apply button), body (full description, required competencies list, AI-matched skills breakdown with match percentages), sidebar (employer info card, related jobs list).
|
||||
- **Verify:** Job detail renders with all sections; apply button is interactive (non-functional)
|
||||
- **Done:** Job detail page complete
|
||||
|
||||
#### Task 3-2-02: Employer profile
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(marketplace)/employers/[employerId]/page.tsx`, `apps/web/components/marketplace/employer-header.tsx`, `apps/web/components/marketplace/employer-openings.tsx`, `apps/web/components/marketplace/employer-culture.tsx`
|
||||
- **Action:** Build employer profile page. Header: logo, company name, tagline, industry, size, location, social links. Body: about section, culture section (mock photos grid), open positions list (job cards).
|
||||
- **Verify:** Employer profile renders with all sections; social links are clickable (mock URLs)
|
||||
- **Done:** Employer profile complete
|
||||
|
||||
#### Task 3-2-03: Pricing page
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(marketplace)/pricing/page.tsx`, `apps/web/components/marketplace/pricing-card.tsx`, `apps/web/components/marketplace/feature-comparison.tsx`
|
||||
- **Action:** Build pricing page. Three pricing cards: Job Posting (single — $49, bundle — $399 for 10, enterprise — custom). Talent Access plans (starter, pro, enterprise). Feature comparison table. CTA buttons on each plan.
|
||||
- **Verify:** Pricing page renders with 3 tiers and comparison table; responsive
|
||||
- **Done:** Pricing page complete
|
||||
|
||||
### Must-Haves (Phase 3)
|
||||
- [ ] Job board shows 20+ mock job listings with match scores
|
||||
- [ ] Search bar filters jobs client-side
|
||||
- [ ] Filter sidebar filters by skills, seniority, remote, salary
|
||||
- [ ] Job detail page shows full description, competencies, skills breakdown
|
||||
- [ ] Employer profile shows company info, culture, open positions
|
||||
- [ ] Pricing page shows 3 tiers with feature comparison
|
||||
- [ ] All pages responsive at 375px, 768px, 1280px
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Employer Dashboard UI
|
||||
|
||||
**Requirements:** REQ-018, REQ-019, REQ-020, REQ-021
|
||||
**Persona:** frontend-engineer
|
||||
**Goal:** All 4 employer dashboard pages render with mock data; charts display
|
||||
|
||||
### Wave 1: Dashboard + talent search
|
||||
|
||||
#### Task 4-1-01: Employer dashboard overview
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(employer)/page.tsx`, `apps/web/components/employer/overview/metric-cards.tsx`, `apps/web/components/employer/overview/applicant-pipeline.tsx`, `apps/web/components/employer/overview/talent-matches.tsx`, `apps/web/components/employer/overview/analytics-charts.tsx`
|
||||
- **Action:** Build employer dashboard overview. Top row: 4 metric cards (active postings, total applicants, talent matches, placement rate). Middle: applicant pipeline (kanban-style columns: applied, screening, interview, offer, hired). Right: talent matches (list of matched candidates with match score). Bottom: analytics charts (recharts — bar chart for postings over time, donut chart for applicant sources, line chart for placement trends).
|
||||
- **Verify:** Dashboard renders with metric cards, pipeline, matches, and 3 chart types
|
||||
- **Done:** Employer dashboard overview complete
|
||||
|
||||
#### Task 4-1-02: Talent search
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(employer)/talent/page.tsx`, `apps/web/components/employer/talent/candidate-card.tsx`, `apps/web/components/employer/talent/talent-filters.tsx`
|
||||
- **Action:** Build talent search page. Layout: top (search bar + AI-matched filters), main (grid of candidate cards). Each candidate card: avatar, name, headline (competency stack + level), microcredential badges (top 3), artifact count, defense score, match percentage, "View Profile" button. 15+ mock candidates. Client-side filtering.
|
||||
- **Verify:** 15+ candidate cards render; filters work client-side; clicking "View Profile" navigates to candidate profile
|
||||
- **Done:** Talent search complete
|
||||
|
||||
### Wave 2: Detail + management
|
||||
|
||||
#### Task 4-2-01: Candidate profile view
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(employer)/talent/[candidateId]/page.tsx`, `apps/web/components/employer/talent-profile/artifact-gallery.tsx`, `apps/web/components/employer/talent-profile/process-trace-summary.tsx`, `apps/web/components/employer/talent-profile/defense-transcripts.tsx`, `apps/web/components/employer/talent-profile/competency-mini-graph.tsx`, `apps/web/components/employer/talent-profile/microcredential-verification.tsx`
|
||||
- **Action:** Build candidate profile view. Header: avatar, name, headline, match score, contact button. Body sections: artifact gallery (grid of project artifacts with thumbnails), process trace summary (timeline of build steps), oral defense transcripts (accordion of defense sessions with Q&A), competency mini-graph (react-flow visualization of candidate's competencies), microcredential verification (list of earned credentials with verification badges).
|
||||
- **Verify:** All profile sections render; defense transcripts accordion expands; mini-graph renders
|
||||
- **Done:** Candidate profile complete
|
||||
|
||||
#### Task 4-2-02: Posting management
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(employer)/postings/page.tsx`, `apps/web/components/employer/postings/posting-list.tsx`, `apps/web/components/employer/postings/posting-form.tsx`, `apps/web/components/employer/postings/applicant-list.tsx`
|
||||
- **Action:** Build posting management page. Layout: left (list of job postings with status badges: active, draft, expired), right (selected posting detail or create/edit form). Form fields: title, description, required competencies (multi-select), seniority, salary range, location, remote toggle. Applicant list per posting (table with name, applied date, status, match score). "Create New Posting" button opens form.
|
||||
- **Verify:** Posting list renders; form is interactive (inputs work, non-functional submit); applicant list displays
|
||||
- **Done:** Posting management complete
|
||||
|
||||
### Must-Haves (Phase 4)
|
||||
- [ ] Dashboard overview shows 4 metric cards, applicant pipeline, 3 charts
|
||||
- [ ] Talent search shows 15+ candidate cards with filters
|
||||
- [ ] Candidate profile shows artifact gallery, process trace, defense transcripts, mini-graph, credentials
|
||||
- [ ] Posting management shows posting list, create/edit form, applicant list
|
||||
- [ ] All pages responsive at 375px, 768px, 1280px
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Admin Surface UI
|
||||
|
||||
**Requirements:** REQ-022, REQ-023, REQ-024, REQ-025
|
||||
**Persona:** frontend-engineer
|
||||
**Goal:** All 4 admin pages render; competency graph viewer interactive
|
||||
|
||||
### Wave 1: Overview + learner management
|
||||
|
||||
#### Task 5-1-01: Admin overview
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(admin)/page.tsx`, `apps/web/components/admin/overview/platform-metrics.tsx`, `apps/web/components/admin/overview/activity-feed.tsx`, `apps/web/components/admin/overview/system-health.tsx`
|
||||
- **Action:** Build admin overview. Top: platform metric cards (total learners, total employers, placements, completion rate, NPS). Middle: activity feed (timeline of recent platform events — new registrations, completions, job postings, placements). Right: system health mockup (status indicators for services, uptime bars, error rates).
|
||||
- **Verify:** Admin overview renders with metrics, activity feed, system health
|
||||
- **Done:** Admin overview complete
|
||||
|
||||
#### Task 5-1-02: Learner management
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(admin)/learners/page.tsx`, `apps/web/components/admin/learners/learner-table.tsx`, `apps/web/components/admin/learners/learner-detail.tsx`
|
||||
- **Action:** Build learner management page. Layout: searchable learner table (columns: name, email, stack, progress %, status, joined date). Search and filter (by stack, status). Clicking a learner opens detail panel (progress tracking, competency completion, credential issuance log, recent activity).
|
||||
- **Verify:** Learner table renders with mock data; search filters; detail panel opens on click
|
||||
- **Done:** Learner management complete
|
||||
|
||||
### Wave 2: Graph viewer + moderation
|
||||
|
||||
#### Task 5-2-01: Competency graph viewer
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(admin)/graph/page.tsx`, `apps/web/components/admin/graph/competency-graph.tsx`, `apps/web/components/admin/graph/node-detail.tsx`
|
||||
- **Action:** Build competency graph viewer using @xyflow/react. Interactive node/edge graph showing competency stacks and their relationships. Nodes: competency stacks (colored by category) and individual competencies. Edges: prerequisite relationships. Node click opens detail panel (competency name, description, stack, prerequisites, learners mastering it). Controls: zoom, pan, fit-to-screen. Mock graph data.
|
||||
- **Verify:** Graph renders with nodes and edges; nodes are clickable; detail panel opens; zoom/pan works
|
||||
- **Done:** Competency graph viewer complete
|
||||
|
||||
#### Task 5-2-02: Marketplace moderation
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/app/(admin)/moderation/page.tsx`, `apps/web/components/admin/moderation/review-queue.tsx`, `apps/web/components/admin/moderation/verification-queue.tsx`, `apps/web/components/admin/moderation/flagged-content.tsx`
|
||||
- **Action:** Build marketplace moderation page. Three tabs: Job Posting Review (queue of pending job postings with approve/reject buttons), Employer Verification (queue of employers awaiting identity verification), Flagged Content (list of reported content with reason, reporter, actions). All buttons non-functional but interactive (hover states, click feedback).
|
||||
- **Verify:** Moderation page renders with 3 tabs; queues display mock items; tab switching works
|
||||
- **Done:** Marketplace moderation complete
|
||||
|
||||
### Must-Haves (Phase 5)
|
||||
- [ ] Admin overview shows platform metrics, activity feed, system health
|
||||
- [ ] Learner management shows searchable table with detail panel
|
||||
- [ ] Competency graph viewer renders interactive graph with clickable nodes
|
||||
- [ ] Marketplace moderation shows 3 tabbed queues
|
||||
- [ ] All pages responsive at 375px, 768px, 1280px
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Polish + Integration
|
||||
|
||||
**Requirements:** REQ-026, REQ-027, REQ-028
|
||||
**Persona:** frontend-engineer, design-system-engineer
|
||||
**Goal:** Cross-surface consistency, dark mode everywhere, Storybook
|
||||
|
||||
### Wave 1: Navigation + consistency
|
||||
|
||||
#### Task 6-1-01: Cross-surface navigation polish
|
||||
- **Persona:** frontend-engineer
|
||||
- **Files:** `apps/web/components/navigation-shell.tsx` (update), `apps/web/components/role-switcher.tsx` (update), `apps/web/components/breadcrumbs.tsx`
|
||||
- **Action:** Polish cross-surface navigation. Role switcher dropdown with surface-specific sub-navigation. Breadcrumbs on all pages showing current location. Consistent header/footer across all 4 surfaces. Active nav link highlighting.
|
||||
- **Verify:** Breadcrumbs show on all pages; role switcher dropdown works; active links highlighted
|
||||
- **Done:** Cross-surface navigation polished
|
||||
|
||||
#### Task 6-1-02: Visual consistency audit
|
||||
- **Persona:** design-system-engineer
|
||||
- **Files:** `apps/web/app/globals.css` (update), `packages/ui/src/tokens/index.ts` (update if needed)
|
||||
- **Action:** Audit all surfaces for visual consistency. Check: typography scale (all text uses design tokens), color palette (no hardcoded colors), spacing system (all margins/padding use design tokens), dark mode (all pages support dark mode toggle), WCAG AA contrast (all text meets 4.5:1 ratio). Fix any inconsistencies found.
|
||||
- **Verify:** No hardcoded colors; dark mode works on all pages; contrast check passes
|
||||
- **Done:** Visual consistency audit complete
|
||||
|
||||
### Wave 2: Storybook
|
||||
|
||||
#### Task 6-2-01: Storybook setup
|
||||
- **Persona:** design-system-engineer
|
||||
- **Files:** `apps/web/.storybook/main.ts`, `apps/web/.storybook/preview.ts`, `packages/ui/src/primitives/*.stories.tsx` (one per primitive)
|
||||
- **Action:** Set up Storybook for the component library. Configure for Next.js + Tailwind. Create stories for all 12 primitives and key composites (JobCard, CandidateCard, CompetencyBadge, MetricCard). Each story: default, variants, sizes, dark mode.
|
||||
- **Verify:** `pnpm storybook` starts; all primitive stories render; dark mode toggle in Storybook
|
||||
- **Done:** Storybook documents all primitives + key composites
|
||||
|
||||
### Must-Haves (Phase 6)
|
||||
- [ ] Breadcrumbs on all pages
|
||||
- [ ] Role switcher dropdown with surface-specific nav
|
||||
- [ ] Active nav link highlighting
|
||||
- [ ] No hardcoded colors — all from design tokens
|
||||
- [ ] Dark mode works on all 4 surfaces
|
||||
- [ ] WCAG AA contrast passes
|
||||
- [ ] Storybook runs with all primitive stories
|
||||
|
||||
---
|
||||
|
||||
## MVP/UX Sections
|
||||
|
||||
### User-Facing Surface
|
||||
The primary user-facing surface is the **Nextcraft web application** at `localhost:3000` (dev) with 4 route groups:
|
||||
- `/` — Learner surface (landing, catalog, dashboard, learn, build, defend)
|
||||
- `/marketplace` — Marketplace surface (jobs, employers, pricing)
|
||||
- `/employer` — Employer dashboard (overview, talent, postings)
|
||||
- `/admin` — Admin surface (overview, learners, graph, moderation)
|
||||
|
||||
### Happy Path
|
||||
1. User visits landing page → sees hero, how-it-works (Byte→Build→Demonstrate→Defend), program highlights
|
||||
2. User clicks "Explore Programs" → program catalog shows 5 competency stacks
|
||||
3. User clicks "AI Orchestration Engineer" → competency stack view shows 15 competencies
|
||||
4. User clicks a competency → byte tutorial viewer shows concept + worked example
|
||||
5. User clicks "Start Building" → build sandbox mockup shows IDE UI with telemetry
|
||||
6. User clicks "Submit for Assessment" → assessment/defense mockup shows rubric, AI reviewer, oral defense interface
|
||||
7. User navigates to marketplace → job board shows AI-era job listings with match scores
|
||||
8. User searches/filters jobs → results update client-side
|
||||
9. User clicks a job → job detail page shows full description, required competencies, employer info
|
||||
10. User switches to employer dashboard → overview shows metrics, pipeline, charts
|
||||
11. User searches talent → candidate cards with microcredentials, defense scores
|
||||
12. User clicks a candidate → profile shows artifact gallery, process trace, defense transcripts
|
||||
13. User switches to admin → overview shows platform metrics, activity feed
|
||||
14. User opens competency graph viewer → interactive graph with clickable nodes
|
||||
|
||||
### UX Acceptance Criteria
|
||||
1. All 4 surfaces are accessible via the role switcher in the header
|
||||
2. Navigation is consistent across all surfaces (same header, footer, breadcrumb pattern)
|
||||
3. All pages are responsive at 375px (mobile), 768px (tablet), 1280px (desktop)
|
||||
4. Dark mode toggle works on all surfaces
|
||||
5. All interactive elements have hover states and click feedback
|
||||
6. Form inputs are non-functional but visually complete (placeholders, labels, validation states)
|
||||
7. Mock data is realistic and typed — no "lorem ipsum" or placeholder text
|
||||
8. All charts render correctly (recharts) with mock data
|
||||
9. Competency graph viewer is interactive (zoom, pan, click nodes)
|
||||
10. AI tutor chat displays pre-scripted responses on message "send"
|
||||
11. No console errors on any page
|
||||
12. `pnpm build` succeeds without warnings
|
||||
@@ -0,0 +1,102 @@
|
||||
# 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.1 — UI/UX Prototype
|
||||
|
||||
**Scope:** High-fidelity interactive prototype of all four Nextcraft surfaces with realistic mock data, navigation flows, responsive layouts, and a shared component library. No backend, no business logic, no database — everything static/mocked.
|
||||
|
||||
**Constraint:** MAJOR 0 until MVP is released. No business logic until the first milestone prototype is agreed upon by the founder.
|
||||
|
||||
**Tech stack:** TypeScript monorepo (pnpm/turborepo) with Next.js for all web surfaces. Python FastAPI AI services planned for later milestones (not in v0.1).
|
||||
|
||||
---
|
||||
|
||||
## Requirements (Validated)
|
||||
|
||||
The following requirements have been validated during specification and are locked for milestone v0.1:
|
||||
|
||||
1. Learner surface UI — landing page, program catalog, competency stack view, learner dashboard, byte tutorial viewer, build sandbox mockup, assessment/defense mockup
|
||||
2. Marketplace surface UI — job board listing, job detail page, employer profile, search/filter UI, job posting packages pricing page
|
||||
3. Employer dashboard UI — overview, talent search, candidate profile view, posting management
|
||||
4. Admin surface UI — overview, learner management, competency graph viewer, marketplace moderation
|
||||
5. Shared component library — design system, reusable UI primitives, surface-specific theming
|
||||
6. Responsive layout system — mobile, tablet, desktop breakpoints
|
||||
7. Mock data layer — typed, realistic data reflecting the vision (competency stacks, job listings, candidate profiles)
|
||||
8. Navigation/routing — cross-surface navigation, role-based route groups
|
||||
|
||||
## Requirements (Active — Future Milestones)
|
||||
|
||||
The following are deferred beyond v0.1 and will be activated in subsequent milestones:
|
||||
|
||||
- AI tutor agent architecture (Coach, Tutor, Lab, Assessor, Proctor, Mentor)
|
||||
- Competency graph engine and adaptive pathways
|
||||
- Assessment engine (process-trace grading, oral defense, per-learner variant tasks)
|
||||
- Sandbox fabric (sandboxed IDE, design tool, simulation)
|
||||
- Identity verification and age-gating logic (16+/18+)
|
||||
- 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.cloudinit.dev, owner=coreci, repo=nextcraft | Founder-provided Gitea instance for release management. Token stored in .ciagent/.env.secrets. | 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. Future: TS + Python |
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,154 @@
|
||||
# Nextcraft — REQUIREMENTS.md
|
||||
|
||||
## v0.1 Requirements (UI/UX Prototype)
|
||||
|
||||
### Infrastructure
|
||||
|
||||
| ID | Description | Priority | Phase | Status |
|
||||
|----|-------------|----------|-------|--------|
|
||||
| REQ-001 | Monorepo scaffolding: pnpm workspaces, turborepo, Next.js app, TypeScript config, ESLint, Prettier | critical | 1 | pending |
|
||||
| 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)
|
||||
|
||||
### AI Tutor Architecture
|
||||
|
||||
| ID | Description | Priority | Milestone | Status |
|
||||
|----|-------------|----------|-----------|--------|
|
||||
| REQ-F-001 | Coach agent: pacing, motivation, retrieval practice | high | v0.2+ | deferred |
|
||||
| REQ-F-002 | Tutor agent: concept delivery, Socratic questioning | high | v0.2+ | deferred |
|
||||
| REQ-F-003 | Lab agent: sandbox execution, in-flow feedback | high | v0.2+ | deferred |
|
||||
| REQ-F-004 | Assessor agent: rubric application to artifacts and defenses | high | v0.2+ | deferred |
|
||||
| REQ-F-005 | Proctor agent: identity, attention, integrity signals | high | v0.2+ | deferred |
|
||||
| REQ-F-006 | Mentor agent: long-horizon career narrative | medium | v0.2+ | 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 |
|
||||
|
||||
### 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+) | high | v0.2+ | 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
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| REQ-001 | 1 | pending |
|
||||
| REQ-002 | 1 | pending |
|
||||
| REQ-003 | 1 | pending |
|
||||
| REQ-004 | 1 | pending |
|
||||
| REQ-005 | 1 | pending |
|
||||
| REQ-006 | 2 | pending |
|
||||
| REQ-007 | 2 | pending |
|
||||
| REQ-008 | 2 | pending |
|
||||
| REQ-009 | 2 | pending |
|
||||
| REQ-010 | 2 | pending |
|
||||
| REQ-011 | 2 | pending |
|
||||
| REQ-012 | 2 | pending |
|
||||
| REQ-013 | 3 | pending |
|
||||
| REQ-014 | 3 | pending |
|
||||
| REQ-015 | 3 | pending |
|
||||
| REQ-016 | 3 | pending |
|
||||
| REQ-017 | 3 | pending |
|
||||
| REQ-018 | 4 | pending |
|
||||
| REQ-019 | 4 | pending |
|
||||
| REQ-020 | 4 | pending |
|
||||
| REQ-021 | 4 | pending |
|
||||
| REQ-022 | 5 | pending |
|
||||
| REQ-023 | 5 | pending |
|
||||
| REQ-024 | 5 | pending |
|
||||
| REQ-025 | 5 | pending |
|
||||
| REQ-026 | 6 | pending |
|
||||
| REQ-027 | 6 | pending |
|
||||
| REQ-028 | 6 | pending |
|
||||
@@ -0,0 +1,192 @@
|
||||
# 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 | in_progress | — | — | Specification, clarify, research, plan complete; .ciagent/ files created |
|
||||
| 1 | Project scaffolding | not_started | 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 | not_started | 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 | not_started | 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 | not_started | 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 | not_started | 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 | not_started | 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 | not_started | 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
|
||||
@@ -0,0 +1,54 @@
|
||||
{
|
||||
"version": "0.7.0",
|
||||
"autonomy": {
|
||||
"level": "full",
|
||||
"decision_confidence_threshold": 0.6,
|
||||
"escalation_hooks": ["deploy", "delete_data", "merge_to_main"],
|
||||
"max_revision_iterations": 3,
|
||||
"clarify_budget": 10
|
||||
},
|
||||
"release": {
|
||||
"forge": "gitea",
|
||||
"base_url": "https://git.cloudinit.dev",
|
||||
"owner": "coreci",
|
||||
"repo": "nextcraft"
|
||||
},
|
||||
"secrets": {
|
||||
"scopes": ["gitea"],
|
||||
"env_files": [".env", ".env.secrets", ".env.*"]
|
||||
},
|
||||
"ship": {
|
||||
"per_phase": true,
|
||||
"allow_skip": false,
|
||||
"release_blocking": false,
|
||||
"max_release_retries": 3
|
||||
},
|
||||
"verification": {
|
||||
"bdd_default": false
|
||||
},
|
||||
"personas": {
|
||||
"enabled": true,
|
||||
"territory_enforcement": "warn"
|
||||
},
|
||||
"parallelization": {
|
||||
"enabled": false,
|
||||
"max_concurrent_agents": 1
|
||||
},
|
||||
"ideation": {
|
||||
"max_ideas": 20,
|
||||
"categories": ["security", "quality", "architecture", "coverage", "improvement", "spec", "chaos", "bdd"]
|
||||
},
|
||||
"security": {
|
||||
"bash_allowlist": {
|
||||
"blocked_env_vars": ["GITEA_TOKEN", "GITHUB_TOKEN", "GITLAB_TOKEN"]
|
||||
}
|
||||
},
|
||||
"projects": [],
|
||||
"active_project": null,
|
||||
"milestone": {
|
||||
"version": "v0.1",
|
||||
"name": "nextcraft-ui-prototype",
|
||||
"type": "feature",
|
||||
"branch": "milestone/v0.1-nextcraft-ui-prototype"
|
||||
}
|
||||
}
|
||||
+42
@@ -0,0 +1,42 @@
|
||||
# Environment files — never commit credentials
|
||||
.env
|
||||
.env.secrets
|
||||
.env.*
|
||||
!.env.example
|
||||
|
||||
# CIAgent secrets
|
||||
.ciagent/.env.secrets
|
||||
|
||||
# Dependencies
|
||||
node_modules/
|
||||
__pycache__/
|
||||
*.pyc
|
||||
.venv/
|
||||
venv/
|
||||
|
||||
# Build artifacts
|
||||
dist/
|
||||
build/
|
||||
.next/
|
||||
.turbo/
|
||||
*.tsbuildinfo
|
||||
|
||||
# OS files
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# IDE
|
||||
.idea/
|
||||
.vscode/
|
||||
*.swp
|
||||
*.swo
|
||||
|
||||
# Logs
|
||||
*.log
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
|
||||
# Test coverage
|
||||
coverage/
|
||||
.nyc_output/
|
||||
Reference in New Issue
Block a user