Context Loading Protocol

Token-budget reference (CLAUDE.md baseline, full-load ceiling, per-agent and per-skill costs) is the Baseline Budget section of CLAUDE.md. This skill is the runtime procedure; don't duplicate the table here — it goes stale.

Constraints

• Never load all agents upfront; load only the primary agent for each phase.
• Keep total context below 40% of the model's window at all times.
• Load agents on demand when their phase begins, not speculatively.
• Use tool-based file reads (Read); do not paste file contents into the prompt.

Enforcement

No hook blocks or warns on capability loads any more (the former context
ceiling hook was removed; see ADR 0043).
The harness compacts the conversation itself at the percentage
/dev-team:setup writes to the repo's .claude/settings.json
(CLAUDE_AUTOCOMPACT_PCT_OVERRIDE, default 40). Repos that never ran /setup
keep the harness default, which is much later, and get a one-line advisory at
session start. After a compaction, a compact SessionStart hook re-injects
the active /build phase, step and plan progress.

So the budget estimate below is the planning tool you apply before loading,
and /handoff is yours to run by hand when a deliberate, structured summary
is worth more than a generic compaction.

Why 40%

The 40% default is a conservative planning target, not a claimed accuracy cliff.
Chroma's Context Rot study found
degradation across 18 models (including Claude 4) is gradual, not a sharp drop at
any single percentage. Needle-in-a-haystack benchmarks like RULER and NoLiMa show a
model's effective context is often only about half its advertised window, with
sharp accuracy drops on non-lexical retrieval well before the window limit. Anthropic's
effective context engineering guidance
recommends proactive compaction well ahead of the limit. Given that evidence,
budgeting to 40% of the window leaves headroom before quality degrades, rather
than chasing a precise threshold that doesn't exist. There is no absolute token
cap: the percentage applies to the window, so 40% of a 1M window is 400K.

Full guide — how the threshold is configured, the two SessionStart hooks,
troubleshooting: Context Management.

Loading Decision Procedure

Step 0: Confirm there is a task

Before loading anything or reading files, confirm an actionable instruction exists. If the user has not yet said what they want, wait — do not speculatively read files, verify code, or load agents. Premature investigation before a task is given wastes context and is a common interrupt trigger. Once a task exists, proceed to Step 1.

Step 1: Classify the task

Profile	Description	Example
Simple/Single	One agent, no skills	"Fix this typo", "Write a unit test"
Standard/Single	One agent + 1–2 skills	"Implement this feature using hexagonal architecture"
Multi-Agent	2–3 agents coordinating	"Design and implement a new API endpoint"
Complex/Multi	3+ agents + skills	"Build a new bounded context with full test coverage"

Step 2: Select agents

Load the minimum set:

1. Identify the primary agent (owns the deliverable).
2. Identify supporting agents (input or review).
3. Do NOT load agents for downstream validation yet — load them when their phase begins.

Order: primary first, then supporting agents one at a time as their phase begins.

Step 3: Select skills

For each loaded agent, check its ## Skills section:

• Only load skills relevant to the current task — not all skills the agent references.
• Skills shared by multiple loaded agents only need to be loaded once.

Step 4: Calculate token budget

Total = CLAUDE.md baseline
      + conversation history (estimate)
      + agent files (sum selected)
      + skill files (sum selected)
      + expected output (estimate)

Target: total < 40% of the model's context window. For Claude with a 200K window, that's < 80K tokens; on a 1M-window model it is 400K (there is no absolute cap). See Why 40% for the rationale. The config files are a small fraction; the real budget concern is conversation history + output accumulation over multi-turn tasks.

Step 5: Load via tool-based file reads

Read agents/software-engineer.md
Read skills/hexagonal-architecture/SKILL.md

Do NOT copy file contents into the system prompt or conversation.

Loading Profiles

Pre-computed loading sets for common task types.

Code Implementation

• Load: Software Engineer + relevant skill(s)
• Defer: QA (load after implementation), Architect (load only if design questions arise)

Architecture Design

• Load: Architect + relevant architecture skill(s)
• Defer: Software Engineer (load at implementation), QA (load at validation)

Bug Fix

• Load: Software Engineer only
• Defer: QA (load if regression test needed)

New Feature (full lifecycle)

Three phases, each in a fresh context window with a human review gate between. Each phase's output is a structured progress file in .claude/memory/ that onboards the next phase.

Phase	Load	Purpose	Output
1. Research	Orchestrator + sub-agents (exploration)	Understand system, find files, trace data flows	Research progress file
2. Plan	Architect + PM (if needed) + relevant skill(s)	Specify every change: files, snippets, tests	Implementation plan progress file
3. Implement	Software Engineer + QA + skill(s)	Execute the plan; code, tests	Working code + test results

Key rules:

• Each phase starts with a fresh context window, loading only the previous phase's progress file.
• Human reviews and approves the progress file before the next phase begins.
• Sub-agents primarily provide context isolation — they search, read, and return concise findings.
• If implementation is large, compact mid-phase: update the plan progress file with completed steps and continue in a fresh context.

Unloading

Since tokens can't be literally removed from context:

1. Phase transitions — summarize completed phase output into .claude/memory/ and start a new conversation for the next phase.
2. Within a conversation — stop referencing the agent/skill; the orchestrator mentally notes it's no longer active. Use the Handoff skill (continue mode) to compress stale content.
3. Multi-turn accumulation — when conversation history crosses 30% utilization, trigger summarization before loading additional agents.

Anti-patterns

• Loading all agents upfront — wastes tokens before any work begins. Load only the primary agent.
• Loading all of an agent's skills — most are irrelevant to the specific request.
• Never unloading — context grows monotonically until hallucination risk. Summarize and phase-transition.
• Loading agents "just in case" — adds cost without value. Load on demand when the phase begins.

Output

Loading plan as one table: selected agents + skills, token costs, estimated total, and utilization percentage against the 40% ceiling. No narration.