@windyroad/jtbd 0.2.0 → 0.2.1-preview.34

package/README.md

@@ -0,0 +1,62 @@
+# @windyroad/jtbd
+
+**Jobs-to-be-done enforcement for Claude Code.** Reviews UI changes against your documented user jobs, personas, and desired outcomes before they ship.
+
+Part of [Windy Road Agent Plugins](../../README.md).
+
+## What It Does
+
+An AI agent building a feature doesn't know *why* the feature exists or *who* it's for. It builds what you describe, but can't validate whether the result actually serves the user's job-to-be-done.
+
+The JTBD plugin:
+
+1. **Detects** when an edit touches user-facing UI files
+2. **Blocks** the edit until the JTBD agent has reviewed it
+3. **Reviews** changes against your `docs/JOBS_TO_BE_DONE.md` and `docs/PRODUCT_DISCOVERY.md`
+4. **Reports** alignment gaps -- features that don't map to a documented job, or that conflict with persona constraints
+
+## Install
+
+```bash
+npx @windyroad/jtbd
+```
+
+Restart Claude Code after installing.
+
+## Usage
+
+The plugin works automatically. On first use in a project without a JTBD document, it blocks edits and directs you to create one:
+
+```
+/wr-jtbd:update-guide
+```
+
+This examines your existing features and asks about your user jobs, personas, and desired outcomes to generate a `docs/JOBS_TO_BE_DONE.md`.
+
+## How It Works
+
+| Hook | Trigger | What it does |
+|------|---------|-------------|
+| `jtbd-eval.sh` | Every prompt | Evaluates whether the task involves user-facing UI |
+| `jtbd-enforce-edit.sh` | Edit or Write | Blocks edits until the JTBD agent has reviewed |
+| `jtbd-mark-reviewed.sh` | Agent completes | Marks the review as done |
+| `jtbd-reset-marker.sh` | Session end | Cleans up review markers |
+
+## Agent
+
+The `wr-jtbd:agent` reads your `docs/JOBS_TO_BE_DONE.md` and reviews proposed UI changes against:
+
+- Documented user jobs and their success criteria
+- Persona definitions and constraints
+- Screen-to-job mappings
+
+## Updating and Uninstalling
+
+```bash
+npx @windyroad/jtbd --update
+npx @windyroad/jtbd --uninstall
+```
+
+## Licence
+
+[MIT](../../LICENSE)

package/bin/install.mjs

@@ -4,7 +4,7 @@ import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const utils = await import(resolve(__dirname, "../../shared/install-utils.mjs"));
+const utils = await import(resolve(__dirname, "../lib/install-utils.mjs"));
 
 const PLUGIN = "wr-jtbd";
 const DEPS = [];
@@ -20,6 +20,7 @@ Jobs-to-be-done enforcement for UI changes
 Options:
   --update     Update this plugin and its skills
   --uninstall  Remove this plugin
