ControlFlow

A multi-agent orchestration system for VS Code Copilot, plus maintained Codex, Claude, and Cursor plugins. ControlFlow coordinates 13 specialized agents under deterministic P.A.R.T contracts (Prompt → Archive → Resources → Tools), structured text outputs, and layered reliability gates.

---

Contents

• ControlFlow
  • Contents
  • Why ControlFlow?
  • Quick Start
  • When to Use Which Agent
  • Pipeline by Complexity
  • Orchestration State Machine
  • Failure Routing
  • Agent Architecture
    • Interaction diagram
    • Primary Agents
    • Specialized Subagents
  • Evaluation Suite
  • Project Structure
  • Documentation
  • Installation
    • Adding Custom Agents
    • Included Skills
  • ControlFlow for Claude Code (Plugin)
    • Installing the Plugin
    • Skills
    • Intentional Differences from VS Code
  • ControlFlow for Cursor
    • Plugin Installation
    • Usage
    • Validating Codex Strict-Plan Artifacts
    • Intentional Differences from the VS Code Version
  • License
  • Acknowledgments

---

Why ControlFlow?

	Single Agent	ControlFlow (13 agents)
Planning	Agent guesses architecture on-the-fly	Planner runs structured idea interview, produces phased plan with Mermaid diagrams
Quality gates	None	PlanAuditor + AssumptionVerifier + ExecutabilityVerifier audit before implementation
Execution	Sequential, monolithic	Wave-based parallel execution with inter-phase contracts
Failures	Silent or catastrophic	Classified (transient/fixable/needs_replan/escalate, plus model_unavailable) with bounded retry routing
Scope drift	Common	LLM Behavior Guidelines enforce surgical changes
Verification	Manual	Offline eval suite + CodeReviewer gates every phase

---

Quick Start

# 1. Clone
git clone https://github.com/Smithbox-ai/ControlFlow.git

# 2. Copy to your VS Code prompts directory (or symlink)
#    Windows: %APPDATA%\Code\User\prompts
#    macOS:   ~/Library/Application Support/Code/User/prompts
#    Linux:   ~/.config/Code/User/prompts

# 3. Enable in VS Code settings:
#    { "chat.customAgentInSubagent.enabled": true,
#      "github.copilot.chat.responsesApiReasoningEffort": "high" }

# 4. Reload VS Code → type @Planner in Copilot Chat

# 5. Verify evals
cd evals && npm install && npm test

First task? Type @Planner "Add OAuth login with Google" — the system handles the rest.

Quick project status? Run cd evals && npm run health for an offline, read-only operator report (git status by surface, NOTES.md state, plans by status, latest session outcome, artifact coverage).

---

When to Use Which Agent

Scenario	Agent	What happens
Abstract idea or vague goal	@Planner	Idea interview → phased plan → Mermaid diagram
Detailed task, clear requirements	@Orchestrator	Dispatches subagents → verification gates → phase-by-phase execution
Research question	@Researcher	Evidence-based investigation with confidence scores
Quick codebase exploration	@CodeMapper	Read-only discovery — files, dependencies, entry points

Typical workflow: @Planner authors a plan → you approve → @Orchestrator executes it with full subagent coordination, review gates, and approvals.

---

Pipeline by Complexity

Tier	Scope	Review Agents	Max Iterations
TRIVIAL	1–2 files, single concern	None (CodeReviewer still runs per-phase)	—
SMALL	3–5 files, single domain	PlanAuditor	2
MEDIUM	6–15 files, cross-domain	PlanAuditor + AssumptionVerifier	5
LARGE	15+ files, system-wide	PlanAuditor + AssumptionVerifier + ExecutabilityVerifier	5

Any plan with an unresolved HIGH-impact risk_review entry forces the full pipeline regardless of tier.

CodeReviewer still runs after each implementation, testing, documentation, or platform phase. Ordinary multi-phase waves use one user approval per wave; destructive/high-risk phases and phases that are FAILED or BLOCKED require per-phase approval. Todo completion remains per-phase.

---

Orchestration State Machine

stateDiagram-v2
    [*] --> PLANNING
    PLANNING --> WAITING_APPROVAL: plan ready
    WAITING_APPROVAL --> PLAN_REVIEW: user approved
    PLAN_REVIEW --> ACTING: audit passed
    PLAN_REVIEW --> PLANNING: needs revision
    WAITING_APPROVAL --> ACTING: trivial plan (skip review)
    ACTING --> REVIEWING: phase complete
    REVIEWING --> WAITING_APPROVAL: review / approval point
    WAITING_APPROVAL --> ACTING: next wave or phase approved
    WAITING_APPROVAL --> COMPLETE: all phases done
    COMPLETE --> [*]

Simplified — REJECTED transition, HIGH_RISK_APPROVAL_GATE, required PLAN_REVIEW ABSTAIN handling, and final review paths omitted for clarity. See Orchestrator.agent.md for the full state machine.

---

Failure Routing

Classification	Action	Max Retries
transient	Retry same agent	3
fixable	Retry with fix hint	1
needs_replan	Delegate to Planner	1
escalate