tutor-service/.planning/phases/001-go-backend-foundation-and-workflow-boundary/001-PLAN.md

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:

go test ./...
openspec validate bootstrap-job-tutor-platform --strict

Also check manually authored source file length:

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