Agents Flow
A multi-agent workflow for omp (Oh My Pi), an AI coding assistant that runs in your terminal.
Agents Flow splits nontrivial project work across a small team of specialized agents with strictly separated powers: one agent plans and validates, one independently reviews risky changes, and exactly one is allowed to edit your files. The agent that writes a change is never the one that approved it, and every change is tied to an acceptance check that is frozen before implementation starts.
Version 3.1.0 · License MIT · Requires omp with sub-agent spawning (depth ≥ 2)
Its lightweight sibling, Quick Flow, handles small bounded jobs in a single session with no delegation. See Quick Flow vs Agents Flow.
Table of contents
Why Agents Flow
A single AI agent doing everything — planning, editing, and grading its own work — has an obvious conflict of interest, and on large or risky jobs its mistakes compound. Agents Flow is built on three ideas:
-
Separation of powers. Planning, reviewing, and editing are done by different agents. No agent approves its own work, and only one agent (
smol) can touch your real files. -
Freeze before you act. The plan is written down as a numbered checklist — each item with exact files, an execution mode, and an observable acceptance check — and locked in before any edit happens. Committed checks can be strengthened later, but never silently weakened or dropped.
-
Proof over confidence. Bulk changes are rehearsed on a throwaway copy of the project before touching real files; scripts must pass independent review; and the final result is validated against the frozen acceptance checklist, not against the agent's own summary.
This costs more time and tokens than a single-agent run. That is the intended trade: use Agents Flow for work where a mistake is expensive, and Quick Flow for the rest.
Quick Flow vs Agents Flow
Quick Flow Agents Flow
Topology one agent, entirely in your live session orchestrator + PLAN + up to five specialist agents
Best for small, bounded, well-defined jobs multi-file, risky, or judgment-heavy jobs
Independent review none mandatory for scripts, risk-gated for batch edits
File editing
the session agent edits directly
only the dedicated smol agent edits
Speed fast slower, more thorough
Install one skill folder skill folder + six agent definitions
The two are deliberately incompatible: a Quick Flow invocation that turns out to need delegation pauses and asks you to switch, rather than quietly spawning agents.
The team
Each role is a separate omp agent, defined by its own file in agents/. Roles are spawned by exact name — the workflow never substitutes a general-purpose agent.
Role Agent file Edits your files? Responsibility
Orchestrator (your current session) no Structures your request into a workflow, launches PLAN, then becomes a passive relay: it forwards PLAN's messages and your answers verbatim, and displays the final report unmodified. It never inspects, edits, or adds its own summary.
PLAN
plan.md
no
Owns the run: inspects the project once, gathers specialist input, asks you at most one round of questions, freezes the checklist, routes review and implementation, validates the integrated result, and authors the final report.
SMOL
smol.md
yes — the only one
Implements the finalized checklist exactly. Refuses items with stale anchors or missing review records rather than improvising.
ADVISOR
reviewer.md
no
Independent reviewer. Every transformation script requires its explicit code approved verdict before touching real files; risky batch edits get a lighter structural review.
DESIGNER
designer.md
no
Read-only web/UI specialist: produces an implementation-ready specification before UI work and a visual review after it.
VISION
vision.md
no
Read-only PDF/image fidelity inspector. Renders only PLAN-assigned PDF pages into private temporary images (via restricted render_pdf_pages / render_pdf_region tools) and reports discrepancies against bounded criteria.
Semantic inspector
inspector_semantic.md
no
Narrow escalation for correctness judgments that structural inspection (searching, parsing, diffing) cannot settle.
How a run works
flowchart TD
U[You invoke agentsflow] --> O[Orchestrator structures the request<br/>and writes the workflow contract]
O --> P[PLAN: one proportional inspection<br/>of the project]
P --> S{Pre-freeze specialist needed?}
S -->|web/UI| D[DESIGNER specification]
S -->|narrow semantic doubt| I[Semantic inspector]
D --> Q
I --> Q
S -->|no| Q{Material user decision left?}
Q -->|yes| QQ[One questionnaire,<br/>at most 3 questions]
Q -->|no| F
QQ --> F[Freeze checklist:<br/>files + mode + acceptance check per item]
F --> R{Item risky or scripted?}
R -->|scripted| A[ADVISOR full review:<br/>code approved required]
R -->|risky batch| AL[ADVISOR-light structural review]
R -->|routine| SM
A --> SM[SMOL edits the real files]
AL --> SM
SM --> PD{Post-implementation specialist?}
PD -->|web/UI| D2[DESIGNER visual review<br/>+ PLAN browser check]
PD -->|PDF fidelity| V[VISION page inspection]
PD -->|none| PV
D2 --> PV
V --> PV[PLAN validates the integrated project<br/>against the frozen acceptance checklist]
PV --> H[Authorized housekeeping<br/>LaTeX intermediates only]
H --> Rep[Final report, relayed verbatim]
In sequence:
-
Structure and launch. The orchestrator turns your request into a binding workflow (goal, inputs, selected profiles, requirements, validation expectations), passes a mechanical authoring gate, and spawns PLAN. From this point it only relays messages.
-
Inspect once. PLAN performs one proportional inspection: locating the relevant files and call sites, diagnosing the problem, discovering the project's native build/test commands, and classifying every candidate change. Exhaustive corpus-wide counts are done only when a batch or scripted mode is under consideration.
-
Specialist input. Web/UI work gets a DESIGNER specification before the checklist is frozen; unresolved narrow correctness questions go to the semantic inspector.
-
Ask once, if at all. If a material decision remains that evidence cannot settle, PLAN sends one questionnaire (at most three questions). Zero questions is the norm — discoverable facts are never asked.
-
Freeze. PLAN commits a numbered checklist. Each item names its exact files, one of four execution modes, the intended change, and a focused observable acceptance check.
-
Review, then edit. Scripted transformations are dry-run on a whole project copy in
/tmpand must receive ADVISOR'scode approved; risky batches get ADVISOR-light. Only then does SMOL implement, and only what the checklist says. -
Validate and report. PLAN exercises the real integrated project — narrowest sufficient project-native checks, real browser interaction for UI, compilation and page inspection for LaTeX — performs authorized cleanup, and writes the final report, which the orchestrator shows you word for word.
Throughout the run, PLAN emits one-line status messages at phase boundaries (PLAN STATUS — <phase>: ...), and announces any operation expected to exceed 90 seconds, so you always know what state the run is in.
The workflow contract
By default a run is durable: the orchestrator writes two files under .agentsflow/ in your project before anything starts —
.agentsflow/AGENTS_WORKFLOW.md # the task-specific contract
.agentsflow/AGENTS_LAUNCHER.md # universal launcher pointing at it
The workflow records the goal, named inputs and boundaries, selected profiles, atomic requirements, facts PLAN must discover by inspection, validation expectations, and the stopping condition — plus a single Agents Flow skill version stamp for provenance. Each run authors a fresh workflow; a new run never overwrites a workflow you may still be running, taking a collision-free filename (AGENTS_WORKFLOW_<slug>.md) instead.
If you say "don't create workflow files," the same contract fields are passed directly in PLAN's spawn prompt instead (direct local branch); the runtime behavior after launch is identical.
A deliberate boundary: the orchestrator authors the contract without inspecting your project — no compiling, diagnosing, or site-hunting before PLAN exists. Anything that requires looking at the project is listed as a fact for PLAN to discover. This keeps the contract honest and the inspection in the hands of the agent that owns the run.
Task profiles
Profiles are composable rulebooks that define obligations — what must be preserved, what counts as done, what evidence proves it — never execution mechanics. There are 19, in four groups (full definitions in skills/agentsflow/references/profiles.md):
- Intent (exactly one primary): inquiry, diagnosis, repair, feature implementation, r