---
name: controlflow-orchestration
description: "Use when executing a multi-step repository task in phases, especially when progress should be tracked with gates, approvals, retries, localized replanning, or optional subagent delegation instead of one long monolithic run."
---

# ControlFlow Orchestration

## Overview

Execute an approved plan with explicit state, disciplined gates, bounded retries, and Codex-local evidence. Keep ControlFlow's orchestration discipline without assuming VS Code agent runtime contracts.

## Local Contract

- Start from a saved plan, preferably `plans/<task-slug>-plan.md`; create one with `controlflow-planning` if needed.
- Confirm strict plan review before executing non-trivial work.
- Track current phase, last verification, blocker, and next action.
- Apply [../controlflow-planning/references/llm-behavior-guidelines.md](../controlflow-planning/references/llm-behavior-guidelines.md) for generic scope and verification discipline.

## Workflow

1. Confirm plan path, current phase, target files, validation command, and approval needs.
2. For non-trivial work, run or verify review routing first: `SMALL` -> `controlflow-plan-audit`; `MEDIUM`/`LARGE` -> add `controlflow-assumption-verifier`; `LARGE` -> add `controlflow-executability-verifier`; unresolved `HIGH` risk -> include `controlflow-assumption-verifier`.
3. If review blocks, revise the plan before implementation.
4. Run the **Pre-Wave Cache Guard** before each wave: inspect recent task artifacts for similar scope, surface a recommendation when useful, and never auto-complete work or skip approval.
5. Use wave execution only when write ownership is clearly disjoint; otherwise serialize phases. Present one approval request per ordinary wave; keep destructive, high-risk, failed, or blocked phases separately gated.
6. Keep immediate blocking work local. Use subagents only when delegation is available and the user explicitly wants it.
7. Use [references/failure-taxonomy.md](references/failure-taxonomy.md) and [references/runtime-policy.json](references/runtime-policy.json) for retry and replan decisions. Reduce later-wave parallelism when transient failures in the same wave reach the configured threshold.
8. Gate destructive or high-blast-radius actions behind explicit approval.
9. After each phase, run [references/phase-checklist.md](references/phase-checklist.md) checks and update user-visible state before moving on.
10. Refresh the context packet after each completed wave with verified facts, invalidated assumptions, changed paths, and next-wave reuse notes.
11. Save plan-review artifacts under `plans/artifacts/<task-slug>/` and keep them concise Markdown.

## Codex Subagent Delegation

ControlFlow-Codex is skill-first; it does not install a fixed VS Code-style subagent roster. It still supports Codex subagent delegation when the user explicitly asks for subagents, delegation, or parallel agent work and the runtime exposes `multi_agent_v1.spawn_agent`.

- Use `multi_agent_v1.spawn_agent` only for bounded sidecar work after identifying the local critical-path task.
- Prefer `explorer` subagents for specific read-only questions and `worker` subagents for disjoint write scopes.
- Give every subagent a concrete scope, ownership boundary, expected artifact, validation expectation, and "do not revert others' work" instruction.
- Store subagent outputs under `plans/artifacts/<task-slug>/` so orchestration can review, summarize, and resume without relying on chat memory.
- If subagent tooling is unavailable or not explicitly authorized, serialize the same work locally with the relevant `$controlflow-*` skills and record the reason in `## Decision Log`.

## Portable Evidence And Challenge

- Before changing a shared prompt, schema, validator, template, or public interface, run a shared-component usage impact scan and record likely consumers.
- Use [references/source-grounding.md](references/source-grounding.md) when execution depends on external framework or API claims.
- Use [references/decision-challenge.md](references/decision-challenge.md) once for a high-risk or non-trivial decision whose failure would materially change the plan.

## Stop-the-Line Guidance

Stop the phase before starting the next one when verification fails, a plan assumption proves false, a security/data/contract risk appears, or required approval is missing. Retry only with a recorded diagnosis. Replan the affected phase when the fix changes files, dependencies, acceptance criteria, phase order, or blast radius.

## Change Sizing Heuristic

Use roughly 100 changed lines per phase as a soft reviewability target. Split unrelated concerns, overlapping write sets, or broad ownership crossings. Document exceptions for mechanical fixture, generated, or documentation-heavy edits where verification remains clear.

## Orchestration-Specific Failure Checks

- Do not continue after a failed phase without classification and diagnosis.
- Do not retry the same command repeatedly without changing the smallest relevant variable.
- Do not merge nearby but unrelated phase outcomes under one gate.
- Do not treat plan-review blockers as advisory.

## References

- `references/runtime-policy.json`
- `references/failure-taxonomy.md`
- `references/phase-checklist.md`
- `references/tdd-patterns.md`
- `references/source-grounding.md`
- `references/decision-challenge.md`
- `../controlflow-planning/references/llm-behavior-guidelines.md`