Agentic Workflow (awf)

Multi-agent pipeline orchestrator for opencode. Plan → build → verify → commit — through typed MCP tools, not bash.

The problem it solves

AI coding agents are powerful but chaotic. They jump straight to code without planning, skip review, leave bugs. You watch helplessly as tokens burn.

awf adds structure: a supervisor agent plans the work, worker agents execute through a pipeline you design (any roles, any depth — from a single worker to a multi-stage chain), and you approve each result before it commits. All through natural language — "start working on the backlog", "verify and approve", "reject — the DOMParser fix is missing".

You stay in control. The agent stays on rails.

Quick Start

# 1. Install
pip install awf agent-workflow-ui
# After install the `awf` console command is available (or `python -m awf`)

# 2. Configure opencode — add to ~/.config/opencode/opencode.json:
# {
#   "mcp": {
#     "agent-workflow-ui": {
#       "type": "local",
#       "command": ["python3", "-m", "agent_workflow_ui"],
#       "enabled": true,
#       "timeout": 600000
#     }
#   }
# }

# 3. Run — just talk to opencode:
# "Initialize awf in my project"
# "Develop the MVP based on the backlog"

Requirements

Timeouts: each agent stage times out after 1 hour by default — a supervisor paused on verify longer than that gets the stage salvaged. Extend with AWF_SUPERVISOR_TIMEOUT=7200 (env) or awf start --timeout 7200 (USAGE.md → Troubleshooting).

Features

• 🎯 State-Machine Orchestration (SMO) — awf guides the supervisor through phases: init → goal → form → normalize → brief → run → verify → done. Every tool returns a next_action hint — even weak models follow the full flow without getting lost.
• 🔧 45 MCP tools — typed pipeline control: init, dispatch, start, approve, reject, rollback, dashboard, model validation. No bash, no manual file editing.
• 📊 Live Dashboard — HTTP server with real-time polling. Chat-style agent handoffs, TODO content, TODO timeline, worker status, browser notifications. No page reloads.
• 🧱 Custom pipelines — any roles, any depth. 1 stage or 10. You choose in the setup form.
• ✅ Approve / Reject — symmetric verify tools. Approve commits and archives. Reject kills the pipeline and asks for fixes.
• 🔍 Pre-dispatch check — before launching a pipeline, awf greps your codebase for keywords from the TODO. Warning if the task might already be done.
• 🔄 Crash recovery — salvage path when workers don't signal, orphan TODO cleanup, state reconciliation on startup.
• 📋 Increment planning — decomposition variants (vertical, horizontal, risk-first) presented as an HTML form for user choice.

Usage

Talk in natural language — the supervisor agent calls the right tools:

See USAGE.md for full scenarios and tool reference.

SMO Flow

graph LR
    init --> goal --> form --> normalize --> brief --> run --> verify --> done

Architecture

graph TD
    A[opencode supervisor LLM] -->|MCP stdio - 45 tools| B[agent-workflow-ui plugin]
    B -->|Python import| C[awf orchestrator]
    C -->|subprocess| D[opencode run - worker agents]
    C -->|HTTP daemon| E[Dashboard - live /api/state]

Two packages:

• awf — Python core. Pipeline engine, phase state machine, signals, commit gate, dashboard server.
• agent_workflow_ui — MCP plugin. Thin async wrappers + next_action guidance + HTML forms.

Comparison

Dashboard

Live HTTP dashboard opens automatically when pipeline starts:

• Two-panel layout — pipeline sidebar (stages, progress, worker) + content tabs
• 💬 Agent Chat — handoffs as conversation messages with chain visualization
• 📝 Задача — full TODO content in rendered markdown
• 📊 События — meaningful events, newest first
• TODO timeline — [✅ TODO-0001] ─ [✅ TODO-0002] ─ [🔄 TODO-0003]
• Browser notification when pipeline reaches verify

Real-world results

6 sessions on jira-epic-presenter (Qwen vLLM):

• Full SMO flow end-to-end: init → goal → form → normalize → brief → run → verify
• 4 TODOs per session, 1× approve (no loops), zero polling
• Reject flow tested: supervisor found missing work, rejected, re-dispatched with fix
• Pre-dispatch check caught already-implemented tasks

Roadmap

• SMO escape-hatch'и — manual phase jumps, interruptions (from real session edge cases)
• Coverage — CI gates ≥80% (awf core + plugin) are in place; keep them from sliding
• ✅ PyPI — pip install awf agent-workflow-ui (done!)
• Dashboard v3 — stage timing bars, session summary, sound notifications
• Standalone mode — awf without opencode (API-only)

Full backlog: BACKLOG.md

Documentation

• USAGE.md — usage scenarios and tool reference
• Architecture — components, data flow, design decisions
• Product Vision — competitive advantages
• Supervisor Flow (SMO) — phase system, next_action pattern
• CHANGELOG.md — version history
• CONTRIBUTING.md — how to contribute
• BACKLOG.md — open tasks
• README.ru.md — Russian README

License

MIT — see LICENSE.