context-groups

Generate context groups from an existing task list, organizing tasks into batches that fit within AI context window limits.

Process

1. Parse arguments

   • $1 = Project name (optional)
   • --max-tokens=N = Maximum context window tokens (default: 100000)
   • --reserve=N = Reserved tokens for agent responses (default: 20000)

2. Locate and read the task file

   • If project name provided: Read tasks/$1.tasks.json
   • If no project name: Find most recently modified .tasks.json

3. Load token configuration

   • Read defaults from skills/spec-task-management/references/context-defaults.json
   • Apply any command-line overrides

4. Calculate token estimates for each task

   Use complexity-based estimation:

   Complexity	Base Tokens
   XS	500
   S	1,500
   M	4,000
   L	10,000
   XL	25,000

   Add overhead:

   • Base per task: 200 tokens
   • Per hard dependency: 100 tokens

5. Build dependency graph

   • Create adjacency list from hard dependencies
   • Detect any cycles (should already be handled)
   • Calculate in-degree for each task

6. Topological sort by execution phase

   • Order tasks by their execution_phase first
   • Within phase, order by dependency depth (tasks that unblock more come first)
   • Break ties by priority (critical > high > medium > low)

7. Bin-pack tasks into context groups

   effective_limit = max_tokens - reserve_tokens
   current_group = new group
   current_tokens = 0
   
   for each task in sorted_order:
       # Calculate tokens needed for task + any hard deps not yet assigned
       task_tokens = estimate_tokens(task)
       unassigned_dep_tokens = sum(estimate_tokens(d) for d in task.hard_deps if not d.assigned)
       total_needed = task_tokens + unassigned_dep_tokens
   
       # Check if task exceeds effective limit (oversized)
       if task_tokens > effective_limit:
           # Close current group if not empty
           if current_group.tasks.length > 0:
               mark_group_end(current_group.tasks.last)
               save_group(current_group)
   
           # Create dedicated group for oversized task
           oversized_group = new group with oversized_warning=true
           add_task(oversized_group, task)
           mark_group_start(task)
           mark_group_end(task)
           save_group(oversized_group)
   
           current_group = new group
           current_tokens = 0
           continue
   
       # Check if adding task exceeds limit
       if current_tokens + total_needed > effective_limit:
           # Close current group
           mark_group_end(current_group.tasks.last)
           save_group(current_group)
   
           # Start new group
           current_group = new group
           current_tokens = 0
   
       # Add unassigned hard dependencies first (in order)
       for dep in task.hard_deps:
           if not dep.assigned:
               if current_group.tasks.length == 0:
                   mark_group_start(dep)
               add_task(current_group, dep)
               current_tokens += estimate_tokens(dep)
   
       # Add the task
       if current_group.tasks.length == 0:
           mark_group_start(task)
       add_task(current_group, task)
       current_tokens += task_tokens
   
   # Close final group
   if current_group.tasks.length > 0:
       mark_group_end(current_group.tasks.last)
       save_group(current_group)
   

8. Handle dependency chains exceeding limit

   • If a chain of hard dependencies exceeds limit, split at minimum-cut points
   • Add context_handoff metadata to indicate split
   • Document which outputs from previous group are needed

9. Update task file

   • Add context_group_id to each task
   • Set context_group_start on first task of each group
   • Set context_group_end on last task of each group
   • Add estimated_tokens to each task
   • Add context_groups array at root level
   • Update metadata.context_config with configuration used
   • Set metadata.total_context_groups