Task Supervisor

1. Plan before parallel execution - Never run parallel sub-tasks without a written plan
2. Detect collisions before launch - Check write-write AND read-write overlaps
3. Route models by complexity - Use the cheapest model that can do the job well
4. Isolate sub-task writes - Each sub-task gets its own folder in .subagents/{run_id}/
5. Single status file - One .subagents/{run_id}/status.json per run, no denormalization
6. Monitor via status, not transcripts - Read transcripts only for failed sub-tasks
7. Retry with escalation - Same model → escalate model → escalate to user
8. Keep artifacts minimal - Status files are JSON, no prose reports

DO NOT

• Do NOT execute without a written plan in .subagents/{run_id}/manifest.json
• Do NOT run parallel sub-tasks without collision analysis
• Do NOT use expensive models for simple tasks
• Do NOT read transcripts unless a sub-task failed
• Do NOT write prose in status files - use JSON only
• Do NOT allow two sub-tasks to write to the same file
• Do NOT skip the review phase
• Do NOT exceed 3 iterations without escalating to user

Execution Flow

Phase 0: Decide Mode

Evaluate task complexity:

• If ≤2 files, no dependencies, straightforward: light mode → skip to Phase 4 with inline plan
• Otherwise: full mode → proceed to Phase 1

Phase 1: Plan

For tasks with >5 sub-tasks, use incremental planning:

1. Plan first 3 sub-tasks
2. Execute them
3. Plan next batch based on results
4. Continue until complete

This reduces upfront token cost and allows course correction.

Before planning, think step by step:

1. What is the core goal?
2. What are the natural boundaries?
3. What could go wrong?
4. What's the simplest decomposition?

Then:

1. Generate a unique run_id (e.g., run-20240101-abc123)
2. Create .subagents/{run_id}/ directory
3. Parse the user's task into discrete sub-tasks
4. For each sub-task, identify:
   • What files it will write to (write_scope)
   • What files it needs to read (read_scope)
   • Dependencies on other sub-tasks (depends_on)
   • Estimated complexity (low, medium, high)
   • Sub-task type: implementation, test, investigation, or review
5. Write the plan to .subagents/{run_id}/manifest.json
6. Run scripts/validate_plan.py to validate the plan shape
7. Run scripts/check_collisions.py --read-write to detect write-write AND read-write overlaps

Phase 2: Resolve Collisions

1. If check_collisions.py finds overlaps:
   • Write-write: sequentialize (add depends_on) or merge into single sub-task
   • Read-write: make the reader depend on the writer
   • Update manifest and re-validate
2. If no overlaps: proceed to parallel execution

Phase 3: Route Models

For each sub-task, assign model profile based on complexity:

See references/model-routing.md for the full routing matrix and escalation rules.

Phase 3.5: Pre-Flight Checks

Before executing any sub-task:

1. Verify all files in write_scope parent directories exist
2. Verify all files in read_scope exist
3. Verify test commands are available
4. Verify working directory is correct
5. Record baseline file checksums for rollback

Phase 4: Execute

If parallel execution fails:

1. Capture all partial outputs

2. Switch to sequential execution mode

3. Re-run sub-tasks in dependency order

4. Compare outputs to verify consistency

5. Initialize .subagents/{run_id}/status.json:

   {
     "run_id": "run-20240101-abc123",
     "state": "running",
     "started_at": "2024-01-01T00:00:00Z",
     "iterations": 1,
     "subtasks": {}
   }
   

6. For each sub-task, add entry to status.json:

   "subtask-1": {
     "state": "pending",
     "model_profile": "balanced",
     "retries": 0
   }
   

7. Execute sub-tasks in dependency order:

   • Parallel: sub-tasks with no collisions and no unmet dependencies
   • Sequential: sub-tasks with dependencies or resolved collisions
   • Solo: if only one sub-task or all collide, execute directly

8. For each sub-task execution:

   • Update state to "running", record started_at
   • Capture full transcript to transcript.log
   • On success: state "done", record finished_at, duration_seconds
   • On failure: state "failed", record error, finished_at

Phase 5: Monitor and Retry

1. Check status.json for overall progress
2. If a sub-task fails:
   • Retry 1: Same model, pass error context from previous attempt
   • Retry 2: Escalate one model tier (fast→balanced, balanced→deep), pass full transcript
   • Retry 3: Escalate to user with transcript excerpt and error summary
3. If a sub-task writes outside its write_scope: flag as scope violation in status
4. If a sub-task exceeds timeout_seconds (default 300): kill and mark as failed

Phase 6: Review

