Flowline use cases — cross-repo evidence survey
State: open/active · Genre: analysis
Date: 2026-07-05 Status: Proposal — evidence aggregation, no decisions minted.
Companion: the workflow-constellation RFC and flowline spike (PR #682); this survey grounds and
extends the RFC’s §4 use-case taxonomy (UC1–UC10) with evidence from every repo under sksizer/.
What this is
Section titled “What this is”The RFC’s taxonomy was drawn from two sources (SDLC and DarkFactory). This survey asks: what has
actually been built, hand-rolled, and re-built across all sksizer/* repos that a workflow
library would absorb? 55 repos were examined; 39 had relevant findings. Clustering those findings
produced the 14 use cases below — one file each, every claim cited to files in the source repo.
Use cases
Section titled “Use cases”The ordering is additive: each file’s Proposed API introduces only primitives not seen in
earlier files, and later examples reuse earlier ones by nesting (06 nests 05’s cycle; 11 nests
06’s judge and 09’s fanOut as DAG nodes). Entries marked ext. propose surface beyond the
current RFC/spike.
| # | Use case | RFC mapping | Introduces |
|---|---|---|---|
| 01 | Typed LLM/agent invocation (no sentinel scraping) | UC1 | agent(), invokers |
| 02 | CLI ops wrapped as typed tasks | UC10 | task(), payload(), taskFromOp() |
| 03 | Linear pipeline of deterministic + LLM steps | UC2 | pipe(), workflow(), run() |
| 04 | Bounded retry + recovery/fallback | UC3 | onFailure: { task, retry } |
| 05 | Produce → deterministic gate → fix cycle | UC4 (+UC3) | cycle() |
| 06 | Produce → judgement gate → revise cycle | UC5 | judge() |
| 07 | Confirm gates; interactive handoff-then-resume | UC9 | confirm(), handoff invoker |
| 08 | Dry-run default; plan → review → apply | cross-cutting; partially new | dryRun; ext. planRun()/applyRun() |
| 09 | Concurrency-capped fan-out with join | UC6 | fanOut() |
| 10 | Structured per-step run reporting as a schema | new | ext. StepEvent, onEvent |
| 11 | DAG of tasks: readiness, topo order, parallel branches | UC7 | dag(), runDag() |
| 12 | Durable orchestration: journal, idempotent re-entry | UC8 | runDurable(), fileJournal() |
| 13 | Triggers: watchers, cron, polling daemons | new | ext. watch()/cron()/poll() |
| 14 | LLM output extends the running workflow | new | ext. graph.append() |
Example repos per use case are cited inside each file (3–6 each; dev, DarkFactory,
ontological, agentpants, harness, and the worker-prototype line recur most).
Taxonomy gaps
Section titled “Taxonomy gaps”Recurring needs the evidence shows that UC1–UC10 does not name. Proposed for the RFC’s §4 (or explicit deferral in §11):
| Gap | Evidence summary | Covered in |
|---|---|---|
| Structured run reporting as an emitted, versioned schema | Two frontends built solely to reconstruct run state (agent-dashboard, deprecated-agent-visualizer); ontological copy-pastes StepResult journaling six times | 10 |
| Triggers and scheduling (watch/debounce, cron, polling with cursors) | The taxonomy describes what runs, never what wakes it: DarkFactory rework_watch, dev watch_loop, polish scheduler spec, agentpants cron | 13 |
| Dynamic workflow growth (nodes appended from an LLM step’s output) | DarkFactory reload-and-repick hacks; dev’s prose-coordinated spawn protocols | 14 |
| Plan → typed plan artifact → approve → apply as a two-phase flow | 2b’s dedup plan JSON, rust-ontogen’s discarded REVIEW.md joins — beyond a dry-run flag | 08 |
| Persistent work-queue supervision (claim/dispatch over a durable queue) | ontological’s Supervisor with optimistic-lock claims, DarkFactory drain-queue, dev orchestrate tick — wants an incremental ready-frontier API, not run-whole-graph | 11, 12 |
| Multi-runner coordination and liveness (leases, fencing, heartbeats, reconcile) | dev’s git-ref lease layer with LLM-maintained heartbeats; DarkFactory FileLocks; zoo reconcile_state — @flow/durable’s journal covers none of this | 12 |
| Long-lived resource lifecycle state machines outliving any run | zoo/harness InstanceState, agentpants 9-state requirement lifecycle, dev lease phases | 12 |
| Workflow as compile target and distributable dependency | agentpants compiles graphs to prose for lack of a runtime; the same bash harness is vendored byte-identical into ~10 repos with an LLM meta-workflow keeping copies in sync | 01, 03 |
Method
Section titled “Method”One survey agent per candidate repo (22 deep scans), four batch-triage agents over the long tail
(32 repos), one local scan of this repo (excluding the flowline package and its two analysis docs),
then one synthesis pass clustering findings against the RFC taxonomy. Findings without file-level
evidence were discarded. dev, DarkFactory, ontological, agentpants, harness, and the
rust-worker-prototype/rust-evented-worker line are the densest sources; the rust-agent-adapt
→ kiosk/rust-markdown/rust-ontogen script family is the clearest case of the same harness
vendored and drifting across repos. API examples use the spike’s package subpaths
(flowline/llm, flowline/workflow, …) and the RFC §5 primitives; proposed extensions are
marked as such in each file.