# 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*