convez.ai
SkillAutomaçãoAvançado
Smithbox-ai

ControlFlow

Smithbox-ai/ControlFlow

Orquestração multi-agente com 13 especialistas e contratos P.A.R.T

Ver no GitHub
BomPluginScore · de 0 a 100

Sistema de orquestração multi-agente para VS Code Copilot, Claude Code, OpenAI Codex e Cursor. Coordena 13 agentes especializados sob contratos determinísticos P.A.R.T, com gates de confiabilidade estruturados e roteamento inteligente de falhas.

Instalação

$npx convez-ai Smithbox-ai/ControlFlow

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
14
Forks
0
Acompanhando
2
Saúde
71%
Último commit
há 4 meses
Versão
1.4.0
Issues abertas
0
Contribuidores
4

Casos de uso

  • Planejamento arquitetural estruturado com diagrama de fases
  • Execução paralela em ondas com auditoria de qualidade entre fases
  • Classificação e roteamento de falhas (transientes, consertáveis, replanejamento, escalação)

Veredito

Framework robusto para orquestração complexa de agentes em editores populares, com mecanismos maduros de planejamento, auditoria e tratamento de falhas. Indicado para quem precisa ir além de agentes únicos em projetos de engenharia exigentes.

README

A tradução para o português deste README ainda está na fila.

ControlFlow

CI Agents Eval License

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


Why ControlFlow?

Single AgentControlFlow (13 agents)
PlanningAgent guesses architecture on-the-flyPlanner runs structured idea interview, produces phased plan with Mermaid diagrams
Quality gatesNonePlanAuditor + AssumptionVerifier + ExecutabilityVerifier audit before implementation
ExecutionSequential, monolithicWave-based parallel execution with inter-phase contracts
FailuresSilent or catastrophicClassified (transient/fixable/needs_replan/escalate, plus model_unavailable) with bounded retry routing
Scope driftCommonLLM Behavior Guidelines enforce surgical changes
VerificationManualOffline 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

ScenarioAgentWhat happens
Abstract idea or vague goal@PlannerIdea interview → phased plan → Mermaid diagram
Detailed task, clear requirements@OrchestratorDispatches subagents → verification gates → phase-by-phase execution
Research question@ResearcherEvidence-based investigation with confidence scores
Quick codebase exploration@CodeMapperRead-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

TierScopeReview AgentsMax Iterations
TRIVIAL1–2 files, single concernNone (CodeReviewer still runs per-phase)—
SMALL3–5 files, single domainPlanAuditor2
MEDIUM6–15 files, cross-domainPlanAuditor + AssumptionVerifier5
LARGE15+ files, system-widePlanAuditor + AssumptionVerifier + ExecutabilityVerifier5

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

ClassificationActionMax Retries
transientRetry same agent3
fixableRetry with fix hint1
needs_replanDelegate to Planner1
escalateStop — present to user0
model_unavailableRetry same agent with model-substitution semantics, then escalate on exhaustionretry_budgets.model_unavailable_max

When any retry budget is exhausted the phase escalates to the user with accumulated failure evidence.

PlanAuditor and AssumptionVerifier intentionally exclude transient and may use model_unavailable when their assigned model is unreachable. ExecutabilityVerifier can use all five failure classifications.


Agent Architecture

Interaction diagram

