# 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:
```markdown
# 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