Skills
skills/fyrsmithlabs/marketplace/context-folding

context-folding

SKILL.md

Context Folding

Create isolated branches for complex sub-tasks. Each branch has its own token budget and cleans up on return, preventing context bloat.

Prerequisites: contextd Integration

Context folding uses contextd MCP tools:

  • branch_create - Create isolated context branch
  • branch_return - Return summary and cleanup branch
  • branch_status - Monitor budget and hierarchy

If contextd unavailable: Context folding degrades to inline execution (no isolation).

When to Use

Use context folding when:

  • Investigating a problem requiring many file reads
  • Running exploratory work that would bloat context
  • Multi-step sub-tasks with verbose intermediate steps
  • Parallel agent coordination is needed
  • Task complexity is STANDARD or COMPLEX tier

Don't use when:

  • Task is SIMPLE tier (< 3 steps)
  • Results need to stay in main context
  • You're at end of session anyway

Tools

branch_create

{
  "session_id": "my-session",
  "description": "Brief description of the sub-task",
  "prompt": "Detailed instructions for the branch",
  "budget": 4096,
  "timeout_seconds": 300,
  "parent_branch_id": "br_parent123"
}
Parameter Required Default Description
session_id Yes - Session identifier
description Yes - Brief description (shown in status)
prompt No - Detailed instructions
budget No 8192 Token budget
timeout_seconds No 300 Auto-return timeout
parent_branch_id No - Parent branch for nesting

branch_return

{
  "branch_id": "br_abc123",
  "message": "Summary of findings",
  "return_value": { "key": "structured data" }
}
Parameter Required Description
branch_id Yes Branch to return from
message Yes Summary (scrubbed for secrets)
return_value No Structured data for parent

branch_status

{ "branch_id": "br_abc123" }

Or check active branch:

{ "session_id": "my-session" }

Returns:

{
  "status": "active",
  "budget_total": 8192,
  "budget_used": 3421,
  "budget_remaining": 4771,
  "budget_percent": 42,
  "depth": 2,
  "parent_id": "br_parent123",
  "children": ["br_child456", "br_child789"],
  "timeout_remaining_seconds": 180
}

Complexity-Based Budget Allocation

Integrate with complexity-assessment skill to determine appropriate budgets:

Tier Budget Timeout Rationale
SIMPLE 4096 120s Quick investigation, minimal context
STANDARD 8192 300s Multi-file analysis, moderate exploration
COMPLEX 16384 600s Deep investigation, cross-system analysis

Adaptive allocation pattern:

1. Run complexity-assessment on sub-task
2. Map tier to budget:
   - SIMPLE (5-8): budget=4096
   - STANDARD (9-12): budget=8192
   - COMPLEX (13-15): budget=16384
3. Create branch with calculated budget

Observability

Real-Time Budget Monitoring

Check budget proactively during branch execution:

# Check at natural breakpoints
branch_status(branch_id) -> {
  budget_percent: 72,
  budget_remaining: 2294,
  warning_level: "caution"
}

Warning Levels:

Percent Used Level Action
0-70% normal Continue execution
70-85% caution Consider wrapping up
85-95% warning Begin summarization
95-100% critical Force return

Branch Hierarchy Visualization

For nested branches, use branch_status with session to see full tree:

branch_status(session_id: "main") -> {
  hierarchy: {
    "br_root": {
      status: "active",
      budget_percent: 45,
      children: {
        "br_analysis": { status: "active", budget_percent: 72 },
        "br_testing": { status: "completed", budget_percent: 89 }
      }
    }
  }
}

Token Usage Breakdown

Monitor what consumes budget:

branch_status(branch_id, detailed: true) -> {
  usage_breakdown: {
    file_reads: 1200,
    searches: 800,
    tool_calls: 400,
    reasoning: 1021
  }
}

Adaptive Budget Management

Dynamic Warnings

Implement threshold-based warnings:

# After each significant operation
status = branch_status(branch_id)

if status.budget_percent >= 95:
  # CRITICAL: Force immediate return
  branch_return(branch_id, message: "Budget exhausted: {partial_findings}")

elif status.budget_percent >= 85:
  # WARNING: Begin summarization
  # Summarize findings, stop new exploration

elif status.budget_percent >= 70:
  # CAUTION: Plan exit strategy
  # Complete current task, avoid new threads

Graceful Degradation

When approaching limits, auto-summarize:

# At 85% budget
1. Stop exploratory work
2. Consolidate findings so far
3. Create summary of discovered patterns
4. Return with partial results + "investigation incomplete" flag

branch_return(
  branch_id,
  message: "Partial analysis (budget: 87%): Found 3 of estimated 5 patterns...",
  return_value: {
    complete: false,
    findings: [...partial...],
    unexplored: ["area1", "area2"]
  }
)

Dependency DAG

Branch Dependencies

Track dependencies between parallel branches:

# Create independent branches
br_auth = branch_create(description: "Analyze auth module")
br_db = branch_create(description: "Analyze DB schema")

