flow — the /flow engine

One unified, PM-agnostic workflow system spanning capture → done. A single identifiable installable unit: manual stages you drive from the terminal, and an autonomous loop seated on DorkOS Pulse.

This README is the manual. See SPEC.md for the contract (the stage model, the PMClient promotion surface, the config schema, the FlowRun record, and the typed engine), CHARTER.md for the 15 goals the system is audited against, and the published guide series on dorkos.ai for the user-facing reference. These three docs and the guides ship with the package (charter G15); the manifest enumerates them as docs members.

[!IMPORTANT] Autonomous mode depends on a running DorkOS server (Pulse). Manual mode does not. /flow, /flow:<stage>, and /flow auto (terminal draining) run without the server. The autonomous Pulse-seated loop (${CLAUDE_PLUGIN_ROOT}/skills/flow-drain/) requires the DorkOS server running to host the chokidar watcher + croner.

Stages

One canonical spine — the unit of "where work is." Spec status, tracker state, labels, and loop phase are all projected from the stage by the adapter, never authored independently.

 manual ─▶  CAPTURE → TRIAGE → IDEATE → SPECIFY → DECOMPOSE → EXECUTE → PM-driven ─▶        VERIFY → ⟦HUMAN REVIEW⟧ → DONE → (MONITOR → SIGNAL)                     ▲ adapter (PMClient): Linear today, swappable

• CAPTURE — quick, low-commitment intake of a raw thought as an idea. Does not evaluate or classify. (capturing-work)
• TRIAGE — classify freeform input into a type, or evaluate a captured item (accept / reject / needs-research / needs-refinement) and make the simple-vs-complex routing call. (triaging-work)
• IDEATE — shape a complex brief into a structured ideation artifact. (ideating-features)
• SPECIFY — turn ideation into a frozen specification + draft ADRs. (specifying-work)
• DECOMPOSE — break the spec into 03-tasks.json tasks (mirrored to the tracker as a checklist; promote a sub-issue only at size ≥ "xl"). (decomposing-work)
• EXECUTE — implement the tasks across dependency-aware batches in an isolated worktree. (executing-specs)
• VERIFY — run the touched surface, capture proof-of-completion evidence, open the PR, and hand off to review. (verifying-work)
• REVIEW — the human gate. The engine parks here; there is no skill and no command. On approval + green CI it resumes into DONE.
• DONE — close the work, create follow-ups, run the project-pulse check, and tear down the worktree. (closing-work)
• MONITOR / SIGNAL — the optional tail that keeps the loop spinning.

Match on a tracker state's category (backlog | unstarted | started | completed | canceled), never its display name — that is what keeps the system portable across teams and trackers.

Modes

The trigger source is orthogonal to the execution mode — a 2×2, not a single axis:

• Manual + Step — /flow:<stage> advances one stage and stops. Questions arrive interactively. Server-free.
• Manual + Autonomous — /flow auto drains the ready queue sequentially from the terminal, carrying each item to its review gate. Server-free.
• PM-driven + Step — rare; an explicit single-stage advance triggered by a tracker transition.
• PM-driven + Autonomous — the default seat: a Pulse tick claims the top-ranked eligible item and carries it to its gate in a fresh per-item session. Requires the DorkOS server (see below).

Every stage is autonomous-capable. The human is pulled in by uncertainty (the calibration ladder), not by stage — which is why IDEATE asks freely while EXECUTE asks rarely, as an emergent property of one rule.

Command ↔ state map

Each /flow:<stage> command is a thin trigger (≤ ~40 LOC) over the stage skill. A PM transition into a stage and the slash command are two triggers for the same skill. The mapping is generated from config.json stages:

/flow (no stage) is the orchestrator: it resolves a stage name, a work item, a project (by name, spec slug, or umbrella id), or auto, then routes to the matching command. Naming a project routes by its state: project-scoped single-item dispatch when it has agent/ready children, or advancing its umbrella one stage when it has none yet (/flow auto|continue <project> narrow the queue modes to that one project). With no arguments at all, it offers four intents: Capture new · Work on a project (pick from the active projects) · Continue the queue (claim the next-ranked item, carry it to its gate, then stop) · Triage the backlog, with a specific item or auto (drain the whole queue) reachable as free text. "Continue the queue" is one tick of auto.

Gates

Involvement is uncertainty-gated, not stage-gated (the calibration ladder, spec §5). The hard gates:

