docs: bootstrap tutor planning
This commit is contained in:
user
84
.planning/PROJECT.md
Normal file
84
.planning/PROJECT.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# Tutor Platform
|
||||
|
||||
## What This Is
|
||||
|
||||
Tutor Platform is a web service for software job seekers preparing for
|
||||
technical interviews. It combines adaptive interview practice, evidence-backed
|
||||
learner memory, source-backed learning ontology, and game-inspired progression
|
||||
to make interview readiness visible and repeatable.
|
||||
|
||||
The backend is Go because the product will internalize `agent-farm-go` workflow
|
||||
patterns and call `third-one` with `deepseek-v4-flash` through typed service
|
||||
boundaries.
|
||||
|
||||
## Core Value
|
||||
|
||||
The user should feel and prove that they are becoming more interview-ready after
|
||||
each short practice loop.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Validated
|
||||
|
||||
(None yet; ship to validate.)
|
||||
|
||||
### 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.
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- Full school LMS replacement; the first product target is job seekers.
|
||||
- Marketplace course publishing; not needed to prove the learning loop.
|
||||
- Automatic certification or hiring decisions; readiness is advisory.
|
||||
- Unreviewed generated canonical content; generated ontology and assets require
|
||||
provenance and review state.
|
||||
- Gambling-like rewards or shame-based leaderboards; progression must be tied to
|
||||
learning evidence.
|
||||
|
||||
## Context
|
||||
|
||||
- Product planning lives in `docs/planning/`.
|
||||
- OpenSpec change baseline lives in
|
||||
`openspec/changes/bootstrap-job-tutor-platform/`.
|
||||
- The service should use a Go backend.
|
||||
- Workflow behavior should be configuration-first and inspired by
|
||||
`agent-farm-go`.
|
||||
- LLM execution should use `third-one`, defaulting to `deepseek-v4-flash`.
|
||||
- Memory should be structured learner state, not a flat RAG transcript.
|
||||
- Gamification should use Flow, adaptive difficulty, growth lines, and strong
|
||||
session endings without exploitative mechanics.
|
||||
|
||||
## Constraints
|
||||
|
||||
- **Backend stack**: Go, to align with internalized `agent-farm-go` workflow
|
||||
patterns.
|
||||
- **File size**: manually authored source files must stay at or below 600 lines.
|
||||
- **Design principles**: SOLID, KISS, and YAGNI govern implementation.
|
||||
- **Workflow state**: product state changes should use typed contracts, not
|
||||
freeform prose parsing.
|
||||
- **Privacy**: learner memory and evidence may become sensitive, especially for
|
||||
future student/school expansion.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
| Decision | Rationale | Outcome |
|
||||
|----------|-----------|---------|
|
||||
| Start with software job seekers | Clear, testable interview-practice loop | Pending |
|
||||
| Use Go backend | Aligns service with internalized `agent-farm-go` substrate | Pending |
|
||||
| Use `third-one` and `deepseek-v4-flash` by default | Matches current local model/runtime direction | Pending |
|
||||
| Structured learner memory, not RAG-first | Product value is learner modeling and readiness | Pending |
|
||||
| Game-inspired progression must be evidence-backed | Creates retention without empty rewards | Pending |
|
||||
| 600-line source limit | Forces responsibility boundaries early | Pending |
|
||||
|
||||
---
|
||||
*Last updated: 2026-04-26 after Go backend and GSD planning direction were set.*
|
||||
111
.planning/REQUIREMENTS.md
Normal file
111
.planning/REQUIREMENTS.md
Normal file
@@ -0,0 +1,111 @@
|
||||
# Requirements: Tutor Platform
|
||||
|
||||
**Defined:** 2026-04-26
|
||||
**Core Value:** The user should feel and prove that they are becoming more
|
||||
interview-ready after each short practice loop.
|
||||
|
||||
## v1 Requirements
|
||||
|
||||
### Backend and Workflow
|
||||
|
||||
- [ ] **BACK-01**: Backend service is implemented in Go.
|
||||
- [ ] **BACK-02**: Backend exposes typed interfaces for tutor workflows.
|
||||
- [ ] **BACK-03**: Backend integrates internalized `agent-farm-go` workflow
|
||||
patterns without ad hoc handler shellouts.
|
||||
- [ ] **BACK-04**: Workflow LLM execution uses `third-one` with configurable
|
||||
runtime and default `deepseek-v4-flash`.
|
||||
- [ ] **BACK-05**: Manually authored source files stay at or below 600 lines.
|
||||
|
||||
### Interview Practice
|
||||
|
||||
- [ ] **INT-01**: User can select target role, stack, and interview timeline.
|
||||
- [ ] **INT-02**: User can complete a diagnostic technical interview.
|
||||
- [ ] **INT-03**: System can generate role-specific interview questions.
|
||||
- [ ] **INT-04**: System can grade user answers against explicit rubrics.
|
||||
- [ ] **INT-05**: System can ask targeted follow-up questions for weak answers.
|
||||
- [ ] **INT-06**: System preserves original answers and grading evidence.
|
||||
|
||||
### Learner Memory
|
||||
|
||||
- [ ] **MEM-01**: System stores learner profile with role, stack, timeline, and
|
||||
preferences.
|
||||
- [ ] **MEM-02**: System stores concept mastery states with evidence.
|
||||
- [ ] **MEM-03**: System stores recurring misconceptions with supporting
|
||||
answers.
|
||||
- [ ] **MEM-04**: System stores intervention history and review schedule.
|
||||
- [ ] **MEM-05**: Temporary session context does not become durable memory
|
||||
without evidence.
|
||||
|
||||
### Progression
|
||||
|
||||
- [ ] **PROG-01**: User can see a role-specific readiness map.
|
||||
- [ ] **PROG-02**: Concepts have challenge ladders from definition to interview
|
||||
pressure.
|
||||
- [ ] **PROG-03**: System selects next challenge based on learner memory and
|
||||
grading evidence.
|
||||
- [ ] **PROG-04**: System unlocks boss-style integrated questions after
|
||||
prerequisite stability.
|
||||
- [ ] **PROG-05**: Streaks and rewards avoid punitive or gambling-like mechanics.
|
||||
|
||||
### Ontology and Learning Materials
|
||||
|
||||
- [ ] **ONTO-01**: User or operator can upload learning materials.
|
||||
- [ ] **ONTO-02**: System creates source-backed ontology candidate nodes and
|
||||
edges.
|
||||
- [ ] **ONTO-03**: System detects missing prerequisites and weakly supported
|
||||
concepts.
|
||||
- [ ] **ONTO-04**: Generated or inferred content is marked as candidate until
|
||||
reviewed.
|
||||
|
||||
### Teaching Assets
|
||||
|
||||
- [ ] **ASSET-01**: System can generate prompt candidates for visual teaching
|
||||
assets.
|
||||
- [ ] **ASSET-02**: Generated assets store source concept, evidence, prompt,
|
||||
model config, and review state.
|
||||
- [ ] **ASSET-03**: Image model configuration verifies the actual OpenAI model
|
||||
identifier before production calls.
|
||||
|
||||
## v2 Requirements
|
||||
|
||||
### General Student Expansion
|
||||
|
||||
- **GEN-01**: Support non-interview learning tracks.
|
||||
- **GEN-02**: Support teacher or parent progress summaries.
|
||||
- **GEN-03**: Support school or organization tenant policies.
|
||||
|
||||
### Advanced Content Operations
|
||||
|
||||
- **ADV-01**: Human review workflow for promoted ontology content.
|
||||
- **ADV-02**: Multi-format teaching material generation beyond static images.
|
||||
- **ADV-03**: Company-specific or role-specific premium interview campaigns.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
| Feature | Reason |
|
||||
|---------|--------|
|
||||
| Full LMS | Too broad for v1; first validate job-seeker loop |
|
||||
| Hiring decisions | Product gives practice/readiness, not employment judgment |
|
||||
| Course marketplace | Not needed for core value |
|
||||
| Social leaderboards | Risk of shame mechanics and weak learning signal |
|
||||
| Random reward economy | Misaligned with evidence-backed learning |
|
||||
|
||||
## Traceability
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| BACK-01..BACK-05 | Phase 1 | Pending |
|
||||
| INT-01..INT-06 | Phase 2 | Pending |
|
||||
| MEM-01..MEM-05 | Phase 3 | Pending |
|
||||
| PROG-01..PROG-05 | Phase 4 | Pending |
|
||||
| ONTO-01..ONTO-04 | Phase 5 | Pending |
|
||||
| ASSET-01..ASSET-03 | Phase 6 | Pending |
|
||||
|
||||
**Coverage:**
|
||||
- v1 requirements: 28 total
|
||||
- Mapped to phases: 28
|
||||
- Unmapped: 0
|
||||
|
||||
---
|
||||
*Requirements defined: 2026-04-26*
|
||||
*Last updated: 2026-04-26 after Go backend direction was locked.*
|
||||
98
.planning/ROADMAP.md
Normal file
98
.planning/ROADMAP.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# Roadmap: Tutor Platform
|
||||
|
||||
## Milestone 1: Job-Seeker Interview Tutor MVP
|
||||
|
||||
### Phase 1: Go Backend Foundation and Workflow Boundary
|
||||
|
||||
**Goal:** Establish the Go service skeleton and typed workflow boundary for
|
||||
internalized `agent-farm-go` patterns.
|
||||
|
||||
**Requirements:** BACK-01, BACK-02, BACK-03, BACK-04, BACK-05
|
||||
|
||||
**Success Criteria:**
|
||||
|
||||
- Go backend scaffold exists with clear module boundaries.
|
||||
- No manually authored source file exceeds 600 lines.
|
||||
- Workflow interfaces are typed and isolated from HTTP handlers.
|
||||
- Runtime config can identify the `third-one` / `deepseek-v4-flash` target.
|
||||
- Basic build/test command is documented in `AGENTS.md`.
|
||||
|
||||
### Phase 2: Diagnostic Interview Loop
|
||||
|
||||
**Goal:** Prove the first job-seeker loop from role selection through graded
|
||||
diagnostic interview.
|
||||
|
||||
**Requirements:** INT-01, INT-02, INT-03, INT-04, INT-05, INT-06
|
||||
|
||||
**Success Criteria:**
|
||||
|
||||
- User can choose target role and stack.
|
||||
- Backend can create a diagnostic session.
|
||||
- System produces role-specific interview questions.
|
||||
- User answers are graded through typed workflow results.
|
||||
- Grading evidence and original answer are persisted.
|
||||
|
||||
### Phase 3: Learner Memory
|
||||
|
||||
**Goal:** Convert graded answer evidence into structured learner memory.
|
||||
|
||||
**Requirements:** MEM-01, MEM-02, MEM-03, MEM-04, MEM-05
|
||||
|
||||
**Success Criteria:**
|
||||
|
||||
- Learner profile is persisted.
|
||||
- Concept mastery updates require evidence.
|
||||
- Misconceptions link to supporting answers.
|
||||
- Session context and durable memory remain separate.
|
||||
- Memory extraction workflow emits typed candidates.
|
||||
|
||||
### Phase 4: Progression and Gamified Learning Routine
|
||||
|
||||
**Goal:** Make readiness and next challenge visible without empty rewards.
|
||||
|
||||
**Requirements:** PROG-01, PROG-02, PROG-03, PROG-04, PROG-05
|
||||
|
||||
**Success Criteria:**
|
||||
|
||||
- Readiness map displays concept states.
|
||||
- Challenge ladder exists for the first backend interview track.
|
||||
- Next challenge is selected from learner memory and grading evidence.
|
||||
- Boss question unlocks after prerequisite stability.
|
||||
- Streak/reward behavior avoids punitive and random-reward mechanics.
|
||||
|
||||
### Phase 5: Source-Backed Ontology Builder
|
||||
|
||||
**Goal:** Start material ingestion and ontology candidate generation.
|
||||
|
||||
**Requirements:** ONTO-01, ONTO-02, ONTO-03, ONTO-04
|
||||
|
||||
**Success Criteria:**
|
||||
|
||||
- User/operator can add source material.
|
||||
- Concepts, prerequisites, rubrics, and question candidates carry provenance.
|
||||
- Missing prerequisites and weak areas are flagged.
|
||||
- Generated/inferred content is not promoted as canonical automatically.
|
||||
|
||||
### Phase 6: Visual Teaching Asset Pipeline
|
||||
|
||||
**Goal:** Generate reviewable teaching asset candidates from ontology concepts.
|
||||
|
||||
**Requirements:** ASSET-01, ASSET-02, ASSET-03
|
||||
|
||||
**Success Criteria:**
|
||||
|
||||
- Asset prompt generation contract exists.
|
||||
- Generated assets store prompt lineage, source concept, source evidence, model
|
||||
config, and review state.
|
||||
- Actual image model identifier is verified before production image calls.
|
||||
|
||||
## Parking Lot
|
||||
|
||||
- General student mode.
|
||||
- Teacher/parent dashboards.
|
||||
- School tenant administration.
|
||||
- Company-specific interview packs.
|
||||
- Human ontology review console.
|
||||
|
||||
---
|
||||
*Roadmap created: 2026-04-26 after initial product planning and Go backend decision.*
|
||||
36
.planning/STATE.md
Normal file
36
.planning/STATE.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# Project State
|
||||
|
||||
## Project Reference
|
||||
|
||||
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:** Phase 1: Go Backend Foundation and Workflow Boundary.
|
||||
|
||||
## Current Decisions
|
||||
|
||||
- Backend is Go.
|
||||
- `agent-farm-go` workflow patterns should be internalized behind typed backend
|
||||
interfaces.
|
||||
- `third-one` is the LLM execution kernel.
|
||||
- Default runtime target is `deepseek-v4-flash`.
|
||||
- Source files should stay at or below 600 lines.
|
||||
- SOLID, KISS, and YAGNI are active implementation constraints.
|
||||
- OpenSpec is the intent/requirements source of truth.
|
||||
|
||||
## Next Actions
|
||||
|
||||
1. Choose first interview track and canonical concept seed list.
|
||||
2. Define typed contracts for diagnostic, grading, memory extraction, next
|
||||
challenge, readiness update, ontology gap, and asset prompt.
|
||||
3. Plan Phase 1 with GSD before writing backend code.
|
||||
|
||||
## Validation Log
|
||||
|
||||
- 2026-04-26: `openspec validate bootstrap-job-tutor-platform --strict` passed
|
||||
before GSD planning docs were created.
|
||||
|
||||
---
|
||||
*State initialized: 2026-04-26.*
|
||||
14
.planning/config.json
Normal file
14
.planning/config.json
Normal file
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"mode": "yolo",
|
||||
"granularity": "standard",
|
||||
"parallelization": true,
|
||||
"commit_docs": true,
|
||||
"model_profile": "inherit",
|
||||
"workflow": {
|
||||
"research": true,
|
||||
"plan_check": true,
|
||||
"verifier": true,
|
||||
"nyquist_validation": true,
|
||||
"auto_advance": true
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user