![\"Animated](\"https://raw.githubusercontent.com/wichayutdew/pi-workflows/main/assets/demo.gif\")
\n \n\n \n \n \n
Animated preview — select it to download the full 73-second MP4.
\n\n## At a glance\n\n| Summary and status | Workflow details |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |\n|![\"Pi](\"https://raw.githubusercontent.com/wichayutdew/pi-workflows/main/assets/Summary.png\")
| ![\"Pi](\"https://raw.githubusercontent.com/wichayutdew/pi-workflows/main/assets/Details.png\")
|\n| See progress, approvals, and outcome at a glance. | Inspect each workflow step and its execution details. |\n\n## Why Pi Workflows\n\n- **Declarative & Structured**: Turn multi-step agent tasks into clear, reviewable workflow definitions with predictable `ready`, `blocked`, `handoff`, and `gaps` transitions.\n- **Typed Handoffs**: Models provide only concrete `completed` and `remaining` items; the extension validates their outcome semantics and renders canonical Markdown.\n- **Durable Checkpoints**: Pause for human approval or feedback and resume seamlessly without repeating completed steps.\n- **Safe Worktree Iterations**: Keep worktree-bound iterations isolated and carry forward verified changes for follow-up enhancements.\n- **Resource & Loop Guarding**: Enforce strict tool and Bash allowlists and halt runaway loops before they exceed step limits.\n- **Role Profiles**: Assign workflow-owned roles (`scout`, `planner`, `worker`, `reviewer`) with custom model and thinking overrides.\n- **Live Terminal UI**: Interactive status board, execution path visualization, step transcript inspection, and real-time cost ledger.\n\n## Closed outcome protocol\n\nEvery step chooses one of four outcomes:\n\n- `ready`: the active step is complete; transition to another step or `$done`.\n- `blocked`: user input is required; transition only to `$pause` and put the question in `remaining`.\n- `handoff`: actionable active-step work remains; transition only back to the same step.\n- `gaps`: an earlier step must refresh requirements or work; transition only to an earlier ordinary step.\n\nCompletion calls contain `outcome`, `completed`, and `remaining`. A `ready`\nresult uses exactly `No active-step work remains.` as its sole remaining item.\nThe extension—not the model—formats these fields into the durable Markdown\nhandoff. Gate artifacts and ready-only workspace bindings remain separate,\nconditionally permitted completion fields.\n\n## Quick Installation\n\nInstall the published extension in Pi:\n\n```bash\npi install npm:@wichayutdew/pi-workflows\n```\n\n## Herdr workflow status\n\nWhen Pi runs delegated workflow steps, the parent agent may be idle while child work continues. Pi Workflows includes a Herdr companion extension that reports workflow lifecycle state so the pane remains **working** until the workflow completes, pauses, or is interrupted.\n\nThe companion is inactive unless Herdr provides `HERDR_ENV=1`, `HERDR_SOCKET_PATH`, and `HERDR_PANE_ID`. It uses Herdr's existing managed Pi reporter, so it does not create a competing pane agent.\n\n### Reapply after a Herdr update\n\nHerdr manages `~/.pi/agent/extensions/herdr-agent-state.ts`; an integration update can replace the workflow lifecycle patch. Locate the installed package with `pi list`, change into that package directory, and run:\n\n```bash\nnpm run patch:herdr\n```\n\nThe script patches the managed integration at its default location. It is idempotent, so it is safe to run after every Herdr update. To patch a non-default integration path, set `HERDR_PI_EXTENSION_PATH` before running the script:\n\n```bash\nHERDR_PI_EXTENSION_PATH=/path/to/herdr-agent-state.ts npm run patch:herdr\n```\n\nRestart Pi or run `/reload` after patching. If Herdr's managed extension changes shape and the script reports an unsupported layout, do not edit it manually; update Pi Workflows or report the integration change.\n\n## Explore\n\n- [Getting started guide](./GETTING_STARTED.md) — install Pi Workflows and run your first workflow.\n- [Contribution guide](./CONTRIBUTING.md) — development setup, code conventions, test layers, and validation pipeline.\n- [Documentation → OpenWiki](./openwiki/quickstart.md) — architecture, workflow authoring, security, integrations, and development references.\n\n## License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.md"}