1. Read status.json - if all sub-tasks "done", proceed
2. For any "failed" sub-tasks: read their transcript.log to diagnose
3. Run the project's test suite (if applicable)
4. Update status.json with review results:

   {
     "run_id": "run-20240101-abc123",
     "state": "done",
     "started_at": "...",
     "finished_at": "...",
     "iterations": 1,
     "review": {
       "passed": true,
       "subtask_results": {},
       "total_duration_seconds": 120
     },
     "subtasks": { ... }
   }
   

5. If passed: false and iterations < 3: go back to Phase 4 with fixes
6. If passed: false and iterations >= 3: escalate to user

Phase 7: Cleanup

1. Remove .subagents/{run_id}/ folder if user confirms success
2. Or keep for audit trail if user wants to review

Common Mistakes to Avoid

1. Over-planning simple tasks - Don't create 5 sub-tasks for a 2-file change
2. Ignoring read-write collisions - A writes X, B reads X = race condition
3. Using deep model for boilerplate - Waste of tokens and time
4. Not declaring dependencies - Parallel sub-tasks that depend on each other will fail
5. Writing prose in status files - Use JSON only, keep it machine-readable
6. Skipping collision check - Always run both write-write and read-write checks
7. Blind retries - Always pass error context, escalate model on retry 2
8. No timeout - Sub-tasks can hang indefinitely without timeout_seconds

Sub-Agents Directory Structure

.subagents/
└── {run_id}/
    ├── manifest.json              # Full execution plan (write-once)
    ├── status.json                # Single source of truth for all status
    ├── subtask-1/
    │   ├── transcript.log         # Full execution log
    │   └── artifacts/             # Test outputs, diffs (optional)
    ├── subtask-2/
    │   ├── transcript.log
    │   └── artifacts/
    └── subtask-N/
        ├── transcript.log
        └── artifacts/

Manifest Contract

See references/plan-contract.md for the full JSON schema.

Key fields:

• task: Overall task description
• cwd: Working directory
• subtasks[]: Array of sub-task definitions
• execution_mode: "parallel", "sequential", or "solo"
• budget_policy: "cost-optimized", "balanced", or "quality-first"

Example Manifest

{
  "$schema_version": "1.0",
  "task": "Add user authentication",
  "cwd": "/path/to/project",
  "run_id": "run-20240101-abc123",
  "subtasks": [
    {
      "id": "auth-types",
      "type": "implementation",
      "description": "Add auth types and interfaces",
      "write_scope": ["src/types/auth.ts"],
      "read_scope": ["src/types/index.ts"],
      "depends_on": [],
      "complexity": "low",
      "model_profile": "fast",
      "success_criteria": ["Types compile", "No conflicts"]
    },
    {
      "id": "login-api",
      "type": "implementation",
      "description": "Implement login endpoint",
      "write_scope": ["src/api/auth.ts"],
      "read_scope": ["src/types/auth.ts", "src/db/connection.ts"],
      "depends_on": ["auth-types"],
      "complexity": "medium",
      "model_profile": "balanced",
      "success_criteria": ["Login works", "Tests pass"]
    }
  ],
  "execution_mode": "sequential",
  "budget_policy": "balanced"
}

Sub-Task Types

Collision Detection

See references/collision-detection.md for the full rules. Load this reference only when analyzing collisions.

Key rules:

1. No two sub-tasks should write to the same file (write-write)
2. No sub-task should read a file another sub-task writes (read-write)
3. If overlap is unavoidable: sequentialize or merge
4. Runtime: monitor for writes outside declared write_scope

Model Routing

See references/model-routing.md for the full routing matrix. Load this reference only when routing models.

Key principle: use the cheapest model that can do the job well. Escalate only on real triggers:

• Repeated test failures
• Hidden dependencies
• Ambiguous requirements
• Changes to shared infrastructure

Monitoring and Review

See references/monitoring-and-review.md for the full process. Load this reference only during monitoring and review phases.

Key points:

• Single status file per run, no denormalization
• Read transcripts only for failed sub-tasks
• Review is structured JSON within status file
• Iterate up to 3 times before escalation
• Retry with model escalation and error context

Validation Scripts

• scripts/validate_plan.py - Validates manifest JSON structure
• scripts/check_collisions.py - Detects write-write AND read-write scope overlaps

Run both scripts after writing the manifest and before launching any sub-tasks.

User Interrupt Handling

If the user provides new information mid-execution:

1. Pause all running sub-tasks
2. Assess impact on current plan
3. Update manifest if needed
4. Resume or replan based on changes

Graceful Degradation

If validation scripts fail or are unavailable:

1. Proceed with manual validation (check JSON structure yourself)
2. Perform collision detection manually (compare write scopes)
3. Log the degradation event in status.json
4. Continue execution with increased caution

Dry Run Mode

Before executing, optionally run in dry-run mode:

1. Validate manifest structure
2. Check for collisions
3. Verify file existence
4. Estimate token cost
5. Report findings without executing

Use dry-run for complex tasks to catch planning errors early.