Understand what ControlFlow is, what it delivers, and why it exists. After this chapter you will know the difference between ControlFlow and other AI tools, and where to start exploring.
- Agent system — a coordinated set of AI agents with defined roles, contracts, and governance.
- Prompt repo — ControlFlow is a repository of agent prompts, schemas, and governance files — not a compiled application.
- Determinism — every decision follows a documented rule; no guessing, no silent assumptions.
ControlFlow is a multi-agent orchestration framework expressed as a set of Markdown prompt files, JSON schemas, and governance configuration. It defines how 13 AI agents collaborate to plan, implement, review, and ship engineering tasks reliably.
ControlFlow is NOT:
- A runtime server or compiled application.
- A code library you
npm install. - A chatbot or single-agent assistant.
- A low-code drag-and-drop workflow builder.
The repository delivers:
| Artifact | Count | Purpose |
|---|---|---|
Agent prompt files (*.agent.md) |
13 | Define role, scope, contracts, and tools for each agent |
JSON schemas (schemas/*.json) |
20 | Formal contracts for inter-agent communication |
Governance configs (governance/*.json) |
7 | Tool permissions, retry budgets, tier routing, model mapping |
Skill patterns (skills/patterns/*.md) |
20 | Reusable domain expertise loaded just-in-time |
Eval harness (evals/) |
~410 checks | Offline validation of schema compliance and behavioral invariants |
Documentation (docs/) |
— | Engineering policies, tutorials, architecture docs |
Without a structured multi-agent framework, LLM-based engineering assistance suffers from recurring failure modes:
- Hallucination — agents invent files, APIs, or behaviors that don't exist.
- Scope drift — agents change things outside their assigned scope.
- Silent assumptions — agents guess instead of asking.
- Missing rollback — destructive operations proceed without a recovery plan.
- Approval bypass — high-risk actions execute without human confirmation.
- Flaky outputs — results vary with no deterministic routing for failures.
ControlFlow addresses all six by enforcing:
- Adversarial plan review before any code is written.
- Schema-validated contracts between agents.
- Explicit human approval gates at phase boundaries.
- Deterministic failure classification and routing.
- Offline eval harness to catch regressions continuously.
A Planner authors phased plans. An Orchestrator governs their review and execution. Executor subagents implement phases. Reviewer subagents validate plans and code. Research subagents gather evidence. Every handoff is a schema-validated contract.
This tutorial is written for two audiences:
Newcomers (chapters 00–04): No prior ControlFlow knowledge required. You need only basic familiarity with Markdown, JSON, and software engineering concepts.
Mid-level developers (chapters 05–14): Assumes you have read chapters 00–04 and want to understand orchestration, planning, schemas, governance, and the eval harness in depth.
Practitioners (chapters 15–18): Hands-on case studies, exercises, a glossary, and an FAQ for day-to-day use.
After completing this tutorial you will be able to:
- Describe the role of each of the 13 agents in the system.
- Read any
*.agent.mdfile and understand its behavior, scope, and tool surface. - Explain how the Orchestrator state machine progresses from
PLANNINGtoCOMPLETE. - Classify any failure scenario into one of the 4 failure classes.
- Run
cd evals && npm testand interpret the output. - Contribute a new agent or schema following the process documented in CONTRIBUTING.md.
- Sequential — read chapters in order for a complete mental model.
- By trajectory — see the README for four curated reading paths.
- As a reference — chapters 03, 09, 10, 17, and 18 are designed for lookup.
- Name three things ControlFlow is not.
- What six failure modes does ControlFlow address?
- Which repository directory holds the offline eval harness?
- What is the relationship between Planner and Orchestrator?