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 independent work and follow the active subagent delegation mode. Without pi-better-subagents, the plan uses adaptive guidance. Manual keeps planned work in the foreground unless the user or an active workflow explicitly requires delegation. Adaptive delegates substantial independent work when useful. Coordinator consults current catalog roles and delegates nontrivial role-owned work while retaining integration and final verification in the foreground.

Independent foreground and delegated milestones may both be in_progress only when both are actually underway. 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 generic checklist updates until workflow ownership is released. /plan never opens a stale generic checklist during workflow ownership.

For rush-issues, call sync_workflow_plan once with the absolute .resolve-issues/rush/<run-id>/task-plan.json path and its persisted planRevision. This binds the run to the session and shows its fleet stages and units in the widget, /plan, and get_plan; the binding survives Pi session resume, and ownership release restores the prior generic checklist. After that, record every transition with update_plan and a workflow object instead of editing task-plan.json or the profiling log by hand:

{ "workflow": {
  "event": "unit-validated",
  "revision": 12,
  "changes": [
    { "id": "1201", "set": { "stage": "done", "status": "succeeded", "worker": null, "headSha": "abc123" } },
    { "id": "C1", "set": { "status": "combining" } }
  ],
  "profiling": { "outcome": "succeeded", "wallMs": 540000 }
} }

changes addresses units, components, and fleet stages by id (a change without an id sets run-level fields); all changes in one call are one transition. For a scope change, a change with target unit or component and an add row appends a new row; existing rows cannot be removed or renamed. The tool checks ids, dependencies (including cycles), worker slots, and status/stage values against the Rush contract (a fleet status of n/a is saved as not-applicable), refuses a stale revision, appends an optional decision, then saves the plan atomically with planRevision + 1 and a new updatedAt, and appends one profiling event with the same revision to the log the run already uses (profiling/run.jsonl or profiling.jsonl). A rejected update changes nothing. The event is appended before the plan is renamed into place, so a crash between the two can leave the log one revision ahead; the next update notices, reuses that revision, and marks its event with logAheadRevision. Other workflow-owned skills retain their own planning and have no generic plan view.

Plan Display

Native and workflow-synced plans share a plan heading, completion counts, aligned identifiers and titles, and status colors. Completed rows use ✓, active rows ●, pending rows ○, and blocked rows !. Active and blocked rows also carry text labels; failed workflow rows use × and failed rather than an active indicator.

Workflow identity, revision, and fleet progress sit on a secondary line that wraps on narrow terminals. /plan uses the same styling and shows workflow stage, raw status, worker, dependencies, and notes beneath each issue. Use ↑/↓ to move the selection and Escape or ← to return. The passive widget never captures editor arrow keys.

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