109 lines
3.0 KiB
Markdown
109 lines
3.0 KiB
Markdown
|
# 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*
|