docs: bootstrap tutor planning

openspec/changes/bootstrap-job-tutor-platform/design.md

@@ -0,0 +1,74 @@
+# Design
+
+## Product Boundary
+
+The first user is a software job seeker. The product should begin with
+technical interview preparation because it gives clear task loops:
+
+- ask a question
+- receive an answer
+- grade against a rubric
+- ask follow-ups
+- extract memory
+- recommend review
+- show progress and next challenge
+
+General students remain a future expansion path, but the first requirements
+should not be diluted by full K-12 scope.
+
+## Architecture Boundary
+
+Use a Go backend as the product service boundary. Internalize `agent-farm-go`
+workflow patterns and contracts inside that backend boundary while keeping agent
+behavior configuration-first where possible. Use `third-one` as the LLM
+execution kernel with `deepseek-v4-flash` as the default configured model
+target.
+
+The product backend owns durable user, learner, memory, ontology, and asset
+records. External memory or graph projects may inform design or become adapters,
+but they should not own product privacy or tenant semantics.
+
+## Memory Boundary
+
+The platform should not model memory as a flat RAG corpus. It should keep
+structured learning state:
+
+- learner profile
+- concept mastery
+- misconception
+- evidence
+- intervention
+- review schedule
+
+Every durable memory update must include evidence so the product can explain why
+it believes a learner is weak or strong on a concept.
+
+## Ontology Boundary
+
+Uploaded materials should become source-backed learning graphs. Inferred gaps
+and generated explanations are candidates until reviewed or otherwise validated.
+
+## Visual Asset Boundary
+
+Image generation should support diagrams and slide-like learning slices, but the
+asset pipeline must preserve prompt lineage, source concept links, and review
+state. The desired image provider key is `gpt-image-v2`, but production
+implementation must verify the current OpenAI API model name before wiring.
+
+## Gamification Boundary
+
+Use game-design principles to create healthy persistence: adaptive challenge,
+visible growth, clear goals, strong session endings, and long-term readiness
+progress. Do not optimize for compulsion alone. Random rewards, punitive streaks,
+and shame-based leaderboards are out of scope for the first product baseline.
+
+The initial learning loop is:
+
+- readiness goal
+- interview question
+- answer
+- rubric feedback
+- follow-up or correction
+- memory update
+- visible progress
+- next best challenge

openspec/changes/bootstrap-job-tutor-platform/proposal.md

@@ -0,0 +1,44 @@
+# Bootstrap Job Tutor Platform
+
+## Summary
+
+Create the first product baseline for a web-based AI tutor aimed at software job
+seekers. The platform uses workflow-driven technical interview practice,
+structured learner memory, and source-backed ontology building from uploaded
+learning materials.
+
+## Why
+
+Software job seekers need adaptive practice and evidence-backed feedback more
+than another generic interview-question list. A narrow first audience lets the
+platform prove diagnosis, tutoring, memory extraction, and review planning
+before expanding to broader student use cases.
+
+## Motivation
+
+The first product target should be narrow enough to build and evaluate:
+developers preparing for technical interviews. This target naturally exercises
+adaptive questioning, answer grading, misconception tracking, review planning,
+and material-to-curriculum transformation. The same foundation can later expand
+to general students.
+
+## Scope
+
+- Define the job-seeker-first product direction.
+- Define learner memory requirements.
+- Define ontology ingestion and gap-detection requirements.
+- Define workflow boundaries for `agent-farm-go` and `third-one`.
+- Define generated visual teaching asset requirements.
+
+## Non-Goals
+
+- Implement the full web service in this change.
+- Replace a school LMS.
+- Build a marketplace or certification product.
+- Treat generated ontology content as canonical without review.
+
+## Impact
+
+This establishes the planning baseline for future implementation. Future code
+changes should trace back to these specs and keep OpenSpec updated as the
+product shape evolves.

