Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/5queezer/pi-subflow

Pi extension and TypeScript orchestration core for bounded subagent workflows, including chains, parallel fanout, and validated DAG fan-in.
https://github.com/5queezer/pi-subflow

dag llm-tools pi pi-extension subagents typescript workflow-orchestration

Last synced: 15 days ago
JSON representation

Pi extension and TypeScript orchestration core for bounded subagent workflows, including chains, parallel fanout, and validated DAG fan-in.

Awesome Lists containing this project

README 

          
# pi-subflow



Delegate bounded work from Pi to isolated subagents with single-task, chain, parallel, and DAG workflows, including conditional edges, nested workflows, and bounded loops.



`pi-subflow` is a Pi extension and TypeScript orchestration core for coordinating focused subagents without putting planning, policy checks, execution, validation, and rendering into one oversized prompt.



Use it when work benefits from independent research/review streams, staged handoffs, or a final verifier. Do not use it for small direct tasks the current assistant can do faster by itself.



## Features



- Single, chain, parallel, DAG, conditional-edge, bounded-loop, and nested-workflow subagent execution

- DAG preflight validation with precise diagnostics

- PocketFlow node-backed internal DAG execution for validation, max-turns guards, stage execution, verifier repair, and result aggregation

- `dagYaml` shorthand for concise LLM-authored task graphs

- Inline nested workflows with parent/child namespacing and synthetic summaries

- Verifier fan-in with dependency-output injection

- Markdown-section and minimal JSON required-field validation

- Retry, timeout, max-turn, and budget helpers

- Project/user agent discovery with policy gates

- Runtime tool allowlist checks

- Workflow slash commands from `.pi/subflow/workflows/*.{yaml,yml}` and `~/.pi/agent/subflow/workflows/*.{yaml,yml}`

- Dry-run workflow optimization with `subflow_optimize`, scorer-backed eval sets, objective scoring, manual candidate comparison, train/holdout splits, budget controls, and safe JSON reports in `.pi/subflow/optimizer-reports/`

- JSONL run history at `.pi/subflow/runs.jsonl`



## Quick start



```bash

git clone git@github.com:5queezer/pi-subflow.git pi-subflow

cd pi-subflow

npm install

npm run build

pi -e ./dist/extension.js

```



Then ask Pi to use the `subflow` tool, for example:



```text

Use subflow to run API, test, and docs reviewers in parallel, then run a verifier that synthesizes the findings.

```



For local development, you can symlink the built extension and reload Pi after rebuilding. The build also links `dist/node_modules` back to the project dependencies so Pi can resolve runtime packages such as `yaml` when the extension directory points at `dist`.



```bash

ln -sfn "$PWD/dist" ~/.pi/agent/extensions/subflow

npm run build

# then run /reload inside Pi

```



## Workflow modes



```mermaid

flowchart TD

  U[User request] --> D{Work shape?}

  D -->|One bounded task| S[Single]

  D -->|Linear handoff| C[Chain]

  D -->|Independent tasks| P[Parallel]

  D -->|Named dependencies| G[DAG]

  P --> V[Verifier fan-in]

  G --> V

```



| Mode | Use when | Input shape |

| --- | --- | --- |

| Single | exactly one focused subagent task is useful | `agent` + `task` |

| Chain | each step needs the previous step's output | `chain: [{ agent, task }]` with optional `{previous}` |

| Parallel | 2+ tasks are independent | `tasks: [...]` with no `dependsOn` |

| DAG | tasks have named dependencies, conditional edges, verifier fan-in, or bounded loops | `tasks: [...]` with `dependsOn`, `when`, `loop`, or `dagYaml` |

| Nested workflows | a task contains inline child tasks or statically includes a relative workflow file | `workflow: { tasks: [...] }`, `workflow: { dagYaml }`, or `workflow: { uses }` |



Example DAG shorthand:



```yaml

api-review:

  agent: reviewer

  task: Review src/index.ts and public exports



test-review:

  agent: reviewer

  task: Review tests for coverage gaps



final-verdict:

  agent: reviewer

  role: verifier

  needs: [api-review, test-review]

  task: Synthesize the findings into a prioritized verdict

```



Verifier tasks receive dependency outputs automatically. A verifier with no explicit `dependsOn` depends on all non-verifier tasks. `dagYaml` is parsed as YAML, so arrays can be written inline (`needs: [api-review, test-review]`) or as block sequences. Conditional edges use `when` expressions against dependency outputs. Nested workflows namespace child task names under the parent, flow the parent `dependsOn` into workflow roots, and expose a synthetic parent summary for downstream dependents. Bounded loops repeat a namespaced body up to `loop.maxIterations`, can stop early with `loop.until`, and expose a synthetic loop summary for downstream dependents. DAG execution is node-backed internally even though the public API stays `runDag`; chain and parallel remain custom orchestration.



## Workflow templates



Example workflows live in [`examples/workflows/`](examples/workflows/), split into concrete **recipes** (task-specific jobs) and abstract **patterns** (reusable shapes). Both advertise the DAG YAML schema with:



```yaml

# yaml-language-server: $schema=https://raw.githubusercontent.com/5queezer/pi-subflow/refs/heads/master/schemas/subflow-dag.schema.json

```



Recipes (concrete jobs):



