diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index d0491df..a12872f 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -54,6 +54,7 @@ each short practice loop. - Workflow behavior should be configuration-first and inspired by `agent-farm-go`. - LLM execution should use `third-one`, defaulting to `deepseek-v4-flash`. +- The first interview track is Backend Developer Interview. - 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. @@ -79,6 +80,7 @@ each short practice loop. | 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 | +| Backend Developer Interview first track | Gives a broad but testable MVP concept set | Pending | --- -*Last updated: 2026-04-26 after Go backend and GSD planning direction were set.* +*Last updated: 2026-04-26 after first track and Phase 1 plan were set.* diff --git a/.planning/STATE.md b/.planning/STATE.md index d60d95c..f07bca9 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -19,18 +19,22 @@ interview-ready after each short practice loop. - 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. +- First interview track is Backend Developer Interview. +- Phase 1 has context, research, and plan artifacts. ## 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. +1. Execute Phase 1 Go backend foundation plan. +2. Keep `docs/planning/WORKFLOW_CONTRACTS.md` aligned with Go structs during + implementation. +3. After Phase 1, plan Phase 2 diagnostic interview loop. ## Validation Log - 2026-04-26: `openspec validate bootstrap-job-tutor-platform --strict` passed before GSD planning docs were created. +- 2026-04-26: First track, workflow contracts, and Phase 1 GSD plan were + created. --- *State initialized: 2026-04-26.* diff --git a/.planning/phases/001-go-backend-foundation-and-workflow-boundary/001-CONTEXT.md b/.planning/phases/001-go-backend-foundation-and-workflow-boundary/001-CONTEXT.md new file mode 100644 index 0000000..8b3e063 --- /dev/null +++ b/.planning/phases/001-go-backend-foundation-and-workflow-boundary/001-CONTEXT.md @@ -0,0 +1,93 @@ +# Phase 1: Go Backend Foundation and Workflow Boundary - Context + +**Gathered:** 2026-04-26 +**Status:** Ready for planning +**Source:** GSD continuation from product planning + + +## Phase Boundary + +Phase 1 establishes the Go backend foundation and the typed workflow boundary. +It does not need to implement the full tutoring loop. It should create the +minimal service skeleton that future phases can build on without violating the +600-line rule, SOLID/KISS/YAGNI, or OpenSpec. + + + + +## Implementation Decisions + +### Stack + +- Backend is Go. +- The first source package structure should separate app/bootstrap, HTTP + transport, config, workflow contracts, and domain placeholders. +- The implementation should not introduce a database, queue, UI, auth provider, + or image provider in Phase 1 unless needed for scaffold validation. + +### Workflow Boundary + +- `agent-farm-go` patterns are internalized behind typed Go interfaces. +- API/handler code must not shell out to workflow scripts directly. +- `third-one` / `deepseek-v4-flash` runtime selection belongs behind config and + workflow interfaces. +- Workflow result contracts should align with + `docs/planning/WORKFLOW_CONTRACTS.md`. + +### Engineering Constraints + +- No manually authored source file over 600 lines. +- SOLID, KISS, and YAGNI are active constraints. +- Keep learner memory, ontology, grading, progression, and assets separated as + future module boundaries. + + + + +## Canonical References + +Downstream agents MUST read these before planning or implementing. + +### Product and Requirements + +- `docs/planning/PRD.md` - product direction and MVP scope. +- `docs/planning/ARCHITECTURE.md` - Go backend and internalized workflow shape. +- `docs/planning/ENGINEERING.md` - implementation constraints. +- `.planning/REQUIREMENTS.md` - Phase 1 requirement IDs. +- `.planning/ROADMAP.md` - phase goal and success criteria. + +### Workflow Contracts and Specs + +- `docs/planning/WORKFLOW_CONTRACTS.md` - typed workflow contract plan. +- `openspec/changes/bootstrap-job-tutor-platform/specs/tutor-workflows/spec.md` + - workflow and Go backend requirements. +- `openspec/changes/bootstrap-job-tutor-platform/specs/engineering-quality/spec.md` + - code-size and design quality requirements. + + + + +## Specific Ideas + +- Start with a small Go module and one health endpoint or CLI smoke path. +- Add config structs for runtime/model keys without calling live providers yet. +- Add workflow interface definitions and stub implementations that return typed + errors or no-op evidence-safe results. +- Add tests for config loading and workflow interface behavior where practical. + + + + +## Deferred Ideas + +- Real diagnostic interview flow belongs to Phase 2. +- Persistent learner memory belongs to Phase 3. +- Progression/readiness map belongs to Phase 4. +- Ontology ingestion belongs to Phase 5. +- Image asset generation belongs to Phase 6. + + + +--- +*Phase: 001-go-backend-foundation-and-workflow-boundary* +*Context gathered: 2026-04-26* diff --git a/.planning/phases/001-go-backend-foundation-and-workflow-boundary/001-PLAN.md b/.planning/phases/001-go-backend-foundation-and-workflow-boundary/001-PLAN.md new file mode 100644 index 0000000..4e256e7 --- /dev/null +++ b/.planning/phases/001-go-backend-foundation-and-workflow-boundary/001-PLAN.md @@ -0,0 +1,108 @@ +# Phase 1 Plan: Go Backend Foundation and Workflow Boundary + +**Status:** Ready for execution +**Phase Goal:** Establish the Go service skeleton and typed workflow boundary +for internalized `agent-farm-go` patterns. + +## Scope + +This phase creates the backend foundation only. It should not implement the full +diagnostic interview loop, persistence, frontend, ontology ingestion, or image +generation. + +## Requirements Covered + +- 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. + +## Tasks + +### 1. Initialize Go backend scaffold + +- Create `go.mod`. +- Create `cmd/tutor-api/main.go`. +- Create minimal app assembly package under `internal/app`. +- Keep entrypoint thin and below 600 lines. + +### 2. Add configuration boundary + +- Add `internal/config`. +- Support app address, environment name, workflow runtime path, model key, and + third-one binary path as config fields. +- Default model key to `deepseek-v4-flash`. +- Avoid storing secrets in tracked files. + +### 3. Add typed workflow boundary + +- Add `internal/workflows`. +- Define minimal Go structs/interfaces for: + - `DiagnosticResult` + - `GradedAnswer` + - `MemoryUpdateCandidate` + - `NextChallenge` + - `ReadinessUpdate` +- Add a narrow runner interface that future internalized `agent-farm-go` + execution can satisfy. +- Do not call shell commands from HTTP handlers. + +### 4. Add HTTP smoke surface + +- Add `internal/httpapi`. +- Add health endpoint such as `GET /healthz`. +- Optionally expose config-safe runtime metadata, excluding secrets. + +### 5. Add validation tests + +- Test config defaults. +- Test health handler. +- Test workflow stub returns typed results or typed not-implemented errors. +- Verify no source file exceeds 600 lines. + +### 6. Update repo instructions + +- Add concrete Go build/test commands to `AGENTS.md`. +- Update OpenSpec/GSD state if implementation changes scope. + +## Verification + +Run: + +```powershell +go test ./... +openspec validate bootstrap-job-tutor-platform --strict +``` + +Also check manually authored source file length: + +```powershell +Get-ChildItem -Recurse -File *.go | ForEach-Object { + $lines = (Get-Content -LiteralPath $_.FullName | Measure-Object -Line).Lines + if ($lines -gt 600) { throw "$($_.FullName) has $lines lines" } +} +``` + +## Out of Scope + +- Database schema. +- Authentication. +- Real LLM calls. +- Live `third-one` execution. +- Frontend. +- Material ingestion. +- Image generation. + +## Plan Quality Check + +- Goal-backward fit: each task supports Go scaffold or typed workflow boundary. +- KISS/YAGNI: no database, queue, provider SDK, or full workflow engine in this + phase. +- SOLID: app, config, HTTP, and workflow responsibilities are separated. +- Evidence: build/tests/OpenSpec/file-length checks prove the phase. + +--- +*Plan created: 2026-04-26* diff --git a/.planning/phases/001-go-backend-foundation-and-workflow-boundary/001-RESEARCH.md b/.planning/phases/001-go-backend-foundation-and-workflow-boundary/001-RESEARCH.md new file mode 100644 index 0000000..8f5c7de --- /dev/null +++ b/.planning/phases/001-go-backend-foundation-and-workflow-boundary/001-RESEARCH.md @@ -0,0 +1,69 @@ +# Phase 1 Research + +## Question + +How should the first Go backend scaffold be shaped so it can internalize +`agent-farm-go` workflow patterns without overbuilding? + +## Findings + +### Keep the first backend narrow + +Phase 1 should prove structure, contracts, and validation, not product behavior. +The safest first slice is: + +- `cmd/tutor-api` entrypoint +- internal config package +- internal HTTP/app package +- internal workflow contract package +- small health or version endpoint +- tests for config and workflow boundary behavior + +### Prefer typed interfaces over runtime coupling + +The backend should expose a `WorkflowRunner` style interface that future phases +can implement using internalized `agent-farm-go` execution. Phase 1 can use +stub/no-op implementations as long as the interface boundaries and contracts are +clear. + +### Avoid premature infrastructure + +Do not add Postgres, migrations, queues, auth, frontend, or image generation in +Phase 1. Those are real needs later, but adding them before the backend boundary +exists would violate KISS/YAGNI. + +### Module boundary recommendation + +Initial Go package boundaries: + +- `internal/app`: service assembly and dependency wiring +- `internal/config`: environment/runtime config +- `internal/httpapi`: HTTP routing and handlers +- `internal/workflows`: workflow interfaces and typed contracts +- `internal/version`: version/build metadata if needed + +Future packages can be added when their phase arrives: + +- `internal/interview` +- `internal/learner_memory` +- `internal/progression` +- `internal/ontology` +- `internal/assets` + +## Risks + +- Making workflow interfaces too generic creates a framework before use. +- Putting typed contracts in HTTP handlers will make future phases hard to + isolate. +- Shelling out from handlers would contradict the internalized workflow decision. + +## Recommendation + +Plan Phase 1 as a scaffold and boundary proof: + +1. Create Go module and package skeleton. +2. Add config for app address and workflow runtime keys. +3. Add typed workflow contracts from the planning document in minimal Go form. +4. Add a stub workflow runner. +5. Add health endpoint and tests. +6. Document build/test commands in `AGENTS.md`. diff --git a/docs/planning/ARCHITECTURE.md b/docs/planning/ARCHITECTURE.md index 481f739..96a046a 100644 --- a/docs/planning/ARCHITECTURE.md +++ b/docs/planning/ARCHITECTURE.md @@ -58,6 +58,9 @@ Implementation should follow the engineering rules in SOLID responsibility boundaries, KISS implementation choices, and YAGNI for future-only abstractions. +Initial typed workflow contracts are defined in +`docs/planning/WORKFLOW_CONTRACTS.md`. + Initial workflow set: - `diagnose_job_seeker` @@ -91,6 +94,9 @@ Core progression surfaces: - strong-answer portfolio - interview-date campaign plan +The first progression track is the backend developer interview seed list in +`docs/planning/INTERVIEW_TRACKS.md`. + Progression decisions should read from learner memory and grading evidence. They should be exposed as workflow outputs so the service can explain why a question, reward, or unlock appeared. diff --git a/docs/planning/INTERVIEW_TRACKS.md b/docs/planning/INTERVIEW_TRACKS.md new file mode 100644 index 0000000..41aa828 --- /dev/null +++ b/docs/planning/INTERVIEW_TRACKS.md @@ -0,0 +1,112 @@ +# Interview Tracks + +## MVP Track: Backend Developer Interview + +The first interview track is backend developer preparation. This track is broad +enough to be valuable to job seekers and narrow enough to produce testable +diagnostic, grading, memory, and progression behavior. + +## Target User + +- Junior backend developer candidates. +- Bootcamp graduates preparing for backend interviews. +- Full-stack developers who need backend interview readiness. +- Developers changing stack into backend service work. + +## Canonical Concept Seed List + +### 1. HTTP and Web Fundamentals + +- request and response lifecycle +- headers, status codes, methods +- idempotency and safe methods +- cookies, sessions, tokens +- latency, timeout, retry basics + +### 2. REST and API Design + +- resource modeling +- endpoint shape +- validation and error responses +- pagination and filtering +- versioning +- backward compatibility + +### 3. Databases and Indexes + +- relational modeling +- primary keys and foreign keys +- index purpose and tradeoffs +- query plans at a conceptual level +- N+1 query problem +- migrations + +### 4. Transactions and Consistency + +- ACID +- isolation anomalies +- transaction boundaries +- optimistic vs pessimistic locking +- idempotent writes +- eventual consistency basics + +### 5. Caching + +- cache-aside +- TTL and invalidation +- stale data risks +- cache stampede +- CDN vs application cache +- when not to cache + +### 6. Concurrency and Async Work + +- race conditions +- locks and coordination +- worker queues +- retry and dead-letter basics +- backpressure +- Go goroutine/channel concepts for Go-oriented tracks + +### 7. Testing and Reliability + +- unit vs integration tests +- test doubles +- contract tests +- observability basics +- logging and metrics +- failure-mode thinking + +### 8. System Design Basics + +- load balancing +- horizontal scaling +- stateless service design +- database bottlenecks +- rate limiting +- file/object storage +- basic architecture tradeoffs + +## Challenge Ladder + +Each concept should support five levels: + +1. Define the concept. +2. Explain tradeoffs. +3. Debug a realistic scenario. +4. Design under constraints. +5. Answer under interview pressure. + +## First Boss Question + +"Design a rate-limited backend API for submitting job applications. Cover HTTP +API design, database transaction boundaries, duplicate submission prevention, +cache behavior, failure handling, and test strategy." + +## MVP Exclusions + +- Advanced distributed systems theory. +- Deep database internals. +- Language-specific trivia-heavy questions. +- Company-specific interview packs. +- Frontend, mobile, AI, and DevOps tracks. diff --git a/docs/planning/PRD.md b/docs/planning/PRD.md index c04d5c6..b5ebeb2 100644 --- a/docs/planning/PRD.md +++ b/docs/planning/PRD.md @@ -85,12 +85,13 @@ The first MVP should prove one loop: 7. User sees visible readiness progress, next unlocks, and a recommended next challenge. -Recommended first track: +First track: - Backend developer interview preparation. -- Topics: HTTP, REST, databases, transactions, caching, concurrency, testing, - system design basics, Go or JavaScript/TypeScript depending on first content - corpus. +- Topics: HTTP and web fundamentals, REST/API design, databases and indexes, + transactions and consistency, caching, concurrency/async work, testing and + reliability, and system design basics. +- Canonical seed list: `docs/planning/INTERVIEW_TRACKS.md`. ## Core User Flows @@ -183,6 +184,8 @@ the configured image generation provider. configuration. - Workflow outputs SHALL prefer typed JSON contracts for grading, memory extraction, ontology updates, and review-plan generation. +- Initial workflow contract plan SHALL follow + `docs/planning/WORKFLOW_CONTRACTS.md`. ### Visual teaching assets diff --git a/docs/planning/WORKFLOW_CONTRACTS.md b/docs/planning/WORKFLOW_CONTRACTS.md new file mode 100644 index 0000000..98877ac --- /dev/null +++ b/docs/planning/WORKFLOW_CONTRACTS.md @@ -0,0 +1,200 @@ +# Workflow Contracts + +## Purpose + +LLM workflow outputs that affect product state must be typed and inspectable. +The Go backend should call internalized workflow interfaces and then persist +validated results. Product state must not depend on parsing arbitrary prose. + +These contracts are initial planning contracts. Field names may evolve during +implementation, but the responsibilities should remain stable. + +## Shared Types + +```json +{ + "evidence_ref": { + "kind": "answer|grading|source|session|asset", + "id": "string", + "quote": "string", + "confidence": 0.0 + } +} +``` + +```json +{ + "concept_ref": { + "id": "string", + "label": "string", + "track": "backend-developer" + } +} +``` + +## DiagnosticResult + +Produced by `diagnose_job_seeker`. + +```json +{ + "user_id": "string", + "track": "backend-developer", + "target_role": "junior-backend-developer", + "stack": ["go", "postgres"], + "initial_readiness": "unknown|fragile|improving|interview_ready|strong_signal", + "concept_findings": [ + { + "concept": "concept_ref", + "readiness": "unknown|fragile|improving|interview_ready|strong_signal", + "reason": "string", + "evidence": ["evidence_ref"] + } + ], + "recommended_next_concepts": ["concept_ref"] +} +``` + +## GradedAnswer + +Produced by `grade_interview_answer`. + +```json +{ + "answer_id": "string", + "question_id": "string", + "concepts": ["concept_ref"], + "scores": { + "correctness": 0, + "depth": 0, + "communication": 0, + "production_judgment": 0 + }, + "overall": "miss|partial|solid|strong", + "strengths": ["string"], + "gaps": ["string"], + "misconception_candidates": [ + { + "label": "string", + "description": "string", + "evidence": ["evidence_ref"], + "confidence": 0.0 + } + ], + "follow_up": { + "needed": true, + "question": "string", + "purpose": "clarify|repair|stretch|pressure_test" + } +} +``` + +## MemoryUpdateCandidate + +Produced by `extract_learning_memory`. + +```json +{ + "user_id": "string", + "source_answer_id": "string", + "updates": [ + { + "kind": "concept_mastery|misconception|intervention|review_schedule", + "concept": "concept_ref", + "proposed_state": "unknown|fragile|improving|interview_ready|strong_signal", + "summary": "string", + "evidence": ["evidence_ref"], + "confidence": 0.0, + "durability": "tentative|confirmed" + } + ] +} +``` + +## NextChallenge + +Produced by `select_next_challenge`. + +```json +{ + "user_id": "string", + "track": "backend-developer", + "concept": "concept_ref", + "ladder_level": "define|tradeoffs|debug|design_constraints|interview_pressure", + "question": "string", + "rationale": "string", + "difficulty_action": "lower|hold|raise|recover", + "evidence": ["evidence_ref"] +} +``` + +## ReadinessUpdate + +Produced by `update_readiness_map`. + +```json +{ + "user_id": "string", + "track": "backend-developer", + "concept_updates": [ + { + "concept": "concept_ref", + "previous": "unknown|fragile|improving|interview_ready|strong_signal", + "next": "unknown|fragile|improving|interview_ready|strong_signal", + "reason": "string", + "evidence": ["evidence_ref"] + } + ], + "unlocks": [ + { + "kind": "boss_question|review_card|portfolio_entry", + "label": "string", + "reason": "string" + } + ] +} +``` + +## OntologyGap + +Produced by `detect_ontology_gaps`. + +```json +{ + "track": "backend-developer", + "missing_or_weak": [ + { + "concept": "concept_ref", + "gap_type": "missing_prerequisite|weak_evidence|outdated|needs_rubric", + "reason": "string", + "supporting_sources": ["evidence_ref"], + "proposed_action": "generate_candidate|request_source|human_review" + } + ] +} +``` + +## TeachingAssetPrompt + +Produced by `generate_teaching_asset_prompt`. + +```json +{ + "concept": "concept_ref", + "asset_type": "diagram|lesson_slice|worksheet|interview_card", + "prompt": "string", + "source_evidence": ["evidence_ref"], + "model_key": "gpt-image-v2", + "requires_model_id_verification": true, + "review_state": "candidate" +} +``` + +## Validation Rules + +- Required IDs must be non-empty. +- Any state-changing output must include evidence. +- Confidence values must be between 0 and 1. +- Generated or inferred content starts as `candidate` or `tentative`. +- `model_key` is a product config key; production code must verify the actual + provider model identifier before image calls. diff --git a/openspec/changes/bootstrap-job-tutor-platform/specs/job-seeker-tutor/spec.md b/openspec/changes/bootstrap-job-tutor-platform/specs/job-seeker-tutor/spec.md index c6ee3e5..b13e857 100644 --- a/openspec/changes/bootstrap-job-tutor-platform/specs/job-seeker-tutor/spec.md +++ b/openspec/changes/bootstrap-job-tutor-platform/specs/job-seeker-tutor/spec.md @@ -15,6 +15,14 @@ while preserving an architecture that can later support general students. - **AND** grades the user's answers against explicit rubrics - **AND** creates an initial concept weakness map. +#### Scenario: backend developer track is the first canonical track + +- **GIVEN** the MVP track catalog is initialized +- **WHEN** the system loads the first interview track +- **THEN** it provides the Backend Developer Interview track +- **AND** includes HTTP, REST/API design, databases, transactions, caching, + concurrency, testing, and system design basics as seed concept clusters. + #### Scenario: practice session adapts to weak answers - **GIVEN** a user answers an interview question weakly or incorrectly diff --git a/openspec/changes/bootstrap-job-tutor-platform/specs/tutor-workflows/spec.md b/openspec/changes/bootstrap-job-tutor-platform/specs/tutor-workflows/spec.md index 5e60123..a7060a7 100644 --- a/openspec/changes/bootstrap-job-tutor-platform/specs/tutor-workflows/spec.md +++ b/openspec/changes/bootstrap-job-tutor-platform/specs/tutor-workflows/spec.md @@ -23,6 +23,15 @@ The system SHALL express core tutor behavior as configurable workflows using - **THEN** it emits memory update candidates - **AND** each candidate identifies its evidence and confidence. +#### Scenario: initial contract set is available for backend planning + +- **GIVEN** the backend workflow boundary is planned +- **WHEN** implementation begins +- **THEN** the initial contract set includes DiagnosticResult, GradedAnswer, + MemoryUpdateCandidate, NextChallenge, ReadinessUpdate, OntologyGap, and + TeachingAssetPrompt +- **AND** each state-changing contract carries evidence references. + ### Requirement: Default LLM runtime is configurable The system SHALL keep the LLM model target configurable while defaulting the diff --git a/openspec/changes/bootstrap-job-tutor-platform/tasks.md b/openspec/changes/bootstrap-job-tutor-platform/tasks.md index 7abca1f..52b046b 100644 --- a/openspec/changes/bootstrap-job-tutor-platform/tasks.md +++ b/openspec/changes/bootstrap-job-tutor-platform/tasks.md @@ -7,8 +7,9 @@ - [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, +- [x] 7. Choose the first interview track and canonical concept seed list. +- [x] 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. +- [x] 9. Create Phase 1 GSD context, research, and plan artifacts. +- [ ] 10. Draft the first `agent-farm-go` YAML workflow package. +- [x] 11. Validate the OpenSpec change.