{"id":50312514,"url":"https://github.com/5queezer/pi-subflow","last_synced_at":"2026-05-28T22:01:53.648Z","repository":{"id":356751216,"uuid":"1233779382","full_name":"5queezer/pi-subflow","owner":"5queezer","description":"Pi extension and TypeScript orchestration core for bounded subagent workflows, including chains, parallel fanout, and validated DAG fan-in.","archived":false,"fork":false,"pushed_at":"2026-05-09T16:32:35.000Z","size":173,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-09T16:37:55.172Z","etag":null,"topics":["dag","llm-tools","pi","pi-extension","subagents","typescript","workflow-orchestration"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/5queezer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-09T10:52:49.000Z","updated_at":"2026-05-09T16:32:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/5queezer/pi-subflow","commit_stats":null,"previous_names":["5queezer/pi-subflow"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/5queezer/pi-subflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5queezer%2Fpi-subflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5queezer%2Fpi-subflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5queezer%2Fpi-subflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5queezer%2Fpi-subflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/5queezer","download_url":"https://codeload.github.com/5queezer/pi-subflow/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5queezer%2Fpi-subflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33627948,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dag","llm-tools","pi","pi-extension","subagents","typescript","workflow-orchestration"],"created_at":"2026-05-28T22:01:52.031Z","updated_at":"2026-05-28T22:01:53.627Z","avatar_url":"https://github.com/5queezer.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pi-subflow\n\nDelegate bounded work from Pi to isolated subagents with single-task, chain, parallel, and DAG workflows, including conditional edges, nested workflows, and bounded loops.\n\n`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.\n\nUse 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.\n\n## Features\n\n- Single, chain, parallel, DAG, conditional-edge, bounded-loop, and nested-workflow subagent execution\n- DAG preflight validation with precise diagnostics\n- PocketFlow node-backed internal DAG execution for validation, max-turns guards, stage execution, verifier repair, and result aggregation\n- `dagYaml` shorthand for concise LLM-authored task graphs\n- Inline nested workflows with parent/child namespacing and synthetic summaries\n- Verifier fan-in with dependency-output injection\n- Markdown-section and minimal JSON required-field validation\n- Retry, timeout, max-turn, and budget helpers\n- Project/user agent discovery with policy gates\n- Runtime tool allowlist checks\n- Workflow slash commands from `.pi/subflow/workflows/*.{yaml,yml}` and `~/.pi/agent/subflow/workflows/*.{yaml,yml}`\n- 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/`\n- JSONL run history at `.pi/subflow/runs.jsonl`\n\n## Quick start\n\n```bash\ngit clone git@github.com:5queezer/pi-subflow.git pi-subflow\ncd pi-subflow\nnpm install\nnpm run build\npi -e ./dist/extension.js\n```\n\nThen ask Pi to use the `subflow` tool, for example:\n\n```text\nUse subflow to run API, test, and docs reviewers in parallel, then run a verifier that synthesizes the findings.\n```\n\nFor 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`.\n\n```bash\nln -sfn \"$PWD/dist\" ~/.pi/agent/extensions/subflow\nnpm run build\n# then run /reload inside Pi\n```\n\n## Workflow modes\n\n```mermaid\nflowchart TD\n  U[User request] --\u003e D{Work shape?}\n  D --\u003e|One bounded task| S[Single]\n  D --\u003e|Linear handoff| C[Chain]\n  D --\u003e|Independent tasks| P[Parallel]\n  D --\u003e|Named dependencies| G[DAG]\n  P --\u003e V[Verifier fan-in]\n  G --\u003e V\n```\n\n| Mode | Use when | Input shape |\n| --- | --- | --- |\n| Single | exactly one focused subagent task is useful | `agent` + `task` |\n| Chain | each step needs the previous step's output | `chain: [{ agent, task }]` with optional `{previous}` |\n| Parallel | 2+ tasks are independent | `tasks: [...]` with no `dependsOn` |\n| DAG | tasks have named dependencies, conditional edges, verifier fan-in, or bounded loops | `tasks: [...]` with `dependsOn`, `when`, `loop`, or `dagYaml` |\n| Nested workflows | a task contains inline child tasks or statically includes a relative workflow file | `workflow: { tasks: [...] }`, `workflow: { dagYaml }`, or `workflow: { uses }` |\n\nExample DAG shorthand:\n\n```yaml\napi-review:\n  agent: reviewer\n  task: Review src/index.ts and public exports\n\ntest-review:\n  agent: reviewer\n  task: Review tests for coverage gaps\n\nfinal-verdict:\n  agent: reviewer\n  role: verifier\n  needs: [api-review, test-review]\n  task: Synthesize the findings into a prioritized verdict\n```\n\nVerifier 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.\n\n## Workflow templates\n\nExample 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:\n\n```yaml\n# yaml-language-server: $schema=https://raw.githubusercontent.com/5queezer/pi-subflow/refs/heads/master/schemas/subflow-dag.schema.json\n```\n\nRecipes (concrete jobs):\n\n- [`code-review.yaml`](examples/workflows/recipes/code-review.yaml)\n- [`implementation-planning.yaml`](examples/workflows/recipes/implementation-planning.yaml)\n- [`red-green-implementation.yaml`](examples/workflows/recipes/red-green-implementation.yaml)\n- [`research-synthesis.yaml`](examples/workflows/recipes/research-synthesis.yaml)\n- [`docs-consistency.yaml`](examples/workflows/recipes/docs-consistency.yaml)\n- [`bug-investigation.yaml`](examples/workflows/recipes/bug-investigation.yaml)\n\nPatterns (reusable DAG shapes — see [Workflow patterns](https://github.com/5queezer/pi-subflow/wiki/Workflow-patterns) for model fit and rationale):\n\n- [`adversarial-triangle.yaml`](examples/workflows/patterns/adversarial-triangle.yaml)\n- [`two-tier-audit.yaml`](examples/workflows/patterns/two-tier-audit.yaml)\n- [`tournament.yaml`](examples/workflows/patterns/tournament.yaml)\n- [`cross-validation.yaml`](examples/workflows/patterns/cross-validation.yaml)\n- [`map-group-reduce.yaml`](examples/workflows/patterns/map-group-reduce.yaml)\n\nCopy a `.yaml` or `.yml` template into `.pi/subflow/workflows/` to register it as a slash command at Pi session startup:\n\n```text\n.pi/subflow/workflows/code-review.yaml -\u003e /code-review\n.pi/subflow/workflows/code-review.yml  -\u003e /code-review\n```\n\nUser-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.\n\n## Development\n\n```bash\nnpm install\nnpm run build \u0026\u0026 npm test\n```\n\nBefore submitting changes, run:\n\n```bash\nnpm run build \u0026\u0026 npm test\n```\n\n## Optimizer\n\n`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:\n\n```text\nsubflow_optimize({\n  workflowPath | dagYaml,\n  evalSet: { path | inline },\n  candidateDagYamls?,\n  maxCandidateRuns?,\n  maxCost?,\n  maxRunCost?,\n  maxCandidateCost?,\n  maxTotalCost?,\n  maxConcurrency?,\n  timeoutSeconds?,\n})\n```\n\n- Use `subflow_propose_candidates` to generate candidate YAMLs, then pass selected valid outputs to `subflow_optimize` as `candidateDagYamls`.\n- 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.\n- Canonical eval sets should be stored at `.pi/subflow/evals/*.yaml` and loaded via `evalSet.path`.\n- For quick experiments, use `evalSet.inline` (not recommended for reusable cases).\n- `maxCandidateRuns` limits candidate runs per case.\n- `maxRunCost` caps cost per run, `maxCandidateCost` caps total cost per candidate, and `maxTotalCost` caps total optimizer spend.\n- `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.\n- `maxConcurrency` and `timeoutSeconds` control executor behavior.\n- Invalid candidates are reported individually and do not abort the entire optimizer run.\n- Reports are written under `.pi/subflow/optimizer-reports/`.\n- Optimizer assets: [`examples/evals/docs-consistency.yaml`](examples/evals/docs-consistency.yaml), [`examples/workflows/recipes/docs-consistency.yaml`](examples/workflows/recipes/docs-consistency.yaml)\n\n## Documentation\n\n- [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`.\n- [`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\n- [`schemas/subflow-dag.schema.json`](schemas/subflow-dag.schema.json) — YAML schema for workflow templates\n- [`schemas/subflow-eval.schema.json`](schemas/subflow-eval.schema.json) — YAML schema for optimizer eval sets\n- [`doc/adr/`](doc/adr/) — architecture decision records\n- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution workflow\n\nKeep 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.\n\n## License\n\nISC\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5queezer%2Fpi-subflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F5queezer%2Fpi-subflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5queezer%2Fpi-subflow/lists"}