codeflash-agent/.claude/rules/sessions.md

# Session Discipline

## Scope

One task per session. Don't mix implementation with communication drafting, transcript search, or strategic planning. These have different context needs and dilute each other.

## Duration

Cap sessions at 2-3 hours. Use `/handoff` at natural breakpoints rather than letting auto-compaction degrade context.

- After 1 compaction: consider wrapping up the current task and handing off.
- After 3 compactions: stop what you're doing, update `status.md`, and tell the user to start a fresh session.
- Never continue past 5 compactions. Context is too degraded to be productive.

## Context preservation

- Update `status.md` in the optimization project after completing any milestone
- When compacting, preserve: modified files list, current branch, VM state, test commands used, key decisions made
- Use subagents for exploration to keep main context clean

## No polling

Never poll background tasks. No `wc -l`, no `tail -f`, no `sleep` loops checking output files. Use `run_in_background` and wait for the completion notification. One check after notification is fine. Sixty-two checks in a loop is not.

## File read budget

If you've read the same file 3+ times in a session, something is wrong. Either:
- The session is too long and compaction destroyed your context -- write a handoff
- You're not retaining key information from previous reads -- write it down in your response before it compacts away