Context Aware Delegation

---
name: context-aware-delegation
description: Understand agent context isolation and write effective prompts for spawned agents. Use when orchestrating multi-agent workflows to ensure subagents receive complete, self-contained context.
---

# Context-Aware Delegation Skill

> **Purpose:** Help coordinators understand and leverage agent context isolation
> **Created:** 2025-12-29
> **Audience:** Program coordinators, ORCHESTRATOR agents, anyone spawning subagents

---

## The Core Model: Context Isolation

**Spawned agents have their own isolated context** - they do NOT inherit the parent's conversation history.

```
┌─────────────────────────────────────────────────────────┐
│  Parent Agent (ORCHESTRATOR)                            │
│  ┌─────────────────────────────────────────────────┐   │
│  │ Conversation History                             │   │
│  │ - User request                                   │   │
│  │ - File reads                                     │   │
│  │ - Previous decisions                             │   │
│  │ - Context accumulated over session               │   │
│  └─────────────────────────────────────────────────┘   │
│                         │                               │
│                    Task tool                            │
│                         │                               │
│          ┌──────────────┼──────────────┐               │
│          ▼              ▼              ▼               │
│    ┌──────────┐   ┌──────────┐   ┌──────────┐         │
│    │ Agent A  │   │ Agent B  │   │ Agent C  │         │
│    │ ──────── │   │ ──────── │   │ ──────── │         │
│    │ EMPTY    │   │ EMPTY    │   │ EMPTY    │         │
│    │ context  │   │ context  │   │ context  │         │
│    │          │   │          │   │          │         │
│    │ Only has │   │ Only has │   │ Only has │         │
│    │ YOUR     │   │ YOUR     │   │ YOUR     │         │
│    │ PROMPT   │   │ PROMPT   │   │ PROMPT   │         │
│    └──────────┘   └──────────┘   └──────────┘         │
└─────────────────────────────────────────────────────────┘
```

### What This Means for You

| What Parent Has | What Subagent Gets |
|-----------------|-------------------|
| Full conversation history | **NOTHING** - starts empty |
| Files you've read | Must read them again |
| Decisions you've made | Must be told explicitly |
| Context from user | Must be passed in prompt |

---

## L3 Minimal Context Pattern (VALIDATED 2026-01-10)

**Key Discovery:** Subagents can autonomously invoke MCP tools with just mission intent + parameters.

### Context Levels Comparison

| Level | Identity | Mission | Explicit Tools | Parameters | Result |
|-------|----------|---------|----------------|------------|--------|
| L1 | Yes | Yes | Yes | Yes | MCP used (expected) |
| L2 | Yes | Yes | No | Yes | MCP used + RAG |
| **L3** | No | Yes | No | Yes | **MCP used (3 tools!)** |
| L4 | No | Minimal | No | No | Failed (file search) |

### L3 Prompt Template

```markdown
## MISSION
[Clear objective: "Assess Block 10 schedule compliance"]
[Domain context if needed: "medical residency schedule"]

[Key parameters]
- Dates: 2026-01-06 to 2026-01-31
- Requirements: ACGME compliance check

## OUTPUT
[Expected structure - JSON/markdown]
```

### When to Use L3

| Scenario | Use L3? |
|----------|---------|
| Clear mission, known domain | Yes |
| MCP tools available for task | Yes |
| Agent has standing orders | Yes |
| Uncertain requirements | No (use L2) |
| Novel task, no tools | No (use L1) |

### Anti-Pattern: Over-Contextualizing

**Wrong:** 2000 tokens of identity card + explicit tool instructions for clear tasks
**Right:** 100 tokens of mission intent + parameters (L3)

---

## Key Insight: Mid-Task Updates Don't Affect Running Agents

**Updating an agent's specification file while it's running has ZERO effect on the running instance.**

This is non-obvious but important:

```
Timeline:
─────────────────────────────────────────────────────────────────────

 T=0   ORCHESTRATOR spawns COORD_PLATFORM with Task tool
       └─ Agent receives snapshot of context from prompt

 T=1   COORD_PLATFORM is executing its task...
       └─ Running with T=0 context (frozen)

 T=2   META_UPDATER edits COORD_PLATFORM.md (fixes broken refs)
       └─ File on disk changes

 T=3   COORD_PLATFORM completes and returns results
       └─ Still using T=0 context - UNAWARE of T=2 changes

 T=4   ORCHESTRATOR spawns COORD_PLATFORM again for new task
       └─ THIS instance gets the updated spec (if included in prompt)
─────────────────────────────────────────────────────────────────────
```

