Pi Visual Plan

A project-local pi extension that separates idea discovery from implementation design, writes the plan to Markdown, and renders Mermaid UML on a live localhost site.

Install

Install for your user account:

pi install npm:pi-visual-plan

Or try it for one run without installing:

pi -e npm:pi-visual-plan

To share it through project settings, install it locally with pi install -l npm:pi-visual-plan. Pi installs the package after collaborators trust the project.

Update or remove it with:

pi update npm:pi-visual-plan
pi remove npm:pi-visual-plan

For local development, clone the repository, run npm install in .pi/extensions/visual-plan/, and use /reload after changing extension code.

Commands

• /visual-plan on — enter read-only planning mode
• /visual-plan off — leave planning mode and restore tools
• /visual-plan open — open the localhost viewer
• /visual-plan status — show phase, file, and URL
• /visual-plan execute — validate and begin an approved implementation plan
• /visual-plan — toggle the mode

Start directly with pi --visual-plan. The viewer uses a free localhost port for each Pi session, so always use /visual-plan open or /visual-plan status rather than assuming a URL. Set PI_VISUAL_PLAN_PORT only when you need a fixed port; startup fails clearly if that port is occupied.

Workflow

1. Enable the mode and discuss the product idea. The agent records prose only.
2. Once goals and constraints are understood, the agent moves to implementation design.
3. The implementation plan must contain Mermaid classDiagram and/or stateDiagram-v2 fenced blocks.
4. Open the live viewer. Its header shows the project directory, and it refreshes when .pi/plans/plan.md changes.
5. Review the plan and run /visual-plan execute when approved.

Planning mode disables pi's edit, write, and bash tools. Its dedicated visual_plan_write tool can only replace the plan file and validates stage rules before writing.

Mermaid example

```mermaid
classDiagram
  PlanMode --> PlanRepository
  PlanRepository --> ViewerServer
```

```mermaid
stateDiagram-v2
  [*] --> Idea
  Idea --> Implementation: requirements understood
  Implementation --> Approved
  Approved --> Executing
```

The viewer serves only on 127.0.0.1, uses local npm assets (no CDN), disables raw HTML in Markdown, and configures Mermaid's strict security mode. It reports missing and unreadable plan files explicitly and exposes local viewer diagnostics at /api/status.