WorkBuddy Local Reading Site Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Restore the supplied WorkBuddy guide as a Chrome-opened, localhost-only reading site on this Mac.

Architecture: Extract the existing VitePress project without altering its authored tutorial content. Add two macOS shell entry points: one starts the VitePress server on 127.0.0.1 and launches Chrome, while the other stops the recorded process cleanly.

Tech Stack: Node.js 20-24, npm, VitePress 1.6.4, macOS zsh, Google Chrome.

Global Constraints

• Keep the supplied ZIP file unchanged at /Users/owenwang/Desktop/学习资料/workbuddy/WorkBuddyGuide-main.zip.
• Preserve the upstream authored content and assets from WorkBuddyGuide-main/.
• Bind the reader only to 127.0.0.1; do not deploy or expose it on the LAN.
• Open the reader with Google Chrome at http://127.0.0.1:5173/.
• Target macOS and use zsh-compatible scripts.

---

Task 1: Restore the supplied VitePress project

Files:

• Create: source files restored under docs/, assets/, functions/, migrations/, scripts/, and root configuration files
• Preserve: docs/superpowers/ design and plan documents
• Test: project dependency and production-build commands

Interfaces:

• Consumes: /Users/owenwang/Desktop/学习资料/workbuddy/WorkBuddyGuide-main.zip

• Produces: package.json with npm run docs:build and a VitePress source tree at docs/

• [ ] Step 1: Inspect the archive root before extraction

Run: unzip -Z1 '/Users/owenwang/Desktop/学习资料/workbuddy/WorkBuddyGuide-main.zip' | rg '^WorkBuddyGuide-main/(README.md|package.json|docs/)'

Expected: results include WorkBuddyGuide-main/package.json and WorkBuddyGuide-main/docs/.

• [ ] Step 2: Extract the archive into a temporary directory

Run: staging_dir=$(mktemp -d /private/tmp/workbuddy-guide.XXXXXX) && unzip -q '/Users/owenwang/Desktop/学习资料/workbuddy/WorkBuddyGuide-main.zip' -d "$staging_dir" && test -f "$staging_dir/WorkBuddyGuide-main/package.json"

Expected: exit code 0 and an extracted project root containing package.json.

• [ ] Step 3: Copy the restored project files into the current project without replacing docs/superpowers/

Run: rsync -a --exclude 'docs/superpowers' "$staging_dir/WorkBuddyGuide-main/" ./

Expected: package.json, docs/.vitepress/config.mts, and docs/bluebook/ exist, while the design and plan remain.

• [ ] Step 4: Install locked dependencies

Run: npm ci

Expected: npm creates node_modules/ using the lockfile with no package changes.

• [ ] Step 5: Build the original website

Run: npm run docs:build

Expected: exit code 0 and docs/.vitepress/dist/index.html exists.

• [ ] Step 6: Commit restored source files

Run: git add . ':!node_modules' ':!docs/.vitepress/dist' && git commit -m 'feat: restore WorkBuddy guide site'

Expected: Git records the supplied source code and content, excluding generated dependencies and build output.

Task 2: Add local Chrome launcher and stopper

Files:

• Create: bin/start-workbuddy-local.zsh
• Create: bin/stop-workbuddy-local.zsh
• Create: .workbuddy-local/server.pid at runtime only
• Test: script syntax and endpoint responses

Interfaces:

• Consumes: node_modules/.bin/vitepress, docs/, Google Chrome.app

• Produces: a VitePress process bound to 127.0.0.1:5173 and a PID file at .workbuddy-local/server.pid

• [ ] Step 1: Write the launcher behavior test

Run: zsh -n bin/start-workbuddy-local.zsh && rg -n '127\.0\.0\.1|Google Chrome|server\.pid' bin/start-workbuddy-local.zsh

Expected: this initially fails because the launcher does not exist.

• [ ] Step 2: Implement bin/start-workbuddy-local.zsh

#!/bin/zsh
set -euo pipefail
project_dir="${0:A:h:h}"
state_dir="$project_dir/.workbuddy-local"
pid_file="$state_dir/server.pid"
url="http://127.0.0.1:5173/"
mkdir -p "$state_dir"
cd "$project_dir"
if [[ ! -x node_modules/.bin/vitepress ]]; then
  npm ci
fi
if [[ -f "$pid_file" ]] && kill -0 "$(<"$pid_file")" 2>/dev/null; then
  open -a "Google Chrome" "$url"
  exit 0
fi
rm -f "$pid_file"
npm run docs:dev >"$state_dir/server.log" 2>&1 &
server_pid=$!
print -r -- "$server_pid" > "$pid_file"
for attempt in {1..30}; do
  if curl --fail --silent "$url" >/dev/null; then
    open -a "Google Chrome" "$url"
    exit 0
  fi
  sleep 1
done
kill "$server_pid" 2>/dev/null || true
rm -f "$pid_file"
print -u2 -- "WorkBuddy local site did not start; see $state_dir/server.log"
exit 1

• [ ] Step 3: Implement bin/stop-workbuddy-local.zsh

#!/bin/zsh
set -euo pipefail
project_dir="${0:A:h:h}"
pid_file="$project_dir/.workbuddy-local/server.pid"
if [[ -f "$pid_file" ]]; then
  server_pid="$(<"$pid_file")"
  if kill -0 "$server_pid" 2>/dev/null; then
    kill "$server_pid"
  fi
  rm -f "$pid_file"
fi

• [ ] Step 4: Mark scripts executable and verify syntax

Run: chmod +x bin/start-workbuddy-local.zsh bin/stop-workbuddy-local.zsh && zsh -n bin/start-workbuddy-local.zsh bin/stop-workbuddy-local.zsh

Expected: exit code 0.

• [ ] Step 5: Start the site and verify key pages

Run: bin/start-workbuddy-local.zsh && curl --fail --silent http://127.0.0.1:5173/ >/dev/null && curl --fail --silent http://127.0.0.1:5173/bluebook/ >/dev/null && curl --fail --silent http://127.0.0.1:5173/cases/ >/dev/null

Expected: exit code 0, Chrome opens, and all three responses return successfully.

• [ ] Step 6: Verify localhost-only binding and clean stop

Run: lsof -nP -iTCP:5173 -sTCP:LISTEN && bin/stop-workbuddy-local.zsh && test ! -f .workbuddy-local/server.pid

Expected: listener address contains 127.0.0.1:5173; PID file is removed after stop.

• [ ] Step 7: Commit launcher scripts and runtime ignore rule

Run: git add bin .gitignore && git commit -m 'feat: add local Chrome launcher'

Expected: Git records scripts and ignores .workbuddy-local/.