MCP SERVER
Phase-based tool scoping that narrows what an agent can do at each step — fewer choices, better focus.
| Tool | Purpose | Returns |
|---|---|---|
| start | Enter a workflow from a named definition, repo:name reference, or YAML file path. Creates an instance and sets the initial phase. | Instance ID, phase, focus, scope, available shifts |
| orient | Reorient to the current phase. Returns the focus frame, scope constraints, attention signal checklist, and valid transitions. | Phase focus, attended/total signals, ready-to-shift flag |
| shift | Advance to a new phase. Validates the transition edge and checks that gated attention signals are satisfied before allowing the move. | New phase focus, scope, signals, terminal flag |
| nod | Acknowledge one or more attention signals in the current phase. A nod says "I attended to this" — gated phases require all nods before shifting. | Nodded IDs, remaining unattended signals |
| bubble | Pause the current phase with a reason. Blocks shift and nod until popped. Resolved bubbles are preserved in history for session recovery. | Bubble state, reason, resume confirmation |
| confirm | Grant single-shot approval for a tool in the confirm policy list. The grant is consumed on the next call — one confirmation per use. | Granted tools, confirmable list |
| suspend | Temporarily disable scope enforcement without abandoning the flow. The phase stays active but tool constraints are lifted. | Enforcing flag, changed status |
| list | List all flow definitions and active instances. Shows effective tier, source repo, completion stats, and bubble state. | Definition catalog, instance summary, detail file path |
| record | Tape recorder for process discovery. Backfill phases already completed, mark new phases as you go, press stop to generate a reusable flow YAML. | Recording ID, generated flow path |
| scaffold | Create a flow definition from a skeleton pattern. Linear (analyze→execute→verify) or iterative (plan→process loop→verify). Custom state names supported. | Flow name, file path, pattern, states |
| abandon | Mark an active instance as abandoned. Preserves full history for inspection. Increments the abandonment counter for tier computation. | Final phase, history |
| cleanup | Remove abandoned and completed instances from disk. Supports dry-run preview, age filtering, and explicit ID targeting. | Removed count, candidate list |
Each phase declares a scope that classifies every tool as blocked (rejected before execution), confirm (rejected until user approves, then single-shot grant), or allowed (passes through). An OpenCode plugin intercepts tool calls at runtime — this is enforcement, not guidance. A blocked tool never executes.
Presets are named block lists that cover common patterns. read-only blocks all writes. code-write allows edits and commits but blocks publishing. wiki-write allows wiki ops but blocks code changes. verification is read-only plus test execution. cassettes-only restricts to VCR operations. full removes all restrictions.
Scopes compose. Start with a preset, then apply allow (remove specific blocks), block (add restrictions), and category (restrict git-ops_commit to specific commit categories like DISCOVERY or CORE). The object form gives fine-grained control without building block lists from scratch.
Some tools are occasionally legitimate but should be deliberate. The confirm policy gates them behind user approval — the agent asks, the user approves, the agent calls confirm, then retries. The grant is consumed immediately. Phase shifts clear all outstanding grants.
Phases declare attention signals — a checklist of things the agent must attend to. When gated: true (the default), every signal must be nodded before the agent can shift to the next phase. This prevents premature advancement.
When an agent backtracks to a previous phase, attention signals reset by default (refocus: true). Each pass through a looping state starts clean — previously nodded signals don't accumulate and clutter the orient response.
When progress is blocked — waiting for input, a dependency, or a decision — the agent bubbles the phase. Shift and nod are blocked until the bubble is popped. Resolved bubbles are preserved in history so resuming sessions know what happened.
The flowbot-enforce plugin intercepts every tool call before execution. It checks the active instance's current phase scope, evaluates the tool against blocked/confirm/allowed policies, and rejects inappropriate calls at runtime. Without the plugin, flows are advisory only.
Flows are YAML files discovered from three sources: built-in (flows/), workspace repos (~/source/*/flows/), and explicit paths via FLOWBOT_EXTRA_FLOWS. Any repo can ship flows that flowbot discovers and serves.
Any MCP agent that calls flowbot tools gets phase-scoped behavior. The implementation flow drives feature work. The mr-review flow structures code review. The session-mode flow enforces plan vs implement mode switching. Flows are the agent's cognitive scaffolding.
A workflow engine that enforces its own constraints. The tools that built this page were scoped by the flow that sequenced them.