Planning Like Coding

Treat agent orchestration like writing a program. The main agent is main(). Sub-agents are function calls. Context isolation = scope.

Trace File

Every invocation writes a trace file — a human-readable log of what ran, in what order, and what each function found. The model never reads this file. It exists only for the user to inspect progress and audit results.

Location: <project-root>/.claude/traces/YYYY-MM-DD-HHmmss-<task-slug>.md

If .claude/traces/ doesn't exist, create it (on Unix: mkdir -p; on Windows: mkdir handles intermediate directories natively). If there is no clear project root (e.g. working from ~), fall back to ./.claude/traces/... relative to the current working directory.

Full structure (written incrementally across the workflow):

# Trace: <one-line task summary>
**Started**: YYYY-MM-DD HH:MM:SS
**Status**: running

## Pseudocode
(full pseudocode block with parallel/serial annotations)

## Execution Log

### func_X — completed HH:MM:SS (parallel|serial, batch N)
- **Status**: success | failed | partial
- **Evidence**: N data points found
- **Sources**: N files/URLs consulted
- **Contradictions**: N (within this function's own data)

**Findings**:
(human-readable summary — bullet lists for file paths, inline text for short strings)

## Assembled Result
(the final output shown to the user)

## Execution Summary
(table of aggregate stats — see Step 4)

When to write each section:

Workflow

1. Write pseudocode

Do NOT start executing. Output the plan:

main():
    parallel:
        result_A = func_A(input) → {field1: [items], field2: int}
        result_B = func_B(input) → [{field3: type, field4: type}]
    serial:
        result_C = func_C(result_A.field1) → {field5: type}
    return assemble(result_A, result_B, result_C)

func_A(input):
    Goal: one sentence describing what this function does
    Returns: {field1: [items], field2: int}

func_B(input):
    Goal: one sentence describing what this function does
    Returns: [{field3: type, field4: type}, ...]

func_C(dependency):
    Goal: one sentence; depends on result_A.field1
    Returns: {field5: type}

Execution strategy:

• No data dependency → same parallel batch
• Depends on one prior result → serial, after that function completes
• Depends on multiple prior results → serial, after the LAST dependency completes (note in pseudocode: // blocks on: A, B)
• Max 5 per parallel batch → split into successive batches in definition order

2. User confirms pseudocode

Show the pseudocode. Wait for explicit approval before dispatching.

If the user has said "just go ahead" or "don't ask for confirmation", skip confirmation for this session but still write pseudocode internally — it forces decomposition before action.

If the user modifies the pseudocode, only adjust the flagged functions. Leave unrelated ones untouched.

After confirmation, create the trace file with the header, status running, and ## Pseudocode section.

3. Dispatch sub-agents

Each function = one sub-agent (depth = 1). Prompt must include:

• The goal (one clear sentence)
• Input values from prior serial steps, if any
• The expected return format: { "meta": {...}, "data": {...} } JSON

Return format (every sub-agent must follow this):

{
  "meta": {
    "evidence_count": <int>,
    "source_count": <int>,
    "contradiction_count": <int>
  },
  "data": { <function-specific fields> }
}

The data field holds the function-specific payload. No Markdown, no prose — JSON only, so the main agent merges results without parsing natural language.

After each sub-agent returns, append to the trace file under ## Execution Log:

• Status line (success / failed / partial)
• The three meta numbers with brief parenthetical descriptions
• A human-readable "Findings" summary — convert paths to backticked relative links, convert short strings to inline text. Do NOT dump raw JSON here. The user reads this, not a parser.

Example trace entry:

### check_stale_notes — completed 14:30:23 (parallel, batch 1)
- **Status**: success
- **Evidence**: 3 (stale notes found)
- **Sources**: 342 (.md files scanned)
- **Contradictions**: 0

**Findings**: 3 notes unmodified >90 days out of 342 total:
- `20-Projects/archived-idea.md` — 213 days
- `30-Knowledge/old-pattern.md` — 157 days
- `00-Inbox/draft-2025-11.md` — 104 days

Sub-agent tools: Explore agents get only read/search tools (Read, Grep, Glob). General-purpose agents may also use Write, Edit, Bash. Never give a sub-agent tools it doesn't need.

Parallel limit: max 5 per batch. If more than 5 independent functions, split into batches of 5 in definition order.

Error handling:

4. Assemble results

Combine return values per the pseudocode's assemble() logic. Never inspect sub-agent internal context.

After assembly, finalize the trace file:

1. Append ## Assembled Result with the final output
2. Append ## Execution Summary:

| Metric | Value |
|--------|-------|
| Total functions | N |
| Parallel batches | N |
| Serial steps | N |
| Succeeded / failed | N / N |
| Contradictions found (cross-function) | N |
| Trace file | (relative path) |

Do NOT sum evidence_count or source_count across functions — evidence from "3 broken links" and "184.3 MB disk usage" are different dimensions and a total is meaningless. Report per-function in the Assembled Result instead.

1. Update the top-of-file status line from running to complete.

Sub-agent Prompt Template

Goal: {func_X's goal}

Input:
{concrete parameters from main agent, if any}

Return format (strict):
{
  "meta": {
    "evidence_count": <int>,
    "source_count": <int>,
    "contradiction_count": <int>
  },
  "data": { <fields> }
}

Return only the structured JSON. No extra explanation.

Context Passing

Main agent and sub-agent contexts are physically isolated. Never read a file ≥2KB just to pass it to a sub-agent — that shifts cost without saving tokens.

Exception: if the file is small (<2KB) and the sub-agent would need an expensive search to locate it, reading to pass can be a net win.

When to Use

• 3+ independent exploration dimensions
• Scanning/counting across non-overlapping directories or files
• Collecting data from multiple sources, single assembly step
• Requests implying "find everything about X, Y, and Z"

When NOT to Use

• Single-step tasks or tightly-coupled sequential steps (each doable with one Bash/Grep)
• User gave precise step-by-step instructions — follow them directly
• The only reason to read a file is to pass it to a sub-agent (anti-pattern: cost shift, not savings)

Example

See examples/vault-health-check.md — 5 parallel sub-agents, 59:1 context isolation, full trace file walkthrough.