# Create dependent branch
br_integration = branch_create(
  description: "Analyze auth-DB integration",
  depends_on: [br_auth, br_db]  # Waits for these to complete
)

Parallel Branch Coordination

For orchestration patterns:

# Phase 1: Independent branches (parallel)
branches = [
  branch_create(description: "Task A"),
  branch_create(description: "Task B"),
  branch_create(description: "Task C")
]

# Monitor all branches
for br in branches:
  status = branch_status(br)
  # Track completion

# Phase 2: Collect results
results = [branch_return(br) for br in branches]

# Phase 3: Dependent work using results
branch_create(
  description: "Synthesize findings",
  prompt: "Combine results: {results}"
)

Return Value Propagation

Pass structured data between branches:

# Child branch returns structured data
branch_return(
  branch_id: "br_analysis",
  message: "Found 3 security issues",
  return_value: {
    issues: [
      { severity: "high", file: "auth.go", line: 42 },
      { severity: "medium", file: "db.go", line: 108 },
      { severity: "low", file: "utils.go", line: 15 }
    ],
    recommendations: ["Add input validation", "Use parameterized queries"]
  }
)

# Parent receives return_value for further processing

Error Handling

Branch Timeout Handling

Branches auto-return on timeout. Handle gracefully:

# Timeout returns partial results
branch_return(
  branch_id,
  message: "TIMEOUT: Partial results after 300s",
  return_value: {
    timed_out: true,
    completed_steps: ["step1", "step2"],
    incomplete_steps: ["step3", "step4"],
    partial_findings: {...}
  }
)

# Parent should:
1. Check return_value.timed_out
2. Decide: retry with larger timeout OR accept partial
3. Record in memory for future budget planning

Failed Branch Recovery

When a branch fails:

# Branch encounters error
try:
  # ... work that might fail ...
except error:
  # Record remediation for future reference
  remediation_record(
    title: "Branch failure: {description}",
    problem: error.message,
    root_cause: "...",
    solution: "..."
  )

  # Return with error flag
  branch_return(
    branch_id,
    message: "FAILED: {error.summary}",
    return_value: {
      failed: true,
      error: error.message,
      partial_work: {...},
      recovery_suggestions: [...]
    }
  )

Orphaned Branch Cleanup

Detect and clean up orphaned branches:

# Check for orphaned branches at session start
status = branch_status(session_id: "main")

for branch in status.all_branches:
  if branch.status == "orphaned" or branch.timeout_exceeded:
    # Force return with cleanup
    branch_return(
      branch_id: branch.id,
      message: "CLEANUP: Orphaned branch recovered"
    )

    # Record for awareness
    memory_record(
      title: "Orphaned branch cleanup",
      content: "Branch {branch.description} was orphaned and cleaned up"
    )

Checkpoint Integration

Save Branch State

Before risky operations or at natural breakpoints:

# Within a branch, save checkpoint
checkpoint_save(
  session_id: current_session,
  name: "branch-{branch_id}-checkpoint",
  summary: "Mid-branch checkpoint: completed {steps}, next {remaining}",
  context: "Branch work in progress..."
)

Resume From Branch Checkpoint

# List available checkpoints
checkpoints = checkpoint_list(session_id)

# Find branch checkpoints
branch_checkpoints = [c for c in checkpoints if "branch-" in c.name]

# Resume specific branch state
checkpoint_resume(
  checkpoint_id: branch_checkpoint.id,
  level: "context"
)

Memory Recording at Boundaries

On Branch Create

memory_record(
  project_id: current_project,
  title: "Branch created: {description}",
  content: "Created branch for: {prompt}. Budget: {budget}.",
  outcome: "in_progress",
  tags: ["context-folding", "branch-start"]
)

On Branch Return

memory_record(
  project_id: current_project,
  title: "Branch completed: {description}",
  content: "Findings: {summary}. Budget used: {percent}%.",
  outcome: "success",  # or "partial" or "failed"
  tags: ["context-folding", "branch-complete"]
)

Cross-Branch State Sharing

Use memory for state that needs to persist across branches:

# In branch A: Record finding
memory_record(
  title: "Discovery: Auth pattern",
  content: "Found JWT validation in auth/middleware.go",
  tags: ["auth", "discovery", "branch-a"]
)

# In branch B: Search for related
results = memory_search(
  query: "auth pattern discovery",
  tags: ["discovery"]
)
# Use findings from branch A

Integration Patterns

With Orchestration Skill

# Orchestration creates branches for each task group
branch_create(
  description: "Group 1: Issues #42, #43",
  budget: 8192
)

# Launch task agents within branch
Task(subagent_type: "contextd:task-agent", ...)

# Return with group results
branch_return(message: "Group complete: 2 issues resolved")

With Complexity Assessment

# Before creating branch
tier = complexity_assessment(task_description)

# Map tier to budget
budget = {
  "SIMPLE": 4096,
  "STANDARD": 8192,
  "COMPLEX": 16384
}[tier]

