# Workflow-engine ecosystem review > **Status:** Process — describes the bounded, recurring review of upstream and > peer workflow engines. This is a **concept/compatibility watch**, not an > installation or merge mandate. The process cannot trigger installation or code > mutation by itself; every adoption flows through a bounded GitHub issue with > its own review/repair lane. > > Owner doc: [PROVENANCE.md](../PROVENANCE.md). Parent issue: #137. See also > [docs/harness-engine-compat.md](./harness-engine-compat.md) for the engine > ⇄ repo-artifact compatibility discipline this review feeds. ## Why this exists This project (`pi-dynamic-workflows-oc-style`) is an **independently maintained derivation** that has diverged from its origin. Two engine lineage branches are relevant, plus a set of peer Pi workflow engines that each carry one distinct mechanism worth watching. None of them is an *upstream* of this fork: there is no merge/cherry-pick path. They are **read-only idea sources**, and every candidate idea is adapted through a bounded issue against this architecture rather than vendored wholesale. ## Lineage branches under review ### 1. Original engine — `Michaelliv/pi-dynamic-workflows` The original `pi-dynamic-workflows` by Michael Livs. Our project did **not** derive directly from its current tip; we derived from the maintained fork below. The original branch ended at two releases and carries a small set of mechanism commits not contained in the maintained fork at the reviewed ref. - **Repo:** (MIT) - **npm:** [`pi-dynamic-workflows`](https://www.npmjs.com/package/pi-dynamic-workflows) - **Reviewed ref:** `v1.0.1`, release commit `31b2aca` (2026-05-31); the `v1.0.1` tag object points at `dbc6800`. Two releases total: `v1.0.0` (`e22388e`, 2026-05-28) and `v1.0.1` (`31b2aca`, 2026-05-31). npm last published 2026-05-31. **No newer release as of the 2026-08-13 review.** - **Reviewed by:** reading the GitHub commit log + PR bodies (#15, #19, #21, #22, #23) via the GitHub API. ### 2. Maintained derivation — `QuintinShaw/pi-dynamic-workflows` The actively maintained fork that this project originally derived from (at `v2.6.0` / `622f6df`, aligned to `v2.7.0` / `b11fdbd`). It has since diverged far upstream into a general-purpose workflow engine with model routing, resume, worktree isolation, and a `/workflows` TUI. - **Repo:** (MIT) - **npm:** [`@quintinshaw/pi-dynamic-workflows`](https://www.npmjs.com/package/@quintinshaw/pi-dynamic-workflows) - **Reviewed ref:** `v3.5.1`, HEAD commit `bab5ad7` (2026-08-05); npm `3.5.1` (last published 2026-08-05). **No newer release as of the 2026-08-13 review.** (The issue body recorded the date as 2026-08-06; the GitHub API author date is 2026-08-05. We record the API-verified 2026-08-05.) - **Prior review outcome (v3.5.1 → bounded issues):** the v3.5.1 concept audit produced `#133`–`#136` (persisted-state/retention, fatal-sibling drain + explicit-model errors + checkpoint identity, resource-loader retention + reload handoff, workflow control + usage-limit auto-resume) — see [PROVENANCE.md](../PROVENANCE.md) for the ledger. `#133`, `#135`, `#136` are closed; `#134` remains open. > **No-merge invariant:** a `git merge` or `cherry-pick` from either branch is > neither possible nor desirable. Upstream is a **read-only concept source**; > concepts are ported as bounded issues against this fork's harness > broker/catalog contract. ## The seven Michael-original-only commits — disposition The original branch (`Michaelliv/pi-dynamic-workflows`, through `v1.0.1`) contains seven commits not contained in `QuintinShaw/pi-dynamic-workflows` `v3.5.1`. Five are mechanism commits (PRs #15, #19, #21, #22, #23), plus the Pi-namespace rename (`dc6ad26`) and the `v1.0.1` release commit (`31b2aca`). Each is dispositioned against **current local / QuintinShaw behavior**. | # | Commit | Mechanism | Disposition | Evidence | |---|--------|-----------|-------------|----------| | 1 | `4189d2b` (#15) | Forward `modelRegistry` + `model` to workflow subagents so spawned sessions can authenticate to the provider (otherwise they return `null`/empty). | **Already present** | Local `WorkflowAgent.sharedRegistry` (`src/agent.ts:932–991`) shares the host `modelRegistry` with every subagent session; QuintinShaw also has this. | | 2 | `c914116` (#19) | Dynamic workflow phases — phases can be created as the script runs; progress follows phases that actually appear; `meta.phases` is optional. | **Already present** | Local `phase()` global + `meta.phases` + runtime `snapshot.phases` (`src/workflow.ts:90,304,425,637`); progress follows executed phases, not a pre-rendered list. | | 3 | `1c61834` (#21) | Guard workflow results against Promise-clone failures: wait for started subagents to settle; reject non-structured-cloneable results with a "forgot-to-await" error; validate runtime phase titles + agent prompt/options before they enter progress snapshots. | **Queue** | Local `parallel()`/`pipeline()` settle their thunks (`src/workflow.ts:2058–2125`) and validate options, but there is **no explicit non-cloneable-result / forgot-to-await guard** on the script's return value. A leaked unresolved `agent()` in a returned object is not surfaced as a targeted error today. Bounded issue candidate. | | 4 | `21bfc79` (#22) | Ambient TypeScript authoring declarations for workflow-script globals (`pi-dynamic-workflows/workflow`), exported for editor IntelliSense. | **Queue** | Local ships runtime `dist/index.d.ts` and documents globals in tool guidance + `docs/architecture.md`, but ships **no ambient authoring `.d.ts`** for workflow-script globals. Editor IntelliSense for `agent()/parallel()/phase()/dag()` authoring is a gap. Bounded issue candidate. | | 5 | `7b34dec` (#23) | AST-aware determinism check: allow `Date.now()`/`Math.random()`/`new Date()` **mentions** in prompts/metadata/comments/string literals while continuing to reject their **executable** use. Replaces a raw-source regex that over-rejects. | **Queue (minor)** | Local enforces determinism two ways: a parse-time raw-source regex `DETERMINISM_BLOCKLIST` (`src/workflow.ts:439`) that **does** hard-block on raw source (so a prompt string mentioning `Date.now()` is falsely rejected), plus a runtime `DETERMINISM_PRELUDE` that neuters the builtins in-realm (more advanced than #23's AST check). The runtime prelude already solves the real problem; the parse-time regex hint is the remaining false-positive. An AST-aware hint (the project already uses `acorn`) would remove the over-rejection. Bounded issue candidate. | | 6 | `dc6ad26` | Update Pi package namespace to `@earendil-works`. | **Not applicable** | This fork is published as `pi-dynamic-workflows-oc-style`, a different package name/namespace. The namespace decision does not port. | | 7 | `31b2aca` | Release `v1.0.1` (version-string + bundled surface). | **Not applicable** | A release tag, not a mechanism. | **Summary:** 2 already present, 3 queued as bounded issues, 2 not applicable. No mechanism is *rejected* on its merits — the three queued items are genuine gaps with bounded-issue scope. None requires merging from the original branch; each would be reimplemented against this fork's architecture. ## Peer-engine watchlist The Pi catalog contains many packages whose descriptions say "workflow" or "multi-agent." This watchlist is **deliberately narrow**: a package is listed only when it demonstrates a **distinct, source-verifiable mechanism** relevant to this architecture, or materially higher adoption. All entries below were verified against the npm registry + GitHub on **2026-08-13** (versions, publish dates, and weekly downloads are point-in-time observations, not durable facts). | Package | Distinct mechanism watched for | Verified (2026-08-13) | |---|---|---| | [`pi-subagents`](https://www.npmjs.com/package/pi-subagents) — [repo](https://github.com/nicobailon/pi-subagents) | Delegated-agent **artifacts/session sharing** and a mature async runtime; single-agent delegation + scripted multi-agent workflows with truncation handling. Highest adoption in the set. | `0.48.0`, published 2026-08-13, ~69.6k weekly downloads, ~3.1k stars | | [`pi-taskflow`](https://www.npmjs.com/package/pi-taskflow) — [repo](https://github.com/heggria/taskflow) | **Statically verified/resumable task DAGs** and gates; a declarative runtime that compiles a graph into a verifiable execution contract with "trusted effects" and cross-host adapters (Pi, Codex, Claude Code, OpenCode, Grok). | `0.2.10`, published 2026-08-12, ~462 weekly downloads | | [`@zhushanwen/pi-subagent-workflow`](https://www.npmjs.com/package/@zhushanwen/pi-subagent-workflow) | **Persistent workflow state machine + execution tracing**; spawned-process agent runtime with sync/background modes and stateful workflow management. | `7.3.2`, published 2026-08-12, ~1.6k weekly downloads | | [`pi-extensible-workflows`](https://www.npmjs.com/package/pi-extensible-workflows) — [repo](https://github.com/vekexasia/pi-extensible-workflows) | **Deterministic extensibility + optional Herdr integration** (`@piewf/herdr` companion opens live/completed workflow-agent sessions in Herdr panes). Closest peer to this fork's Herdr sink model. | `5.4.0`, published 2026-08-12, ~640 weekly downloads, ~175 stars | | [`pi-crew`](https://www.npmjs.com/package/pi-crew) — [repo](https://github.com/baphuongna/pi-crew) | **Teams, worktrees, schedules, handoffs, TUI observability**; durable-state multi-agent orchestration with worktree isolation and an explicit "AI-generated, limited human review" trust disclosure. | `0.9.68`, published 2026-08-13, ~2.3k weekly downloads | | [`@onlinechefgroep/pi-agent-orchestrator`](https://www.npmjs.com/package/@onlinechefgroep/pi-agent-orchestrator) — [repo](https://github.com/OnlineChefGroep/pi-agent-orchestrator) | **Swarms, schedules, structured handoffs, prompt compression, live terminal observability**; autonomous subagents + isolated worktrees. | `0.18.0`, published 2026-07-31, ~93 weekly downloads | | [`@mjasnikovs/pi-task`](https://www.npmjs.com/package/@mjasnikovs/pi-task) — [repo](https://github.com/mjasnikovs/pi-task) | **Local-model-first planning with verify/enforce gates**; deterministic spec-orchestration driving prompts through refine→research→grill→compose→critique, with bundled web/docs/fetch worker tools. | `0.38.4`, published 2026-08-12, ~5.5k weekly downloads | > **Do not fan out.** Packages not on this list are intentionally excluded — > either their mechanism overlaps an existing watchlist entry, or their > description alone is not source-verifiable evidence of a distinct mechanism. > Adding a package requires a source-backed reason, recorded here. ## Secondary inspiration source — `mattpocock/skills` Per issue #132, [Matt Pocock's skills repository](https://github.com/mattpocock/skills) is a documented **secondary, read-only** inspiration source for workflow/skill design (stable skills, changelog, relevant ADRs at a pinned ref). It is **not** an upstream and implies no derivation or ownership. The existing acknowledgements in the `0.2.1`/`0.2.2` changelog and `CONTEXT.md` remain part of the provenance record. **Bounded update-review cadence:** inspect at a pinned stable tag/commit (never an in-progress branch); read the source repo's stable skills, changelog, and relevant ADRs at that pinned ref; record the reviewed ref/date; classify every candidate idea as adopted (release-specific credit), queued (bounded GitHub issue), rejected, or not applicable; **adapt** concepts to this architecture rather than vendoring; create bounded GitHub issues before implementation; and skip `in-progress`/`deprecated` material unless explicitly relevant. Release- specific attribution is required when an idea is adopted: name/link the source, say "adapted", and record the credit in the CHANGELOG or release notes — never only in an ephemeral issue comment. **Reviewed 2026-08-13:** pinned stable tag `v1.2.3`, release commit `6acc160` (2026-08-06); `main` HEAD at review time was `8b78b53` (2026-08-13), recorded only for freshness, not for adoption. Refs verified via the GitHub API (`api.github.com/repos/mattpocock/skills`). ## Review cadence - **Run approximately quarterly**, and additionally **before any broad workflow-engine release** of this fork. - **Pin and record** for each candidate: package/repository version, commit (short SHA), and review date. The table above records the 2026-08-13 review. - **Read source/tests/docs** for candidate mechanics. Search snippets and package descriptions are **discovery only** — a snippet is not adoption evidence. - **Classify** each candidate as one of: - **already present** — the mechanism exists in this fork (cite the local file/symbol). - **adopt** — source-backed value found; create a bounded issue and adapt the concept to this architecture. - **queue** — genuine gap, worth a bounded issue, but not in scope this cycle. - **reject** — conflicts with this fork's harness broker/catalog contract, or duplicates an existing mechanism. - **not applicable** — release tags, namespace renames, or other non-mechanism commits. - **Adapt via bounded GitHub issues; never merge or cherry-pick wholesale** into this diverged fork. - **Evaluate** each candidate against, at minimum: - security/authority (does it weaken the read-only/edit or context-security posture?), - deterministic resume (does it break the resume/journal hash contract?), - context cost (does it balloon local-model prompt windows?), - worktree/finalization behavior (does it leak dirty/transient paths?), - harness broker/catalog compatibility (does it fit `harness_type`/ `harness_config` + the workflow-lock contract?). - **Preserve original licensing and attribution.** Give **release-specific credit** for every adopted idea: name/link the source and state that the concept was *adapted*, not vendored. No adopted idea may be credited only in an ephemeral issue comment — record it in the CHANGELOG / release notes. ## Strict scope/time boundary This review process is a **watch**, not a pipeline. It cannot: - install a package, - mutate source, tests, or `package.json`, - open or merge a PR, - change the catalog/workflow-lock, - or trigger any code mutation by itself. Every adoption flows through a separate bounded GitHub issue with its own Scout → Thinker → Worker → LocalChecks → Verifier → PR delivery lane. The only output of this review is **classified findings** recorded here and in `PROVENANCE.md`, plus optionally created issues. ## Verification record for this review (2026-08-13) - **Local package:** `pi-dynamic-workflows-oc-style` `0.2.4` (this checkout, `f7e8b56`). - **Lineage refs:** verified via the GitHub API (`api.github.com/repos/...`) and npm registry (`registry.npmjs.org/...`): - `Michaelliv/pi-dynamic-workflows` → `v1.0.1`, release commit `31b2aca` (2026-05-31), npm `1.0.1` (2026-05-31). No newer release. - `QuintinShaw/pi-dynamic-workflows` → `v3.5.1`, HEAD `bab5ad7` (2026-08-05), npm `3.5.1` (2026-08-05). No newer release. - **Seven commits:** enumerated from the Michaelliv `main` commit log (`31b2aca`, `7b34dec`, `21bfc79`, `1c61834`, `c914116`, `4189d2b`, `dc6ad26`, plus the v1.0.0 base `e22388e`); mechanism descriptions from PR bodies #15, #19, #21, #22, #23. Local disposition verified by reading this checkout's `src/agent.ts` and `src/workflow.ts`. - **Peer engines:** all seven packages confirmed present on npm with active publish dates (2026-07-31 → 2026-08-13); repo URLs and descriptions from the npm registry `repository`/`description` fields and GitHub repo metadata; weekly downloads from `api.npmjs.org/downloads/point/last-week/...`. - **mattpocock/skills:** repo metadata, pinned stable tag `v1.2.3` (`6acc160`, 2026-08-06), and `main` HEAD (`8b78b53`, 2026-08-13) via the GitHub API. All version/download numbers above are point-in-time observations from 2026-08-13 and will drift; re-verify at the next review.