- [`code-review.yaml`](examples/workflows/recipes/code-review.yaml)

- [`implementation-planning.yaml`](examples/workflows/recipes/implementation-planning.yaml)

- [`red-green-implementation.yaml`](examples/workflows/recipes/red-green-implementation.yaml)

- [`research-synthesis.yaml`](examples/workflows/recipes/research-synthesis.yaml)

- [`docs-consistency.yaml`](examples/workflows/recipes/docs-consistency.yaml)

- [`bug-investigation.yaml`](examples/workflows/recipes/bug-investigation.yaml)



Patterns (reusable DAG shapes — see [Workflow patterns](https://github.com/5queezer/pi-subflow/wiki/Workflow-patterns) for model fit and rationale):



- [`adversarial-triangle.yaml`](examples/workflows/patterns/adversarial-triangle.yaml)

- [`two-tier-audit.yaml`](examples/workflows/patterns/two-tier-audit.yaml)

- [`tournament.yaml`](examples/workflows/patterns/tournament.yaml)

- [`cross-validation.yaml`](examples/workflows/patterns/cross-validation.yaml)

- [`map-group-reduce.yaml`](examples/workflows/patterns/map-group-reduce.yaml)



Copy a `.yaml` or `.yml` template into `.pi/subflow/workflows/` to register it as a slash command at Pi session startup:



```text

.pi/subflow/workflows/code-review.yaml -> /code-review

.pi/subflow/workflows/code-review.yml  -> /code-review

```



User-level workflow files are also supported under `~/.pi/agent/subflow/workflows/`. If a project and user workflow have the same command name, the project workflow wins. During prompt-resource discovery, the extension writes generated prompt stubs under `.pi/subflow/prompts/` or `~/.pi/agent/subflow/prompts/` when no manual prompt file with the same name exists, so Pi can discover the workflow prompt surface. Run `/reload` or start a new session after adding, removing, or renaming workflow files.



## Development



```bash

npm install

npm run build && npm test

```



Before submitting changes, run:



```bash

npm run build && npm test

```



## Optimizer



`subflow_propose_candidates` generates validated static DAG candidate YAMLs without executing or mutating workflows. `safe` and `exploratory` currently share the verifier fan-in transform; `model-thinking` proposes deterministic verifier-only model/thinking variants for later optimizer evaluation. `subflow_optimize` is dry-run-only and writes JSON reports without mutating workflow files:



```text

subflow_optimize({

  workflowPath | dagYaml,

  evalSet: { path | inline },

  candidateDagYamls?,

  maxCandidateRuns?,

  maxCost?,

  maxRunCost?,

  maxCandidateCost?,

  maxTotalCost?,

  maxConcurrency?,

  timeoutSeconds?,

})

```



- Use `subflow_propose_candidates` to generate candidate YAMLs, then pass selected valid outputs to `subflow_optimize` as `candidateDagYamls`.

- Use `strategy: "model-thinking"` to generate verifier-only model/thinking variants from the built-in Mini/Strong search space; Bayesian search, all-task mutation, and custom search spaces are future work.

- Canonical eval sets should be stored at `.pi/subflow/evals/*.yaml` and loaded via `evalSet.path`.

- For quick experiments, use `evalSet.inline` (not recommended for reusable cases).

- `maxCandidateRuns` limits candidate runs per case.

- `maxRunCost` caps cost per run, `maxCandidateCost` caps total cost per candidate, and `maxTotalCost` caps total optimizer spend.

- `maxCost` is a compatibility alias for current per-candidate budget behavior; when no dedicated caps are provided, it is also passed as the run-level cost cap.

- `maxConcurrency` and `timeoutSeconds` control executor behavior.

- Invalid candidates are reported individually and do not abort the entire optimizer run.

- Reports are written under `.pi/subflow/optimizer-reports/`.

- Optimizer assets: [`examples/evals/docs-consistency.yaml`](examples/evals/docs-consistency.yaml), [`examples/workflows/recipes/docs-consistency.yaml`](examples/workflows/recipes/docs-consistency.yaml)



## Documentation



- [GitHub Wiki](https://github.com/5queezer/pi-subflow/wiki) — detailed usage, TypeScript API, configuration, policy, architecture, current DAG expressiveness (conditional edges, nested workflows, bounded loops), remaining graph roadmap items, workflow optimization, self-optimizing static DAGs, and troubleshooting. Source pages live in [`doc/wiki/`](doc/wiki/) and are published with `npm run wiki:sync` or `npm run wiki:sync:push`.

- [`doc/wiki/Workflow-optimization.md`](doc/wiki/Workflow-optimization.md) — dry-run optimizer, canonical eval sets, scorer-backed recommendations, train/holdout splits, and safety model

- [`schemas/subflow-dag.schema.json`](schemas/subflow-dag.schema.json) — YAML schema for workflow templates

- [`schemas/subflow-eval.schema.json`](schemas/subflow-eval.schema.json) — YAML schema for optimizer eval sets

- [`doc/adr/`](doc/adr/) — architecture decision records

- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution workflow



Keep the README, wiki, ADRs, and the `subflow` tool's LLM-facing guidance synchronized when behavior, schema, validation, public API, install/test commands, or design rationale change.



## License



ISC