openspec/changes/bootstrap-job-tutor-platform/specs/engineering-quality/spec.md

@@ -0,0 +1,52 @@
+# engineering-quality Specification
+
+## ADDED Requirements
+
+### Requirement: Implementation follows bounded file-size and design principles
+
+The system SHALL be implemented with bounded file sizes and pragmatic SOLID,
+KISS, and YAGNI principles.
+
+#### Scenario: backend source is Go by default
+
+- **GIVEN** a developer adds backend service code
+- **WHEN** no explicit OpenSpec change revisits the stack
+- **THEN** the backend code is implemented in Go
+- **AND** workflow integration uses typed Go boundaries.
+
+#### Scenario: source files stay under the manual file-size limit
+
+- **GIVEN** a developer adds or modifies manually authored source code
+- **WHEN** the change is ready for review
+- **THEN** no manually authored source file exceeds 600 lines
+- **AND** files approaching the limit are split by responsibility.
+
+#### Scenario: domain responsibilities remain separated
+
+- **GIVEN** a feature touches interview grading, learner memory, ontology,
+  progression, or generated assets
+- **WHEN** the implementation is designed
+- **THEN** each responsibility remains in a cohesive module or service
+- **AND** provider SDKs, storage adapters, and workflow calls do not leak into
+  unrelated domain logic.
+
+#### Scenario: speculative abstractions are deferred
+
+- **GIVEN** a future feature might need a generic framework, plugin system,
+  queue, or provider abstraction
+- **WHEN** the current MVP slice does not require it
+- **THEN** the implementation defers that abstraction
+- **AND** uses the simplest design that satisfies the current OpenSpec
+  requirement.
+
+### Requirement: Workflow state changes use typed contracts
+
+The system SHALL prefer typed contracts for workflow inputs and outputs that
+change product state.
+
+#### Scenario: grading output updates learner state
+
+- **GIVEN** a tutor workflow grades a user's answer
+- **WHEN** the result can affect memory, readiness, or next challenge selection
+- **THEN** the workflow returns a typed result
+- **AND** the product state update does not depend on parsing freeform prose.

openspec/changes/bootstrap-job-tutor-platform/specs/job-seeker-tutor/spec.md

@@ -0,0 +1,37 @@
+# job-seeker-tutor Specification
+
+## ADDED Requirements
+
+### Requirement: Job seeker interview preparation is the first product target
+
+The system SHALL prioritize software job seekers as the first product audience
+while preserving an architecture that can later support general students.
+
+#### Scenario: diagnostic session creates an initial study map
+
+- **GIVEN** a user chooses a target software role and technology stack
+- **WHEN** the user starts a diagnostic interview
+- **THEN** the system asks role-relevant technical questions
+- **AND** grades the user's answers against explicit rubrics
+- **AND** creates an initial concept weakness map.
+
+#### Scenario: practice session adapts to weak answers
+
+- **GIVEN** a user answers an interview question weakly or incorrectly
+- **WHEN** the tutoring workflow evaluates the answer
+- **THEN** the system asks a targeted follow-up question or gives a corrective
+  explanation
+- **AND** records the evidence used for that decision.
+
+### Requirement: Review plans are based on learner evidence
+
+The system SHALL generate review plans from graded answers, concept mastery, and
+misconception evidence rather than generic topic lists.
+
+#### Scenario: session produces next actions
+
+- **GIVEN** a completed tutoring session
+- **WHEN** the review-plan workflow runs
+- **THEN** the user receives prioritized concepts, practice questions, and
+  review timing
+- **AND** each recommendation links back to learning evidence.

openspec/changes/bootstrap-job-tutor-platform/specs/learner-memory/spec.md