# Create appropriately sized branch
branch_create(
  description: task_description,
  budget: budget
)

With Consensus Review

# Create branch for review work
branch_create(
  description: "Security review: {files}",
  budget: 4096
)

# Run review agents
# ... review work ...

# Return findings
branch_return(
  message: "Review complete: 2 findings",
  return_value: {
    verdict: "APPROVED_WITH_FINDINGS",
    findings: [...]
  }
)

Workflow

1. branch_create(session_id, description, budget) -> branch_id
2. memory_record(title: "Branch started: {description}")
3. Do work in the branch (read files, search, analyze)
4. branch_status(branch_id) - monitor budget at intervals
5. If budget >= 70%: plan exit strategy
6. If budget >= 85%: begin summarization
7. branch_return(branch_id, message, return_value)
8. memory_record(title: "Branch completed: {description}")

Example: Basic Usage

# Create branch for code analysis
branch_create(
  session_id: "main",
  description: "Analyze auth module structure",
  budget: 4096
) -> branch_id: "br_abc123"

# Record branch start
memory_record(title: "Branch: auth analysis started")

# Do analysis...
semantic_search("authentication handlers")
Read files, analyze patterns...

# Check budget mid-way
branch_status("br_abc123") -> budget_percent: 45

# Continue work...

# Return with summary
branch_return(
  branch_id: "br_abc123",
  message: "Auth module has 3 handlers: login, logout, refresh. Uses JWT with 15min expiry.",
  return_value: {
    handlers: ["login", "logout", "refresh"],
    token_type: "JWT",
    expiry: "15min"
  }
)

# Record completion
memory_record(title: "Branch: auth analysis complete", outcome: "success")

Example: Adaptive Budget with Warnings

# Create branch
br = branch_create(description: "Deep code analysis", budget: 8192)

# Work loop with monitoring
while work_remaining:
  status = branch_status(br)

  if status.budget_percent >= 85:
    # WARNING: Begin wrap-up
    summary = summarize_findings_so_far()
    branch_return(br, message: summary, return_value: {complete: false})
    break

  if status.budget_percent >= 70:
    # CAUTION: Prioritize remaining work
    work_remaining = prioritize(work_remaining)

  # Continue most important work
  do_next_task(work_remaining.pop())

# Normal completion
branch_return(br, message: final_summary, return_value: {complete: true})

Example: Parallel Branches with Dependencies

# Phase 1: Create parallel branches
br_frontend = branch_create(description: "Analyze frontend auth")
br_backend = branch_create(description: "Analyze backend auth")
br_database = branch_create(description: "Analyze auth tables")

# Phase 2: Execute in parallel (via Task tool)
Task(prompt: "Analyze frontend auth components", branch_id: br_frontend)
Task(prompt: "Analyze backend auth handlers", branch_id: br_backend)
Task(prompt: "Analyze user/session tables", branch_id: br_database)

# Phase 3: Collect results
results = {
  frontend: branch_return(br_frontend).return_value,
  backend: branch_return(br_backend).return_value,
  database: branch_return(br_database).return_value
}

# Phase 4: Synthesize (new branch)
br_synthesis = branch_create(description: "Synthesize auth analysis")
# Use results from all three branches...
branch_return(br_synthesis, message: "Full auth architecture documented")

Best Practices

Practice Why
Keep summaries concise Only essential info returns to parent
Use complexity-based budgets Match budget to task tier
Monitor at 70/85/95% thresholds Graceful degradation
Record memories at boundaries Cross-session learning
Use return_value for structured data Enable dependent processing
Checkpoint before risky operations Recovery capability
Clean up orphaned branches Prevent resource leaks

Common Mistakes

Mistake Fix
Not returning from branch Always call branch_return
Huge return messages Summarize, don't dump
Nesting too deep Max depth is 3
Ignoring timeout Branch auto-returns on timeout
Skipping budget monitoring Check at 70%, 85%, 95%
Not recording memories Record at branch start/end
Fixed budgets for all tasks Use complexity-based allocation
No error handling Handle timeouts and failures gracefully
Orphaned branches Clean up at session start

Anti-Patterns

Pattern Problem Solution
Budget guessing Under/over allocation Use complexity assessment
Ignore budget warnings Context overflow Monitor thresholds
No return_value Lost structured data Always return structured findings
Skip memory recording Lost cross-session context Record at boundaries
Monolithic branches Hard to recover Break into smaller branches
No checkpoint integration Can't resume Checkpoint before risky ops

Quick Reference

Scenario Action
Starting sub-task branch_create + memory_record
Mid-task check branch_status -> check budget_percent
Budget at 70% Plan exit strategy
Budget at 85% Begin summarization
Budget at 95% Force return
Task complete branch_return + memory_record
Before risky op checkpoint_save
Session start Check for orphaned branches
Error in branch Record remediation + return with error flag
Weekly Installs
1
Repository
fyrsmithlabs/marketplace
First Seen
Mar 2, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
amp1
cline1
opencode1
cursor1
kimi-cli1
codex1