Plan-Collab: Collaborative Plan Review

A web interface for reviewing and commenting on Claude's implementation plans. Users can select text and add inline comments (like Google Docs), answer questions in a dedicated panel, and track plan versions.

When to Use

Use this skill when:

• Entering plan mode to create detailed implementation plans
• User wants to review and comment on plans
• You need structured user feedback on implementation approaches
• Creating complex multi-step plans that benefit from user review

Quick Start

1. Start Server and Open Plan

# Start the web server (finds available port automatically)
cd ~/.claude/skills/plan-collab/scripts
node cli.js start-server

# Open a plan in the browser
node cli.js open-plan ~/.claude/plans/my-feature.md

2. Get User Feedback

After user has reviewed and added comments:

# Fetch pending comments and answers
node cli.js get-feedback

Output:

{
  "planPath": "~/.claude/plans/my-feature.md",
  "planName": "my-feature",
  "pending": {
    "comments": [
      {
        "selectedText": "use Redis for caching",
        "comment": "Can we use Memcached instead?",
        "status": "OPEN"
      }
    ],
    "answers": []
  },
  "summary": {
    "totalComments": 1,
    "openComments": 1,
    "pendingComments": 1
  }
}

3. Check Status

node cli.js status

Server Management

IMPORTANT: Always Check Status First

Before starting the server, ALWAYS check if it's already running:

node cli.js status

If server is running (response shows "running": true):

• DO NOT run start-server - use the existing instance
• Note the URL from the response (e.g., http://localhost:3847)
• Proceed directly to open-plan

If server is not running (response shows "running": false):

• Run node cli.js start-server

Note: The start-server command is idempotent - if the server is already running, it returns {"status": "already_running", ...} and exits safely. However, checking status first is more efficient and avoids unnecessary startup attempts.

Commands Reference

Command	Description	Example
start-server	Start web server	node cli.js start-server
stop-server	Stop server	node cli.js stop-server
open-plan <path>	Open plan in browser	node cli.js open-plan ~/.claude/plans/feature.md
get-feedback	Get pending comments	node cli.js get-feedback
sync-plan [path]	Sync plan content	node cli.js sync-plan
set-status <id|path> <status>	Set plan status	node cli.js set-status ~/.claude/plans/feature.md done
status	Check server status	node cli.js status

Plan Status Management

Plans in the queue have a status that tracks their lifecycle:

Status	Meaning	Visual
pending	Plan pushed, waiting for work	Normal appearance
working	Agent actively working on plan	Blue badge, pulsing border
updated	Plan content has been updated	Orange badge
done	Work complete or user dismissed	Green badge, muted appearance

Automatic Status Changes

• When you call open-plan: Status automatically set to working
• When plan content is updated: Status set to updated
• When exiting plan mode: Call set-status <path> done

Manual Status Changes

Users can manually mark plans as done or reactivate them via hover buttons in the web UI.

Example Workflow

# Start working on a plan (sets status to 'working')
node cli.js open-plan ~/.claude/plans/my-feature.md

# ... do work ...

# Mark plan as done when complete
node cli.js set-status ~/.claude/plans/my-feature.md done

Web UI Features

Text Selection Commenting

1. User selects text in the rendered plan
2. Comment popup appears
3. User types feedback and submits
4. Comment is anchored to the selected text

Questions Panel

Claude's questions appear in a dedicated sidebar panel. Questions should use this format in the plan:

> [!QUESTION]
> Which database should we use: PostgreSQL or MySQL?
> - Option A: PostgreSQL (better JSON support)
> - Option B: MySQL (team familiarity)

Dark Mode

Toggle dark/light mode with the button in the header.

Keyboard Shortcuts

• Cmd+Enter / Ctrl+Enter: Submit comment
• Escape: Cancel comment

Workflow Integration

When Creating Plans

1. Write plan to ~/.claude/plans/<plan-name>.md
2. Check server status: node cli.js status
3. If server NOT running ("running": false): node cli.js start-server
4. Open plan: node cli.js open-plan <path>
5. Inform user: "I've opened the plan in your browser. Please review and add any comments."

When Collecting Feedback

1. Wait for user signal ("done reviewing", "check my comments")
2. Fetch feedback: node cli.js get-feedback
3. Address each comment in your response
4. Update plan if needed

Hook Integration (Optional)

Add to .claude/settings.json for automatic browser opening:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/skills/plan-collab/scripts/on-plan-write.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

This automatically opens the browser when you write to ~/.claude/plans/.

Data Storage

Plan Files

• Location: ~/.claude/plans/*.md
• Format: Standard markdown

Database

• Location: ~/.plan-collab/plan-collab.db
• Stores: Plans, versions, comments, questions

Feedback Files

• Location: ~/.claude/plans/<name>.feedback.json
• Auto-generated with user feedback

Setup

First-Time Setup

# Install CLI dependencies (none required - uses Node.js built-ins)
cd ~/.claude/skills/plan-collab/scripts

# Install webapp dependencies
cd ~/.claude/skills/plan-collab/webapp
npm install

# Build for production
npm run build

Requirements

• Node.js 18+
• Modern browser (Chrome, Firefox, Safari, Edge)

Error Handling

All CLI commands output JSON. Errors include:

{ "error": "Error message here" }

Common errors:

• Server not running: Run start-server first
• Plan not found: Check file path exists
• No active plan: Run open-plan first

Best Practices

1. One plan at a time: Only one plan can be actively reviewed
2. Poll for feedback: Don't poll automatically; wait for user signal
3. Address all comments: Respond to each feedback item
4. Version tracking: Each plan change creates a new version
5. Question format: Use > [!QUESTION] blocks for structured questions

Mermaid Diagram Best Practices

Include Mermaid diagrams in plans to visualize complex concepts. The plan-collab web UI renders them beautifully.

Recommended Diagram Types

Type	Use Case	Example
flowchart	System architecture, decision trees	Component relationships
sequenceDiagram	API interactions, data flow	Request/response cycles
stateDiagram-v2	State machines, workflows	Order status transitions
erDiagram	Database schema	Data model visualization

Example: System Architecture

flowchart TD
    subgraph Frontend
        A[React App] --> B[API Client]
    end
    subgraph Backend
        C[Server] --> D[Database]
    end
    B --> C

Example: API Flow

sequenceDiagram
    participant U as User
    participant A as API
    participant D as Database
    U->>A: POST /data
    A->>D: INSERT
    D-->>A: Success
    A-->>U: 201 Created

When to Include Diagrams

• Multi-step processes or workflows
• System architecture changes
• API design or data flow
• Database schema modifications
• Component relationships

Working Directory

CLI commands should be run from:

~/.claude/skills/plan-collab/scripts/

Or use full paths:

node ~/.claude/skills/plan-collab/scripts/cli.js <command>