pi-plan-exec

Turn a Markdown execution plan into an isolated, resumable Pi run.

pi-plan-exec solves the control problem of long-running AI implementation. A capable agent can lose context, repeat work, skip verification, or start a second writer after a restart. This extension moves task order, retry limits, worktree checks, and recovery out of prompt prose into durable controller state. It has been exercised in runs lasting a few hours; the controller keeps polling instead of asking one chat prompt to remember the whole job.

It executes one checked-list task at a time in a Git checkout you choose, then runs review and fix stages with fresh Pi subagents and optional Fusion. A worker saying “done” is not enough: the plan’s checked items are the implementation record.

Experimental. Start with disposable repositories or reviewable worktrees.

What it does

• Keeps one writer in one checkout. /exec always asks whether to use an isolated Git worktree or work in place. Isolated runs move the interactive Pi session into that worktree, so its tools and footer use the execution branch.
• Executes plans deterministically. It selects the first incomplete task, starts a fresh worker, and verifies completion from the plan checkboxes.
• Recovers deliberately. A reload reattaches a matching run owned by the returning session. /exec resume takes over a run whose owning session is proven dead, and resets a run whose worker is provably gone before continuing it. Compare-and-set records, operation IDs, controller locks, and leases avoid intentionally starting another writer or losing a pause or cancellation.
• Reviews before it finishes. It runs comprehensive, smells, Fusion, and critical review/fix phases. Fusion >=0.7.0 validates the strict plan-review-v1 output contract; plan-exec consumes only top-level callerOutput.output and fails closed when validation evidence is absent. If Fusion is unavailable, the Fusion review stage falls back to the pi-subagents reviewer without changing the persisted operation ID. Unresolved findings remain visible in the final completed_with_findings state.

Install and run

Install the required packages, then plan-exec. Fusion is optional; install it for the preferred Fusion review provider:

pi install npm:pi-subagents
pi install npm:@tintinweb/pi-tasks
pi install 'npm:@alexeiled/pi-subagents-bridge@>=0.2.2'
pi install 'npm:@alexeiled/pi-fusion@>=0.7.0'
pi install npm:@alexeiled/pi-plan-exec

The providers remain independent Pi packages. pi-plan-exec requires Bridge 0.2.2 or later for safe operation lookup and pi-subagents workflow execution. Fusion is optional: the controller falls back to the pi-subagents reviewer when Fusion is absent or its launch response is unusable.

Reload Pi. From an interactive session in a Git repository, run an executable plan:

/reload
/exec help
/exec docs/plans/20260713-add-greeting.md

While it runs, Pi shows the execution-worktree path, branch, stage, and worker. Four verbs cover everything after the start:

• /exec status only observes; it never interrupts or restarts a run. With no run ID it lists every run, groups the ones that claim a worker by the evidence for that claim, reports any missing package with its install command, and ends every row in one next command. Add a full run ID for one run in detail, or --all to include terminal runs older than a day.
• /exec resume continues or recovers anything stuck. It takes the lease over from a session proven dead, resets a run whose worker is provably gone and then continues it, and asks before retrying a task blocked outside the run or rebinding the execution branch after external work moved the worktree. It never launches on partial evidence: a run whose worker cannot be proven gone is reported, not reset. A model or provider failure is retried with the model this Pi session is signed in to and does not consume an implementation retry; --model current or --model provider/model is an advanced override for that one replacement child and never pins later workers.
• /exec stop asks whether to pause the run (resumable) or cancel it (final, worktree preserved).
• /exec cleanup retires run records. It previews by default and deletes nothing; --apply removes the registry entry — never the worktree, branch, or progress file — for terminal runs that finished more than 7 days ago. failed runs are excluded, because their record is what /exec resume needs.

Implementation checkboxes remain sequential and cannot be force-skipped. When a provider operation may still exist, plan-exec keeps its recorded operation ID and reconciles it before any retry. If a review, finalization, or statistics stage cannot recover, /exec skip <full-run-id> --reason <text> stops the tracked child before recording an explicit waiver and advancing. It never skips implementation or archival, and the run finishes as completed_with_findings. The installed exec-plan skill is also available as /skill:exec-plan for the plan format, the recovery rules, and the retired names and flags a scripted agent uses instead of a prompt.

The Guide defines the accepted plan format, including the exact heading and checkbox rules. Omit the path to select an eligible Markdown plan below docs/plans/.

Runtime model

flowchart LR
    plan["Markdown plan"] --> controller["durable controller"]
    controller --> bridge["pi-subagents-bridge"]
    bridge --> worker["fresh worker / reviewer"]
    worker --> worktree["Git worktree"]
    worktree --> checks["plan checkboxes"]
    checks --> controller
    controller --> fusion["optional pi-fusion panel + judge"]
    fusion -. unavailable .-> bridge
    fusion --> controller
    controller --> result["completed or completed_with_findings"]

pi-plan-exec owns plan-specific control flow. Existing Pi packages retain ownership of subagent execution, task UI, and multi-model review.

Read next

• Guide — requirements, executable-plan format, commands, lifecycle, recovery, and safety limits.
• Architecture — component ownership, state, RPC contracts, stages, and trust boundaries.
• Development — local verification and release process.
• Changelog — release history and compatibility changes.
• Original design record — design decisions and intended behavior.

License

MIT