+  --scope      Installation scope: project (default) or user
   --dry-run    Show what would be done without executing
   --help, -h   Show this help
 `);
@@ -38,5 +39,5 @@ if (flags.uninstall) {
 } else if (flags.update) {
   utils.updatePackage(PLUGIN);
 } else {
-  utils.installPackage(PLUGIN, { deps: DEPS });
+  utils.installPackage(PLUGIN, { deps: DEPS, scope: flags.scope });
 }

package/hooks/jtbd-enforce-edit.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # JTBD - PreToolUse enforcement hook
-# BLOCKS Edit/Write to UI files until jtbd-lead is consulted.
+# BLOCKS Edit/Write to project files until jtbd-lead is consulted.
 # Uses shared review-gate.sh for TTL, drift detection, and fail-closed.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -35,17 +35,43 @@ if [ -z "$FILE_PATH" ]; then
   exit 0
 fi
 
-# Gate UI component and route files
+BASENAME=$(basename "$FILE_PATH")
+
+# Exclude non-JTBD files (matches architect gate exclusions)
 case "$FILE_PATH" in
-  *.html|*.jsx|*.tsx|*.vue|*.svelte|*.ejs|*.hbs) ;;
-  *) exit 0 ;;
+  *.css|*.scss|*.sass|*.less)
+    exit 0 ;;
+  *.png|*.jpg|*.jpeg|*.gif|*.svg|*.ico|*.webp)
+    exit 0 ;;
+  *.woff|*.woff2|*.ttf|*.eot)
+    exit 0 ;;
+  *package-lock.json|*yarn.lock|*pnpm-lock.yaml)
+    exit 0 ;;
+  *.map)
+    exit 0 ;;
+  *.changeset/*.md|*/.changeset/*.md)
+    exit 0 ;;
+  */MEMORY.md|*/.claude/projects/*/memory/*)
+    exit 0 ;;
+  */.claude/plans/*.md|*.claude/plans/*.md)
+    exit 0 ;;
+  */RISK-POLICY.md)
+    exit 0 ;;
+  */.risk-reports/*)
+    exit 0 ;;
+  */docs/BRIEFING.md|docs/BRIEFING.md)
+    exit 0 ;;
+  */docs/problems/*.md|docs/problems/*.md)
+    exit 0 ;;
+  */docs/JOBS_TO_BE_DONE.md|docs/JOBS_TO_BE_DONE.md)
+    exit 0 ;;
+  */docs/PRODUCT_DISCOVERY.md|docs/PRODUCT_DISCOVERY.md)
+    exit 0 ;;
 esac
 
-BASENAME=$(basename "$FILE_PATH")
-
 # If no JTBD doc exists, block and direct to create skill
 if [ ! -f "docs/JOBS_TO_BE_DONE.md" ]; then
-  review_gate_deny "BLOCKED: Cannot edit '${BASENAME}' because docs/JOBS_TO_BE_DONE.md does not exist. Run /wr-jtbd:create to generate a JTBD document for this project, then delegate to wr-jtbd:agent for review."
+  review_gate_deny "BLOCKED: Cannot edit '${BASENAME}' because docs/JOBS_TO_BE_DONE.md does not exist. Run /wr-jtbd:update-guide to generate a JTBD document for this project, then delegate to wr-jtbd:agent for review."
   exit 0
 fi
 

package/hooks/jtbd-eval.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # JTBD - UserPromptSubmit hook
 # Detects JOBS_TO_BE_DONE.md in the project and injects delegation instruction.
-# If the file doesn't exist, instructs Claude to create it via the agent.
+# If the file doesn't exist, instructs Claude to create it via the update-guide skill.
 
 if [ -f "docs/JOBS_TO_BE_DONE.md" ]; then
   cat <<'HOOK_OUTPUT'
@@ -9,27 +9,24 @@ INSTRUCTION: MANDATORY JTBD CHECK. YOU MUST FOLLOW THIS.
 DETECTED: docs/JOBS_TO_BE_DONE.md exists in this project.
 
 This is a NON-OPTIONAL instruction. You MUST use the jtbd-lead agent
-before editing any user-facing UI file (.html, .jsx, .tsx, .vue, .svelte, .ejs, .hbs).
-This is proactive. Do not wait for the user to ask.
+before editing any project file. This is proactive. Do not wait for the
+user to ask.
 
 REQUIRED ACTIONS:
 1. Use the Agent tool to delegate to wr-jtbd:agent
    (subagent_type: "wr-jtbd:agent")
 2. The jtbd-lead will review proposed changes against docs/JOBS_TO_BE_DONE.md
    and PRODUCT_DISCOVERY.md persona definitions
-3. Do NOT write or edit UI code without jtbd-lead review FIRST
+3. Do NOT write or edit project files without jtbd-lead review FIRST
 4. Do NOT skip this step even if you think you can handle it yourself
 
-SCOPE: User-facing files (.html, .jsx, .tsx, .vue, .svelte, .ejs, .hbs).
-Does NOT apply to: .css files, .ts/.js backend files, config files.
+SCOPE: All project files.
+Does NOT apply to: CSS, images, fonts, lockfiles, changesets, memory files, plan files.
 HOOK_OUTPUT
 else
-  # Check if this is a web project (has UI files)
-  if ls src/**/*.tsx src/**/*.jsx src/**/*.html 2>/dev/null | head -1 | grep -q .; then
-    cat <<'HOOK_OUTPUT'
-NOTE: This project has UI files but no docs/JOBS_TO_BE_DONE.md.
-If the user's task involves editing UI files, the edit will be blocked
-until a JTBD document exists. Run /wr-jtbd:create to generate one.
+  cat <<'HOOK_OUTPUT'
+NOTE: This project has no docs/JOBS_TO_BE_DONE.md.
+Edits to project files will be blocked until a JTBD document exists.
+Run /wr-jtbd:update-guide to generate one.
 HOOK_OUTPUT
-  fi
 fi

package/hooks/jtbd-mark-reviewed.sh

@@ -28,7 +28,7 @@ case "$SUBAGENT" in
     case "$VERDICT" in
       PASS)
         touch "/tmp/jtbd-reviewed-${SESSION_ID}"
-        store_review_hash "$SESSION_ID" "jtbd" "docs/jtbd"
+        store_review_hash "$SESSION_ID" "jtbd" "docs/JOBS_TO_BE_DONE.md"
         ;;
       FAIL)
         # Do NOT create marker — review found issues
@@ -36,7 +36,7 @@ case "$SUBAGENT" in
       *)
         # No verdict file — backward compat, allow with marker
         touch "/tmp/jtbd-reviewed-${SESSION_ID}"
-        store_review_hash "$SESSION_ID" "jtbd" "docs/jtbd"
+        store_review_hash "$SESSION_ID" "jtbd" "docs/JOBS_TO_BE_DONE.md"
         ;;
     esac
 

package/hooks/lib/gate-helpers.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+# Shared portable helpers for gate enforcement hooks.
+# Sourced by architect-gate.sh, risk-gate.sh, and all hook scripts.
+# Provides: _mtime, _hashcmd, _doc_exclusions, _err_trap, _get_*
+
+# ---------------------------------------------------------------------------
+# Portable utilities
+# ---------------------------------------------------------------------------
+
+# Portable mtime: tries GNU stat, falls back to macOS stat
+_mtime() { stat -c%Y "$1" 2>/dev/null || /usr/bin/stat -f%m "$1" 2>/dev/null || echo 0; }
+
+# Portable hash: tries md5sum, falls back to md5 -r, then shasum
+_hashcmd() { md5sum 2>/dev/null || md5 -r 2>/dev/null || shasum 2>/dev/null; }
+
+# Paths excluded from pipeline state hashing and docs-only detection.
+_doc_exclusions() {
+    echo ':!docs/' ':!.risk-reports/' ':!.changeset/' ':!governance/' ':!.claude/plans/' ':!CLAUDE.md' ':!AGENTS.md' ':!PRINCIPLES.md' ':!DECISION-MANAGEMENT.md' ':!AGENTIC_RISK_REGISTER.md' ':!PROBLEM-MANAGEMENT.md'
+}
+
+# ---------------------------------------------------------------------------
+# ERR trap: outputs diagnostic JSON on hook errors (P010)
+# Usage: source gate-helpers.sh at top of hook, then call _enable_err_trap
+# ---------------------------------------------------------------------------
+
+_enable_err_trap() {
+    trap '_err_trap_handler "$BASH_SOURCE" "$LINENO" "$BASH_COMMAND"' ERR
+}
+
+_err_trap_handler() {
+    local script="$1" line="$2" cmd="$3"
+    local name
+    name=$(basename "$script" 2>/dev/null || echo "$script")
+    # Output diagnostic as systemMessage so it's visible in conversation
+    cat <<EOF
+{
+  "systemMessage": "Hook error in ${name} at line ${line}: ${cmd}"
+}
+EOF
+}
+
+# ---------------------------------------------------------------------------
+# JSON input parsing: standardised helpers replacing inline python3
+# Each reads from _HOOK_INPUT (set by the hook before calling these)
+# ---------------------------------------------------------------------------
+
+# Store hook input for reuse by parsing helpers
+_HOOK_INPUT=""
+
+_parse_input() {
+    _HOOK_INPUT=$(cat)
+}
+
+_get_tool_name() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_name', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_session_id() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('session_id', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_command() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('command', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_file_path() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    ti = data.get('tool_input', {})
+    print(ti.get('file_path', ti.get('path', '')))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_subagent_type() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('subagent_type', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_user_prompt() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('user_prompt', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_tool_output() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    # PostToolUse provides tool_response (dict with content array), not tool_output
+    tr = data.get('tool_response', {})
+    if isinstance(tr, dict):
+        content = tr.get('content', [])
+        if isinstance(content, list):
+            texts = [c.get('text', '') for c in content if isinstance(c, dict) and c.get('type') == 'text']
+            if texts:
+                print('\n'.join(texts))
+                sys.exit(0)
+    # Fallback for older/different hook formats
+    print(data.get('tool_output', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+# ---------------------------------------------------------------------------
+# Session-scoped tmp directory for risk files
+# ---------------------------------------------------------------------------
+
+# Returns the session-scoped directory for risk temp files.
+# Creates the directory if it doesn't exist.
+# Usage: DIR=$(_risk_dir "$SESSION_ID"); echo "1" > "$DIR/commit"
+_risk_dir() {
+  local sid="$1"
+  local dir="${TMPDIR:-/tmp}/claude-risk-${sid}"
+  mkdir -p "$dir"
+  echo "$dir"
+}
+
+# ---------------------------------------------------------------------------
+# Non-doc file detection for WIP gating
+# ---------------------------------------------------------------------------
+
+_is_doc_file() {
+    local file_path="$1"
+    local EXCL
+    EXCL=$(_doc_exclusions)
+    for pattern in $EXCL; do
+        local clean="${pattern#:!}"
+        case "$file_path" in
+            *"$clean"*) return 0 ;;
+        esac
+    done
+    case "$file_path" in
+        *.claude/*|*.risk-reports/*|*RISK-POLICY.md) return 0 ;;
+    esac
+    return 1
+}

package/hooks/lib/review-gate.sh

@@ -16,7 +16,7 @@ check_review_gate() {
   local POLICY_FILE="$3"   # e.g., "docs/STYLE-GUIDE.md"
   local MARKER="/tmp/${SYSTEM}-reviewed-${SESSION_ID}"
   local HASH_FILE="/tmp/${SYSTEM}-reviewed-${SESSION_ID}.hash"
-  local TTL_SECONDS="${REVIEW_TTL:-600}"
+  local TTL_SECONDS="${REVIEW_TTL:-1800}"
 
   # 1. Marker must exist
   if [ ! -f "$MARKER" ]; then

package/hooks/test/jtbd-enforce-scope.bats

@@ -0,0 +1,66 @@
+#!/usr/bin/env bats
+
+# Tests for jtbd-enforce-edit.sh — verifies broadened scope with exclusions
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/jtbd-enforce-edit.sh"
+}
+
+# Helper: check if a file extension is in the exclusion list by grepping the hook
+file_is_excluded() {
+  local pattern="$1"
+  # The hook should have a case statement that exits 0 for excluded files
+  grep -q "$pattern" "$HOOK"
+}
+
+@test "enforce: excludes CSS files" {
+  file_is_excluded '\.css'
+}
+
+@test "enforce: excludes image files" {
+  file_is_excluded '\.png'
+}
+
+@test "enforce: excludes font files" {
+  file_is_excluded '\.woff'
+}
+
+@test "enforce: excludes lockfiles" {
+  file_is_excluded 'package-lock.json'
+}
+
+@test "enforce: excludes changeset files" {
+  file_is_excluded '\.changeset'
+}
+
+@test "enforce: excludes memory files" {
+  file_is_excluded 'MEMORY.md'
+}
+
+@test "enforce: excludes plan files" {
+  file_is_excluded '\.claude/plans'
+}
+
+@test "enforce: excludes risk reports" {
+  file_is_excluded '\.risk-reports'
+}
+
+@test "enforce: excludes RISK-POLICY.md" {
+  file_is_excluded 'RISK-POLICY.md'
+}
+
+@test "enforce: excludes JOBS_TO_BE_DONE.md (P002 chicken-and-egg fix)" {
+  # Must have a case pattern that exempts the policy file itself
+  grep -q 'JOBS_TO_BE_DONE.md)' "$HOOK"
+}
+
+@test "enforce: excludes PRODUCT_DISCOVERY.md" {
+  file_is_excluded 'PRODUCT_DISCOVERY.md'
+}
+
+@test "enforce: does NOT have UI-only case guard" {
+  # The old guard matched only UI extensions then exited for everything else.
+  # The new hook should NOT exit 0 for all non-UI files.
+  ! grep -q '\*) exit 0 ;;' "$HOOK"
+}

package/hooks/test/jtbd-eval.bats

@@ -0,0 +1,46 @@
+#!/usr/bin/env bats
+
+# Tests for jtbd-eval.sh — verifies JTBD suggestion fires for any project
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/jtbd-eval.sh"
+  ORIG_DIR="$PWD"
+  TEST_DIR=$(mktemp -d)
+  cd "$TEST_DIR"
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+}
+
+@test "eval: suggests update-guide when JOBS_TO_BE_DONE.md missing (no UI files)" {
+  # No UI files, no docs — should still suggest
+  run bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"wr-jtbd:update-guide"* ]]
+}
+
+@test "eval: suggests update-guide when JOBS_TO_BE_DONE.md missing (with UI files)" {
+  mkdir -p src
+  touch src/App.tsx
+  run bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"wr-jtbd:update-guide"* ]]
+}
+
+@test "eval: injects enforcement instruction when JOBS_TO_BE_DONE.md exists" {
+  mkdir -p docs
+  echo "# Jobs" > docs/JOBS_TO_BE_DONE.md
+  run bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"MANDATORY JTBD CHECK"* ]]
+}
+
+@test "eval: does not reference UI-only scoping in output" {
+  run bash "$HOOK"
+  [ "$status" -eq 0 ]
+  # Should not contain the old UI-only messaging
+  [[ "$output" != *"UI files"* ]]
+}

package/hooks/test/jtbd-mark-reviewed.bats

@@ -0,0 +1,20 @@
+#!/usr/bin/env bats
+
+# Tests for JTBD mark-reviewed hook — verifies hash path matches enforce hook
+
+@test "mark-reviewed uses docs/JOBS_TO_BE_DONE.md path" {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  grep -q 'docs/JOBS_TO_BE_DONE.md' "$SCRIPT_DIR/jtbd-mark-reviewed.sh"
+}
+
+@test "mark-reviewed does NOT use docs/jtbd path" {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  ! grep -q '"docs/jtbd"' "$SCRIPT_DIR/jtbd-mark-reviewed.sh"
+}
+
+@test "enforce-edit and mark-reviewed use same policy path" {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  ENFORCE_PATH=$(grep -o 'docs/JOBS_TO_BE_DONE.md' "$SCRIPT_DIR/jtbd-enforce-edit.sh" | head -1)
+  MARK_PATH=$(grep -o 'docs/JOBS_TO_BE_DONE.md' "$SCRIPT_DIR/jtbd-mark-reviewed.sh" | head -1)
+  [ "$ENFORCE_PATH" = "$MARK_PATH" ]
+}

package/lib/install-utils.mjs

@@ -0,0 +1,143 @@
+/**
+ * Shared install utilities for @windyroad/* packages.
+ * Used by both per-plugin installers and the meta-installer.
+ */
+
+import { execSync } from "node:child_process";
+
+const MARKETPLACE_REPO = "windyroad/agent-plugins";
+const MARKETPLACE_NAME = "windyroad";
+
+let _dryRun = false;
+
+export { MARKETPLACE_REPO, MARKETPLACE_NAME };
+
+export function setDryRun(value) {
+  _dryRun = value;
+}
+
+export function isDryRun() {
+  return _dryRun;
+}
+
+export function run(cmd, label) {
+  console.log(`  ${label}...`);
+  if (_dryRun) {
+    console.log(`    [dry-run] ${cmd}`);
+    return true;
+  }
+  try {
+    execSync(cmd, { stdio: "inherit" });
+    return true;
+  } catch {
+    console.error(`  FAILED: ${label}`);
+    return false;
+  }
+}
+
+export function checkPrerequisites() {
+  if (_dryRun) return;
+
+  try {
+    execSync("claude --version", { stdio: "pipe" });
+  } catch {
+    console.error(
+      "Error: 'claude' CLI not found. Install Claude Code first:\n  https://docs.anthropic.com/en/docs/claude-code\n"
+    );
+    process.exit(1);
+  }
+}
+
+export function addMarketplace() {
+  return run(
+    `claude plugin marketplace add ${MARKETPLACE_REPO}`,
+    `Marketplace: ${MARKETPLACE_NAME}`
+  );
+}
+
+export function installPlugin(pluginName, { scope = "project" } = {}) {
+  return run(
+    `claude plugin install ${pluginName}@${MARKETPLACE_NAME} --scope ${scope}`,
+    pluginName
+  );
+}
+
+export function updatePlugin(pluginName) {
+  return run(`claude plugin update ${pluginName}`, pluginName);
+}
+
+export function uninstallPlugin(pluginName) {
+  return run(`claude plugin uninstall ${pluginName}`, `Removing ${pluginName}`);
+}
+
+/**
+ * Install a single package: marketplace add + plugin install.
+ */
+export function installPackage(pluginName, { deps = [], scope = "project" } = {}) {
+  console.log(`\nInstalling @windyroad/${pluginName.replace("wr-", "")} (${scope} scope)...\n`);
+
+  addMarketplace();
+  installPlugin(pluginName, { scope });
+
+  if (deps.length > 0) {
+    console.log(`\nNote: This plugin works best with:`);
+    for (const dep of deps) {
+      console.log(`  - @windyroad/${dep.replace("wr-", "")} (npx @windyroad/${dep.replace("wr-", "")})`);
+    }
+  }
+
+  console.log(
+    `\nDone! Restart Claude Code to activate.\n`
+  );
+}
+
+/**
+ * Update a single package.
+ */
+export function updatePackage(pluginName) {
+  console.log(`\nUpdating @windyroad/${pluginName.replace("wr-", "")}...\n`);
+
+  run(
+    `claude plugin marketplace update ${MARKETPLACE_NAME}`,
+    "Updating marketplace"
+  );
+  updatePlugin(pluginName);
+
+  console.log("\nDone! Restart Claude Code to apply updates.\n");
+}
+
+/**
+ * Uninstall a single package.
+ */
+export function uninstallPackage(pluginName) {
+  console.log(`\nUninstalling @windyroad/${pluginName.replace("wr-", "")}...\n`);
+
+  uninstallPlugin(pluginName);
+
+  console.log("\nDone. Restart Claude Code to apply changes.\n");
+}
+
+/**
+ * Parse standard flags used by all per-plugin installers.
+ */
+export function parseStandardArgs(argv) {
+  const args = argv.slice(2);
+  const flags = {
+    help: args.includes("--help") || args.includes("-h"),
+    uninstall: args.includes("--uninstall"),
+    update: args.includes("--update"),
+    dryRun: args.includes("--dry-run"),
+    scope: "project",
+  };
+  const scopeIdx = args.indexOf("--scope");
+  if (scopeIdx !== -1 && args[scopeIdx + 1]) {
+    const val = args[scopeIdx + 1];
+    if (["project", "user", "local"].includes(val)) {
+      flags.scope = val;
+    } else {
+      console.error("--scope requires: project, user, or local");
+      process.exit(1);
+    }
+  }
+  return flags;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/jtbd",
-  "version": "0.2.0",
+  "version": "0.2.1-preview.34",
   "description": "Jobs-to-be-done enforcement for UI changes",
   "bin": {
     "windyroad-jtbd": "./bin/install.mjs"
@@ -23,6 +23,7 @@
     "agents/",
     "hooks/",
     "skills/",
-    ".claude-plugin/"
+    ".claude-plugin/",
+    "lib/"
   ]
 }

package/skills/{wr:jtbd → update-guide}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: wr:jtbd
+name: wr-jtbd:update-guide
 description: Create or update the project's docs/JOBS_TO_BE_DONE.md by examining existing features and asking the user about user jobs, personas, and desired outcomes.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---