### Why This Matters

1. **Safe parallel updates:** You can run an agent AND update its documentation simultaneously
2. **No "hot reload" surprises:** Running agents won't suddenly change behavior
3. **Blueprints vs. soldiers:** The `.md` spec is a blueprint; spawned agents are soldiers already deployed
4. **Only future spawns see updates:** Changes take effect on the NEXT spawn, not current execution

### Practical Implications

| Scenario | Safe? | Why |
|----------|-------|-----|
| Update agent spec while agent runs | ✅ Yes | Running agent has frozen context |
| Fix broken refs in `.claude/Agents/` during multi-agent operation | ✅ Yes | Each agent operates independently |
| Change agent's constraints mid-task | ❌ Won't work | Agent won't see the change |
| Update shared documentation (CLAUDE.md) | ✅ Safe for running agents | They already read it at spawn |

**Bottom line:** Treat spawned agents like deployed units. Updating HQ's playbook doesn't radio new orders to troops already in the field.

---

## The Golden Rule

> **Write prompts as if the agent knows NOTHING about your session.**

Think of spawning an agent like calling a function:
- You must pass all parameters explicitly
- You cannot rely on global state
- The function only knows what you tell it

---

## What to Include in Agent Prompts

### Required Elements Checklist

```markdown
□ Agent persona/role (who they are)
□ Explicit file paths (absolute, not relative)
□ Complete task description (what to do)
□ Success criteria (how to know when done)
□ Constraints (what NOT to do)
□ Expected output format (how to report back)
```

### Context Transfer Template

```markdown
## Agent: [AGENT_NAME]

**Role:** [Brief description of agent's expertise]

**Relevant Context:**
- [Key fact 1 from parent conversation]
- [Key fact 2 the agent needs to know]
- [Decision already made that affects this task]

**Files to Read:**
- `/absolute/path/to/file1.py` - [why this file matters]
- `/absolute/path/to/file2.md` - [what to look for]

## Task

[Clear, specific task description]

## Constraints

- [Constraint 1]
- [Constraint 2]

## Expected Output

Return:
1. [What to include in response]
2. [Format expectations]
```

---

## Anti-Patterns: What NOT to Do

### Anti-Pattern 1: Assuming Shared Context

```markdown
❌ BAD:
"Fix the bug we discussed earlier"

✅ GOOD:
"Fix the null reference error in /backend/app/services/swap_executor.py:142
where `person.assignments` is accessed before checking if person exists.
The error occurs when a swap request references a deleted faculty member."
```

### Anti-Pattern 2: Vague File References

```markdown
❌ BAD:
"Check the scheduler file for issues"

✅ GOOD:
"Read /backend/app/scheduling/engine.py and verify that the
generate_schedule() function properly handles the case where
no faculty are available for a given rotation."
```

### Anti-Pattern 3: Implicit Decisions

```markdown
❌ BAD:
"Implement the solution"

✅ GOOD:
"Implement retry logic using exponential backoff (2s, 4s, 8s, 16s).
We decided to use this approach because the API has rate limiting.
Maximum 4 retries before failing permanently."
```

### Anti-Pattern 4: Missing Success Criteria

```markdown
❌ BAD:
"Make the tests pass"

✅ GOOD:
"Fix the failing test in /backend/tests/test_swap_executor.py::test_rollback.
The test expects SwapExecutor.rollback() to restore the original assignment
within 24 hours. Currently it's returning None instead of the Assignment object.
Success = test passes AND no other tests regress."
```

---

## Prompt Templates by Agent Type

### SCHEDULER Agent

```markdown
## Agent: SCHEDULER

**Charter:** Handle all scheduling operations with ACGME compliance as top priority.

**Context:**
- Academic year: [YEAR]
- Block being scheduled: [BLOCK_NUMBER] ([START_DATE] to [END_DATE])
- Known constraints: [LIST ANY SPECIAL CONSTRAINTS]

**Files:**
- `/backend/app/scheduling/engine.py` - Core scheduling logic
- `/backend/app/scheduling/acgme_validator.py` - Compliance rules

## Task

[Specific scheduling task]

## Constraints

- Never violate ACGME 80-hour rule
- Maintain 1-in-7 day off requirement
- Verify backup database exists before writes

## Expected Output

1. Schedule assignments (JSON or table format)
2. Any ACGME warnings generated
3. Coverage gaps if any exist
```

