openspec-plannotator

Pi extension that bridges OpenSpec and Plannotator — visually review and annotate OpenSpec-generated plans (proposal, design, tasks) in Plannotator's browser UI, then send structured feedback back to the coding agent.

Prerequisites

• Pi >= 0.53.0
• Plannotator Pi extension installed:

  pi install npm:@plannotator/pi-extension

• OpenSpec skills configured in Pi

Install

Copy the extension to your Pi extensions directory:

cp openspec-plannotator.ts ~/.pi/agent/extensions/

Restart Pi. The extension auto-loads from ~/.pi/agent/extensions/.

Usage

Workflow

/opsx:propose "Add authentication"
  → proposal.md, design.md, tasks.md generated
  → 💡 Auto-notification: "Use /opsx-review to open in Plannotator"

/opsx-review
  → Select change → Select artifact (tasks/design/proposal)
  → Plannotator UI opens in browser
  → Annotate visually → Feedback sent to agent

/opsx:apply
  → Agent implements the plan

/plannotator-review
  → Visual code review of git diff

Commands

Command	Description
/opsx-review	Select change and artifact interactively, open in Plannotator
/opsx-review <change> <artifact>	Open specific artifact directly (e.g. /opsx-review auth tasks.md)

Auto-notification

When the agent writes or edits openspec/changes/*/tasks.md, a notification appears suggesting /opsx-review. Notifications are throttled (30s cooldown) to avoid noise.

How It Works

1. Reads OpenSpec artifacts from openspec/changes/<name>/ directory
2. Starts a local HTTP server serving Plannotator's annotation UI (HTML loaded from the installed @plannotator/pi-extension package)
3. Opens the browser to the local server
4. Waits for user annotations/feedback in the Plannotator UI
5. Sends feedback back to the agent via pi.sendUserMessage()

License

MIT