# 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`](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: | Need | File | |---|---| | Use cases: actors, steps, business rules (W-1…W-163) | `docs/agent/12-use-cases.md`, then `docs/agent/use-cases/.md` | | Functions per education level (UNI-01…08, SS-01…15) | `docs/agent/03-modules.md` | | Role Matrix / Security Matrix (drafts) | `docs/agent/13-role-matrix.md`, `docs/agent/14-security-matrix.md` | | Tech stack and other decisions | `docs/adr/` (start with `0001-tech-stack.md`) | | Domain terms (Thai ↔ English) | `docs/agent/02-glossary.md` | | Roles and data access | `docs/agent/04-roles-and-access.md` | | What is unresolved | `docs/agent/11-open-questions-and-known-issues.md` | ## 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** (, 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`.