# Phase 1.1: Allow Flexible Token Budget - Context

**Gathered:** 2026-01-22
**Status:** Ready for planning

<domain>
## Phase Boundary

Handle token budget flexibility by enabling automatic budget calculation based on agent's context window. Remove hardcoded 5000 token default and implement window-relative budgets with model-specific percentages. Scope: Make budget calculation automatic and context-aware, not changing the core tracking mechanism.

</domain>

<decisions>
## Implementation Decisions

### Budget Calculation (Automatic)
- Agent auto-detects context window size and calculates budget automatically
- Model-specific percentages:
  - **Gemini**: 40-50% of context window (e.g., 2M window → 800k-1M token budget)
  - **Claude**: 30-40% of context window (varies by model safety margins)
- Agent determines exact percentage within range based on model knowledge
- **Fallback**: If agent can't detect window size → prompt user for budget preference

### Warning Thresholds
- Budget represents total tokens available for loading files (40-50% of window)
- Warnings trigger when approaching budget limit: **80%+ of budget used**
- Example: 800k budget → warn at 640k+ tokens used
- STOP behavior remains: 50%+ of context window (not budget) means stop and scope down

### Bug Fixes Required
1. **Remove hardcoded 5000 token default** - appears in 5 templates:
   - INIT_PROMPT.md (line 72)
   - CONTEXT_TEMPLATE.md
   - BOOTLOADER_TEMPLATE.md
   - SUMMARY_TEMPLATE.md
   - STATE_TEMPLATE.md
2. **Add explicit template loading instructions** - INIT_PROMPT.md mentions templates but doesn't instruct agent to read them. Needs explicit steps: "Step 1: Read BOOTLOADER_TEMPLATE.md, Step 2: Read LOOPS_TEMPLATE.md, etc."

### Template Loading Pattern
- INIT_PROMPT.md must include explicit read instructions for all protocol templates
- Sequential loading: BOOTLOADER → LOOPS → CONTEXT → STATE (in initialization order)
- Ensures full protocol loaded before agent starts operating

### Claude's Discretion
- Exact percentage within model-specific ranges (e.g., 40% vs 45% vs 50% for Gemini)
- Budget calculation implementation details (how agent detects window size)
- Warning message phrasing and frequency
- Fallback prompt UX when window can't be detected

</decisions>

<specifics>
## Specific Ideas

**Real bug discovered during discussion:**
- User tested INIT_PROMPT.md with agent
- Agent read template and reported "5000 token budget" in sticky note
- Agent should have calculated 30% of 1M window (Gemini) = 300k tokens
- This confirmed hardcoded default is being used instead of calculation

**User's target budget:**
- Gemini 2M window → 40k tokens optimal (40% = 800k, user said "40k" likely meant 40%)
- Can safely fill to 70-80% of budget without breaking operation
- Conservative Phase 1 approach (20/40/50% thresholds) was too restrictive

**Desired behavior:**
- Agent calculates budget automatically based on its knowledge of context window
- No manual configuration needed in normal case
- Only prompt user if detection fails (fallback scenario)

</specifics>

<deferred>
## Deferred Ideas

None - discussion stayed within phase scope. Focus is specifically on budget calculation flexibility, not expanding the token tracking system or adding new features.

</deferred>

---

*Phase: 01.1-allow-flexible-token-budget*
*Context gathered: 2026-01-22*
