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.2.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.

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 — a required agent that is missing blocks the run with a clear notice; 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 mutating UI work and a visual review after it. Read-only UI questions skip 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[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.

Read-only runs (inquiry or diagnosis) and tasks without a writable project root keep your repository clean: their workflow pair is written under an external records root instead — the host's session store when it has one (omp's local://agentsflow), else ~/.agentsflow, else the OS temp directory. Required recovery packets use the same root.

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. You can also point a later request at an existing generated launcher: the orchestrator verifies the workflow file exists and stamps the current skill version, then launches PLAN on it without re-authoring — a stale or missing pair is reported with an offer of fresh authoring, never silently migrated.

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, refactor, optimization, translation, formatting, conversion.
Artifact (what is being edited): code, web UI, configuration/data, LaTeX documents, generic documents, generic files.
Evidence (optional overlays defining proof): build/test, visual/browser/PDF, source-reference.
Fallback: generic-fallback, used only when no artifact profile clearly applies; PLAN's first inspection resolves it into exactly one specific artifact profile.

Composition is constrained — read-only intents never combine with mutating ones, repair already includes diagnosis, editing requires an artifact profile — and PLAN may add a compatible profile that inspection proves applies, but may never remove or weaken one you selected.

Execution modes and review

After inspection, PLAN assigns exactly one mode to every checklist item. The mode determines what artifact PLAN must prepare and how much independent review the item gets before SMOL may implement it (full contract in skills/agentsflow/references/execution-modes.md):

Mode	Used for	Required artifact	Independent review
`anchored`	one or a few unique edit sites	exact file + anchor (symbol, line, or unique text)	none
`batch-anchored`	a repeated change fully enumerated in advance	exact `(file, line, old, new)` tuple list + an applier that refuses the whole batch on any mismatch	ADVISOR-light, only when the risk trigger fires
`scripted-pattern`	a genuine regex/AST transformation at scale	full spec, the script itself, whole-copy `/tmp` dry-run, offender scan, validation evidence	always — ADVISOR must return `code approved`; two review rounds maximum
`planned-implementation`	new files or substantial coordinated behavior	file-by-file behavior contract with interfaces, error states, and acceptance criteria	none (SMOL exercises bounded judgment inside the contract)

Guard rails worth knowing:

The batch applier is exact-once-or-refuse: if any tuple's old text doesn't occur exactly once on its named line, nothing is written at all — no partial batches. Within each file, tuples are applied in descending line order, so a replacement that changes the line count can never shift the locations of tuples still pending.
Tuples bind to the source state they were captured from. If another checklist item touches a tuple's file first, the batch is re-captured with fresh evidence and, when required, a fresh review; a second stale refusal of the same item blocks the run instead of looping.
The batch risk trigger (public APIs, schemas, cross-file references, deletions, meaningful whitespace, and similar) is what escalates a batch from PLAN's fast path to ADVISOR-light.
Every scripted item is rehearsed on a complete copy of the project in /tmp, where PLAN must prove every catalogued target changed, nothing else changed, edge cases held, the copy still builds, and rerunning is safe — before ADVISOR even sees it.
A script that fails review cannot be smuggled through as a "batch" instead; downgrading a failed scripted review is prohibited.

User interaction during a run

A run waits for at most one user reply, ever. Either:

PLAN QUESTIONNAIRE [I1] — one consolidated packet after inspection, at most three evidence-grounded questions with bounded options and a recommendation; or
PLAN DECISION REQUEST [D1] — one later bounded decision, only if no questionnaire was sent and a newly revealed choice controls continuation.

Never both, and never questions about discoverable facts, mode preferences, or checklist approval — those are PLAN's job. If continuation is genuinely impossible and no bounded choice can fix it, PLAN sends PLAN BLOCKED [B1] stating the reason, the current file state, and narrow next options, then ends the run with a blocked report. A blocked notice is information, not a request to approve a plan.

Validation

Validation is proportional: the narrowest project-native evidence that proves each frozen acceptance criterion, with equivalent obligations collapsed into one check. Concretely:

reported defects are reproduced when practical, then shown gone;
UI changes are exercised in a real browser (by PLAN), plus DESIGNER's visual review;
LaTeX is compiled with the project's native pipeline and task-relevant diagnostics are checked; when PDF/page fidelity is a committed criterion, VISION must inspect image evidence for every assigned comparison pair or page — PLAN may not substitute its own inspection or text extraction;
tests are added only for a new observable contract without existing coverage, or when you ask;
broad formatters, full test suites, and unrelated warning sweeps are avoided unless the changed surface requires them.

A committed check that cannot run is reported as failed or blocked — never silently dropped. Dry-run evidence from /tmp copies supplements, but never replaces, validation of the real integrated project.

After full success, the only automatic housekeeping is a bounded LaTeX intermediate cleanup (resolved build boundary, latexmk -c followed by a known-extension sweep across the boundary that also removes .bbl and per-chapter .aux, with final PDFs, sources, and figures always preserved), defined in the artifact-document-latex profile in references/profiles.md. No other profile inherits automatic cleanup.

Safety guarantees

Hard rules, canonical in skills/agentsflow/references/safety.md:

Only SMOL edits real project files, and only from the finalized checklist. PLAN's scratch work stays outside the project.
Destructive git commands (git reset --hard, git checkout -- <file>, git clean -fd, git stash drop) require your explicit approval in the current conversation. Your uncommitted changes are never discarded to repair the workflow's own mistakes.
Irreversible or externally visible actions (permanent deletion, publishing, sending) require exact authorization plus recovery and validation boundaries.
Secrets and credentials are treated as opaque and never printed.
On suspected corruption, the run stops and reports rather than attempting destructive self-repair.
No automatic backups are made. If you want a safety net before a big run, create your own restore point first (e.g. git commit or git stash).

Installation

Prerequisites

omp (Oh My Pi). Agents Flow is a skill plus six agent definitions that omp executes; it is not a standalone program.
Sub-agent spawning to depth 2 (the default): the orchestrator spawns PLAN, and PLAN spawns the specialists.
Access to capable AI models for the agents — see Choosing the AI models. No specific vendor is required.

Install

git clone https://github.com/xzhang17/agentsflow.git
cd agentsflow
./install.sh

install.sh copies:

the skill → ~/.agents/skills/agentsflow/
the six agent files → ~/.omp/agent/agents/

Then start a new omp session so discovery picks them up. Destinations can be overridden:

AGENTSFLOW_SKILLS_DIR="$HOME/.agents/skills" \
PI_CODING_AGENT_DIR="$HOME/.omp/agent" \
AGENTSFLOW_AGENTS_DIR="$HOME/.omp/agent/agents" \
./install.sh

Manual install

# globally
cp -R skills/agentsflow ~/.agents/skills/agentsflow
cp agents/*.md ~/.omp/agent/agents/

# or per-project
mkdir -p .agents/skills .omp/agents
cp -R skills/agentsflow .agents/skills/agentsflow
cp agents/*.md .omp/agents/

Verify

In a new omp session, /skill:agentsflow should load the instructions, and listing available agents should show plan, reviewer, smol, designer, vision, and inspector_semantic.

Usage

Agents Flow activates only when you name it — it never takes over ordinary requests, and activation does not carry across turns. Examples:

Use agentsflow to reorganize the auth module: move session handling out of
handlers.py into a new session.py, update all callers, keep the public
interface unchanged, and make the existing tests pass.

Run an Agents Flow workflow to fix the citation numbering across all chapters
of paper/, without changing any equation or figure labels.

agentsflow: convert every inline figure in chapters 3-5 to the float
environment used in chapter 1; the rendered PDF must be page-identical
except for float placement.

You interact at exactly two points: the optional single questionnaire, and the final report. Everything else is visible as status lines.

Choosing the AI models

Each agent file sets a default model. As shipped:

Agent	Default model	Thinking effort
`plan`	`openai-codex/gpt-5.5`	high
`reviewer`	`anthropic/claude-opus-4-8`	high
`smol`	`deepseek/deepseek-v4-pro`	off
`designer`	`google-antigravity/gemini-3.1-pro`	high
`vision`	`google-antigravity/gemini-3.1-pro`	default
`inspector_semantic`	`google-antigravity/gemini-3.1-pro`	high

The requirements are functional, not vendor-specific: PLAN needs a strong reasoner, ADVISOR a strong independent reviewer, SMOL a capable and cheap editor, and the DESIGNER/VISION/inspector roles need vision-capable models. Three ways to change them (pick one):

A. Override in omp settings (recommended — leaves the repo files untouched):

# ~/.omp/agent/config.yml
task:
  agentModelOverrides:
    plan: your-provider/strong-reasoner:high
    reviewer: your-provider/independent-reviewer:high
    smol: your-provider/capable-coder
    designer: your-provider/vision-model:high
    vision: your-provider/vision-model
    inspector_semantic: your-provider/vision-model:high

B. Edit the model: line in each file under agents/ before running install.sh.

C. Add fallback chains so one provider's outage doesn't stall a run:

# ~/.omp/agent/config.yml
retry:
  modelFallback: true
  fallbackChains:
    openai-codex/gpt-5.5:            # PLAN
      - anthropic/claude-opus-4-8:high
    anthropic/claude-opus-4-8:       # ADVISOR
      - openai-codex/gpt-5.5:high
    deepseek/deepseek-v4-pro:        # SMOL
      - your-provider/backup-coder
    google-antigravity/*:            # DESIGNER / VISION / inspector
      - google/*
      - google-vertex/*

Note: an agent's model comes from its own file or task.agentModelOverrides — not from modelRoles, which only controls your main session.

Repository layout

agentsflow/
├── README.md
├── README.zh-CN.md
├── LICENSE
├── install.sh                  # copies skill + agents into omp
├── skills/agentsflow/
│   ├── SKILL.md                # the core contract (always loaded on activation)
│   ├── CHANGELOG.md
│   ├── assets/
│   │   ├── AGENTS_WORKFLOW_CORE.template.md   # workflow template
│   │   └── AGENTS_LAUNCHER.template.md        # universal launcher
│   ├── evals/
│   │   └── scenarios.md        # release-audit scenarios (never loaded at runtime)
│   └── references/             # loaded per phase, not all at once
│       ├── workflow-authoring.md   # authoring rules + pre-launch gate
│       ├── profiles.md             # 19 task profiles + composition + LaTeX cleanup
│       ├── execution-modes.md      # the four modes, review routing, SMOL handoff
│       ├── grilling-intake.md      # questionnaire / decision / blocked protocol
│       ├── safety.md               # scope, secrets, destructive actions, recovery
│       └── templates.md            # status, packet, and report formats
└── agents/                     # the six agent definitions
    ├── plan.md
    ├── reviewer.md
    ├── smol.md
    ├── designer.md
    ├── vision.md
    └── inspector_semantic.md

Both halves are required: the skill spawns the agents by exact name, so it cannot run without the agents/ files installed.

Troubleshooting

Symptom	Likely cause and fix
`/skill:agentsflow` not found	Skill not at `~/.agents/skills/agentsflow/SKILL.md`, or skills disabled. Re-run `install.sh`, start a new session.
`Unknown agent 'plan'`	Agent files missing from `~/.omp/agent/agents/`. Re-run `install.sh`.
An agent won't start / model unavailable	You lack that provider. Override or add fallbacks — see Choosing the AI models.
PLAN can't spawn specialists	Recursion depth limited. Ensure `task.maxRecursionDepth` ≥ 2.
SMOL's edits don't appear in your files	omp is editing an isolated copy. Set `task.isolation.mode: none`.

Versioning

The skill carries a single semantic version (currently 3.2.0), stamped into each generated workflow for provenance. Workflows are authored fresh every run rather than migrated across versions. Each release is audited against the scenario fixtures in skills/agentsflow/evals/scenarios.md — hand-checkable cases covering the contract's edge behavior (stale batch tuples, exhausted reviews, missing agents, blocked VISION evidence, and more). Full history: skills/agentsflow/CHANGELOG.md.

Contributors

xzhang17 — author and maintainer
Claude (Anthropic) — development assistant

Navigation Menu

Repository files navigation

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

Prerequisites

Install

Manual install

Verify

Usage

Choosing the AI models

Repository layout

Troubleshooting

Versioning

Contributors

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
agents		agents
skills/agentsflow		skills/agentsflow
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
install.sh		install.sh

Folders and files

Latest commit

History

Repository files navigation

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

Prerequisites

Install

Manual install

Verify

Usage

Choosing the AI models

Repository layout

Troubleshooting

Versioning

Contributors

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages