From 3493f8b5a59b4a1bbd866399032c7d3ba8328313 Mon Sep 17 00:00:00 2001 From: user Date: Sun, 26 Apr 2026 18:34:47 +0900 Subject: [PATCH] docs: start frontend mvp milestone --- .planning/PROJECT.md | 62 +++++++++++++++---- .planning/REQUIREMENTS.md | 24 ++++++- .planning/ROADMAP.md | 47 +++++++++++++- .planning/STATE.md | 9 ++- openspec/changes/frontend-mvp/design.md | 30 +++++++++ openspec/changes/frontend-mvp/proposal.md | 19 ++++++ .../frontend-mvp/specs/frontend-mvp/spec.md | 44 +++++++++++++ openspec/changes/frontend-mvp/tasks.md | 8 +++ 8 files changed, 225 insertions(+), 18 deletions(-) create mode 100644 openspec/changes/frontend-mvp/design.md create mode 100644 openspec/changes/frontend-mvp/proposal.md create mode 100644 openspec/changes/frontend-mvp/specs/frontend-mvp/spec.md create mode 100644 openspec/changes/frontend-mvp/tasks.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index a12872f..4956b23 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -20,20 +20,38 @@ each short practice loop. ### Validated -(None yet; ship to validate.) +- [x] Developer job seekers can complete a diagnostic technical interview. +- [x] Answers are graded with rubrics and preserved as evidence. +- [x] Learner memory tracks concept mastery, misconceptions, evidence, and + interventions. +- [x] The system selects the next best interview challenge from learner state. +- [x] The user sees a readiness map and meaningful progression after each loop. +- [x] Uploaded learning materials can become source-backed ontology candidates. +- [x] Generated learning assets preserve prompt, source, and review lineage. +- [x] Backend implementation uses Go and keeps `agent-farm-go` workflow patterns + internalized behind typed interfaces. ### Active -- [ ] Developer job seekers can complete a diagnostic technical interview. -- [ ] Answers are graded with rubrics and preserved as evidence. -- [ ] Learner memory tracks concept mastery, misconceptions, evidence, and - interventions. -- [ ] The system selects the next best interview challenge from learner state. -- [ ] The user sees a readiness map and meaningful progression after each loop. -- [ ] Uploaded learning materials can become source-backed ontology candidates. -- [ ] Generated learning assets preserve prompt, source, and review lineage. -- [ ] Backend implementation uses Go and keeps `agent-farm-go` workflow patterns - internalized behind typed interfaces. +- [ ] Job seekers can use the first web app without API tooling. +- [ ] The web app guides users through diagnostic practice and shows feedback. +- [ ] The web app shows learner memory, readiness, and next challenge after + practice. +- [ ] Operators can ingest learning material and inspect ontology candidates. +- [ ] Operators can generate source-backed teaching asset prompt candidates. + +## Current Milestone: v2 Frontend MVP + +**Goal:** Turn the completed backend learning loop into a usable web service +experience for developer job seekers. + +**Target features:** + +- Web app shell served by the Go backend. +- Diagnostic interview practice UI. +- Learner memory, readiness map, and next challenge views. +- Material ingestion and ontology snapshot UI. +- Teaching asset prompt candidate UI. ### Out of Scope @@ -81,6 +99,26 @@ each short practice loop. | Game-inspired progression must be evidence-backed | Creates retention without empty rewards | Pending | | 600-line source limit | Forces responsibility boundaries early | Pending | | Backend Developer Interview first track | Gives a broad but testable MVP concept set | Pending | +| v2 frontend first | The backend loop is proven; the next risk is whether users can operate it as a web service | Active | + +## Evolution + +This document evolves at phase transitions and milestone boundaries. + +**After each phase transition**: + +1. Requirements invalidated? Move to Out of Scope with reason. +2. Requirements validated? Move to Validated with phase reference. +3. New requirements emerged? Add to Active. +4. Decisions to log? Add to Key Decisions. +5. "What This Is" still accurate? Update if drifted. + +**After each milestone**: + +1. Full review of all sections. +2. Core Value check: still the right priority? +3. Audit Out of Scope: reasons still valid? +4. Update Context with current state. --- -*Last updated: 2026-04-26 after first track and Phase 1 plan were set.* +*Last updated: 2026-04-26 after v2 Frontend MVP milestone start.* diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 52a8a62..2deabb3 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -68,6 +68,22 @@ interview-ready after each short practice loop. ## v2 Requirements +### Frontend MVP + +- [ ] **WEB-01**: User can open a web app served by the Go service. +- [ ] **WEB-02**: User can create a diagnostic interview session from the web + app. +- [ ] **WEB-03**: User can answer a diagnostic question and see rubric feedback. +- [ ] **WEB-04**: User can see learner memory, readiness, and next challenge + after answering. +- [ ] **WEB-05**: Operator can ingest source material from the web app. +- [ ] **WEB-06**: Operator can inspect ontology candidate concepts, edges, and + gaps. +- [ ] **WEB-07**: Operator can generate and inspect teaching asset prompt + candidates. +- [ ] **WEB-08**: Web UI includes loading, empty, and error states for the MVP + flows. + ### General Student Expansion - **GEN-01**: Support non-interview learning tracks. @@ -100,12 +116,16 @@ interview-ready after each short practice loop. | PROG-01..PROG-05 | Phase 4 | Complete | | ONTO-01..ONTO-04 | Phase 5 | Complete | | ASSET-01..ASSET-03 | Phase 6 | Complete | +| WEB-01..WEB-03 | Phase 7 | Pending | +| WEB-04 | Phase 8 | Pending | +| WEB-05..WEB-08 | Phase 9 | Pending | **Coverage:** - v1 requirements: 28 total -- Mapped to phases: 28 +- v2 frontend requirements: 8 total +- Mapped to phases: 36 - Unmapped: 0 --- *Requirements defined: 2026-04-26* -*Last updated: 2026-04-26 after Phase 6 execution.* +*Last updated: 2026-04-26 after v2 Frontend MVP milestone start.* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index d3c98f6..9c7dd7d 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -94,5 +94,50 @@ diagnostic interview. - Company-specific interview packs. - Human ontology review console. +## Milestone 2: Frontend MVP + +### Phase 7: Web App Shell and Diagnostic Start + +**Goal:** Serve the first web app from the Go service and let a job seeker +start diagnostic practice without API tooling. + +**Requirements:** WEB-01, WEB-02, WEB-03 + +**Success Criteria:** + +- Go service serves a web app at `/`. +- User can enter target role, stack, and interview timeline. +- User can create a diagnostic session from the browser. +- User can submit an answer and see typed grading feedback. +- UI has loading and error states for the diagnostic flow. + +### Phase 8: Learning Progress View + +**Goal:** Show evidence-backed learning progress after practice. + +**Requirements:** WEB-04 + +**Success Criteria:** + +- User can see learner profile and concept mastery after answering. +- User can see readiness percentage and concept ladder state. +- User can see the next recommended challenge and its evidence. +- Empty states explain what to do before memory/progression exists. + +### Phase 9: Material and Asset Workspace + +**Goal:** Let an operator use ontology and teaching asset prompt workflows from +the web app. + +**Requirements:** WEB-05, WEB-06, WEB-07, WEB-08 + +**Success Criteria:** + +- Operator can ingest text material from the browser. +- Operator can inspect ontology candidate concepts, edges, and gaps. +- Operator can generate teaching asset prompt candidates from a concept. +- UI clearly shows candidate review state, source evidence, and model + verification guard. + --- -*Roadmap created: 2026-04-26 after initial product planning and Go backend decision.* +*Roadmap updated: 2026-04-26 after v2 Frontend MVP milestone start.* diff --git a/.planning/STATE.md b/.planning/STATE.md index c2a97d9..0aa9924 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -7,7 +7,7 @@ See: `.planning/PROJECT.md` (updated 2026-04-26) **Core value:** The user should feel and prove that they are becoming more interview-ready after each short practice loop. -**Current focus:** v1 milestone audited; ready to choose the next milestone. +**Current focus:** v2 Frontend MVP milestone started; ready for Phase 7. ## Current Decisions @@ -35,11 +35,12 @@ interview-ready after each short practice loop. evidence, model config, review state, and model-id verification guard. - v1 milestone audit completed with all 28/28 requirements satisfied and tech-debt items recorded in `.planning/v1-MILESTONE-AUDIT.md`. +- v2 Frontend MVP milestone selected to turn the backend learning loop into a + usable web service. ## Next Actions -1. Choose the next milestone: frontend MVP, persistence, real workflow runtime, - or document parser integration. +1. Plan and execute Phase 7: Web App Shell and Diagnostic Start. 2. Verify the production OpenAI image model identifier before real image generation calls. 3. Add standardized SUMMARY frontmatter or Nyquist validation files if future @@ -73,6 +74,8 @@ interview-ready after each short practice loop. integration, E2E diagnostic/progression and material/asset flows. Audit status is `tech_debt` because MVP storage, real workflow runtime, parsers, real image generation, and Nyquist validation artifacts remain deferred. +- 2026-04-26: v2 Frontend MVP milestone started with WEB-01..WEB-08 mapped to + phases 7 through 9. --- *State initialized: 2026-04-26.* diff --git a/openspec/changes/frontend-mvp/design.md b/openspec/changes/frontend-mvp/design.md new file mode 100644 index 0000000..eee3ecb --- /dev/null +++ b/openspec/changes/frontend-mvp/design.md @@ -0,0 +1,30 @@ +# Design: Frontend MVP + +## Approach + +Use a dependency-light web app served by the Go backend. The first UI can be +plain HTML/CSS/JavaScript so the repo avoids frontend build tooling until the +interaction model is proven. + +## UX Principles + +- First screen is the working tutor experience, not a marketing landing page. +- Keep the UI quiet, operational, and focused on repeated practice. +- Show evidence-backed feedback and next actions after each loop. +- Use clear loading, empty, and error states. + +## Boundaries + +In scope: + +- Diagnostic practice. +- Learner memory and readiness display. +- Material ingestion and ontology inspection. +- Teaching asset prompt candidates. + +Out of scope: + +- Authentication. +- Multi-user persistence. +- Payment/subscription. +- Real provider image generation. diff --git a/openspec/changes/frontend-mvp/proposal.md b/openspec/changes/frontend-mvp/proposal.md new file mode 100644 index 0000000..4abd0e1 --- /dev/null +++ b/openspec/changes/frontend-mvp/proposal.md @@ -0,0 +1,19 @@ +# Change: frontend-mvp + +## Why + +The backend MVP now exposes the core tutoring loop, but job seekers still need +a web service experience instead of API tooling. + +## What Changes + +- Serve a web app from the Go backend. +- Add diagnostic practice UI. +- Add learner progress UI. +- Add material ingestion, ontology inspection, and teaching asset prompt UI. + +## Impact + +- Adds frontend capability requirements. +- Keeps Go backend as the serving boundary for the MVP. +- Does not introduce authentication, persistence, or real image generation. diff --git a/openspec/changes/frontend-mvp/specs/frontend-mvp/spec.md b/openspec/changes/frontend-mvp/specs/frontend-mvp/spec.md new file mode 100644 index 0000000..c8cb80c --- /dev/null +++ b/openspec/changes/frontend-mvp/specs/frontend-mvp/spec.md @@ -0,0 +1,44 @@ +# frontend-mvp Specification + +## ADDED Requirements + +### Requirement: Web app exposes the job-seeker tutoring loop + +The system SHALL provide a browser UI for the diagnostic interview loop. + +#### Scenario: user starts diagnostic practice + +- **GIVEN** a job seeker opens the web app +- **WHEN** they enter target role, stack, and interview timeline +- **THEN** the app creates a diagnostic session +- **AND** shows role-relevant questions. + +#### Scenario: user submits an answer + +- **GIVEN** a diagnostic session is active +- **WHEN** the user submits an answer +- **THEN** the app shows typed grading feedback +- **AND** the feedback links to evidence-backed learning state. + +### Requirement: Web app exposes learning progress + +The system SHALL show learner memory, readiness, and next challenge from the +backend APIs. + +#### Scenario: progress appears after answer + +- **GIVEN** the user has submitted at least one answer +- **WHEN** the app refreshes progress +- **THEN** it shows concept mastery, readiness percentage, and next challenge. + +### Requirement: Web app exposes content operations + +The system SHALL provide MVP operator controls for material ingestion, +ontology inspection, and teaching asset prompt candidates. + +#### Scenario: operator creates teaching asset prompt + +- **GIVEN** source material has produced ontology candidates +- **WHEN** the operator generates an asset prompt for a concept +- **THEN** the prompt shows source evidence, review state, model key, and model + verification guard. diff --git a/openspec/changes/frontend-mvp/tasks.md b/openspec/changes/frontend-mvp/tasks.md new file mode 100644 index 0000000..d783c34 --- /dev/null +++ b/openspec/changes/frontend-mvp/tasks.md @@ -0,0 +1,8 @@ +# Tasks + +- [ ] 1. Implement web app shell served by the Go backend. +- [ ] 2. Implement diagnostic session start and answer submission UI. +- [ ] 3. Implement learner memory, readiness, and next challenge UI. +- [ ] 4. Implement material ingestion and ontology inspection UI. +- [ ] 5. Implement teaching asset prompt candidate UI. +- [ ] 6. Validate frontend MVP with tests, smoke checks, and OpenSpec.