AGENTS.md

1# AGENTS.md
2 
3## Purpose
4 
5Universal operating rules for coding agents working on Conditions Translator.
6 
7This is the cross-agent source of truth for Codex, Cline-hosted models such as Z.AI, Copilot-compatible agents, and other repository-aware coding assistants.
8 
9Tool-specific instruction files may add workflow details but must not contradict this file.
10 
11---
12 
13## Non-Negotiable Rules
14 
15Every agent must:
16 
17- Read the project documentation before implementation.
18- Ask for clarification whenever the task, requirements, or next step is unclear.
19- Preserve the approved architecture unless an explicit architecture-change process is followed.
20- Never change the PRD.
21- Never bypass the `READY` Document requirement.
22- Never bypass ownership or authorization checks.
23- Never expose server secrets.
24- Never push or merge Git branches.
25- Create branches when the environment permits.
26- Make small, logical local commits when the environment permits.
27- Use PowerShell commands only.
28- Update `.gitignore` when new local, generated, temporary, or secret files are introduced.
29- Check current official documentation before installing or configuring dependencies whose setup may have changed.
30- Report limitations when the environment cannot perform Git, testing, file, or package operations.
31 
32---
33 
34## Instruction Precedence
35 
36This is the single canonical documentation authority hierarchy for the project. Other project documents must refer to this hierarchy rather than restating it.
37 
38Follow instructions in this order:
39 
401. Frozen PRD
412. Architecture Overview
423. Relevant subsystem specification
434. `AGENTS.md`
445. Tool-specific instructions such as `CLAUDE.md` or `.clinerules/`
456. Current task instructions
46 
47A current task may refine implementation details, but it may not silently override architecture, ownership, privacy, AI grounding, lifecycle states, retention, or security.
48 
49When sources conflict, the higher-authority source wins. Do not guess which source controls. Stop and ask for clarification.
50 
51---
52 
53## Required Reading Order
54 
55Before coding:
56 
571. `README.md`
582. `docs/01_MVP_PRD.md`
593. `docs/02_Architecture_Overview.md`
604. Relevant subsystem specification
615. `docs/08_Conditions_Translator_Implementation_Roadmap.md`
626. Relevant sections of the Launch Readiness Checklist, Coding Risk Register, and Testing Guide
63 
64Do not begin implementation until the applicable specification has been reviewed.
65 
66---
67 
68## Git Workflow
69 
70Create a dedicated branch for each phase, feature, test effort, bug fix, refactor, rework, documentation change, or chore.
71 
72Use these prefixes:
73 
74```text
75feat/
76fix/
77refactor/
78test/
79docs/
80chore/
81rework/
82build/
83ci/
84```
85 
86Examples:
87 
88```text
89feat/document-intake
90test/prisma-ownership
91fix/chat-session-expiry
92refactor/ocr-service
93docs/update-schema-spec
94chore/configure-eslint
95rework/account-transfer
96```
97 
98Agents may create local branches, make local commits, and inspect Git status/history.
99 
100Agents must not push, merge, force-push, delete remote branches, or merge pull requests.
101 
102The user handles pushing and GitHub merges.
103 
104If the environment cannot create branches or commits, report that clearly and provide the exact PowerShell commands the user should run.
105 
106---
107 
108## Commit Rules
109 
110Use small, coherent commits. Do not commit an entire phase or large feature as one oversized commit.
111 
112Use conventional prefixes:
113 
114```text
115feat:
116fix:
117refactor:
118test:
119docs:
120chore:
121build:
122ci:
123perf:
124style:
125revert:
126```
127 
128Commit messages must be descriptive, concise, understandable to another developer or employer, and focused on one coherent change.
129 
130A phase may contain many commits.
131 
132---
133 
134## PowerShell-Only Commands
135 
136All commands must be written for PowerShell.
137 
138Do not provide Bash syntax unless explicitly requested.
139 
140Examples:
141 
142```powershell
143npm install
144npm run dev
145npm run build
146npm run test
147npx prisma generate
148npx prisma migrate dev
149Copy-Item .env.example .env.local
150New-Item -ItemType Directory -Path .agent-memory -Force
151```
152 
153---
154 
155## Dependency and Official Documentation Checks
156 
157Before installing or configuring important dependencies:
158 
1591. Read the relevant project specification.
1602. Check current official documentation.
1613. Confirm the integration pattern is current.
1624. Explain any setup choice that differs from older examples.
1635. Avoid relying on outdated syntax.
1646. Record important setup decisions in session memory or the Decision Log.
165 
166This is especially important for Prisma, Next.js, authentication libraries, OpenAI SDK, Vercel Blob, Neon, testing frameworks, and build tooling.
167 
168---
169 
170## Architecture Invariants
171 
172Every agent must preserve:
173 
174- A Document is the central domain object.
175- Pages belong to exactly one Document.
176- A Document has exactly one owner: user or temporary session.
177- Only `READY` Documents are available to AI.
178- Accepted page text is the factual source of truth.
179- AI chat is temporary.
180- Full chat history is not permanent.
181- AI answers are grounded in selected `READY` Documents.
182- General AI knowledge must not fill supervision gaps.
183- Architecture changes require a separate Decision Log entry, affected documentation updates, and explicit approval before implementation.
184 
185---
186 
187## Package Scripts
188 
189Keep `package.json` scripts clear and easy to inspect.
190 
191Add scripts incrementally as functionality is implemented.
192 
193Suggested structure:
194 
195```json
196{
197  "scripts": {
198    "dev": "next dev",
199    "build": "next build",
200    "lint": "eslint .",
201    "typecheck": "tsc --noEmit",
202    "test": "vitest run",
203    "test:watch": "vitest",
204    "test:schema": "vitest run tests/schema",
205    "test:auth": "vitest run tests/auth",
206    "db:generate": "prisma generate",
207    "db:migrate": "prisma migrate dev",
208    "db:validate": "prisma validate"
209  }
210}
211```
212 
213Do not add duplicate or confusing scripts without a clear reason.
214 
215---
216 
217## Testing Expectations
218 
219Required for:
220 
221- schema and ORM changes
222- authentication
223- authorization and ownership
224- document lifecycle
225- deletion and cleanup
226- security-sensitive code
227- environment configuration
228- temporary session behavior
229 
230Strongly advised for:
231 
232- OCR
233- AI prompts
234- AI safety behavior
235- section generation
236- upload workflow
237- dashboard
238- multi-document chat
239 
240Optional for:
241 
242- documentation-only updates
243- styling-only changes
244- copy changes
245- non-functional refactors
246 
247Always report tests run, tests passed, tests failed, tests not run, and known gaps.
248 
249---
250 
251## UI Rules
252 
253- Mobile-first.
254- Must also work in desktop browsers.
255- Prioritize functional flows before polish.
256- Prefer one primary decision per screen where practical.
257- Use clear loading, empty, success, and error states.
258- Do not invent final styling or interaction patterns before wireframes exist.
259- Add basic wireframes when a flow needs validation.
260- Preserve readability, accessibility, and simple navigation.
261- Avoid overbuilding the visual system before core logic is stable.
262 
263---
264 
265## Clarification Rule
266 
267If an agent is unsure:
268 
269- stop
270- explain what is unclear
271- ask a focused clarification question
272- do not guess at architecture
273- do not invent requirements
274- do not proceed silently
275 
276---
277 
278## Shared Agent Memory
279 
280Use:
281 
282```text
283.agent-memory/
284  CURRENT_SESSION.md
285  DECISIONS.md
286  OPEN_QUESTIONS.md
287  WORK_LOG.md
288```
289 
290Required behavior:
291 
292- Read these files before resuming work.
293- Update `CURRENT_SESSION.md` during long sessions.
294- Record durable implementation decisions in `DECISIONS.md`.
295- Record unresolved issues in `OPEN_QUESTIONS.md`.
296- Add concise chronological notes to `WORK_LOG.md`.
297- Never store secrets, tokens, passwords, private document text, or sensitive user data.
298- Keep entries concise.
299 
300Recommended Git policy:
301 
302Local only:
303- `CURRENT_SESSION.md`
304- `WORK_LOG.md`
305 
306Potentially committed:
307- `DECISIONS.md`
308- `OPEN_QUESTIONS.md`
309 
310Claude-specific memory remains separate under `.claude/session-memory/`.
311 
312---
313 
314## Tool-Specific Files
315 
316Claude Code must also read `CLAUDE.md`.
317 
318Cline-hosted models, including Z.AI through Cline, must also follow `.clinerules/`.
319 
320A Copilot-specific bridge may exist at `.github/copilot-instructions.md` and must not contradict this file.
321 
322---
323 
324## Model Routing Guide
325 
326Use this table to decide which model to assign a task to. The current agent should
327flag a handoff recommendation in `OPEN_QUESTIONS.md` when the active task crosses
328into another model's strength zone.
329 
330| Task Type | Best Model | Why |
331|---|---|---|
332| Schema design, ownership logic, auth flow | Claude Opus 4.8 | Complex multi-file reasoning, fewer architectural mistakes |
333| API routes, Prisma queries, migrations, tests | Claude Sonnet 4.6 | Fast, reliable daily implementation driver |
334| React components, Tailwind UI, loading/empty states | GLM-4.7 (via Cline/Cerebras) | ~17x faster, strong UI output, lower cost |
335| Multi-file refactors, repo-wide sweep, PR review | OpenAI Codex | Parallel task execution across the whole codebase |
336| AI safety system prompt, grounding rules (Phase 6) | Claude Opus 4.8 | Critical correctness required |
337| Phase 1–2 foundation and config | Claude Sonnet 4.6 | Routine but must be exact |
338| Phase 3 document intake UI | GLM-4.7 | Fast React/Tailwind iteration |
339| Phase 7 ownership transfer (atomic) | Claude Opus 4.8 | High-risk, complex transactional logic |
340 
341### Handoff Signal
342 
343If you are mid-task and recognize the next logical step belongs to a different model,
344do not attempt it. Instead:
345 
3461. Complete your current atomic unit of work and commit it.
3472. Add a note to `OPEN_QUESTIONS.md`: `[MODEL SWITCH NEEDED] — suggest switching to <model> for <reason>`
3483. Report it in your Change Summary under "What should happen next?"
349 
350---
351 
352## Change Summary
353 
354For meaningful changes, report:
355 
3561. What changed?
3572. Why was it changed?
3583. Which specification guided the work?
3594. What assumptions were made?
3605. What tests were run?
3616. What remains untested?
3627. What should happen next?
3638. Which commits were created?
364 
365---
366 
367## Stop Conditions
368 
369Stop and ask before:
370 
371- changing architecture
372- changing the PRD
373- changing ownership behavior
374- changing lifecycle states
375- changing AI grounding rules
376- replacing a major framework or provider
377- introducing permanent chat storage
378- weakening authorization
379- changing data-retention behavior
380- installing a major dependency without checking current official documentation
381