pi-workflow

A personal, session-persistent workflow extension for Pi. Its workflow tool schemas are always visible to Pi, but orchestration remains opt-in: Pi stays a normal coding agent until you explicitly start a workflow with /work <task>. It then turns that task into a controlled loop:

clarify → plan → user approval → execute small tasks → verify goal
                                      ↑                   │
                                      └── remediation ─────┘

It stops in explicit waiting, blocked, paused, complete, or cancelled states rather than treating prose as completion.

Install

This is a project-local directory extension:

.pi/extensions/pi-workflow/index.ts

Trust the project if prompted, then run /reload or restart Pi.

Runtime requirement

Use this workflow in Pi's interactive TUI (or an RPC host with dialogs). Print and JSON mode intentionally do not perform automatic continuation because their sessions terminate after a response.

Visibility and activation

workflow_question, workflow_plan, workflow_task, workflow_verify, workflow_wait, and workflow_blocked remain visible in Pi's tool list for the entire session. They fail closed when no matching active workflow phase exists. This keeps the tool schema stable and discoverable without making normal conversations enter workflow mode.

Only /work <task> creates a work item and enables the workflow system contract, task widget, and automatic continuation.

Start and manage work

/work Add GitHub OAuth login and verify the full login flow
/work status
/work plan        # show the saved plan without changing execution
/work show        # alias for /work plan
/work tasks       # show live task graph/status without changing execution
/work summary     # show goal outcome, evidence, blockers, and waits
/work approve
/work pause
/work resume
/work cancel

Only one unfinished work item exists in a session. Its state is stored in branch-aware Pi custom entries, so reload, resume, and /tree restore the state matching the selected conversation branch.

Plan review

When Pi calls workflow_plan, pi-workflow writes the proposed Markdown to plan.md in the current project directory and opens a review editor in Pi. Read or revise the full plan there. The review choices also include Edit in configured external editor, which launches Pi's configured editor (for example, nano) against a temporary plan.md copy and saves its returned contents. After editing, choose one action:

• Approve and execute — saves the reviewed text to plan.md and begins the first ready task.
• Request changes — enter revision feedback; Pi returns to planning and must submit a revised plan.
• Edit in Pi again — reopen Pi's multiline editor and review again.
• Edit in configured external editor — use nano or another editor configured in Pi, then return to review.
• Keep for later — retains plan.md and the work item in awaiting_approval; run /work approve or /work review later.

Non-interactive modes save the plan but never auto-approve it.

Console status

While a work item is clarifying, planning, awaiting approval, executing, verifying, waiting, or blocked, pi-workflow renders a compact widget above Pi's editor with the objective, phase, completed/total task count, and current task. It clears this widget when the workflow is paused, complete, cancelled, or absent.

workflow_plan writes the full plan to plan.md and the full task graph to tasks.md in the project directory. The final goal/outcome report is printed in Pi through terminal tool output or /work summary; no summary.md file is created. tasks.md is refreshed whenever workflow state changes, including task start/completion, remediation, waiting, blocking, and verification. Run /work plan or /work show to print the current plan, or /work tasks to print the live task list and its path, without changing workflow state or stopping execution.

Workflow phases

Phase	Meaning	How it exits
clarifying	Pi inspects first and asks only material user decisions.	Pi saves a plan.
planning	Pi prepares an implementation-ready plan and task graph.	workflow_plan.
awaiting_approval	Pi has saved a plan; direct edit/write and obvious mutating shell forms are blocked.	/work approve.
executing	Pi works one dependency-ready task at a time.	All tasks complete, wait, block, or pause.
verifying	Pi audits the original objective requirement-by-requirement.	Complete, or remediation tasks.
waiting	An external person/system/agent must wake the work.	/work resume.
blocked	You or an external party must take a concrete action.	/work resume.
paused, complete, cancelled	Stopped states.	Resume where applicable, or start another work item.

Model tools

The extension gives Pi these tools:

• workflow_question — one material clarification with 2–4 choices and an Other response.
• workflow_plan — saves the Markdown plan plus a dependency-aware task graph. It always waits for /work approve.
• workflow_task — starts or completes exactly one task, retaining task evidence.
• workflow_verify — records full-goal evidence. A failed verification must add remediation tasks, returning to execution.
• workflow_wait — records an external wait reason and stops continuation.
• workflow_blocked — records a concrete blocker and evidence, then stops continuation.

Automatic continuation guards

The internal orchestrator observes Pi's agent_settled lifecycle. While a phase is active, it continues the workflow only when Pi is idle. It pauses after either 25 automatic continuations or three settled turns without a state-changing workflow tool result. These are deliberately conservative MVP defaults.

Current scope and integration boundary

This extension is self-contained; it does not require rpiv-todo, rpiv-ask-user-question, pi-plan-mode, or pi-goal. Its tools deliberately model the same concepts so it can later gain adapters:

• replace workflow_question with ask_user_question;
• mirror tasks into rpiv-todo;
• use pi-plan-mode for the read-only planning surface;
• delegate automatic execution and external wake deadlines to pi-goal through its managed-run event protocol.

Do not run pi-goal as a second autonomous loop for the same work item yet: both extensions would attempt continuation. The planned adapter must give pi-goal ownership of execution and make pi-workflow the durable orchestration/phase state owner.

Limitations

The orchestrator enforces valid phase and task transitions and blocks direct file edits/writes plus obvious mutating shell forms before approval. It cannot independently prove command results or recognize every shell script mutation. Verification evidence remains model-provided and should be reviewed for important work. This is a personal-use MVP; swarm roles and assignment are intentionally out of scope.