tutor-service/AGENTS.md

AGENTS.md

Planning and Spec Source of Truth

When doing coding work in this repository, treat OpenSpec as the source of truth for product intent and requirements. Before implementation, read the relevant change, specs, and tasks under openspec/.

For medium or larger changes, multi-file changes, API/DTO/service-boundary changes, or architecture-impacting changes, update the touched OpenSpec surfaces after implementation.

Engineering Principles

Use these principles as default implementation constraints:

• Backend code is Go unless an OpenSpec change explicitly revisits the stack.
• agent-farm-go workflow patterns should be internalized behind typed backend interfaces, not treated as ad hoc shell scripts from request handlers.
• SOLID: keep responsibilities clear, dependencies explicit, and extension points narrow.
• KISS: choose the simplest design that satisfies the current requirement.
• YAGNI: do not add future-facing abstractions, services, queues, plugins, or configuration surfaces until there is a current need.
• Evidence-first: prefer tests, builds, smoke checks, and inspectable artifacts over claims.

File Size Rule

No source file should exceed 600 lines.

If a file approaches 600 lines, split it by responsibility before adding more behavior. Prefer small modules with explicit boundaries over large coordinator files. Generated files, lockfiles, vendored files, and external data snapshots are exempt, but should not be edited manually unless necessary.

Design Style

• Prefer small, cohesive functions and modules.
• Keep business rules close to the domain they describe.
• Keep workflow orchestration separate from low-level adapters.
• Keep learner memory, ontology, grading, progression, and asset generation as separate responsibilities.
• Prefer typed contracts for workflow inputs and outputs.
• Avoid broad helper packages that become dumping grounds.
• Avoid speculative generic frameworks.

Validation

After code changes, run the narrowest meaningful validation first, then broader checks when the touched surface justifies it.

For planning/spec-only changes, run:

openspec validate bootstrap-job-tutor-platform --strict

For Go backend changes, run:

gofmt -w cmd internal
go test ./...
openspec validate bootstrap-job-tutor-platform --strict

Before completing implementation work, confirm manually authored Go files stay at or below 600 lines.