@@ -0,0 +1,33 @@
+# learner-memory Specification
+
+## ADDED Requirements
+
+### Requirement: Durable learner memory is structured and evidence-backed
+
+The system SHALL store durable learner memory as structured learning state
+rather than an untyped RAG transcript.
+
+#### Scenario: answer grading updates concept mastery
+
+- **GIVEN** a user answers a technical interview question
+- **WHEN** the answer is graded
+- **THEN** the system may update concept mastery
+- **AND** the update includes the original answer or grading evidence.
+
+#### Scenario: repeated mistakes become misconceptions
+
+- **GIVEN** the same reasoning error appears across multiple answers
+- **WHEN** the memory extraction workflow runs
+- **THEN** the system records or strengthens a misconception entry
+- **AND** links it to the supporting answers.
+
+### Requirement: Temporary context does not become durable truth automatically
+
+The system SHALL separate session context from durable learner memory.
+
+#### Scenario: inferred memory requires evidence
+
+- **GIVEN** a tutor infers that a learner may misunderstand a concept
+- **WHEN** the inference lacks enough evidence
+- **THEN** the system records it as tentative or ignores it
+- **AND** does not promote it to durable mastery state as confirmed truth.

openspec/changes/bootstrap-job-tutor-platform/specs/learning-ontology/spec.md

@@ -0,0 +1,34 @@
+# learning-ontology Specification
+
+## ADDED Requirements
+
+### Requirement: Uploaded materials produce a source-backed ontology
+
+The system SHALL analyze uploaded learning materials into concepts,
+prerequisites, examples, questions, rubrics, and source evidence.
+
+#### Scenario: material ingestion creates ontology candidates
+
+- **GIVEN** an operator uploads learning materials
+- **WHEN** the ingestion workflow completes
+- **THEN** the system creates ontology candidate nodes and edges
+- **AND** links each supported candidate to source evidence.
+
+#### Scenario: gaps are identified separately from verified content
+
+- **GIVEN** the ontology builder detects a missing prerequisite or weakly
+  supported concept
+- **WHEN** it proposes missing content
+- **THEN** the proposed content is marked as generated or inferred
+- **AND** it is not treated as canonical until reviewed or validated.
+
+### Requirement: Generated study assets keep lineage
+
+The system SHALL preserve provenance for generated learning materials.
+
+#### Scenario: visual teaching asset is generated
+
+- **GIVEN** a concept needs a diagram or slide-like explanation
+- **WHEN** the asset generation workflow runs
+- **THEN** the generated asset stores its prompt, model configuration, source
+  concept, source evidence, and review state.

openspec/changes/bootstrap-job-tutor-platform/specs/learning-progression/spec.md

@@ -0,0 +1,63 @@
+# learning-progression Specification
+
+## ADDED Requirements
+
+### Requirement: Learning progression is evidence-backed and game-inspired
+
+The system SHALL use game-inspired progression loops to make study sessions
+rewarding while tying progress to learning evidence.
+
+#### Scenario: session loop ends with visible progress
+
+- **GIVEN** a user completes an interview-practice loop
+- **WHEN** the system grades the answer and extracts memory
+- **THEN** the user sees what improved, what remains weak, and the next
+  recommended challenge
+- **AND** any progress shown is linked to grading or memory evidence.
+
+#### Scenario: adaptive challenge stays near learner ability
+
+- **GIVEN** the learner repeatedly fails a concept at the current difficulty
+- **WHEN** the next challenge is selected
+- **THEN** the system lowers difficulty, changes explanation strategy, or inserts
+  a recovery question
+- **AND** does not simply continue escalating difficulty.
+
+### Requirement: Progression surfaces support interview readiness
+
+The system SHALL expose progression surfaces that help job seekers understand
+interview readiness.
+
+#### Scenario: readiness map summarizes concept state
+
+- **GIVEN** the learner has completed diagnostic or practice sessions
+- **WHEN** the readiness map is displayed
+- **THEN** each concept has a readiness state
+- **AND** the state can be traced to answer evidence, misconception evidence, or
+  review completion.
+
+#### Scenario: boss question unlocks after prerequisite stability
+
+- **GIVEN** a cluster of prerequisite concepts is stable enough
+- **WHEN** the user reaches the next milestone
+- **THEN** the system may unlock an integrated boss-style interview question
+- **AND** the question combines multiple concepts under realistic constraints.
+
+### Requirement: Engagement mechanics avoid exploitative patterns
+
+The system SHALL avoid engagement mechanics that encourage unhealthy compulsion
+or shame.
+
+#### Scenario: streaks do not punish missed days
+
+- **GIVEN** a user misses a scheduled practice day
+- **WHEN** the user returns
+- **THEN** the system helps the user resume with a recovery plan
+- **AND** does not erase durable learning progress.
+
+#### Scenario: rewards are connected to learning value
+
+- **GIVEN** the system awards progress, badges, unlocks, or generated assets
+- **WHEN** the reward is shown
+- **THEN** it reflects mastery, effort, review completion, or interview readiness
+- **AND** is not primarily a gambling-like random reward.

