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

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

For future code changes, add project-specific build and test commands here once
the implementation stack is initialized.