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