Context Engineering

Context Engineering Skill

This skill provides techniques for managing context effectively throughout the workflow to prevent bloat and maintain efficiency.

Core Principles

1. Stay Under 40%: Orchestrator should never exceed 40% context usage 2. Fresh Context Per Task: Each major task gets a fresh agent with clean context 3. Load Only What's Needed: Don't load full files when summaries suffice 4. Delegate Deep Work: Spawn agents for context-heavy operations

Context Budget Guidelines

Context Loading Strategies

Selective Loading

Instead of loading full files:

BAD: Read entire codebase
GOOD: Read specific files needed for current task
BEST: Read summaries, then specific sections

Hierarchical Loading

Load context in layers: 1. L1 Summary: High-level overview (FLOW.md) 2. L2 Details: Item-specific state (ITEM-XXX.md) 3. L3 Specifics: Task-specific files (only files in current task)

Incremental Loading

Load more context only when needed:

1. Start with minimal context
2. Identify what's missing
3. Load specific missing pieces
4. Repeat as needed

Fresh Context Patterns

When to Use Fresh Context

Spawn a fresh agent when:

• Starting a new task in EXECUTE phase
• Moving to a new phase
• Current context is getting heavy
• Deep codebase exploration needed

Fresh Context Handoff

When spawning fresh agent:

Include in handoff:
- Task ID and definition
- Key decisions from ITEM-XXX.md
- Relevant file paths
- Success criteria

Exclude:
- Full conversation history
- Files not related to task
- Exploration paths not taken

Context Reset Points

Natural points to reset context:

• Phase transitions
• After each completed task
• After resolving a blocker
• After user requests fresh start

Context Monitoring

Signs of Context Bloat

Watch for:

• Repeated information in responses
• Slower response times
• Forgetting earlier context
• Inconsistent references

Context Health Check

Periodically verify:

• Can still reference key decisions?
• Can identify current task?
• Can access state files?
• Response quality maintained?

State File as External Memory

Use state files as external memory:

What to Store in Files

• All decisions (ITEM-XXX.md Decisions section)
• Exploration progress (ITEM-XXX.md Exploration section)
• Task definitions (ITEM-XXX.md Tasks section)
• Requirements (ITEM-XXX.md Requirements section)

What to Keep in Context

• Current phase and task
• Key constraints
• Immediate next steps
• Recent decisions (can reference file for older ones)

Delegation Patterns

Deep Exploration Delegation

Task: Understand how authentication works in this codebase

Instead of:
- Loading all auth-related files into orchestrator context

Do:
- Spawn researcher agent with specific question
- Receive summary findings
- Keep summary in orchestrator context

Implementation Delegation

Task: Implement TASK-005

Instead of:
- Loading full codebase patterns and task into orchestrator

Do:
- Spawn executor with task definition + relevant files only
- Receive completion status
- Update state files

Context Compression Techniques

Summary Generation

After deep work, compress to summary:

Before compression: [Full exploration transcript]

After compression:
**Exploration Result**: Authentication
- Uses JWT tokens
- Stored in localStorage
- Refresh flow in AuthService.refresh()
- Decision needed: token expiry duration

Reference Instead of Inline

BAD: Include full task XML in every message
GOOD: "Executing TASK-005 (see ITEM-XXX.md Tasks section)"

Checkpoint Snapshots

At checkpoints, snapshot key state:

### CHECKPOINT: EXECUTE-001
**Context snapshot**:
- Phase: EXECUTE
- Progress: 5/10 tasks
- Current: TASK-006
- Blocked: None
- Key decisions: Use JWT (DECISION-003)

Integration with Workflow

During DISCUSS

• Keep exploration map in ITEM-XXX.md
• Summarize findings per area
• Reference decisions by ID

During PLAN

• Read requirements once, create tasks
• Don't reload requirements repeatedly
• Reference task IDs not full definitions

During EXECUTE

• Fresh context per task
• Load only task + relevant files
• Update state after each task

During VERIFY

• Load summary of completed work
• Cross-reference requirements by ID
• Keep verification results in ITEM-XXX.md

Best Practices

1. Reference, don't repeat: Use IDs and file paths 2. Summarize immediately: After deep work, compress findings 3. Clean handoffs: Fresh agents get focused context 4. Use state files: They're your external memory 5. Monitor bloat: Watch for degradation signs 6. Delegate proactively: Don't wait until context is full

Context Engineering Patterns

Pattern: Fresh Task Context

When: Starting each task in EXECUTE phase

Structure:

## Task Context for TASK-XXX

**Task Definition**:
[XML task from ITEM-XXX.md Tasks section]

**Relevant Files**:
- [file1]: [why needed]
- [file2]: [why needed]

**Key Decisions**:
- DECISION-XXX: [relevant decision]

**Conventions**:
- [coding convention to follow]

**Success Criteria**:
- [from task <done> criteria]

