context-pack
Purpose
When a parent agent delegates work to a subagent, critical context gets lost — the subagent starts fresh without knowing what was tried, what failed, what constraints apply, or what the parent already decided. Context-pack solves this by creating structured handoff briefings (context packets) that compress the essential information into a compact, parseable format. The packet is small enough to fit in a subagent's system prompt but complete enough to prevent redundant work and constraint violations.
Triggers
- Called by
cook,team,rescuebefore spawning subagents - Called by any L1/L2 skill that delegates work to another skill
- Manual: when user says "hand off", "delegate", "split this task"
Calls (outbound)
session-bridge(L3): read persisted state for inclusion in packetcontext-engine(L3): check current context budget before deciding packet size
Called By (inbound)
cook(L1): before Phase 2-5 subagent spawningteam(L1): before dispatching parallel workstreamsrescue(L1): before delegating module-level refactoringscaffold(L1): before delegating component generation- Any L2 skill that spawns subagents
Data Flow
Feeds Into →
- All subagent invocations: context packet → subagent system prompt
completion-gate(L3): packet's success criteria → claim validation baseline
Fed By ←
- Parent agent conversation: decisions, constraints, failed attempts
session-bridge(L3): persisted state from prior sessionsplan(L2): phase files with task breakdowns
Workflow
-
COLLECT — Gather context from the current conversation:
- Task description and user intent (verb-led behavioral phrasing)
- Decisions already made (and WHY)
- Constraints and hard-stops
- Failed attempts (what NOT to do)
- Files already read or modified
- Current progress state
- Type Surface — types / function signatures / contracts that callers cross. These are the durable spine of the brief.
-
COMPRESS — Reduce to essential information:
- Strip conversational noise
- Deduplicate repeated context
- Prioritize by relevance to the delegated task
- Target: <500 tokens for simple tasks, <1500 tokens for complex
-
STRUCTURE — Format as a context packet (v2 — see Output Format and references/brief-template.md)
-
VALIDATE — Check packet completeness:
- Does it include the task goal?
- Does it include constraints that could cause failure?
- Does it include what was already tried?
- Does it include
### Out of scope? (mandatory) - Does it include
### Type Surface(mandatory if task >= 300 tokens)? - Is it small enough for the target agent's context budget?
-
PHASE 4.5 — SMELL TESTS — Run mechanical regex gates before emit. See references/durability-rules.md.
Regex Tier Reason \b\S+\.[a-z]{1,4}:\d+\bBLOCK file:line reference (e.g., login.ts:42) — line numbers go stale^- \S*[\\/]\S+\.(ts|js|py|go|rs|java)\boutside### Files TouchedBLOCK Path-only bullet in narrative \b(line |on line )\d+\bBLOCK "line 42" / "on line 100" \b(src|lib|app)/\S+in narrative paragraphsWARN Path mention; verify it belongs in Files Touched section -
EMIT — Send the validated packet to the receiving agent.
Output Format (v2)
markdown## Context Packet **Task**: [One-line behavioral description, verb-led] **Parent**: [delegating skill] **Scope**: [type names / module names — NOT file paths] ### Decisions Made - [Decision]: chose [X] over [Y] because [reason] ### Constraints - MUST: [behavioral assertion] - MUST NOT: [behavioral prohibition] - BLOCKED BY: [contract dependency, not file path] ### Already Tried - [approach] — [observable failure mode] ### Type Surface (durable) - `TypeName { field: type }` — [what it represents] - `Module.method(input: T): Result<O, E>` — [contract] ### Files Touched (locator-only, may rename) - `path/to/file.ts` (TypeName, Module.method) — [behavioral hint] ### Acceptance Criteria - [ ] [verb-led testable statement starting with: accepts, rejects, produces, notifies, persists, retries, times-out, validates, returns, dispatches, redirects, throws, logs, increments, decrements, retrieves, emits, caches, invalidates, authenticates] - [ ] ... ### Out of scope - [Thing the receiver should NOT do] - (or "(none)" if explicitly empty) ### Progress - [partial state if mid-handoff — omit if fresh start]
Full template + worked examples: references/brief-template.md.
Variant: Agent Brief (Async / Durable Handoff)
The standard packet (above) is for immediate sub-agent dispatch in the same session. When the handoff target is async — issue tracker, scheduled cron agent, rune:autopilot (Pro) for multi-session work, or any receiver that may execute hours or days later — switch to the agent brief variant.
Agent brief adds two durability principles on top of the standard packet:
- Durability over precision — describe interfaces, types, and behavioral contracts. NEVER reference line numbers in narrative. File paths only in
### Files Touched(locator-only, may rename). - Behavioral, not procedural — describe WHAT the system should do, not HOW to implement it. The async agent will explore the codebase fresh.
Additional BLOCK-tier checks for agent briefs (on top of the standard smell tests):
**Category:**line present (bug/enhancement/refactor)- Both
**Current behavior:**and**Desired behavior:**sections present - Acceptance criteria are independently testable (each pass/fail alone)
**Key interfaces:**names types/functions, not file paths
Full template + worked examples: references/agent-brief.md.
Returns
| Field | Type | Description |
|---|---|---|
packet | markdown | Structured context packet ready for subagent injection |
token_estimate | number | Estimated token count of the packet |
completeness | enum | full / partial / minimal — how much context was captured |
warnings | string[] | Missing context that could cause subagent failure |
Constraints
- MUST include task goal and acceptance criteria — subagent needs to know when it's done
- MUST include failed attempts — prevents subagent from repeating mistakes
- MUST include hard-stop constraints — prevents constraint violations in delegated work
- MUST NOT exceed 2000 tokens — context packets that are too large defeat the purpose
- MUST NOT include full file contents — use type names + summaries instead
- MUST NOT fabricate context — only include information from the actual conversation
- MUST emit
### Out of scopesection — empty(none)allowed, missing section is rejected by completion-gate - MUST emit
### Type Surfacesection for tasks >= 300 tokens — durable contract spine - MUST pass all BLOCK-tier smell tests — no file:line references, no "line N", no narrative path-only bullets
- MUST use behavior verbs in Acceptance Criteria — shape verbs ("is defined", "has property") rejected
Sharp Edges
| Failure Mode | Severity | Mitigation |
|---|---|---|
| Packet too large (>2000 tokens) | HIGH | Compress aggressively — type names not file contents, decisions not discussions |
| Missing constraint causes subagent violation | CRITICAL | Always scan for MUST/MUST NOT in parent conversation |
| Stale context from prior session included | MEDIUM | Cross-check session-bridge state with current files |
| Over-constraining subagent with parent's approach | MEDIUM | Include constraints and goals, not implementation approach (unless approach is the constraint) |
| File:line references in packet (rotting briefs) | CRITICAL | Phase 4.5 BLOCK gate — regex \b\S+\.[a-z]{1,4}:\d+\b catches them; rewrite to type/function names |
Narrative paragraphs with bare paths (src/auth/) | MEDIUM | WARN tier — surface and rewrite or move to Files Touched table |
| Missing Type Surface section for non-trivial task | HIGH | Mandatory for tasks >= 300 tokens; the durable spine is what survives file moves |
| Missing Out of scope section | HIGH | Always required (even "(none)"); completion-gate rejects briefs without it |
| Acceptance Criteria using shape verbs ("is defined", "has property") | MEDIUM | Rewrite to behavior verbs from the whitelist |
| Async handoff (issue tracker / autopilot / scheduled run) emitted as standard packet | HIGH | Switch to agent-brief variant (references/agent-brief.md) — standard packet rots when receiver runs hours/days later. Brief adds durability rules: behavioral not procedural, no line numbers in narrative |
Agent brief with file:line references in narrative ("change auth.ts:42") | CRITICAL | Brief BLOCK gate — line numbers go stale on first edit. Reference type names, function signatures, contracts instead. File paths only in ### Files Touched |
Agent brief without **Current behavior:** AND **Desired behavior:** split | HIGH | Brief BLOCK gate — without the delta explicit, async agent cannot verify when work is done |
Self-Validation
SELF-VALIDATION (run before emitting output): - [ ] Packet includes a clear task goal (verb-led) - [ ] Packet includes acceptance criteria (verb-led, testable, not vague) - [ ] All MUST/MUST NOT constraints from parent are present - [ ] Failed attempts are listed (if any exist) - [ ] Token estimate is under 2000 - [ ] No full file contents embedded (type names + paths only) - [ ] No file:line references anywhere (regex check) - [ ] No bare-path narrative bullets outside Files Touched - [ ] ### Out of scope section present (even if "(none)") - [ ] ### Type Surface section present (if task >= 300 tokens) - [ ] Files Touched entries include (TypeName, function) annotations IF ANY check fails → fix before reporting done. Do NOT defer to completion-gate.
Done When
- Context packet emitted in structured format
- Token estimate calculated and within budget
- All constraints from parent conversation captured
- Completeness level assessed honestly
- Self-Validation checklist: all checks passed
Cost Profile
~200-500 input tokens (scanning conversation) + ~300-800 output tokens (generating packet). Haiku model — minimal cost per invocation.
Scope guardrail: Do not implement code changes, run tests, or modify files. Only produce context packets for handoff. If asked to do more, defer to the delegated skill.