1. Question / soft-escalation — any stage, dynamic; driven by the calibration ladder. Row 0 (the floor) always stops for irreversible/destructive, outward-facing, secrets/spend/prod, or material-scope-change actions, even at full confidence.
2. Plan-approval gate (after DECOMPOSE) — off by default (gates.planApproval: false). The engine flows DECOMPOSE → EXECUTE and surfaces plan assumptions at the review gate. Flip it on for a pre-code checkpoint.
3. Human-review gate (after VERIFY) — always on. PR + evidence → review state → assign the human → stop. On approval + green CI → auto-merge + close + teardown. v1 caveat: the engine parks here and does not detect approval — merge the approved PR yourself, then run /flow:done <issue> to close the item and tear down the worktree. The merge-decision logic (evaluateAutoMerge, §6 below) is built + tested; the detection + execution that fires it unattended (poll/webhook-driven resume-on-approval) is the P2 server Extension.
4. Circuit breaker — stop + escalate if a unit exceeds estimate × N wall-clock or the token budget.

Auto-merge recovery ladder (spec §6): approval authorizes one specific state — this diff, green, cleanly mergeable. If that state can't be reproduced at merge time, the engine checks mergeable? · CI green? · functionally unchanged? and routes each failure through the calibration ladder (mechanical conflict → resolve

• announce; real tradeoff → bounce; behavior drift → re-request approval).

Adapter interface

The linear-adapter skill is the v1 PMClient: it owns every tracker call (Linear MCP primary, Composio --account personal fallback) and fulfils the capability verbs as a documented prose contract. Generic stage skills call it by naming a verb (e.g. "via the linear-adapter, transition the item …") and never touch a tracker string — a grep guard enforces zero mcp__linear__* / Composio strings outside the adapter.

The verbs: getCurrentUser, getProjects, resolveProject, getProject, getProjectWork, getEligibleWork, getInbox, getRelations, claim, transition, comment, assignToHuman, attachEvidence, needsInput, link, createSubIssue. The adapter normalizes every tracker into one WorkItem shape so the dispatch policy and stage skills never see a tracker-specific field. Full verb contract: the adapter's SKILL.md; the typed interface PMClient the P5 server build promotes it into is in SPEC.md.

The adapter also owns the display convention: every work item shown to a human is rendered as DOR-157 - Title (identifier first, the identifier linked where the surface supports it), never a bare key.

Autonomous mode & the server dependency

The autonomous loop is seated on DorkOS Pulse via a file-based schedule (${CLAUDE_PLUGIN_ROOT}/skills/flow-drain/SKILL.md). Pulse already provides a contextless code-loop (croner) that dispatches a fresh, isolated, resumable, runtime-agnostic agent session per run — so there is no scheduler to build.

• One tick = one issue. Each croner fire is a fresh run-session (sessionId = run.id) that claims and works exactly one issue to its gate, then ends — preserving fresh-session-per-issue.
• Activation requires the DorkOS server running (hosts the watcher + croner) and the project's DorkOS agent registered (a global ~/.dork/tasks/ task is watched unconditionally). No build step, no migration — dropping the file is picked up live.
• Crash/stall recovery is driven by the durable FlowRun record + the next-tick recovery ladder (spec §12): a needs-input item is never reclaimed; an orphaned agent/claimed item is adopted + resumed (re-attach the worktree at HEAD, resume the session) or restarted clean, with attemptCount guarding against runaway retries.

Autonomous mode depends on a running DorkOS server (Pulse); manual mode does not. A generic claude -p-per-issue watcher seat (for non-DorkOS repos) is designed but not built in v1 — so autonomy.seat accepts only pulse today, and watcher rejoins the enum when the seat ships. (The "watcher" is the external poller that fires a headless claude -p tick per issue — not a prompt.)

Configuration

Defaults live in config.json, validated against the Zod-generated config.schema.json (authored as the @dorkos/flow FlowConfigSchema, bridged via z.toJSONSchema). The resolved defaults encode the key decisions: planApproval: false, subIssueThreshold: "xl", perIssue: "fresh-session", seat: "pulse". See SPEC.md → Config schema reference for the full contract.

A per-repo WORKFLOW.md override at the repo root is part of the config contract (Decision #15), but v1 reads .agents/flow/config.json only — applying the override is the promoted config loader's job (DOR-90 / the P5 server build), not the v1 harness skills. A WORKFLOW.md will not take effect yet.

Templates

The system owns a template set under templates/, loaded by skills (not projected to any harness):

• templates/records/ — tracker work-item bodies by type (idea · research · hypothesis · task · project), each with ## Validation criteria + ## On Completion.
• templates/docs/ — the filesystem doc scaffolds (ideation · specification · 03-tasks.json · ADR).
• templates/pr.md — the PR template the VERIFY stage fills at the review gate.