pm-preview

Preamble (run first)

# 检查 docs/ 目录和文档数量
echo "📊 文档预览状态："
echo ""

if [ ! -d docs ]; then
  echo "  ❌ docs/ 目录不存在"
  echo "  💡 请先执行产品流程（/pm-brainstorm → /pm-demand → ... → /pm-docs）生成文档"
  exit 0
fi

total=0 for prefix in "01-Requirements Research" "02-Solution Design" "03-Growth Iteration" "04-Risk Control Management" "05-Product Strategy"; do count=$(ls docs/$prefix/*.md 2>/dev/null | wc -l | tr -d ' ') if [ "$count" -gt 0 ]; then echo " $prefix: $count documents" total=$((total + count)) fi done

Recursively count all .md files

all=$(find docs -name "*.md" 2>/dev/null | wc -l | tr -d ' ') echo "" echo " 📄 Total: $all MD documents" echo ""

if [ "$all" -eq 0 ]; then echo " ❌ No documents found" echo " 💡 Please run the product process first to generate documents" fi


---

## 执行流程

### 步骤 1: 启动预览服务器

先从已加载的本 skill 路径确定其绝对目录（单独安装时不在项目的 `skills/` 目录内），再使用 `Bash` 启动：

```bash
bash "<当前 pm-preview skill 所在目录>/scripts/start-preview.sh" --project-dir .

Notes：

The server starts on a random high port (49152-65535)
Use --project-dir . to persist the session to .superpm/preview/, the file is retained after the server stops; after acceptance is complete, sessions that are no longer needed should be deleted
Runs in the background without blocking the terminal

Output Example：

{"type":"server-started","port":52341,"url":"http://localhost:52341","docs_dir":"/path/to/docs","state_dir":"/path/to/.superpm/preview/..."}

Step 2: Tell the user to open the preview

Extract from the output the url field, and tell the user:

📄 Document preview has started!

🌐 Preview URL: {url}

Open the above URL in your browser to view all product documents.

Left sidebar: document directory tree

Right content area: Markdown rendering result

📝 The browser will automatically refresh when documents are updated

Step 3: Monitor status (optional)

If the user needs continuous preview, you can remind them:

💡 Tip：

The preview server automatically stops after 30 minutes of inactivity

To stop it manually, run:bash "<当前 pm-preview skill 所在目录>/scripts/stop-preview.sh" .superpm/preview/{session_id}

After running another skill (such as /pm-docs) to generate new documents, the browser will automatically refresh

Stop Preview

Users can stop it in the following ways:

# 查找 session 目录
ls -d .superpm/preview/*/

# 停止服务器
bash "<当前 pm-preview skill 所在目录>/scripts/stop-preview.sh" .superpm/preview/{session_id}

Features

Feature	Description
Real-time refresh	Automatically pushes refreshes via WebSocket when documents are updated
Sidebar navigation	Displays all documents grouped by directory, supports collapse/expand
Markdown rendering	Browser-side rendering, supports tables, code blocks, and flowcharts
Light/dark theme	Automatically switches following the operating system theme
Zero dependencies	Uses only Node.js built-in modules, no npm install required
Automatic cleanup	Automatically stops after 30 minutes of inactivity, temporary files under /tmp are automatically deleted

Precautions

First use: Ensure there is at least one .md file under the docs/ directory
Browser compatibility: Requires a modern browser that supports WebSocket (Chrome/Firefox/Safari/Edge)
Network requirements: The Markdown rendering and HTML sanitization libraries are provided locally with the skill, and preview does not depend on a CDN; local Node.js is required
Port conflict: If the random port is occupied, the server will automatically use another port
Multi-session: Each startup creates an independent session, allowing multiple preview instances to run simultaneously

Common Misconceptions / Red Flags — STOP

Misconception	Correct Approach
Starting the preview before the document is generated	First execute the product process to generate the document, then start the preview
Giving up when the preview server fails to start	Try `--foreground` mode to view error information
Expecting instant refresh after manually modifying the document	After the document is updated, the server has a 100ms debounce delay