AGENTS.md — TNSU Education Management Platform

Instructions for coding agents (Codex, Claude Code, Copilot, Gemini, etc.) working in this repo.

Start here

Read docs/agent/README.md before doing anything. It is the project knowledge base: what the project is, which file to read for which task, and which facts can be trusted.

Quick map:

Project status

Discovery and early design. Greenfield (no legacy system). No code or data model yet.

• Tech stack (decided, ADR-0001): Vue + Nuxt.js (SSR) frontend; Go backend on the Stream Framework (<https://api-docs.innovationstream.app/>, Fiber + GORM, module pattern Module → Controller → Service → Repository); RustFS (S3), Redis, Harbor, ArgoCD, Rancher, Kubernetes, OpenSearch + Dashboards (logs), Grafana (monitoring).
• Database: SQL Server (decided 2026-10-30; the customer already runs it). Queues therefore use RabbitMQ. See ADR-0001 for the SQL Server notes (Thai collation, JSON, temporal and ledger tables).
• Policy values (fees, refund rules, grading criteria, limits, retention) are configured by the university and by lecturers. Build them as configuration; never hard-code them.
• Anything else not in docs/adr/ is not decided. Propose it explicitly and record it as a new ADR.

Rules

• Sources: use cases (use_cases/) for behaviour; the BA draw.io file (TNSU_EDU *.drawio, rendered in docs/agent/ba-drawio.md) for functions per education level, the org structure, the curriculum list and BA flows; then the proposal; then the UI mockups.
• Proposal §5 and §7 have not been written for TNSU. They contain leftover template text from another project. Ignore it completely.
• docs/agent/use-cases/ and docs/agent/ba-drawio.md are generated. After use_cases/UC1-Explorer.dc.html or the BA's .drawio file changes, run python3 docs/agent/tools/gen_use_cases.py or python3 docs/agent/tools/gen_ba_drawio.py instead of editing them by hand.
• Keep Thai domain terms. UI copy is Thai. Years use the Buddhist Era (พ.ศ.; 2568 = 2025 CE), and semesters are written 1/2568.
• Reference by code: use cases W-49, UC modules REG/SCH, BA functions UNI-04.6/SS-07, proposal subsystems TNSU-05. Note that UC module SCH means scholarships and กยศ., while the sports-school BA branch is SS.
• When a decision is made or a requirement is clarified, update the relevant file in docs/agent/, including the open-questions list, so it is not left only in chat.

Progress tracking

tracker/ is the team's internal progress dashboard. It is not part of the TNSU EMS product. Keep its data current as you work (schema in tracker/README.md):

• At the start of every session, read the review results in tracker/data/milestones.json: tasks whose review.state is rejected or hold, and recent review.history entries. People submit these from the tracker's review form. Act on rejected items first (the decision says what to change), and report what you did in a checkpoint.

• Data is Milestone → Epic → Task. Milestone 0 is pre-project preparation; the real build will be Milestone 1, 2, 3, … once the team defines them. Put each task under the right epic.
• When you start a task, set it to in_progress in tracker/data/milestones.json and list its steps. Tick steps as you finish them.
• Record started and finished with the time in RFC 3339 (e.g. 2026-10-31T09:30:00+07:00), not just the date, so the Timeline hour view is accurate. For planned work, set start and due.
• When the work needs a person to check it, set review and fill review: reviewer, date, state: "todo", what to check, and a numbered checklist of what the reviewer must do (Markdown). Statuses: done means you finished and all tests pass; reviewed means a person approved it and is set only by the review form (never set it yourself).
• After each piece of work, add a checkpoint to tracker/data/checkpoints.json: what you did and why, the list of changes, task ids and files. Write it for people, not as a git log.
• Record test runs in tracker/data/tests.json grouped by topic, with each case written as a plain sentence and tagged for ba or tech. Record notable problems with their fix in tracker/data/problems.json.

Use-case approval before product implementation

Before implementing TNSU product behaviour from a W-xx use case, check the current status at tracker GET /api/use-cases/{W-id}/approval (default server http://localhost:8099). Proceed only when approved is true for the current source and diagram revision. A save, restore, or source change can invalidate an earlier approval; a historical approval record alone is insufficient. Keep source use cases authoritative and use the approved diagram as the reviewed workflow. If source and approved diagram disagree, resolve the discrepancy with the reviewer before product implementation.

Only a person using the review form should approve real use cases. Agents must never approve production/repository use cases on a person's behalf. Automated approval tests must use isolated temporary tracker data. This gate does not block discovery, documentation, or changes to the internal tracker itself. It is separate from task review in milestones.json.

Actionable task briefs

For planned tasks, include a goal/scope, checkable steps, deliverables and related task IDs. Where information is missing, add specific questions identifying the role who should answer and why. Record unknowns as open questions; label suggested owners as proposals. When answers arrive, retain question IDs and record respondent, time and source, then update the relevant domain document/ADR if a decision is confirmed. Do not change completed/reviewed task status or invent past execution/tests while adding historical context. See docs/agent/15-preparation-task-briefs.md.