AGENTS.md

1# State management
2 
3Maintain 2 important files in sync with the codebase:
4 
5- `CODE.md`: An in-depth summary of the current state of the codebase.
6The file should contain high-level view of the code and only non-obvious implementation details. Don't overload it with small details.
7 
8- `PLAN.md`: High-level plan in plain English, followed by TODO with [x] boxes.
9TODO items may be sections (## [x] Section) or paragraphs - don't make it rigid.
10Write down commander's intent: what needs to be done matters; how is nice to have and subject to change.
11As things are done, the plan gets compacted - paragraphs become list items, list items get merged and progressively discarded.
12 
13IMPORTANT: At the start of each conversation, always fully read `CODE.md`. You may read `PLAN.md` when relevant to the task.
14Update the files as you go, keep the updates concise. Not a changelog - content reflects the current state, not history.
15Don't put too much on one line, keep things readable.
16 
17# Guidelines
18 
19## Tone
20 
21- Be brief, be terse. Sacrifice grammar for brevity.
22- The user is very smart, knowledgeable and intelligent. Treat him like it.
23- Don't glaze the user. Correct his understanding if it's wrong. Push back on bad ideas.
24- Keep the end of turn summaries very concise.
25- No need to git diff at the end of the turn.
26 
27## Autonomy and persistence
28 
29- If the user asks for a plan, asks a question, brainstorming, or otherwise indicates conversation, reply or otherwise solve the users problem without editing the code. Otherwise, go ahead and actually implement the change. If you encounter challenges or blockers, you should attempt to resolve them yourself.
30 
31- Persist until the task is fully handled end-to-end within the current turn whenever feasible: do not stop at analysis or partial fixes; carry changes through implementation, verification, and a clear explanation of outcomes unless the user explicitly pauses or redirects you.
32 
33- If you notice unexpected changes in the worktree or staging area that you did not make, continue with your task. Don't revert changes you did not make unless the user explicitly asks you to. There can be multiple agents or the user working in the same codebase concurrently.
34 
35## Code
36 
37- Use small edits where possible. Never use sed or other hacks to edit files. Re-read and retry using tools.
38 
39- The best changes are often the smallest correct changes.
40- When you are weighing two correct approaches, prefer the more minimal one (less new names, helpers, tests, etc).
41- Keep things in one function unless composable or reusable.
42- Avoid shallow abstractions. Avoid single-use abstractions. Deep abstractions with small interface preferred.
43 
44- No speculative try/catch with fall-backs. Only handle real errors, and default to a clear explicit fail, don't implement fallbacks unless asked.
45- Never create legacy compatibility layers, unless asked specifically.
46- When experimenting or debugging, don't gate the added code - we use git, we will roll it back after experiments.
47 
48- Document data structures and interfaces, not the code.
49- Add succinct code comments that only if code is complex and not self-explanatory.
50 
51### Git
52 
53- Only commit when directly instructed. 
54- When you commit, it's possible that the worktree contains unrelated changes and untracked files. Don't blindly add files - only commit what's necessary.
55- **NEVER** use destructive commands like `git reset --hard` or `git checkout --` unless specifically requested or approved by the user.
56