### QA_TESTER Agent

```markdown
## Agent: QA_TESTER

**Charter:** Ensure code quality through comprehensive testing.

**Context:**
- Feature being tested: [FEATURE_NAME]
- Related PR/commit: [REFERENCE]
- Test framework: pytest (backend) / Jest (frontend)

**Files to Test:**
- `/backend/app/services/[service].py` - Implementation
- `/backend/tests/test_[service].py` - Existing tests (if any)

## Task

Write tests for [SPECIFIC FUNCTIONALITY].

## Test Requirements

- Cover happy path
- Cover error cases: [LIST SPECIFIC ERRORS]
- Cover edge cases: [LIST EDGE CASES]
- Use fixtures from conftest.py where available

## Expected Output

1. Test file with pytest tests
2. List of scenarios covered
3. Any mocking requirements identified
```

### ARCHITECT Agent

```markdown
## Agent: ARCHITECT

**Charter:** Design robust database schemas and API interfaces.

**Context:**
- Current models: [LIST RELEVANT MODELS]
- Problem being solved: [DESCRIPTION]
- Integration points: [OTHER SYSTEMS AFFECTED]

**Files:**
- `/backend/app/models/[model].py` - Current schema
- `/backend/alembic/versions/` - Migration history

## Task

Design [SCHEMA/API CHANGE].

## Constraints

- Must maintain backward compatibility with: [LIST]
- Must support: [REQUIREMENTS]
- Migration must be reversible

## Expected Output

1. Schema design (SQLAlchemy model)
2. Migration strategy
3. API contract changes (if any)
4. Rollback plan
```

---

## Context for Built-in Agent Types

Some Task tool `subagent_type` options have special context behavior:

| subagent_type | Context Behavior |
|---------------|------------------|
| `general-purpose` | Isolated - needs full prompt |
| `Explore` | Can see conversation history before tool call |
| `Plan` | Can see conversation history before tool call |
| `claude-code-guide` | Isolated - searches docs independently |

### Using "Access to Current Context" Agents

For `Explore` and `Plan` agents, you can write shorter prompts:

```markdown
## With Explore agent (HAS context access):

Task(
  prompt="Find where the scheduling conflict we discussed is handled",
  subagent_type="Explore"
)
# Works because Explore can see prior conversation

## With general-purpose agent (NO context access):

Task(
  prompt="""
  Find where scheduling conflicts are detected in the codebase.

  Specifically looking for:
  - Time overlap detection between assignments
  - ACGME work hour limit checks
  - Faculty double-booking prevention

  Search in /backend/app/scheduling/ directory.
  """,
  subagent_type="general-purpose"
)
# Must be explicit because agent starts fresh
```

---

## Parallel Agent Context Strategy

When spawning multiple agents in parallel, each needs independent context:

```markdown
## Parallel Spawn Pattern

# Agent 1: Code Review
Task(
  description="QA_TESTER: Review swap logic",
  prompt="""
  ## Agent: QA_TESTER

  Review /backend/app/services/swap_executor.py for:
  - Error handling completeness
  - Edge case coverage
  - ACGME compliance checks

  Return: List of issues found with line numbers
  """,
  subagent_type="general-purpose"
)

# Agent 2: Security Audit (PARALLEL - different context)
Task(
  description="ARCHITECT: Security review",
  prompt="""
  ## Agent: ARCHITECT (Security Focus)

  Audit /backend/app/services/swap_executor.py for:
  - SQL injection risks
  - Authorization bypass
  - Data exposure in logs

  Return: Security findings with severity ratings
  """,
  subagent_type="general-purpose"
)

# Agent 3: Test Generation (PARALLEL - different context)
Task(
  description="QA_TESTER: Generate tests",
  prompt="""
  ## Agent: QA_TESTER

  Generate pytest tests for SwapExecutor.execute_swap() in
  /backend/app/services/swap_executor.py

  Cover:
  - Successful one-to-one swap
  - Swap with ACGME violation (should fail)
  - Rollback within 24-hour window
  - Rollback after 24-hour window (should fail)

  Return: Complete test file content
  """,
  subagent_type="general-purpose"
)
```

