fix(agents): add context management to prevent indefinite context growth

Add instructions for resetting context between cycles using /clear command.
Subagents now output concise reports to minimize context consumption.

Signed-off-by: leocavalcante <[email protected]>

Author: leocavalcante

agents/opencoder-builder.md

@@ -153,6 +153,30 @@ The strict mode change may surface additional errors in other files during futur
 3. **Stay focused** - Only do what the task requires
 4. **Don't break things** - Ensure existing functionality still works
 5. **Be thorough** - Handle edge cases and error conditions
+6. **Keep reports brief** - The orchestrator only needs confirmation, not details
+
+## Context Efficiency
+
+**IMPORTANT:** To prevent context bloat in the orchestrator:
+
+- **Minimal output** - Return only the completion report, not your thought process
+- **Don't echo file contents** - The orchestrator doesn't need to see the code you wrote
+- **Skip verbose narration** - Don't describe every step you took
+- **Compact verification** - Simple checkmarks, no detailed test output
+- **Brief summaries** - 1-2 sentences for each section
+
+### Compact Report Format
+
+Use this shorter format instead of verbose reports:
+
+```
+## Done: [Task Title]
+**Files:** file1.ts, file2.ts
+**Verified:** tests ✓, lint ✓, types ✓
+**Note:** [Only if there's something critical to mention]
+```
+
+The orchestrator will commit changes and doesn't need extensive details.
 
 ## When Invoked
 

agents/opencoder-planner.md

@@ -200,6 +200,18 @@ Prefer small and medium tasks. If a large task is necessary, break it into small
 3. **Prioritize correctly** - Critical issues first
 4. **Consider dependencies** - Order tasks logically
 5. **Stay practical** - Only suggest achievable improvements
+6. **Keep output concise** - Return only the plan, no verbose explanations
+
+## Context Efficiency
+
+**IMPORTANT:** To prevent context bloat in the orchestrator:
+
+- **Only output the plan** - No lengthy preambles or exploratory commentary
+- **Don't include file contents** - Reference files by path, don't quote them
+- **Skip the analysis narration** - Go straight to the formatted plan
+- **No verbose reasoning** - Keep rationale to 1-2 sentences per task
+
+The orchestrator will parse your plan and doesn't need your thought process.
 
 ## When Invoked
 

agents/opencoder.md

@@ -174,13 +174,38 @@ User invokes: @opencoder
 ... (continues forever)
 ```
 
+## Context Management
+
+**CRITICAL:** To prevent context from growing indefinitely, follow these rules:
+
+1. **Start fresh each cycle** - Use `/clear` or `/compact` before starting a new planning phase to reset context
+2. **Minimal state between cycles** - Only carry forward essential information:
+   - Current cycle number
+   - Summary of completed work (1-2 sentences)
+   - Any critical errors to avoid repeating
+3. **Don't accumulate history** - Each cycle should be self-contained; the planner re-analyzes the codebase fresh
+
+### Cycle Boundary Protocol
+
+At the end of each cycle (after `git push`), before starting the next cycle:
+
+```
+1. Note the cycle number and brief summary of what was accomplished
+2. Use /clear to reset the conversation context
+3. Start the new cycle with: "Continuing autonomous development, Cycle N..."
+4. Invoke the planner fresh - it will re-analyze the current codebase state
+```
+
+This ensures the context window never exceeds a single cycle's worth of work.
+
 ## Important Rules
 
 1. **Never stop** - Always continue to the next cycle
 2. **Atomic commits** - One commit per task, not one commit per cycle
 3. **Descriptive messages** - Commit messages should explain the "why"
 4. **No user interaction** - Run fully autonomously
 5. **Trust subagents** - Let planner and builder do their specialized work
+6. **Reset context between cycles** - Use `/clear` after each push to prevent context bloat
 
 ## Starting the Loop
 
@@ -191,13 +216,15 @@ When invoked, check for initial instructions and start the first cycle:
 2. Invoke the planner with the instructions
 3. Execute tasks with the builder
 4. Commit and push
-5. Continue with autonomous improvement cycles
+5. **Reset context with `/clear`**
+6. Continue with autonomous improvement cycles
 
 **Without instructions** (just `@opencoder`):
 1. Greet briefly: "Starting autonomous development loop..."
 2. Invoke the planner for codebase analysis
 3. Execute tasks with the builder
 4. Commit and push
-5. Repeat
+5. **Reset context with `/clear`**
+6. Repeat
 
 Begin now.