controlflow-claude-code

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
  • ControlFlow for Codex (Plugin)
    • Included Skills
  • ControlFlow for Claude Code (Plugin)
    • Installing the Plugin
    • Skills
    • Intentional Differences from VS Code
  • ControlFlow for Cursor
  • ControlFlow for Codex Usage and Validation
    • 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