---

## Result Synthesis: Getting Information Back

Subagents return a single message. Design your prompts to get structured output:

### Structured Output Request

```markdown
## Expected Output Format

Return a JSON object:
```json
{
  "status": "success" | "failure" | "partial",
  "findings": [
    {
      "file": "path/to/file.py",
      "line": 42,
      "issue": "description",
      "severity": "high" | "medium" | "low",
      "suggestion": "how to fix"
    }
  ],
  "summary": "one-line summary",
  "next_steps": ["recommended action 1", "recommended action 2"]
}
```
```

### Aggregating Multiple Agent Results

```markdown
After spawning 3 parallel agents, synthesize:

1. Collect all findings
2. Deduplicate (same issue found by multiple agents)
3. Prioritize by severity
4. Create unified action plan

Use synthesis pattern from delegation-patterns.md:
- All-or-Nothing: For compliance checks
- Merge-Deduplicate: For findings/issues
- Weighted: For scoring/ranking
```

---

## Quick Reference Card

```
┌─────────────────────────────────────────────────────────┐
│           CONTEXT-AWARE DELEGATION CHEATSHEET           │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  REMEMBER: Subagents start with EMPTY context           │
│                                                         │
│  ALWAYS INCLUDE:                                        │
│  □ Agent role/persona                                   │
│  □ Absolute file paths                                  │
│  □ Complete task description                            │
│  □ Constraints and boundaries                           │
│  □ Expected output format                               │
│                                                         │
│  NEVER ASSUME:                                          │
│  ✗ Agent knows conversation history                     │
│  ✗ Agent has read files you read                        │
│  ✗ Agent knows decisions you made                       │
│  ✗ Agent understands implicit context                   │
│                                                         │
│  CONTEXT-AWARE TYPES:                                   │
│  • Explore, Plan → CAN see prior conversation           │
│  • general-purpose → CANNOT, needs full prompt          │
│                                                         │
│  THINK LIKE A FUNCTION CALL:                            │
│  spawn_agent(                                           │
│    role="QA_TESTER",                                    │
│    files=["/path/to/file.py"],                          │
│    task="Write tests for X",                            │
│    constraints=["no mocking DB"],                       │
│    output_format="pytest file"                          │
│  )                                                      │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

---

## Identity Card Integration

When spawning ANY PAI agent, load their identity card for proper boot context:

### Pattern
```python
Task(
  prompt=f"""
  ## BOOT CONTEXT
  {read('.claude/Identities/AGENT_NAME.identity.md')}

  ## MISSION
  [Task description]

  ## CONSTRAINTS
  [Any additional constraints]

  ## OUTPUT FORMAT
  [Expected output]
  """,
  subagent_type="general-purpose"
)
```

### Why Identity Cards?
- Agent knows who they are (role, tier)
- Agent knows chain of command (reports to, can spawn)
- Agent knows standing orders (pre-authorized actions)
- Agent knows escalation triggers (when to ask)
- Agent knows constraints (what NOT to do)

### Identity Card Location
All identity cards are in `.claude/Identities/[AGENT_NAME].identity.md`

### Available Identity Cards
Current identity cards in the system:
- `ARCHITECT.identity.md` - Database and API architecture specialist
- `SYNTHESIZER.identity.md` - Multi-source synthesis and integration specialist
- `TEMPLATE.identity.md` - Template for creating new identity cards

**Note:** If spawning an agent that doesn't have an identity card yet, follow the template at `.claude/Identities/TEMPLATE.identity.md` to create one.

---

## Related Skills

- **startupO**: Initialize ORCHESTRATOR mode (loads this skill)
- **CORE/delegation-patterns.md**: Execution patterns (parallel, sequential, hybrid)
- **CORE/spawn-with-identity.md**: Identity card loading patterns
- **MCP_ORCHESTRATION**: Tool-level orchestration
- **agent-factory**: Create new agent personas

---

## Version

- **Created:** 2025-12-29
- **Author:** Claude Code Session
- **Applies to:** Claude Code CLI, Claude Agent SDK
- **Last Updated:** 2026-01-06 (Added identity card integration)

---

*Effective delegation requires explicit context transfer. Write prompts as if teaching a capable colleague who just joined the project today.*