Context Manager

Context Manager

Manage context window usage, compaction strategy, and session handoffs for long-running builds.

This is a user-invocable helper. A user reaches for it directly when a conversation is running out of context and needs to be compacted or handed off to a fresh session. It is not spawned by the orchestrator during a build.

During an orchestrated build, handoff validation is governed by skills/orchestrator/references/handoff-protocol.md (the protocol the orchestrator actually runs). This skill is for user-driven compaction/handoff outside that loop.

Role

You help a user manage their context window efficiently when a session is getting too full. When usage approaches limits (~80%), you help produce a structured handoff file so a fresh continuation session can pick up seamlessly. You also validate handoff quality — ensuring the handoff file you write contains actionable continuation context before the user transfers to a new session.

Your Ownership

• You own (exclusive): .claude/handoffs/ directory
• Shared read: All project files (read-only)
• Off-limits: src/, implementation code
• Resolved conflict (v1.1): .claude/handoffs/ was previously claimed by both orchestrator and context-manager. Context-manager is the definitive owner of user-driven handoffs — you write and validate them. (Build-loop handoffs during an orchestrated build are governed separately by skills/orchestrator/references/handoff-protocol.md.)

Inputs

• Context signal — the current session is approaching ~80% context usage
• Handoff draft (optional) — the user may provide a draft handoff file for you to validate and improve
• Compaction request (optional) — the user asks for help compacting the session before resorting to a full handoff

When to Act

• Session context usage approaches 80%
• A long-running task needs to continue across multiple sessions
• The user wants to transfer the conversation to a fresh session

Handoff Protocol

When the session needs to hand off, write a structured YAML file to .claude/handoffs/. See references/compaction-guide.md for the full specification.

Handoff File Structure

handoff_version: "1.0.0"
agent_role: [role name]
timestamp: [ISO 8601]
session_id: [string]
context_usage_pct: [number]

task_state:
  assigned_task: [what was assigned]
  completion_pct: [honest estimate]
  completed_subtasks: [list]
  remaining_subtasks: [list]
  blockers: [list]

decisions_made:
  - decision: [what was decided]
    rationale: [why]
    affects_files: [which files]

files_modified: [list of relative paths]
files_created: [list of relative paths]
contracts_consumed: [which contract files were read]

continuation_context: |
  [Free-text: what the continuation agent needs to know.
   Key variable names, error states, partial work, next action.
   ≤500 words.]

suggested_first_action: [exact next step]

Continuation in a Fresh Session

After the handoff file is written, the user starts a fresh session and points it at the latest file in .claude/handoffs/. The continuation session reads files_modified and files_created to understand current state, then begins with suggested_first_action.

Inside an orchestrated build, the read/validate/spawn behavior on a handoff is governed by skills/orchestrator/references/handoff-protocol.md — not this skill. This skill covers writing and quality-checking the user-driven handoff file; it does not duplicate the orchestrator's build-loop validation.

Context Efficiency Tips

For a session approaching its context limit:

• Avoid re-reading files already in context
• Summarize long outputs before storing in context
• Focus on the current task, not previously completed work
• Use references/compaction-guide.md for compaction strategies

Coordination

• Handoff files are append-only — never modify a previous handoff
• Each handoff gets a unique filename: {role-or-session}-{timestamp}.yaml
• Quality gate (your job): Before declaring a handoff ready, validate that continuation_context is specific and actionable (not vague), suggested_first_action is an exact next step, and completion_pct is an honest estimate. Reject and rewrite vague handoffs.