automaton/prompts/subtask_management.md

Sub-Task Management

This document defines how the Orchestrator manages sub-tasks during the Decomposition phase.

Sub-Task Folder Structure

{project}/.automaton/tasks/parent-task/   → Parent task
  SPEC.md
  DECOMPOSITION.md
  .state
  .state.approvals
  subtasks/
    subtask-a/                → Sub-task (full lifecycle independently)
      .state
      .state.approvals
      ...
    subtask-b/
      .state
      .state.approvals
      ...

Sub-Task Creation Rules

When a parent task reaches Decomposition phase (has SPEC.md and DECOMPOSITION.md):

1. Read ~/.automaton/config.md to get VRAM configuration
2. Run VRAM detection if Auto-detect is Yes
3. Read DECOMPOSITION.md to extract sub-task names, dependencies, and token budgets
4. Verify VRAM constraints for each sub-task
5. For each sub-task:
   • Run python ~/.automaton/scripts/status.py --create-task {parent-task}/subtasks/{subtask-name} --project {project}
   • This creates the folder with .state = new
   • Write PARENT_SPEC.md with the sub-task's scope from DECOMPOSITION.md
   • Write VRAM_CONFIG.md with the VRAM configuration
6. Do NOT drive sub-tasks through the lifecycle — they are driven independently

Sub-Task Lifecycle

Each sub-task follows the full lifecycle independently:

• Starts at new (empty folder, .state = new)
• Goes through new → research → (decomposition or design or implement) → ... → complete
• Ends at complete (VERDICT.md with PASS) or human_intervention

Wave Enforcement

Sub-tasks in the same wave can run in parallel. Sub-tasks in later waves wait for all dependencies:

• Wave 1 sub-tasks run in parallel
• Wave 2 sub-tasks wait for all Wave 1 sub-tasks to reach terminal state
• The Orchestrator MUST NOT start Wave 2 until ALL Wave 1 sub-tasks are complete or blocked

Parent Task Completion

The parent task is NOT complete until ALL sub-tasks are in terminal state (complete or human_intervention).

If ANY sub-task FAILs or NEEDS_REVIEW:

• In Autopilot Mode: The Orchestrator should pause and report that human intervention is required
• In Manual Mode: The Orchestrator creates fix/review/tiebreak tasks

Sub-Task Verdict Aggregation

The Orchestrator MUST aggregate sub-task verdicts:

• If ANY sub-task FAILs or NEEDS_REVIEW, the parent task should be marked as Human Intervention
• The parent task status should include a summary: PASS: {count}, FAIL: {count}, NEEDS_REVIEW: {count}

VRAM Config Propagation

When creating a sub-task folder, write a VRAM_CONFIG.md file with:

# VRAM Configuration for this sub-task
- **Auto-detect**: Yes/No
- **Target VRAM context**: {from detection or config}k tokens
- **Headroom**: {percentage}%
- **Max peak context per sub-task**: {value}k tokens
- **GPU VRAM detected**: {value}GB or "None"
- **RAM detected**: {value}GB
- **Model context window**: {value}k tokens or "Unknown"
- **Framework overhead**: ~{value} tokens
- **This sub-task's estimated peak context**: {from DECOMPOSITION.md}k tokens
- **Fits within VRAM**: Yes/No

Sub-Task Fix Tasks

When a sub-task FAILs or NEEDS_REVIEW:

• Task name: {parent-task-name}-fix-{sub-task-name}
• Created via status.py --create-task
• Starts at bug_find phase (.state = bug_find)
• Copies SPEC.md, BUG_REPORT.md, ADVERSARIAL_BUG_REPORT.md from the sub-task