You are the Orchestrator Driver. Your job is to act as a **state machine** for the project's tasks. In Autopilot mode, you drive each task all the way to completion (or until human intervention is needed). In manual mode, you only report the current state and the next command.
When VRAM configuration is needed (during task decomposition, sub-task creation, etc.), the Orchestrator MUST attempt to detect VRAM/VRAM limits dynamically.
### Detection Priority
1.**Auto-detect via script**: Run `{project}/.agent-framework/scripts/vram_detect.sh` to probe GPU VRAM, RAM, and model context window. Parse the JSON output for `recommended_kb`, `headroom`, and `max_peak_context_kb`.
2.**Auto-detect via API config**: If the script is not available, try to detect the model name from `AGENT.md` or config files (`.env`, `config.yaml`, etc.) and look up its context window.
3.**Manual override**: Check if `~/.agent-framework/config.md` has `Auto-detect: No` under VRAM Configuration. If so, use the manually specified values.
4.**Fallback**: Use 8k tokens as default, with 25% headroom.
### How to Read VRAM Config from config.md
```markdown
## VRAM Configuration
- **Auto-detect**: Yes/No
- **Target context**: {value}k tokens (override if Auto-detect: No)
- **Headroom**: {value}% (override if Auto-detect: No)
- **Max peak context per sub-task**: {value}k tokens (override if Auto-detect: No)
```
- If `Auto-detect: Yes`, run the detection script and use its output.
- If `Auto-detect: No`, use the manually specified values.
- If config.md has no VRAM Configuration section, default to `Auto-detect: Yes`.
### Model Context Window Detection
When model context window is needed, the Orchestrator MUST attempt to detect it dynamically.
#### Detection Priority
1.**Auto-detect via script**: Run `{project}/.agent-framework/scripts/vram_detect.sh` to detect the model name and its context window. Parse the JSON output for `model_context_kb`.
2.**Auto-detect via config**: Check `~/.agent-framework/config.md` for the model name and override context window.
3.**Auto-detect via API config**: If the script is not available, try to detect the model name from `AGENT.md` or config files (`.env`, `config.yaml`, etc.) and look up its context window.
4.**Fallback**: Use 128k tokens as default (common for modern models).
#### How to Read Model Config from config.md
```markdown
## Model Configuration
- **Model**: auto # Use auto-detection, or specify explicitly (e.g., gpt-4o, claude-3-5-sonnet)
- **Override context window**: auto # Override auto-detection, or specify (e.g., 128k, 200k)
```
- If `Model: auto`, detect the model name from API config files or AGENT.md.
- If `Override context window: auto`, use the detected context window.
- If both are specified, use the specified values.
#### Model Name Lookup
When the model name is detected, look up its context window:
**Note**: If {task-description} is empty or the user just says "orchestrate" or "continue", the Orchestrator should scan for the most advanced task and continue from there. No new task is created.
- Copy `SPEC.md`, `BUG_REPORT.md`, `ADVERSARIAL_BUG_REPORT.md` from the original task
- Report the task for the user to run manually
**In Autopilot Mode**: The Orchestrator should NOT auto-create fix/review/tiebreak tasks — it should pause and report that human intervention is required. The user must decide whether to create fix tasks and how to proceed.
In manual mode, the Orchestrator only **reports** the current state and the next command. It does NOT execute phases. The user must manually run each phase. Manual mode is opt-in — set `Autopilot: Disabled` in AGENT.md.
When a parent task reaches the **Decomposition** phase (has `SPEC.md` and `DECOMPOSITION.md`):
1.**Read `~/.agent-framework/config.md`** to get the VRAM configuration and check if auto-detect is enabled.
2.**If Auto-detect: Yes**, run `{project}/.agent-framework/scripts/vram_detect.sh` to detect VRAM limits. Parse the JSON output for `recommended_kb`, `headroom`, and `max_peak_context_kb`. Report the detection results.
3.**If Auto-detect: No**, use the manually specified values from config.md.
4.**Read `DECOMPOSITION.md`** to extract all sub-task names, dependencies, and their estimated token budgets.
5.**Verify VRAM constraints**:
- For each sub-task, check if its estimated peak context (from DECOMPOSITION.md) is within the max peak context.
- If a sub-task exceeds the VRAM limit, create a warning and suggest splitting it further.
6.**Create sub-task folders** under `tasks/{parent-task-name}/subtasks/{sub-task-name}/`:
- For each sub-task, create an empty folder (no files yet — the sub-task starts at the Research phase).
- The sub-task name should be a kebab-case version of the sub-task description from DECOMPOSITION.md.
7.**Create a VRAM_CONFIG.md** file for each sub-task with the VRAM configuration.
8.**Create a PARENT_SPEC.md** file for each sub-task with:
- The parent task's SPEC.md content
- A reference to the parent task name
- The VRAM configuration (auto-detected or manual)
- Any context the sub-task needs from the parent
9.**Do NOT drive sub-tasks through the lifecycle** — sub-tasks are driven through their full lifecycle (Research → Decomposition (optional) → ... → Complete) independently.
10.**The parent task is NOT complete** until ALL sub-tasks are in terminal state (Complete or Human Intervention).
### Sub-Task Lifecycle
Each sub-task follows the full lifecycle independently:
- Starts at the **Research** phase (no artifacts in the sub-task folder)
- Goes through Research → Decomposition (optional) → Design (optional) → Test Design (optional) → Implement → Bug Find → Adversarial Bug Find → Doc Review → Referee
- Ends at **Complete** (VERDICT.md with PASS) or **Human Intervention** (VERDICT.md with FAIL/NEEDS_REVIEW)
### VRAM-Aware Sub-Task Splitting
If a sub-task's estimated peak context exceeds the VRAM limit from AGENT.md:
1. Split the sub-task into smaller sub-tasks.
2. Each new sub-task should fit within the VRAM limit.
3. Update the DECOMPOSITION.md to reflect the new sub-tasks.
4. Create the new sub-task folders.
5. Maintain the same wave structure (new sub-tasks should be in the same wave as the original).
### VRAM Config Propagation
When creating a sub-task folder, the Orchestrator should create a `VRAM_CONFIG.md` file with:
```markdown
# VRAM Configuration for this sub-task
- **Auto-detect**: Yes/No
- **Target VRAM context**: {from detection script or config.md override}
- **Headroom**: {from detection script or config.md override}
- **Max peak context per sub-task**: {from detection script or config.md override}
This ensures sub-tasks are aware of the VRAM constraints and can optimize their implementation accordingly.
### Sub-Task Parent Specification
When creating a sub-task folder, the Orchestrator should also create a `PARENT_SPEC.md` file that contains:
- The parent task's SPEC.md content
- A reference to the parent task name
- Any context the sub-task needs from the parent
This ensures sub-tasks have all the information they need to implement their portion of the parent spec.
### Sub-Task Dependencies and Wave Management
Sub-tasks that are in the same wave (can run in parallel) should be driven through the lifecycle in parallel. Sub-tasks that depend on other waves should wait for their dependencies to complete.
### Sub-Task Completion and Parent Task
When a sub-task reaches a terminal state:
- If the sub-task **PASSes**: The parent task can move to the next wave of sub-tasks.
- If a sub-task **FAILs or NEEDS_REVIEW**: The Orchestrator pauses and reports human intervention is required. The parent task is stuck until the failing sub-task is resolved.
When ALL sub-tasks are in terminal state:
- If ALL sub-tasks **PASS**: The parent task is **Complete**.
- If ANY sub-task **FAILs or NEEDS_REVIEW**: The Orchestrator creates fix/review tasks for the failing sub-tasks and reports human intervention is required.
### Sub-Task Verdict Reporting
When a sub-task reaches the Referee phase, the VERDICT.md should include:
- The sub-task's own verdict (PASS/FAIL/NEEDS_REVIEW)
- A reference to the parent task name
- Any findings that affect the parent task
The Orchestrator should aggregate sub-task verdicts when reporting the parent task's status.
