updated agents to loop less

.opencode/AGENTS.md

@@ -1,18 +1,21 @@
 # AGENTS.md
 
-Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+Behavioral guidelines for reliable, efficient coding work. Merge with project-specific instructions as needed.
 
-**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+**Tradeoff:** Prefer correctness and focused changes over speed, but do not over-analyze simple tasks.
 
-## 1. Think Before Coding
+## 1. Investigate Before Assuming
 
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
+**Use evidence before speculation. Use tools early.**
 
 Before implementing:
-- State your assumptions explicitly. If uncertain, ask.
+- Inspect the relevant code, tests, configuration, or documentation first.
-- If multiple interpretations exist, present them - don't pick silently.
+- Do not invent assumptions when the repository can answer the question.
-- If a simpler approach exists, say so. Push back when warranted.
+- If multiple interpretations remain after inspection, choose the simplest reasonable one when low-risk and state it briefly.
-- If something is unclear, stop. Name what's confusing. Ask.
+- Ask the user only when ambiguity materially affects the outcome and cannot be resolved from available evidence.
+- Surface important tradeoffs, but do not enumerate hypothetical alternatives unnecessarily.
+
+Do not spend excessive time reasoning before acting. Once you have enough evidence for a reasonable hypothesis, proceed and verify it.
 
 ## 2. Simplicity First
 
@@ -20,42 +23,62 @@ Before implementing:
 
 - No features beyond what was asked.
 - No abstractions for single-use code.
-- No "flexibility" or "configurability" that wasn't requested.
+- No flexibility or configurability that was not requested.
 - No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite it.
+- Prefer existing patterns and mechanisms over introducing new ones.
+- If the implementation becomes substantially larger than the problem warrants, reconsider the approach.
 
-Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+Ask yourself: "Would a senior engineer consider this unnecessarily complicated?" If yes, simplify.
 
 ## 3. Surgical Changes
 
 **Touch only what you must. Clean up only your own mess.**
 
 When editing existing code:
-- Don't "improve" adjacent code, comments, or formatting.
+- Do not improve adjacent code, comments, or formatting unless required.
-- Don't refactor things that aren't broken.
+- Do not refactor unrelated code.
-- Match existing style, even if you'd do it differently.
+- Match the existing style and architecture.
-- If you notice unrelated dead code, mention it - don't delete it.
+- If you notice unrelated problems, mention them rather than fixing them.
 
-When your changes create orphans:
+When your changes create unused code:
-- Remove imports/variables/functions that YOUR changes made unused.
+- Remove imports, variables, functions, or files made unused by your changes.
-- Don't remove pre-existing dead code unless asked.
+- Do not remove pre-existing dead code unless asked.
 
-The test: Every changed line should trace directly to the user's request.
+Every changed line should trace directly to the requested task.
 
 ## 4. Goal-Driven Execution
 
-**Define success criteria. Loop until verified.**
+**Work in short inspect → act → verify loops.**
 
-Transform tasks into verifiable goals:
+Turn tasks into verifiable goals:
-- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Add validation" → reproduce invalid cases, implement validation, verify them.
-- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Fix the bug" → reproduce the bug, implement the smallest fix, verify the regression.
-- "Refactor X" → "Ensure tests pass before and after"
+- "Refactor X" → establish current behavior, refactor, verify behavior remains unchanged.
 
-For multi-step tasks, state a brief plan:
+For non-trivial tasks, keep the plan brief:
-```
-1. [Step] → verify: [check]
-2. [Step] → verify: [check]
-3. [Step] → verify: [check]
-```
 
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+1. Inspect the relevant area → identify the cause or required change.
+2. Make the smallest coherent change → avoid unrelated edits.
+3. Verify with the narrowest useful test or check → expand verification only if needed.
+
+Prefer a tool call over extended reasoning when a tool can provide evidence.
+
+After each meaningful action:
+- Evaluate the result.
+- Continue only from new evidence.
+- Do not repeatedly reconsider the same hypothesis without new information.
+- If verification fails, diagnose the failure and iterate.
+
+## 5. Efficient Agent Behavior
+
+**Spend tokens on progress, not narration.**
+
+- Use tools as soon as they can reduce uncertainty.
+- Prefer targeted searches and file reads over broad repository exploration.
+- Do not repeatedly read files whose relevant contents are already known.
+- Do not produce long internal-style analyses or narrate obvious steps.
+- Keep plans, progress updates, and final explanations concise.
+- Make one coherent change at a time when practical.
+- Stop when the requested goal is satisfied and verified.
+
+If blocked, clearly state what is blocking progress and what evidence led there.