graph TB
    User((User))

    subgraph Orchestration
        Orchestrator[Orchestrator<br/><i>conductor & gate controller</i>]
        Planner[Planner<br/><i>structured planning</i>]
    end

    subgraph "Adversarial Review"
        PlanAuditor[PlanAuditor<br/><i>plan audit</i>]
        AssumptionVerifier[AssumptionVerifier<br/><i>mirage detection</i>]
        ExecutabilityVerifier[ExecutabilityVerifier<br/><i>executability check</i>]
    end

    subgraph Research
        Researcher[Researcher<br/><i>evidence-first research</i>]
        CodeMapper[CodeMapper<br/><i>codebase discovery</i>]
    end

    subgraph Implementation
        CoreImplementer[CoreImplementer<br/><i>backend implementation</i>]
        UIImplementer[UIImplementer<br/><i>frontend implementation</i>]
        PlatformEngineer[PlatformEngineer<br/><i>CI/CD & infrastructure</i>]
    end

    subgraph Verification
        CodeReviewer[CodeReviewer<br/><i>code review & safety</i>]
        BrowserTester[BrowserTester<br/><i>scripted E2E & accessibility</i>]
    end

    subgraph Documentation
        TechnicalWriter[TechnicalWriter<br/><i>docs & diagrams</i>]
    end

    User -->|idea / vague goal| Planner
    User -->|detailed task| Orchestrator
    User -->|research question| Researcher
    User -->|codebase question| CodeMapper
    Planner -->|structured plan| Orchestrator
    Orchestrator -->|dispatch| Research
    Orchestrator -->|dispatch| Implementation
    Orchestrator -->|dispatch| Verification
    Orchestrator -->|dispatch| Documentation
    Orchestrator -->|audit| PlanAuditor
    Orchestrator -->|audit| AssumptionVerifier
    Orchestrator -->|audit| ExecutabilityVerifier

    style Orchestrator fill:#4A90D9,color:#fff
    style Planner fill:#7B68EE,color:#fff
    style PlanAuditor fill:#E74C3C,color:#fff
    style AssumptionVerifier fill:#E74C3C,color:#fff
    style ExecutabilityVerifier fill:#E74C3C,color:#fff
    style Researcher fill:#2ECC71,color:#fff
    style CodeMapper fill:#2ECC71,color:#fff
    style CoreImplementer fill:#F39C12,color:#fff
    style UIImplementer fill:#F39C12,color:#fff
    style PlatformEngineer fill:#F39C12,color:#fff
    style CodeReviewer fill:#1ABC9C,color:#fff
    style BrowserTester fill:#1ABC9C,color:#fff
    style TechnicalWriter fill:#9B59B6,color:#fff

Primary Agents

AgentFileRole
OrchestratorOrchestrator.agent.mdConductor, gate controller, delegation
PlannerPlanner.agent.mdStructured planning, idea interviews

Specialized Subagents

AgentFileRole
ResearcherResearcher-subagent.agent.mdEvidence-first research
CodeMapperCodeMapper-subagent.agent.mdRead-only codebase discovery
CodeReviewerCodeReviewer-subagent.agent.mdCode review and safety gates
PlanAuditorPlanAuditor-subagent.agent.mdAdversarial plan audit
AssumptionVerifierAssumptionVerifier-subagent.agent.mdAssumption-fact confusion detection
ExecutabilityVerifierExecutabilityVerifier-subagent.agent.mdCold-start plan executability simulation
CoreImplementerCoreImplementer-subagent.agent.mdBackend implementation
UIImplementerUIImplementer-subagent.agent.mdFrontend implementation
PlatformEngineerPlatformEngineer-subagent.agent.mdCI/CD, containers, infrastructure
TechnicalWriterTechnicalWriter-subagent.agent.mdDocumentation, diagrams, code-doc parity
BrowserTesterBrowserTester-subagent.agent.mdRuns provided E2E/accessibility scripts or harnesses; abstains when no executable harness is supplied

VS Code Copilot's Auto picker is the default model selection for every agent: Auto agents omit the model: frontmatter line and Copilot chooses the runtime model. Deterministic/pinned selection is the opt-in override for four control-plane agents (Orchestrator, Planner, PlanAuditor, AssumptionVerifier) listed in governance/model-routing.json pinned_agents, which carry a literal model: line. For internal orchestrated dispatch (via agent/runSubagent), ControlFlow resolves governance/model-routing.json at call time; in auto mode the outer model is intentionally omitted so Copilot auto-selects the subagent model, while deterministic mode passes the pinned model explicitly — see docs/agent-engineering/MODEL-ROUTING.md.


Evaluation Suite

cd evals && npm test is the canonical offline suite. It runs structural validation plus prompt-behavior, orchestration-handoff, drift, NOTES.md, archive-script, and fingerprint regression checks. No live agents, no network.

See evals/README.md for pass descriptions and how to add scenarios.


Project Structure

