pi-better-plan

pi-better-plan keeps a structured execution plan visible while Pi works.

What It Does

• Gives models update_plan and get_plan tools for atomic, explicit progress updates.
• Supports dependency edges (id and dependsOn) so independent ready steps can run concurrently.
• Shows the complete checklist of completed, active, pending, and blocked steps above the editor.
• Persists plan state and display preferences on the active Pi session branch.
• Keeps a completed plan visible for 30 seconds, then clears it automatically.
• Opens the complete plan with /plan.

Plan progress is checklist progress, not an estimate of effort. The extension never infers completion from prose or successful tool calls.

Coordinating Delegated Work

Use the plan as the foreground coordinator's milestone ledger. Delegate independent, sufficiently substantial work early with subagents, and use background tasks for long-running processes or repeated checks. Keep doing unblocked foreground work after launch; do not poll workers.

Before the first implementation milestone, check for an independent task that can run alongside foreground work. Launch a bounded subagent task when available; otherwise state the specific dependency or shared-worktree constraint that rules delegation out. The plan records milestones, not worker scheduling.

Independent foreground and delegated milestones may both be in_progress. Use steps for distinct deliverables, not individual worker processes; worker tools and the background-work navigator own run status. Complete verification and the plan only after every relevant delegated task is terminal and its result or failure has been inspected and integrated.

For a DAG, assign stable ids to prerequisite steps and list those ids in dependent steps' dependsOn. Dependencies must exist in the same plan; cycles and starting or completing a step before its prerequisites are complete are rejected. get_plan reports pending steps whose prerequisites are complete as ready. Plans without edges keep their existing behavior.

When an explicitly invoked skill declares workflow-role: coordinator in its metadata, that skill's task plan takes precedence. The generic checklist stays persisted but is hidden, and update_plan refuses competing updates until workflow ownership is released. /plan never opens a stale generic checklist during workflow ownership.

For rush-issues, call sync_workflow_plan with the absolute .resolve-issues/rush/<run-id>/task-plan.json path and its persisted planRevision after each checkpoint. This binds the active run to the session and displays its fleet stages and actual units in the widget, /plan, and get_plan. The view reads the file without writing to it; revision mismatches are rejected. The run binding survives Pi session resume, and ownership release restores the prior generic checklist. Other workflow-owned skills retain their own planning and have no generic plan view.

Install

pi install npm:pi-better-plan

Commands

/plan
/plan clear
/plan hide
/plan show
/plan pin auto
/plan pin on
/plan pin off

pin auto and pin on currently use the compact widget until Pi exposes a reserved right-rail extension interface. A floating overlay is intentionally not used as a substitute because it would cover transcript content.

Development

npm run verify