v1.0.0 to v1.0.0

- ---

- name: context-engineering

- description: Context window monitoring and budget management. Keeps orchestrator at 15-30% context usage while subagents get full 200k tokens. Provides warnings at thresholds, context-aware summarization triggers, and wave-level budget planning.

- allowed-tools: Read Bash(*)

- metadata:

- author: babysitter-sdk

- version: "1.0.0"

- category: gsd-core

- backlog-id: SK-GSD-003

- - **Subagents**: Get full 200k tokens of fresh context per spawn.

- - **Context budget**: Plan how much context each wave of execution will consume.

-

- This skill provides:

- - Context window usage estimation for the current session

- - Warning injection at configurable thresholds (70%, 85%, 95%)

- - Orchestrator budget enforcement

- - Subagent context allocation recommendations

- - Context-aware summarization triggers

- - Stale context detection and pruning suggestions

- - Wave-level context budget planning

-

- ## Capabilities

-

- ### 1. Context Usage Estimation

-

- Estimate current context window usage based on conversation history size:

-

- ```

- Tokens used: ~45,000 / 200,000

- Usage: 22.5%

- Status: HEALTHY

- Next threshold: 70% (warning) at ~140,000 tokens

- ```

-

- Estimation methods:

- - Character count / 4 (rough approximation)

- - Tool output tracking (each tool call adds to context)

- - File read accumulation tracking

-

- ### 2. Threshold Warnings

-

- Inject warnings at configurable thresholds:

-

- ```

- [CONTEXT 70%] Warning: Context window at 70%. Consider summarizing completed work.

- [CONTEXT 85%] Critical: Context window at 85%. Spawn new subagent for remaining work.

- [CONTEXT 95%] Emergency: Context window at 95%. Wrap up immediately. Write state and exit.

- ```

-

- Actions per threshold:

- - **70%**: Suggest summarizing completed work, pruning stale context

- - **85%**: Strongly recommend spawning new subagent with fresh context

- - **95%**: Emergency wrap-up: write STATE.md, commit, create continue-here.md

-

- ### 3. Orchestrator Budget Enforcement

-

- Monitor orchestrator-specific budget:

-

- ```

- Target orchestrator usage: 15-30%

- Current orchestrator usage: 18%

- Remaining budget: 12% (~24,000 tokens)

-

- Budget allocation:

- - Phase context loading: 5% (PROJECT, ROADMAP, STATE)

- - Agent spawn overhead: 3% per agent

- - Result processing: 2% per agent result

- - State updates: 1%

- ```

-

- ### 4. Subagent Context Allocation

-

- Recommend context allocation for subagent spawns:

-

- ```

- Agent: gsd-executor

- Available context: 200,000 tokens (fresh)

- Recommended loading:

- - Plan file: ~2,000 tokens

- - Relevant source files: ~15,000 tokens

- - Project context: ~3,000 tokens

- - Remaining for execution: ~180,000 tokens

- ```

-

- ### 5. Context-Aware Summarization

-

- Trigger summarization when context is filling:

-

- ```

- Summarization triggers:

- - Tool output > 10,000 characters: summarize before continuing

- - File read > 5,000 lines: extract relevant sections only

- - Agent result > 20,000 characters: summarize key outcomes

- ```

-

- Summarization strategies:

- - **Completed work**: Replace detailed execution logs with summary

- - **File contents**: Replace full file reads with relevant excerpts

- - **Agent results**: Extract key outcomes, discard detailed reasoning

-

- ### 6. Stale Context Detection

-

- Identify context that is no longer relevant:

-

- ```

- Stale context candidates:

- - File contents read 10+ interactions ago

- - Agent results from completed (not current) phases

- - Tool outputs that were informational only

- - Research documents already synthesized into plans

- ```

-

- ### 7. Wave-Level Budget Planning

-

- Plan context budget across execution waves:

-

- ```

- Wave 1 (3 parallel agents):

- Spawn cost: 3 * 3% = 9%

- Result processing: 3 * 2% = 6%

- Wave total: 15%

-

- Wave 2 (2 parallel agents):

- Spawn cost: 2 * 3% = 6%

- Result processing: 2 * 2% = 4%

- Wave total: 10%

-

- Total orchestrator budget needed: 25%

- Target: 30% -> Sufficient with 5% margin

- ```

-

- ## Tool Use Instructions

-

- ### Checking Context Usage

- 1. Use `Bash` to estimate current session token count if available

- 2. Track cumulative tool output sizes during the session

- 3. Calculate percentage against 200,000 token window

- 4. Return usage report with threshold proximity

-

- ### Injecting Warnings

- 1. Compare current usage against configured thresholds

- 2. If threshold exceeded, format appropriate warning message

- 3. Include recommended action based on threshold level

- 4. For 95%: include emergency state-save instructions

-

- ### Planning Wave Budgets

- 1. Use `Read` to load plan files for the phase

- 2. Count agents needed per wave

- 3. Estimate per-agent spawn and result cost

- 4. Sum wave costs and compare to orchestrator budget target

- 5. Recommend wave splitting if budget exceeded

-

- ## Process Integration

-

- - `execute-phase.js` - Monitor context during multi-wave execution, trigger summarization between waves

- - `iterative-convergence.js` - Track context across convergence iterations, spawn fresh agents when context fills

- - `new-project.js` - Budget context for parallel research agents (4 spawns + synthesis)

-

- ## Output Format

-

- ```json

- {

- "operation": "check|warn|plan|summarize",

- "status": "healthy|warning|critical|emergency",

- "usage": {

- "estimatedTokens": 45000,

- "maxTokens": 200000,

- "percentage": 22.5,

- "nextThreshold": 70

- },

- "recommendation": "Continue normally|Summarize completed work|Spawn new agent|Emergency wrap-up",

- "waveBudget": {

- "totalWaves": 2,

- "estimatedOrchestratorUsage": 25,

- "withinBudget": true

- }

- }

- ```

-

- ## Configuration

-

- | Setting | Default | Description |

- |---------|---------|-------------|

- | `contextWarningThreshold` | `70` | Warning threshold percentage |

- | `contextCriticalThreshold` | `85` | Critical threshold percentage |

- | `contextEmergencyThreshold` | `95` | Emergency threshold percentage |

- | `orchestratorBudgetTarget` | `30` | Target max orchestrator context % |

- | `agentSpawnCost` | `3` | Estimated % per agent spawn overhead |

- | `agentResultCost` | `2` | Estimated % per agent result processing |

- | `autoSummarize` | `true` | Auto-trigger summarization at thresholds |

-

- ## Error Handling

-

- | Error | Cause | Resolution |

- |-------|-------|------------|

- | `Token estimation inaccurate` | Approximation drift | Use conservative estimates (overestimate usage) |

- | `Budget exceeded mid-wave` | Underestimated agent costs | Defer remaining agents to next session with continue-here.md |

- | `Emergency threshold hit` | Orchestrator doing too much work inline | Immediately write state, commit, create handoff document |

- | `Stale context false positive` | Context still needed | Maintain a "pinned context" list that is never pruned |

-

- ## Constraints

-

- - Token estimates are approximations (character/4 heuristic); always err on the side of caution

- - Never discard context that has not been persisted to disk (STATE.md, summaries, etc.)

- - Orchestrator should never exceed 30% context usage

- - Emergency wrap-up at 95% is non-negotiable; quality degrades severely above this

- - Wave budget planning must account for worst-case agent result sizes

- - Context monitoring is advisory; it cannot forcibly stop execution