├── Orchestrator.agent.md          # Conductor agent
├── Planner.agent.md               # Planning agent
├── *-subagent.agent.md            # 11 specialized subagents
├── .github/
│   └── copilot-instructions.md    # Shared agent policy (loaded by all agents)
├── schemas/                       # JSON Schema contracts
├── docs/
│   ├── agent-engineering/         # Governance policies and reliability gates
│   ├── tutorial-en/               # Full English-language tutorial (19 chapters)
│   └── tutorial-ru/               # Full Russian-language tutorial (19 chapters)
├── governance/                    # Operational knobs and tool grants
├── skills/                        # Reusable domain pattern library (20 patterns)
├── evals/                         # Offline validation suite
│   └── scenarios/                 # Eval scenario fixtures
├── plans/                         # Plan artifacts and templates
├── plugins/
│   ├── controlflow-codex/         # Codex CLI plugin (10 portable skills)
│   └── controlflow-claude-code/   # Claude Code plugin (10 portable skills, 6 agents)
└── NOTES.md                       # Active objective state (repo-persistent)

Documentation

  • docs/tutorial-en/ — full English tutorial: architecture, agents, orchestration, planning, review pipeline, schemas, governance, skills, memory, failure taxonomy, evals, case studies, exercises, glossary, FAQ.
  • docs/tutorial-ru/ — то же на русском языке.
  • docs/agent-engineering/ — authoritative governance specs; see its README for the full, current index.
  • CONTRIBUTING.md — how to add agents, schemas, eval scenarios.
  • CHANGELOG.md — version history.

Installation

VS Code prompts directory:

  • Windows: %APPDATA%\Code\User\prompts
  • macOS: ~/Library/Application Support/Code/User/prompts
  • Linux: ~/.config/Code/User/prompts
  1. Clone this repository.

  2. Copy the entire repo contents into the prompts directory (or symlink the repo there).

  3. Enable custom agents in VS Code settings:

    {
      "chat.customAgentInSubagent.enabled": true,
      "github.copilot.chat.responsesApiReasoningEffort": "high"
    }
    
  4. Reload VS Code.

  5. Verify: type @Planner in Copilot Chat — the agent should appear in suggestions.

  6. Run evals: cd evals && npm install && npm test

Without .github/copilot-instructions.md agents will not have access to shared failure classification, conventions, and governance references.

Adding Custom Agents

Create a new .agent.md file following the P.A.R.T structure (Prompt → Archive → Resources → Tools). See CONTRIBUTING.md for the process documented there.


ControlFlow for Codex (Plugin)

A portable adaptation of ControlFlow for OpenAI Codex CLI, located in plugins/controlflow-codex/.

The plugin brings the core ControlFlow disciplines — phased planning, pre-execution plan review, assumption verification, orchestration, evidence-backed code review, and memory hygiene — into Codex without depending on VS Code-specific tool contracts, fixed agent rosters, or @Agent syntax.

Version 0.6.0 adds machine-checked selective parity through plugins/controlflow-shared-source/core-portability-matrix.json: portable workflow invariants are adopted or adapted, while model routing, tool grants, the fixed roster, session telemetry, compaction, budgets, and model_unavailable remain explicit divergences.

Included Skills

SkillAnalogous ControlFlow Role
$controlflow-routerEntry-point dispatcher
$controlflow-specSpec-before-plan capture
$controlflow-strict-workflowOrchestrator (full workflow entry point)
$controlflow-planningPlanner — writes plans/<task-slug>-plan.md
$controlflow-plan-auditPlanAuditor
$controlflow-assumption-verifierAssumptionVerifier
$controlflow-executability-verifierExecutabilityVerifier
$controlflow-orchestrationOrchestrator (execution-only path)
$controlflow-reviewCodeReviewer
$controlflow-memory-hygieneMemory hygiene

ControlFlow for Claude Code (Plugin)

A portable adaptation of ControlFlow for Claude Code, located in plugins/controlflow-claude-code/.

This plugin brings ControlFlow's planning, review, and orchestration discipline to Claude Code via namespaced skills and selected plugin agents. It provides a local development workflow, validation tools built for Claude Code's plugin marketplace, and preserves the strict artifact patterns that ControlFlow requires.

Local Development Usage

# Run Claude Code with the plugin directory loaded
claude --plugin-dir ./plugins/controlflow-claude-code

# Start a planning session natively
/controlflow-claude-code:controlflow-planning

Intentional Differences from VS Code

  • Workflow Skills: Planner and Orchestrator are implemented as skills (/controlflow-claude-code:x) rather than agents because they coordinate workflow logic instead of generating single analysis outputs.
  • Isolated Review Agents: Auditing and mapping roles that require safe, isolated execution (like AssumptionVerifier or CodeMapper) use native Claude Code plugin agents.

See plugins/controlflow-claude-code/README.md for full documentation.

