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

• Quick Flow vs Agents Flow

• The team

• How a run works

• The workflow contract

• Task profiles

• Execution modes and review

• User interaction during a run

• Validation

• Safety guarantees

• Installation

• Usage

• Choosing the AI models

• Repository layout

• Troubleshooting

• Versioning

• License

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 /tmp and must receive ADVISOR's code 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