openspec/changes/bootstrap-job-tutor-platform/specs/tutor-workflows/spec.md

@@ -0,0 +1,49 @@
+# tutor-workflows Specification
+
+## ADDED Requirements
+
+### Requirement: Tutor behavior is workflow-driven
+
+The system SHALL express core tutor behavior as configurable workflows using
+`agent-farm-go` patterns internalized behind the Go backend boundary, with
+`third-one` as the LLM execution kernel.
+
+#### Scenario: grading workflow emits typed output
+
+- **GIVEN** a user answer and grading rubric
+- **WHEN** the grading workflow runs
+- **THEN** it emits a typed grading result
+- **AND** includes correctness, depth, communication clarity, evidence, and
+  follow-up recommendation fields.
+
+#### Scenario: memory extraction workflow emits typed candidates
+
+- **GIVEN** a graded interview answer
+- **WHEN** the memory extraction workflow runs
+- **THEN** it emits memory update candidates
+- **AND** each candidate identifies its evidence and confidence.
+
+### Requirement: Default LLM runtime is configurable
+
+The system SHALL keep the LLM model target configurable while defaulting the
+initial planning baseline to `deepseek-v4-flash`.
+
+#### Scenario: workflow invokes the default model
+
+- **GIVEN** no product override is configured
+- **WHEN** a tutor workflow invokes the LLM kernel
+- **THEN** the workflow uses the configured `deepseek-v4-flash` runtime target.
+
+### Requirement: Backend stack is Go
+
+The system SHALL use Go for the backend service so workflow orchestration,
+typed contracts, and learner state updates share one strongly typed service
+boundary.
+
+#### Scenario: workflow calls cross typed backend interfaces
+
+- **GIVEN** an API handler needs diagnostic, grading, memory extraction, or next
+  challenge behavior
+- **WHEN** it invokes the workflow layer
+- **THEN** it calls a typed Go interface
+- **AND** does not mutate product state by parsing freeform shell output.

openspec/changes/bootstrap-job-tutor-platform/tasks.md

@@ -0,0 +1,14 @@
+# Tasks
+
+- [x] 1. Create initial PRD for job-seeker-first tutoring.
+- [x] 2. Create initial architecture note for workflow, LLM, memory, ontology,
+  and visual assets.
+- [x] 3. Add OpenSpec capability specs for the first product baseline.
+- [x] 4. Incorporate game-design learning loop and progression planning.
+- [x] 5. Add repository engineering principles and code-size constraints.
+- [x] 6. Lock Go backend and internalized agent-farm workflow direction.
+- [ ] 7. Choose the first interview track and canonical concept seed list.
+- [ ] 8. Define typed JSON contracts for diagnostic, grading, memory extraction,
+  ontology gap detection, and asset prompt generation.
+- [ ] 9. Draft the first `agent-farm-go` YAML workflow package.
+- [x] 10. Validate the OpenSpec change.

openspec/config.yaml

@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours