Two files, one repository
summer-marie/conditions-translator ships 3 formats across 3 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 1 | 19 | 18 | 3% |
| Commands | 6 | 0 | 3 | 67% |
| Section tags | 11 | 0 | 0 | 100% |
What each file covers
Sections
1 shared · 19 only in A · 18 only in B- − AGENTS.md
- − Non-Negotiable Rules
- − Instruction Precedence
- − Required Reading Order
- − Git Workflow
- − Commit Rules
- − PowerShell-Only Commands
- − Dependency and Official Documentation Checks
- − Architecture Invariants
- − Package Scripts
- − Testing Expectations
- − UI Rules
- − Clarification Rule
- − Shared Agent Memory
- − Tool-Specific Files
- − Model Routing Guide
- − Handoff Signal
- − Change Summary
- − Stop Conditions
- + CLAUDE.md
- + 1. Non-Negotiable Rules
- + 2. Required Reading Order
- + 3. Git Workflow
- + Branches
- + Staging Discipline
- + 4. Commit Rules
- + 5. PowerShell-Only Commands
- + 6. Dependency and Documentation Checks
- + 7. Architecture Boundaries
- + 8. Package Scripts
- + 9. Testing Expectations
- + 10. UI Rules
- + 11. Clarification Rule
- + 12. Local Session Memory
- + Session continuity and working memory
- + 13. AI Change Summary
- + 14. Stop Conditions
- Purpose
Commands
6 shared · 0 only in A · 3 only in B- + git add <file> <file> ...
- + git add -A
- + git add .
- npm install
- npm run dev
- npm run build
- npm run test
- npx prisma generate
- npx prisma migrate dev
Section tags
11 shared · 0 only in A · 0 only in B- setup
- build
- test
- lint-format
- code-style
- git-pr
- ui
- performance
- do-not
- agent-behaviour
- docs
Line diff
summer-marie/conditions-translator · AGENTS.md
@@ −1 @@
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`
@@ −59 @@
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
@@ −95 @@
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
@@ −125 @@
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
@@ −147 @@
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
@@ −161 @@
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
@@ −210 @@
210}
211```
212
213Do not add duplicate or confusing scripts without a clear reason.
214
215---
216
217## Testing Expectations
218
219Required for:
220
@@ −225 @@
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.
@@ −262 @@
262
263---
264
265## Clarification Rule
266
267If an agent is unsure:
268
269- stop
270- explain what is unclear
@@ −273 @@
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?
@@ −360 @@
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
summer-marie/conditions-translator · CLAUDE.md
@@ +1 @@
1# CLAUDE.md
2
3## Purpose
4
5This file defines how Claude Code should work on the Conditions Translator project.
6
7Keep this file concise. Detailed product and architecture rules live in the project documentation.
8
9---
10
11# 1. Non-Negotiable Rules
12
13Claude must:
14
15- Read the project documentation before implementation.
16- Ask for clarification whenever the task, requirements, or next step is unclear.
17- Preserve the approved architecture unless an explicit architecture-change process is followed.
18- Never change the PRD.
19- Never bypass the `READY` document requirement.
20- Never bypass ownership or authorization checks.
21- Never expose server secrets.
22- Never push or merge Git branches.
23- Make all local commits.
24- Use PowerShell commands only.
25- Update `.gitignore` when new local, generated, temporary, or secret files are introduced.
26- Keep commits small, logical, and descriptive.
27- Check current official documentation before installing or configuring dependencies whose setup may have changed.
28
29---
30
31# 2. Required Reading Order
32
33Before coding:
34
351. `README.md`
@@ +37 @@
373. `docs/02_Architecture_Overview.md`
384. Relevant subsystem specification
395. `docs/08_Conditions_Translator_Implementation_Roadmap.md`
406. Relevant risk and launch-readiness sections
41
42Do not start implementation until the applicable specification has been reviewed.
43
44---
45
46# 3. Git Workflow
47
48## Branches
49
50Create a dedicated branch for each:
51
52- phase
53- feature
54- test effort
55- bug fix
56- refactor
57- rework
58- documentation change
59- chore
60
61Use these prefixes:
62
63```text
@@ +84 @@
84rework/account-transfer
85```
86
87Claude may create branches and make local commits.
88
89Claude must not:
90
91- push branches
92- merge branches
93- open or merge pull requests without explicit instruction
94
95The user will push and merge through GitHub.
96
97## Staging Discipline
98
99- Stage files individually by name (`git add <file> <file> ...`). Never use `git add -A` or `git add .`.
100- Only stage files that are actually in scope for the current task.
101- After each commit, report which touched files were included and which untracked/modified files were deliberately left out, so leftover changes in the working tree are never mistaken for a staging failure.
102
103---
104
105# 4. Commit Rules
106
107Use small, coherent commits.
108
109Do not commit an entire phase or large feature as one oversized commit.
110
111Use conventional prefixes:
112
113```text
@@ +124 @@
124revert:
125```
126
127Examples:
128
129```text
130feat: add temporary document creation flow
131test: cover exclusive document ownership constraints
132fix: prevent expired sessions from loading documents
133refactor: separate OCR validation from provider client
134docs: update account ownership specification
135chore: ignore generated local files
136```
137
138Commit messages must be:
139
140- descriptive
141- concise
142- understandable to another developer or employer
143- focused on one coherent change
144
145A phase may contain many commits.
146
147---
148
149# 5. PowerShell-Only Commands
150
151All commands must be written for PowerShell.
152
153Do not provide Bash syntax unless explicitly requested.
154
155Use PowerShell for:
156
157- package installation
158- file creation
159- directory creation
160- environment setup
161- testing
162- database commands
163- Git commands
164- local development
165- build commands
166- cleanup
167
168Examples:
169
170```powershell
@@ +175 @@
175npx prisma generate
176npx prisma migrate dev
177Copy-Item .env.example .env.local
178New-Item -ItemType Directory -Path .claude\session-memory -Force
179```
180
181---
182
183# 6. Dependency and Documentation Checks
184
185Before installing or configuring important dependencies:
186
@@ +189 @@
1893. Confirm the integration pattern is current.
1904. Explain any setup choice that differs from older examples.
1915. Avoid relying on outdated syntax.
192
193This is especially important for:
194
195- Prisma
196- Next.js
197- authentication libraries
198- OpenAI SDK
199- Vercel Blob
200- Neon
201- testing frameworks
202- build tooling
203
204Do not install a dependency based only on memory when current setup details may have changed.
205
206---
207
208# 7. Architecture Boundaries
209
210Claude must preserve these invariants:
211
212- A Document is the central domain object.
213- Pages belong to exactly one Document.
214- A Document has exactly one owner:
215 - user
216 - or temporary session
217- Only `READY` Documents are available to AI.
218- Accepted page text is the factual source of truth.
219- AI chat is temporary.
220- Full chat history is not permanent.
221- AI answers are grounded in selected READY Documents.
222- General AI knowledge must not fill supervision gaps.
223- Architecture changes require a separate Decision Log entry and explicit approval.
224
225---
226
227# 8. Package Scripts
228
229Keep `package.json` scripts clear and easy to inspect.
230
@@ +250 @@
250}
251```
252
253Do not add scripts that duplicate existing behavior without a clear reason.
254
255---
256
257# 9. Testing Expectations
258
259Required for:
260
@@ +265 @@
265- deletion and cleanup
266- security-sensitive code
267- environment configuration
268- temporary sessions
269
270Strongly advised for:
271
272- OCR
273- AI prompts
274- safety behavior
275- section generation
276- uploads
277- dashboard
278- multi-document chat
279
280Optional for:
281
282- documentation-only changes
283- styling-only changes
284- copy changes
285- non-functional refactors
286
287Always report:
288
289- tests run
290- tests passed
291- tests failed
292- tests not run
293- known gaps
294
295---
296
297# 10. UI Rules
298
299Current UI guidance is intentionally limited.
300
301- Mobile-first.
302- Must also work in desktop browsers.
303- Prioritize functional flows before polish.
@@ +310 @@
310
311---
312
313# 11. Clarification Rule
314
315If Claude is unsure:
316
317- stop
318- explain what is unclear
@@ +321 @@
321- do not invent requirements
322- do not proceed silently
323
324This applies to:
325
326- unclear requirements
327- conflicting documents
328- uncertain implementation direction
329- missing dependencies
330- ambiguous acceptance criteria
331- unclear test expectations
332
333---
334
335# 12. Local Session Memory
336
337## Session continuity and working memory
338
339Before starting or continuing any non-trivial task, Claude should review available local session-memory files (if present) and update them when useful.
340
341Use session memory to:
342- capture the task being worked on
343- record important context, assumptions, and constraints
344- note open questions, risks, or follow-up items
345- preserve handoff context if the session may be interrupted or hit context limits
346
347Guidelines:
348- Keep memory notes short, factual, and useful for future continuation
349- Update memory before or during meaningful work when the task involves debugging,
350 behavior changes, architecture decisions, environment/configuration changes,
351 multi-file edits, or unresolved questions
352- Prefer updating local gitignored memory files rather than creating extra repo docs
353 unless the information belongs in project documentation
354- Do not commit local session-memory files unless explicitly told to do so
355
356Use local memory files for long sessions and context handoff.
357
358Repository location:
359
360```text
361.claude/
362 session-memory/
363 CURRENT_SESSION.md
364 DECISIONS.md
365 OPEN_QUESTIONS.md
366 WORK_LOG.md
367```
368
369Required behavior:
370
371- Read these files before resuming work in a new session.
372- Update `CURRENT_SESSION.md` during long sessions.
373- Record durable decisions in `DECISIONS.md`.
374- Record unresolved issues in `OPEN_QUESTIONS.md`.
375- Add concise chronological notes to `WORK_LOG.md`.
376- Never store secrets, tokens, passwords, private document text, or sensitive user data.
377- Keep entries concise.
378- Update `.gitignore` based on whether each file should remain local or be committed.
379
380Recommended policy:
381
382Local only:
383- `CURRENT_SESSION.md`
384- `WORK_LOG.md`
385
386May be committed when project-relevant:
387- `DECISIONS.md`
388- `OPEN_QUESTIONS.md`
389
390---
391
392# 13. AI Change Summary
393
394For meaningful changes, report:
395
3961. What changed?
@@ +400 @@
4005. What tests were run?
4016. What remains untested?
4027. What should happen next?
403
404---
405
406# 14. Stop Conditions
407
408Stop and ask before:
409
410- changing architecture
411- changing the PRD
412- changing ownership behavior
413- changing document lifecycle states
414- changing AI grounding rules
415- replacing a major framework or provider
416- introducing permanent chat storage
@@ −1 +1 @@
1−# AGENTS.md
1+# CLAUDE.md
22
33 ## Purpose
44
5−Universal operating rules for coding agents working on Conditions Translator.
5+This file defines how Claude Code should work on the Conditions Translator project.
66
7−This 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.
7+Keep this file concise. Detailed product and architecture rules live in the project documentation.
88
9−Tool-specific instruction files may add workflow details but must not contradict this file.
10−
119 ---
1210
13−## Non-Negotiable Rules
11+# 1. Non-Negotiable Rules
1412
15−Every agent must:
13+Claude must:
1614
1715 - Read the project documentation before implementation.
1816 - Ask for clarification whenever the task, requirements, or next step is unclear.
1917 - Preserve the approved architecture unless an explicit architecture-change process is followed.
2018 - Never change the PRD.
21−- Never bypass the `READY` Document requirement.
19+- Never bypass the `READY` document requirement.
2220 - Never bypass ownership or authorization checks.
2321 - Never expose server secrets.
2422 - Never push or merge Git branches.
25−- Create branches when the environment permits.
26−- Make small, logical local commits when the environment permits.
23+- Make all local commits.
2724 - Use PowerShell commands only.
2825 - Update `.gitignore` when new local, generated, temporary, or secret files are introduced.
26+- Keep commits small, logical, and descriptive.
2927 - 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.
3128
3229 ---
3330
34−## Instruction Precedence
31+# 2. Required Reading Order
3532
36−This is the single canonical documentation authority hierarchy for the project. Other project documents must refer to this hierarchy rather than restating it.
37−
38−Follow instructions in this order:
39−
40−1. Frozen PRD
41−2. Architecture Overview
42−3. Relevant subsystem specification
43−4. `AGENTS.md`
44−5. Tool-specific instructions such as `CLAUDE.md` or `.clinerules/`
45−6. Current task instructions
46−
47−A current task may refine implementation details, but it may not silently override architecture, ownership, privacy, AI grounding, lifecycle states, retention, or security.
48−
49−When 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−
5533 Before coding:
5634
5735 1. `README.md`
@@ −59 +37 @@
5937 3. `docs/02_Architecture_Overview.md`
6038 4. Relevant subsystem specification
6139 5. `docs/08_Conditions_Translator_Implementation_Roadmap.md`
62−6. Relevant sections of the Launch Readiness Checklist, Coding Risk Register, and Testing Guide
40+6. Relevant risk and launch-readiness sections
6341
64−Do not begin implementation until the applicable specification has been reviewed.
42+Do not start implementation until the applicable specification has been reviewed.
6543
6644 ---
6745
68−## Git Workflow
46+# 3. Git Workflow
6947
70−Create a dedicated branch for each phase, feature, test effort, bug fix, refactor, rework, documentation change, or chore.
48+## Branches
7149
50+Create a dedicated branch for each:
51+
52+- phase
53+- feature
54+- test effort
55+- bug fix
56+- refactor
57+- rework
58+- documentation change
59+- chore
60+
7261 Use these prefixes:
7362
7463 ```text
@@ −95 +84 @@
9584 rework/account-transfer
9685 ```
9786
98−Agents may create local branches, make local commits, and inspect Git status/history.
87+Claude may create branches and make local commits.
9988
100−Agents must not push, merge, force-push, delete remote branches, or merge pull requests.
89+Claude must not:
10190
102−The user handles pushing and GitHub merges.
91+- push branches
92+- merge branches
93+- open or merge pull requests without explicit instruction
10394
104−If the environment cannot create branches or commits, report that clearly and provide the exact PowerShell commands the user should run.
95+The user will push and merge through GitHub.
10596
97+## Staging Discipline
98+
99+- Stage files individually by name (`git add <file> <file> ...`). Never use `git add -A` or `git add .`.
100+- Only stage files that are actually in scope for the current task.
101+- After each commit, report which touched files were included and which untracked/modified files were deliberately left out, so leftover changes in the working tree are never mistaken for a staging failure.
102+
106103 ---
107104
108−## Commit Rules
105+# 4. Commit Rules
109106
110−Use small, coherent commits. Do not commit an entire phase or large feature as one oversized commit.
107+Use small, coherent commits.
111108
109+Do not commit an entire phase or large feature as one oversized commit.
110+
112111 Use conventional prefixes:
113112
114113 ```text
@@ −125 +124 @@
125124 revert:
126125 ```
127126
128−Commit messages must be descriptive, concise, understandable to another developer or employer, and focused on one coherent change.
127+Examples:
129128
129+```text
130+feat: add temporary document creation flow
131+test: cover exclusive document ownership constraints
132+fix: prevent expired sessions from loading documents
133+refactor: separate OCR validation from provider client
134+docs: update account ownership specification
135+chore: ignore generated local files
136+```
137+
138+Commit messages must be:
139+
140+- descriptive
141+- concise
142+- understandable to another developer or employer
143+- focused on one coherent change
144+
130145 A phase may contain many commits.
131146
132147 ---
133148
134−## PowerShell-Only Commands
149+# 5. PowerShell-Only Commands
135150
136151 All commands must be written for PowerShell.
137152
138153 Do not provide Bash syntax unless explicitly requested.
139154
155+Use PowerShell for:
156+
157+- package installation
158+- file creation
159+- directory creation
160+- environment setup
161+- testing
162+- database commands
163+- Git commands
164+- local development
165+- build commands
166+- cleanup
167+
140168 Examples:
141169
142170 ```powershell
@@ −147 +175 @@
147175 npx prisma generate
148176 npx prisma migrate dev
149177 Copy-Item .env.example .env.local
150−New-Item -ItemType Directory -Path .agent-memory -Force
178+New-Item -ItemType Directory -Path .claude\session-memory -Force
151179 ```
152180
153181 ---
154182
155−## Dependency and Official Documentation Checks
183+# 6. Dependency and Documentation Checks
156184
157185 Before installing or configuring important dependencies:
158186
@@ −161 +189 @@
161189 3. Confirm the integration pattern is current.
162190 4. Explain any setup choice that differs from older examples.
163191 5. Avoid relying on outdated syntax.
164−6. Record important setup decisions in session memory or the Decision Log.
165192
166−This is especially important for Prisma, Next.js, authentication libraries, OpenAI SDK, Vercel Blob, Neon, testing frameworks, and build tooling.
193+This is especially important for:
167194
195+- Prisma
196+- Next.js
197+- authentication libraries
198+- OpenAI SDK
199+- Vercel Blob
200+- Neon
201+- testing frameworks
202+- build tooling
203+
204+Do not install a dependency based only on memory when current setup details may have changed.
205+
168206 ---
169207
170−## Architecture Invariants
208+# 7. Architecture Boundaries
171209
172−Every agent must preserve:
210+Claude must preserve these invariants:
173211
174212 - A Document is the central domain object.
175213 - Pages belong to exactly one Document.
176−- A Document has exactly one owner: user or temporary session.
214+- A Document has exactly one owner:
215+ - user
216+ - or temporary session
177217 - Only `READY` Documents are available to AI.
178218 - Accepted page text is the factual source of truth.
179219 - AI chat is temporary.
180220 - Full chat history is not permanent.
181−- AI answers are grounded in selected `READY` Documents.
221+- AI answers are grounded in selected READY Documents.
182222 - 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.
223+- Architecture changes require a separate Decision Log entry and explicit approval.
184224
185225 ---
186226
187−## Package Scripts
227+# 8. Package Scripts
188228
189229 Keep `package.json` scripts clear and easy to inspect.
190230
@@ −210 +250 @@
210250 }
211251 ```
212252
213−Do not add duplicate or confusing scripts without a clear reason.
253+Do not add scripts that duplicate existing behavior without a clear reason.
214254
215255 ---
216256
217−## Testing Expectations
257+# 9. Testing Expectations
218258
219259 Required for:
220260
@@ −225 +265 @@
225265 - deletion and cleanup
226266 - security-sensitive code
227267 - environment configuration
228−- temporary session behavior
268+- temporary sessions
229269
230270 Strongly advised for:
231271
232272 - OCR
233273 - AI prompts
234−- AI safety behavior
274+- safety behavior
235275 - section generation
236−- upload workflow
276+- uploads
237277 - dashboard
238278 - multi-document chat
239279
240280 Optional for:
241281
242−- documentation-only updates
282+- documentation-only changes
243283 - styling-only changes
244284 - copy changes
245285 - non-functional refactors
246286
247−Always report tests run, tests passed, tests failed, tests not run, and known gaps.
287+Always report:
248288
289+- tests run
290+- tests passed
291+- tests failed
292+- tests not run
293+- known gaps
294+
249295 ---
250296
251−## UI Rules
297+# 10. UI Rules
252298
299+Current UI guidance is intentionally limited.
300+
253301 - Mobile-first.
254302 - Must also work in desktop browsers.
255303 - Prioritize functional flows before polish.
@@ −262 +310 @@
262310
263311 ---
264312
265−## Clarification Rule
313+# 11. Clarification Rule
266314
267−If an agent is unsure:
315+If Claude is unsure:
268316
269317 - stop
270318 - explain what is unclear
@@ −273 +321 @@
273321 - do not invent requirements
274322 - do not proceed silently
275323
324+This applies to:
325+
326+- unclear requirements
327+- conflicting documents
328+- uncertain implementation direction
329+- missing dependencies
330+- ambiguous acceptance criteria
331+- unclear test expectations
332+
276333 ---
277334
278−## Shared Agent Memory
335+# 12. Local Session Memory
279336
280−Use:
337+## Session continuity and working memory
281338
339+Before starting or continuing any non-trivial task, Claude should review available local session-memory files (if present) and update them when useful.
340+
341+Use session memory to:
342+- capture the task being worked on
343+- record important context, assumptions, and constraints
344+- note open questions, risks, or follow-up items
345+- preserve handoff context if the session may be interrupted or hit context limits
346+
347+Guidelines:
348+- Keep memory notes short, factual, and useful for future continuation
349+- Update memory before or during meaningful work when the task involves debugging,
350+ behavior changes, architecture decisions, environment/configuration changes,
351+ multi-file edits, or unresolved questions
352+- Prefer updating local gitignored memory files rather than creating extra repo docs
353+ unless the information belongs in project documentation
354+- Do not commit local session-memory files unless explicitly told to do so
355+
356+Use local memory files for long sessions and context handoff.
357+
358+Repository location:
359+
282360 ```text
283−.agent-memory/
284− CURRENT_SESSION.md
285− DECISIONS.md
286− OPEN_QUESTIONS.md
287− WORK_LOG.md
361+.claude/
362+ session-memory/
363+ CURRENT_SESSION.md
364+ DECISIONS.md
365+ OPEN_QUESTIONS.md
366+ WORK_LOG.md
288367 ```
289368
290369 Required behavior:
291370
292−- Read these files before resuming work.
371+- Read these files before resuming work in a new session.
293372 - Update `CURRENT_SESSION.md` during long sessions.
294−- Record durable implementation decisions in `DECISIONS.md`.
373+- Record durable decisions in `DECISIONS.md`.
295374 - Record unresolved issues in `OPEN_QUESTIONS.md`.
296375 - Add concise chronological notes to `WORK_LOG.md`.
297376 - Never store secrets, tokens, passwords, private document text, or sensitive user data.
298377 - Keep entries concise.
378+- Update `.gitignore` based on whether each file should remain local or be committed.
299379
300−Recommended Git policy:
380+Recommended policy:
301381
302382 Local only:
303383 - `CURRENT_SESSION.md`
304384 - `WORK_LOG.md`
305385
306−Potentially committed:
386+May be committed when project-relevant:
307387 - `DECISIONS.md`
308388 - `OPEN_QUESTIONS.md`
309389
310−Claude-specific memory remains separate under `.claude/session-memory/`.
311−
312390 ---
313391
314−## Tool-Specific Files
392+# 13. AI Change Summary
315393
316−Claude Code must also read `CLAUDE.md`.
317−
318−Cline-hosted models, including Z.AI through Cline, must also follow `.clinerules/`.
319−
320−A Copilot-specific bridge may exist at `.github/copilot-instructions.md` and must not contradict this file.
321−
322−---
323−
324−## Model Routing Guide
325−
326−Use this table to decide which model to assign a task to. The current agent should
327−flag a handoff recommendation in `OPEN_QUESTIONS.md` when the active task crosses
328−into 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−
343−If you are mid-task and recognize the next logical step belongs to a different model,
344−do not attempt it. Instead:
345−
346−1. Complete your current atomic unit of work and commit it.
347−2. Add a note to `OPEN_QUESTIONS.md`: `[MODEL SWITCH NEEDED] — suggest switching to <model> for <reason>`
348−3. Report it in your Change Summary under "What should happen next?"
349−
350−---
351−
352−## Change Summary
353−
354394 For meaningful changes, report:
355395
356396 1. What changed?
@@ −360 +400 @@
360400 5. What tests were run?
361401 6. What remains untested?
362402 7. What should happen next?
363−8. Which commits were created?
364403
365404 ---
366405
367−## Stop Conditions
406+# 14. Stop Conditions
368407
369408 Stop and ask before:
370409
371410 - changing architecture
372411 - changing the PRD
373412 - changing ownership behavior
374−- changing lifecycle states
413+- changing document lifecycle states
375414 - changing AI grounding rules
376415 - replacing a major framework or provider
377416 - introducing permanent chat storage
