English | 简体中文

Quick Flow

A speed-first, single-session workflow skill for AI coding agents — omp (Oh My Pi), Pi agent, Codex, Claude Code, and any other AI agents.

Quick Flow makes the agent you are already talking to carry one bounded job from start to finish — plan, inspect, edit, verify, report — entirely in the foreground. It spawns no helper agents, runs nothing in the background, and hands responsibility to no one. What it keeps from heavier workflows is the discipline: a written plan frozen before the agent looks at your files, at most one question to you per run, an explicit acceptance check for every change, and validation before "done."

Version 5.2.0 · License MIT

Its heavyweight sibling, Agents Flow, splits large or risky jobs across a reviewed multi-agent team. See Quick Flow vs Agents Flow.

Table of contents

• Why Quick Flow
• Quick Flow vs Agents Flow
• How a run works
• The frozen workflow record
• Task profiles
• Decisions: one reply, at most
• Validation and cleanup
• Safety guarantees
• Installation
• Usage
• A worked example
• Repository layout
• Troubleshooting
• Versioning
• License

Why Quick Flow

For a small, well-defined job — a bug fix, a modest feature, a document tweak, a "why is this failing?" — a team of agents is overhead. But "just do it" without structure invites a different failure: the agent drifts from the request halfway through, edits things it shouldn't, or declares success without evidence.

Quick Flow is the middle path. One agent, one visible session, but bound by a contract:

1. Plan first, frozen. Before touching your files, the agent writes a compact workflow record — goal, allowed inputs, selected task profiles, requirements, validation expectations — validates it mechanically, and freezes it. The plan cannot drift mid-run, and every run starts from a fresh record (old ones are never reused or rewritten).
2. Proportional everything. It inspects only what the job needs, asks you at most one consolidated set of questions (usually none), and runs the narrowest check that actually proves the result.
3. Read-only means read-only. Questions and diagnoses never modify your project — not even the workflow record is stored inside it.

Everything happens live in your session; your host shows every tool call, and you can interrupt at any time.

Quick Flow vs Agents Flow

The two are deliberately kept apart: if your request also demands parallelism, delegation, or sub-agents, Quick Flow stops before authoring anything and asks (via the structured Ask UI) whether you want foreground-only Quick Flow or Agents Flow instead.

How a run works

flowchart TD
    A[You invoke quickflow] --> B[Author one fresh workflow record<br/>validate mechanically, write, freeze]
    B --> C[Load only the selected profiles' rules]
    C --> D[Proportional inspection:<br/>just enough of your files]
    D --> E{Material decision<br/>only you can make?}
    E -->|yes| F[One structured Ask UI packet,<br/>at most 3 decisions]
    E -->|no| G
    F --> G[Form one compact checklist:<br/>files + change + acceptance check]
    G --> H{Mutating intent?}
    H -->|yes| I[Edit directly]
    H -->|inquiry / diagnosis| J[Look only — zero edits]
    I --> K[Validate: narrowest sufficient<br/>project-native evidence]
    J --> K
    K --> L[LaTeX-only cleanup, if eligible]
    L --> M[Final report]

Step by step:

1. Author and freeze. From your prompt alone — before reading any target file — the agent renders the workflow template, mechanically validates it (no unfilled slots, exact version stamps, coherent profile selection), writes it to disk, and freezes it as the binding contract for the run.
2. Inspect. It reads just enough of the project to locate the work, resolve discoverable facts, and confirm the selected profiles actually fit what it found. A mismatch it cannot safely cover ends in a terminal safety stop, not improvisation.
3. Ask once, if at all. Genuine user judgments — never discoverable facts, never "approve my plan" — are consolidated into a single structured Ask UI submission of at most three decisions, each with bounded, evidence-grounded options.
4. Checklist. One compact internal checklist ties every change (or every answer, for read-only work) to a focused observable acceptance check. After editing begins, committed checks can be strengthened but never silently weakened.
5. Edit — only for mutating intents. Inquiry and diagnosis runs are strictly read-only.
6. Validate, clean up, report. The narrowest project-native evidence proves each committed check; eligible LaTeX work gets its bounded cleanup; and the run ends with one direct final report. There are no routine progress messages in between — the only mid-run messages you can receive are the single Ask UI packet, a safety stop, or a notice before an operation expected to exceed 90 seconds.

The frozen workflow record

Every invocation writes exactly one new record, and its location encodes the read-only contract:

• Mutating, project-backed work → .quickflow/QUICK_WORKFLOW.md inside your project (collision-free suffixes like QUICK_WORKFLOW_<task-slug>.md when needed).
• Inquiry, diagnosis, or no writable project root → a project-external session location (local://quickflow/workflows/...), so asking a question never dirties your repository.

Each record carries exact stamps — Quick Flow skill: 5.2.0, Workflow schema: 6, Profile schema: 4 — and separates what you said (requirements) from what must be discovered by inspection ("Facts for QUICK to discover"). Records are immutable snapshots: never overwritten, never reused as input for a later run, never migrated across versions. Later bounded decisions are recorded in the final report, not by editing the record.

Task profiles

For each kind of work, Quick Flow follows a composable rulebook, called a profile (full definitions in skills/quickflow/references/profiles.md). Profiles come in four groups:

• Intent — what you asked for: inquiry, diagnosis, repair, feature implementation, refactor, optimization, translation, formatting, conversion. Exactly one is primary; the read-only intents (inquiry, diagnosis) never mix with mutating ones.
• Artifact — what is being touched: 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, when no artifact profile clearly applies; first inspection resolves it into exactly one specific artifact profile.

Profiles decide what "finished" and "properly checked" mean: a LaTeX change must compile with the project's native pipeline, a web-page change must be exercised in a real browser, a refactor must demonstrably preserve behavior at its interfaces. The profile set selected at authoring time is frozen with the record; the agent may mark an obligation inapplicable only before editing, only with observed evidence, and must disclose it in the final report.

Decisions: one reply, at most

A run waits for at most one user reply, through one of two mutually exclusive channels:

• one structured Ask UI submission with up to three evidence-grounded decisions (bounded options, recommendation included), or
• one resumable safety stop, when something genuinely blocks continuation.

Zero questions is the preferred and common case. The agent never asks about discoverable facts, implementation preferences, or checklist approval. A newly discovered non-destructive target clearly implied by your original request may be added and disclosed in the report; genuine scope expansion triggers the safety-stop rules instead of silent growth.

Validation and cleanup

Validation is proportional: semantically equivalent obligations across profiles collapse into a single check, and the narrowest project-native evidence that proves the result is the one that runs. Repairs are re-reproduced when practical; changed UI is exercised in the browser; task-relevant LaTeX is compiled with focused page and diagnostic inspection. Exhaustive comparisons, full test suites, formatters, and linters run only when the prompt or the changed interface requires them. A committed check that cannot run is reported failed or blocked — never dropped, and never "fixed" by editing unrelated source until it passes.

The only automatic cleanup is deliberately narrow: after every committed check passes for a mutating LaTeX job, the agent resolves the actual build directory and removes, non-recursively, the regular files directly in it whose extension is a known LaTeX intermediate (.aux, .bbl, .bcf, .blg, .fls, .fdb_latexmk, .log, .out, .run.xml, .synctex.gz, .toc, and the rest of the generated set). It never removes .pdf, source, figure, or asset files, never recurses, and never runs for inquiry or diagnosis. Cleanup failure is a non-fatal warning