What to Exclude:

• Other tasks not being executed
• Full exploration history
• Resolved conflicts
• Completed task details

---

Pattern: Phase Transition Summary

When: Moving from one phase to another

Structure:

## Phase Transition: [FROM] → [TO]

**Completed in [FROM]**:
- [Key accomplishment 1]
- [Key accomplishment 2]

**Artifacts created**:
- [file]: [brief description]

**Carrying forward**:
- [Key decision or context needed in next phase]

**Starting [TO] with**:
- [Initial focus]

What to Exclude:

• Detailed exploration paths not taken
• Verbose transcripts
• Intermediate states

---

Pattern: Exploration Summary

When: Completing exploration of an area in DISCUSS

Structure:

## [Area Name] - Exploration Summary

**Status**: EXPLORED

**Key Findings**:
1. [Finding 1]
2. [Finding 2]

**Decisions Made**:
- DECISION-XXX: [Summary]

**Open Questions** (if any):
- [Question]

**Related Areas**: [links to related explored areas]

What to Exclude:

• Full question/answer transcript
• Rejected options (unless critical)
• Tangential discussions

---

Pattern: Research Findings

When: Researcher agent returns from codebase exploration

Structure:

## Research: [Topic]

**Question**: [What was investigated]

**Findings**:
- [Key finding with file reference]
- [Key finding with file reference]

**Patterns Identified**:
- [Pattern name]: [Where used, example]

**Recommendations**:
1. [Recommendation]

**Files of Interest**:
- [path]: [relevance]

What to Exclude:

• Full file contents
• Dead ends explored
• Verbose grep/glob results

---

Pattern: Task Completion Report

When: Executor completes a task

Structure:

## TASK-XXX: Complete

**Summary**: [One sentence of what was done]

**Files Modified**:
- [path]: [what changed]

**Verification**:
- [step]: PASS/FAIL

**Commit**: [hash] - [message]

**Notes** (if any): [Anything noteworthy for future tasks]

What to Exclude:

• Full code that was written
• Detailed step-by-step log
• Intermediate states

---

Pattern: Verification Report

When: Verifier completes verification

Structure:

## Verification Report

**Automated Checks**: PASS/FAIL
- Build: [status]
- Tests: [X/Y passed]
- Lint: [status]

**Requirements Coverage**: X/Y
| Requirement | Verified |
|-------------|----------|
| FR-001 | YES |

**UAT Results**: PASS/FAIL
- [Scenario]: [result]

**Issues**: [count]
[List if any]

**Recommendation**: APPROVE / NEEDS_WORK

What to Exclude:

• Full test output
• Verbose build logs
• Passing scenarios details (only note failures)

---

Pattern: Checkpoint Context

When: Creating a checkpoint for resume capability

Structure:

### CHECKPOINT: [PHASE]-[TIMESTAMP]

**Phase**: [current phase]
**Progress**: [X%]

**State**:
- Decisions: [count]
- Tasks: [completed/total]
- Blockers: [count]

**Current Focus**: [what's being worked on]

**Next Action**: [specific next step]

**Key Context**:
- [Essential item to remember]
- [Essential item to remember]

What to Exclude:

• Full history of how we got here
• All decisions (they're in ITEM-XXX.md)
• Completed work details

---

Pattern: Conflict Presentation

When: Presenting a conflict to user

Structure:

## Conflict Detected

**Between**:
- A: [Item A - concise]
- B: [Item B - concise]

**Why they conflict**: [One sentence explanation]

**Options**:
1. [Option with implication]
2. [Option with implication]
3. [Option with implication]

**Waiting for**: User resolution

What to Exclude:

• Full context of how each item arose
• All possible options (pick top 3-4)
• Technical details unless necessary

---

Pattern: Agent Spawn Request

When: Orchestrator spawns a specialized agent

Structure:

## Spawn Request: [agent-name]

**Purpose**: [One sentence]

**Context to provide**:
- [Specific item]
- [Specific item]

**Expected output**: [What to return]

**Files agent should read**:
- [path]
- [path]

**Constraints**:
- [Any limits or guidelines]

What to Exclude:

• Full workflow history
• Unrelated state
• Other phases' details

---

Anti-Patterns to Avoid

The Memory Hoarder

BAD: Keeping full transcripts of all conversations
GOOD: Summarize and reference ITEM-XXX.md for history

The File Dumper

BAD: Loading entire files into context repeatedly
GOOD: Load once, reference by path, load sections as needed

The Everything Reporter

BAD: Agent returns full code + all steps + full logs
GOOD: Agent returns summary + key findings + next actions

The Context Repeater

BAD: Including same context in every message
GOOD: "Continuing TASK-005" (context established)

The Inline Expander

BAD: "The task definition is: [full XML]..."
GOOD: "Task TASK-005 (see ITEM-XXX.md Tasks section)"