Complexity routing matches the main project: TRIVIAL → optional; SMALL → plan-audit; MEDIUM → plan-audit + assumption-verifier; LARGE → full pipeline.

ControlFlow for Cursor

ControlFlow ships a Cursor plugin (level 3 integration): Project Rules, workflow Skills, and 11 project Subagents — approximating the VS Code 13-agent system without agent/runSubagent.

SurfaceLocationPurpose
Project Rules.cursor/rules/Conventions, orchestration discipline, eval gate
Skills.cursor/skills/Planner/Orchestrator workflow (controlflow-strict-workflow, planning, orchestration, review)
Subagents.cursor/agents/Isolated audit, research, implementer roles
Plugin packageplugins/controlflow-cursor/Install into other repositories

Quick start (this repo)

Open the project in Cursor (Agent mode). No extra install required.

Follow the controlflow-strict-workflow skill. Task: <your goal>. Save the plan to plans/<task-slug>-plan.md.

Install into another repository

powershell -ExecutionPolicy Bypass -File plugins/controlflow-cursor/scripts/install-project.ps1 -TargetRepo C:\path\to\your-app

What Cursor does and does not do

  • Does: Tiered plan → review → phased execution → review; artifacts under plans/; delegation via Task when available.
  • Does not: @Planner / @Orchestrator, VS Code runSubagent, or deterministic model-routing enforcement.

See docs/agent-engineering/CURSOR-SUPPORT.md and plugins/controlflow-cursor/USAGE.md.

ControlFlow for Codex Usage and Validation

Plugin Installation

From the repository root:

# Windows — installs to ~/plugins/controlflow-codex/ and registers in ~/.agents/plugins/marketplace.json
powershell -ExecutionPolicy Bypass -File plugins/controlflow-codex/scripts/install-home-local.ps1

# Re-install (replace existing)
powershell -ExecutionPolicy Bypass -File plugins/controlflow-codex/scripts/install-home-local.ps1 -Force

After installation, the plugin is available in Codex as $controlflow-* skills.

Usage

Recommended entry point for any non-trivial task:

Use $controlflow-strict-workflow to handle this repository task from plan through execution.

For individual steps:

# Write a strict plan artifact
Use $controlflow-planning to write a plan in plans/ for this task.

# Audit an existing plan before coding
Use $controlflow-plan-audit to review plans/my-task-plan.md.

# Check for hidden assumptions
Use $controlflow-assumption-verifier to find mirages in plans/my-task-plan.md.

# Execute an approved plan in phases
Use $controlflow-orchestration to execute plans/my-task-plan.md.

# Review completed implementation
Use $controlflow-review to review the completed implementation.

See plugins/controlflow-codex/USAGE.md for the full prompt catalog and plugins/controlflow-codex/README.md for detailed documentation.

Validating Codex Strict-Plan Artifacts

powershell -ExecutionPolicy Bypass -File plugins/controlflow-codex/scripts/validate-strict-artifacts.ps1 `
  -RepoRoot . `
  -PlanPath plans/my-task-plan.md `
  -StrictReviewByTier

The validate-strict-artifacts.ps1 script validates Codex strict-plan artifacts only. Do not use it for core VS Code plans. It enforces the mandatory lifecycle sections (## Progress, ## Discoveries, ## Decision Log, ## Outcomes, ## Idempotence & Recovery) in exact order. -StrictReviewByTier derives required review artifacts from tier and applicable unresolved HIGH risk; the existing -Require* switches remain additive compatibility controls.

Intentional Differences from the VS Code Version

  • Symphony daemon/runtime, Linear workflow, and Gem Team multi-plugin packaging were NOT imported.

  • No @Agent syntax or fixed subagent roster.

  • No agent/runSubagent dispatch or governance/model-routing.json — model selection is Codex's responsibility.

  • No VS Code-specific tool surfaces (vscode/askQuestions, read/problems, etc.).

  • Plan artifact structure (plans/<task-slug>-plan.md) and review artifact paths (plans/artifacts/<task-slug>/) are identical to the main project.

  • Skills use update_plan and local shell inspection rather than schema-driven chat payloads.


License

MIT. Copyright (c) 2026 ControlFlow Contributors.

Acknowledgments

ControlFlow was inspired by and builds upon ideas from:

Ver o original no GitHub

Bom para

Relacionados