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, rescue before 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 packet
• context-engine (L3): check current context budget before deciding packet size

Called By (inbound)

• cook (L1): before Phase 2-5 subagent spawning
• team (L1): before dispatching parallel workstreams
• rescue (L1): before delegating module-level refactoring
• scaffold (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 sessions
• plan (L2): phase files with task breakdowns

Workflow

1. 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.

2. 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

3. STRUCTURE — Format as a context packet (v2 — see Output Format and references/brief-template.md)

4. 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?

5. 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+\b	BLOCK	file:line reference (e.g., login.ts:42) — line numbers go stale
   ^- \S*[\\/]\S+\.(ts|js|py|go|rs|java)\b outside ### Files Touched	BLOCK	Path-only bullet in narrative
   \b(line |on line )\d+\b	BLOCK	"line 42" / "on line 100"
   \b(src|lib|app)/\S+ in narrative paragraphs	WARN	Path mention; verify it belongs in Files Touched section

6. EMIT — Send the validated packet to the receiving agent.

Output Format (v2)

## 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:

1. 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).
2. 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

1. MUST include task goal and acceptance criteria — subagent needs to know when it's done
2. MUST include failed attempts — prevents subagent from repeating mistakes
3. MUST include hard-stop constraints — prevents constraint violations in delegated work
4. MUST NOT exceed 2000 tokens — context packets that are too large defeat the purpose
5. MUST NOT include full file contents — use type names + summaries instead
6. MUST NOT fabricate context — only include information from the actual conversation
7. MUST emit ### Out of scope section — empty (none) allowed, missing section is rejected by completion-gate
8. MUST emit ### Type Surface section for tasks >= 300 tokens — durable contract spine
9. MUST pass all BLOCK-tier smell tests — no file:line references, no "line N", no narrative path-only bullets
10. 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.