@windyroad/jtbd 0.1.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "wr-jtbd",
+  "version": "0.1.0",
+  "description": "Jobs-to-be-done enforcement for Claude Code"
+}

package/agents/agent.md

@@ -0,0 +1,99 @@
+---
+name: agent
+description: Jobs To Be Done reviewer. Use before editing any user-facing UI files.
+  Reads docs/JOBS_TO_BE_DONE.md and PRODUCT_DISCOVERY.md and reviews proposed changes
+  against documented jobs, persona constraints, and screen mappings. Reports alignment
+  or gaps.
+tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+model: inherit
+---
+
+You are the JTBD Lead. You review proposed UI changes against the project's Jobs To Be Done documentation and persona definitions before any user-facing code is edited. You are a reviewer, not an editor.
+
+## Your Role
+
+1. Read `docs/jtbd/README.md` for the index of all personas and jobs
+2. Read the relevant persona and job files matching the area being edited
+3. Read the file(s) being edited to understand what user flow is changing
+4. Review proposed changes against every documented job and the persona
+5. Report: PASS if aligned, or list specific misalignments and gaps
+
+## What You Check
+
+All review criteria come from the JTBD documentation. Read the docs first and apply them. Typical checks include:
+
+### Job Alignment
+- Does the change serve a documented job? Match the change to a specific job ID
+- If the change introduces a new user flow not covered by any job, flag it as a job gap
+- If the change contradicts the intent of a documented job, flag it as a misalignment
+
+### Persona Fit
+- Read the persona definitions from the JTBD docs
+- Check the change against the primary persona's context constraints as documented
+- Flag changes that conflict with documented persona needs
+
+### Screen Mapping
+- Is the file being edited mapped to a specific job in the Job-to-Screen Mapping table?
+- If adding a new route or page, does it have a corresponding job documented?
+- Are `// @jtbd` annotations present and correct?
+
+### API / Action Alignment
+- If the change involves API interactions, do the actions align with the job's expected flow?
+- Are new actions documented in the relevant job's action list?
+
+## How to Report
+
+If the change aligns with documented jobs:
+> **JTBD Review: PASS**
+> Change serves job: `[job-id]` — [brief alignment summary]
+> Persona fit: confirmed — [which constraints were checked]
+
+If there are misalignments or gaps:
+
+> **JTBD Review: ISSUES FOUND**
+>
+> 1. **[Job Gap / Persona Mismatch / Missing Annotation]**
+>    - **File**: `path`, Line ~N
+>    - **Issue**: What is misaligned
+>    - **Job**: Which job is affected (or "no matching job")
+>    - **Fix**: Suggested resolution (update JTBD doc, adjust UI, add annotation)
+>
+> 2. ...
+
+## Guide Gap Detection
+
+If the code introduces a user flow, screen, or interaction not covered by the JTBD docs, flag this as a job gap:
+
+> **JTBD Review: JOB UPDATE NEEDED**
+>
+> The code introduces [flow/screen/interaction] which is not covered by any documented job.
+> Recommended addition to JTBD docs: [specific job definition to add]
+
+If the code serves a user type not described by the existing persona:
+
+> **JTBD Review: PERSONA UPDATE NEEDED**
+>
+> The code serves [user type/context] which is not described by the current persona.
+> Recommended update to persona docs: [specific persona attributes to add]
+
+These are FAIL verdicts — the JTBD documentation must be updated before the code can proceed.
+
+## Verdict
+
+After completing your review, write your verdict to `/tmp/jtbd-verdict`:
+- `printf 'PASS' > /tmp/jtbd-verdict` — change aligns with documented jobs and persona
+- `printf 'FAIL' > /tmp/jtbd-verdict` — misalignment, job gap, or persona gap detected
+
+## Constraints
+
+- You are read-only. You do not edit files (except writing the verdict file).
+- You review user-facing UI files.
+- If the change is purely structural with no user-visible impact (CSS refactor, types, imports), report PASS.
+- Do not review accessibility (that is accessibility-lead's job).
+- Do not review styling (that is style-guide-lead's job).
+- Do not review copy/tone (that is voice-and-tone-lead's job).
+- Focus on: does this change serve a real user job, and does it fit the persona?

package/bin/install.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const utils = await import(resolve(__dirname, "../lib/install-utils.mjs"));
+
+const PLUGIN = "wr-jtbd";
+const DEPS = [];
+
+const flags = utils.parseStandardArgs(process.argv);
+
+if (flags.help) {
+  console.log(`
+Usage: npx @windyroad/jtbd [options]
+
+Jobs-to-be-done enforcement for UI changes
+
+Options:
+  --update     Update this plugin and its skills
+  --uninstall  Remove this plugin
+  --dry-run    Show what would be done without executing
+  --help, -h   Show this help
+`);
+  process.exit(0);
+}
+
+if (flags.dryRun) {
+  utils.setDryRun(true);
+  console.log("[dry-run mode — no commands will be executed]\n");
+}
+
+utils.checkPrerequisites();
+
+if (flags.uninstall) {
+  utils.uninstallPackage(PLUGIN);
+} else if (flags.update) {
+  utils.updatePackage(PLUGIN);
+} else {
+  utils.installPackage(PLUGIN, { deps: DEPS });
+}

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/jtbd-eval.sh" }] }
+    ],
+    "PreToolUse": [
+      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/jtbd-enforce-edit.sh" }] }
+    ],
+    "PostToolUse": [
+      { "matcher": "Agent", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/jtbd-mark-reviewed.sh" }] }
+    ],
+    "Stop": [
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/jtbd-reset-marker.sh" }] }
+    ]
+  }
+}

package/hooks/jtbd-enforce-edit.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# JTBD - PreToolUse enforcement hook
+# BLOCKS Edit/Write to UI files until jtbd-lead is consulted.
+# Uses shared review-gate.sh for TTL, drift detection, and fail-closed.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/review-gate.sh"
+
+INPUT=$(cat)
+
+FILE_PATH=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('file_path', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+SESSION_ID=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('session_id', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+if [ -z "$SESSION_ID" ]; then
+  review_gate_parse_error
+  exit 0
+fi
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Gate UI component and route files
+case "$FILE_PATH" in
+  *.html|*.jsx|*.tsx|*.vue|*.svelte|*.ejs|*.hbs) ;;
+  *) 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."
+  exit 0
+fi
+
+# Check gate with TTL + drift detection
+if check_review_gate "$SESSION_ID" "jtbd" "docs/JOBS_TO_BE_DONE.md"; then
+  exit 0
+fi
+
+review_gate_deny "BLOCKED: Cannot edit '${BASENAME}' without JTBD review. You MUST first delegate to wr-jtbd:agent using the Agent tool (subagent_type: 'wr-jtbd:agent'). ${REVIEW_GATE_REASON}"
+exit 0

package/hooks/jtbd-eval.sh

@@ -0,0 +1,35 @@
+#!/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 [ -f "docs/JOBS_TO_BE_DONE.md" ]; then
+  cat <<'HOOK_OUTPUT'
+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.
+
+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
+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.
+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.
+HOOK_OUTPUT
+  fi
+fi

package/hooks/jtbd-mark-reviewed.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# JTBD - PostToolUse hook for Agent tool
+# Creates session markers when jtbd-lead has been consulted with PASS verdict.
+# Handles both edit review and plan review verdicts.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/review-gate.sh"
+
+INPUT=$(cat)
+
+SUBAGENT=$(echo "$INPUT" | jq -r '.tool_input.subagent_type // empty') || true
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
+
+if [ -z "$SESSION_ID" ]; then
+  exit 0
+fi
+
+case "$SUBAGENT" in
+  *jtbd-lead*|*wr-jtbd*)
+    # Check for edit review verdict
+    VERDICT_FILE="/tmp/jtbd-verdict"
+    VERDICT=""
+    if [ -f "$VERDICT_FILE" ]; then
+      VERDICT=$(cat "$VERDICT_FILE")
+      rm -f "$VERDICT_FILE"
+    fi
+
+    case "$VERDICT" in
+      PASS)
+        touch "/tmp/jtbd-reviewed-${SESSION_ID}"
+        store_review_hash "$SESSION_ID" "jtbd" "docs/jtbd"
+        ;;
+      FAIL)
+        # Do NOT create marker — review found issues
+        ;;
+      *)
+        # No verdict file — backward compat, allow with marker
+        touch "/tmp/jtbd-reviewed-${SESSION_ID}"
+        store_review_hash "$SESSION_ID" "jtbd" "docs/jtbd"
+        ;;
+    esac
+
+    # Plan review: agent completion = reviewed.
+    # The main agent must actually run the review agent to reach this hook.
+    # No verdict file needed — PostToolUse:Agent is the unforgeable signal.
+    touch "/tmp/jtbd-plan-reviewed-${SESSION_ID}"
+    ;;
+esac
+
+exit 0

package/hooks/jtbd-reset-marker.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Stop hook: Clears JTBD review session markers.
+
+INPUT=$(cat)
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
+
+if [ -n "$SESSION_ID" ]; then
+  rm -f "/tmp/jtbd-reviewed-${SESSION_ID}" \
+        "/tmp/jtbd-reviewed-${SESSION_ID}.hash" \
+        "/tmp/jtbd-verdict" \
+        "/tmp/jtbd-plan-reviewed-${SESSION_ID}" \
+        "/tmp/jtbd-plan-verdict"
+fi
+
+exit 0

package/hooks/lib/review-gate.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# Shared gate logic for review enforcement hooks (a11y, voice-tone, style-guide).
+# Sourced by *-enforce-edit.sh hooks and review-plan-enforce.sh.
+# Provides: check_review_gate, review_gate_deny, review_gate_parse_error
+
+# Source shared portable helpers (_mtime, _hashcmd)
+_REVIEW_GATE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$_REVIEW_GATE_DIR/gate-helpers.sh"
+
+# Check review gate marker. Returns 0 if marker is valid (allow), 1 if invalid (deny).
+# Sets REVIEW_GATE_REASON on failure.
+# Usage: check_review_gate "$SESSION_ID" "style-guide" "docs/STYLE-GUIDE.md"
+check_review_gate() {
+  local SESSION_ID="$1"
+  local SYSTEM="$2"        # e.g., "a11y", "voice-tone", "style-guide"
+  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}"
+
+  # 1. Marker must exist
+  if [ ! -f "$MARKER" ]; then
+    REVIEW_GATE_REASON="No ${SYSTEM} review marker found. The ${SYSTEM} agent must review first."
+    return 1
+  fi
+
+  # 2. TTL check — marker mtime must be within TTL
+  local NOW=$(date +%s)
+  local MARKER_TIME=$(_mtime "$MARKER")
+  local AGE=$(( NOW - MARKER_TIME ))
+  if [ "$AGE" -ge "$TTL_SECONDS" ]; then
+    rm -f "$MARKER" "$HASH_FILE"
+    REVIEW_GATE_REASON="${SYSTEM} review expired (${AGE}s old, TTL ${TTL_SECONDS}s). Re-run the ${SYSTEM} agent."
+    return 1
+  fi
+
+  # 3. Drift detection — policy file hash must match
+  if [ -f "$HASH_FILE" ] && [ -n "$POLICY_FILE" ]; then
+    local STORED_HASH=$(cat "$HASH_FILE")
+    local CURRENT_HASH=""
+    if [ -f "$POLICY_FILE" ]; then
+      CURRENT_HASH=$(cat "$POLICY_FILE" | _hashcmd | cut -d' ' -f1)
+    elif [ -d "$POLICY_FILE" ]; then
+      # Directory (e.g., docs/decisions/) — hash all .md files
+      CURRENT_HASH=$(find "$POLICY_FILE" -name '*.md' -not -name 'README.md' -print0 | sort -z | xargs -0 cat 2>/dev/null | _hashcmd | cut -d' ' -f1)
+    else
+      CURRENT_HASH="missing"
+    fi
+    if [ "$STORED_HASH" != "$CURRENT_HASH" ]; then
+      rm -f "$MARKER" "$HASH_FILE"
+      REVIEW_GATE_REASON="${SYSTEM} policy file changed since last review. Re-run the ${SYSTEM} agent."
+      return 1
+    fi
+  fi
+
+  # Slide TTL window forward
+  touch "$MARKER"
+  return 0
+}
+
+# Store policy file hash after a successful review.
+# Usage: store_review_hash "$SESSION_ID" "style-guide" "docs/STYLE-GUIDE.md"
+store_review_hash() {
+  local SESSION_ID="$1"
+  local SYSTEM="$2"
+  local POLICY_FILE="$3"
+  local HASH_FILE="/tmp/${SYSTEM}-reviewed-${SESSION_ID}.hash"
+
+  if [ -n "$POLICY_FILE" ]; then
+    local HASH=""
+    if [ -f "$POLICY_FILE" ]; then
+      HASH=$(cat "$POLICY_FILE" | _hashcmd | cut -d' ' -f1)
+    elif [ -d "$POLICY_FILE" ]; then
+      HASH=$(find "$POLICY_FILE" -name '*.md' -not -name 'README.md' -print0 | sort -z | xargs -0 cat 2>/dev/null | _hashcmd | cut -d' ' -f1)
+    else
+      HASH="missing"
+    fi
+    echo "$HASH" > "$HASH_FILE"
+  fi
+}
+
+# Emit fail-closed deny JSON for PreToolUse hooks.
+review_gate_deny() {
+  local REASON="$1"
+  cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "$REASON"
+  }
+}
+EOF
+}
+
+# Emit fail-closed deny JSON for parse failures.
+review_gate_parse_error() {
+  cat <<'EOF'
+{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny",
+    "permissionDecisionReason": "BLOCKED: Could not parse hook input. Gate is fail-closed." } }
+EOF
+}

package/lib/install-utils.mjs

@@ -0,0 +1,163 @@
+/**
+ * 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);
+  }
+
+  try {
+    execSync("npx --version", { stdio: "pipe" });
+  } catch {
+    console.error(
+      "Error: 'npx' not found. Install Node.js first:\n  https://nodejs.org\n"
+    );
+    process.exit(1);
+  }
+}
+
+export function addMarketplace() {
+  return run(
+    `claude plugin marketplace add ${MARKETPLACE_REPO}`,
+    `Marketplace: ${MARKETPLACE_NAME}`
+  );
+}
+
+export function installPlugin(pluginName) {
+  return run(
+    `claude plugin install ${pluginName}@${MARKETPLACE_NAME}`,
+    pluginName
+  );
+}
+
+export function updatePlugin(pluginName) {
+  return run(`claude plugin update ${pluginName}`, pluginName);
+}
+
+export function uninstallPlugin(pluginName) {
+  return run(`claude plugin uninstall ${pluginName}`, `Removing ${pluginName}`);
+}
+
+export function installSkills() {
+  return run(
+    `npx -y skills add --yes --all ${MARKETPLACE_REPO}`,
+    "Skills (via skills package)"
+  );
+}
+
+export function updateSkills() {
+  return run("npx -y skills update", "Skills update");
+}
+
+export function removeSkills() {
+  return run(
+    `npx -y skills remove --yes --all ${MARKETPLACE_REPO}`,
+    "Removing skills"
+  );
+}
+
+/**
+ * Install a single package: marketplace add + plugin install + skills.
+ */
+export function installPackage(pluginName, { deps = [] } = {}) {
+  console.log(`\nInstalling @windyroad/${pluginName.replace("wr-", "")}...\n`);
+
+  addMarketplace();
+  installPlugin(pluginName);
+  installSkills();
+
+  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);
+  updateSkills();
+
+  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");
+  console.log("Note: Skills are shared across packages. Run");
+  console.log("  npx @windyroad/agent-plugins --uninstall");
+  console.log("to remove all skills.\n");
+}
+
+/**
+ * Parse standard flags used by all per-plugin installers.
+ */
+export function parseStandardArgs(argv) {
+  const args = argv.slice(2);
+  return {
+    help: args.includes("--help") || args.includes("-h"),
+    uninstall: args.includes("--uninstall"),
+    update: args.includes("--update"),
+    dryRun: args.includes("--dry-run"),
+  };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@windyroad/jtbd",
+  "version": "0.1.1",
+  "description": "Jobs-to-be-done enforcement for UI changes",
+  "bin": {
+    "windyroad-jtbd": "./bin/install.mjs"
+  },
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/windyroad/agent-plugins.git",
+    "directory": "packages/jtbd"
+  },
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "ai-agent",
+    "ai-coding"
+  ],
+  "files": [
+    "bin/",
+    "agents/",
+    "hooks/",
+    "skills/",
+    ".claude-plugin/",
+    "lib/"
+  ]
+}

package/skills/wr:jtbd/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: wr:jtbd
+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
+---
+
+# Jobs To Be Done Document Generator
+
+Create or update `docs/JOBS_TO_BE_DONE.md` tailored to this project's users and their goals. The jtbd-lead agent reads this file to review UI changes against user jobs.
+
+## What belongs in docs/JOBS_TO_BE_DONE.md
+
+- **User personas**: Who uses this product and what characterises them
+- **Jobs**: What users are trying to accomplish (functional, emotional, social)
+- **Job stories**: "When [situation], I want to [motivation], so I can [expected outcome]"
+- **Desired outcomes**: Measurable results users want from each job
+- **Current solutions**: How users currently accomplish these jobs (competitors, workarounds)
+- **Last reviewed date**: When the document was last reviewed or updated
+
+## Steps
+
+### 1. Discover project context
+
+Examine the project to understand what it does and who uses it.
+
+**Find the product definition** by scanning for:
+- README.md and documentation
+- Landing page or marketing content
+- Product discovery documents (PRODUCT_DISCOVERY.md, personas, user research)
+- Route/page structure (reveals user workflows)
+- Feature flags or configuration (reveals capabilities)
+
+**Discover user workflows**:
+- Map the main user-facing pages/screens and their purpose
+- Identify the core user journey (what do users do from start to finish?)
+- Look for onboarding flows, dashboards, settings, or admin areas
+- Check for different user roles (admin, member, viewer, etc.)
+
+**Discover existing JTBD artefacts**:
+- User stories in issues or project boards
+- Persona documents
+- User research notes or interview transcripts
+- Analytics configuration (what events are tracked?)
+
+### 2. Check for existing document
+
+If `docs/JOBS_TO_BE_DONE.md` already exists, read it. Identify:
+- Whether jobs still match the current feature set
+- Whether personas still reflect the actual user base
+- Whether the last reviewed date is stale (> 2 weeks)
+
+### 3. Draft the JTBD document
+
+Based on project discovery, draft sections covering:
+
+**Personas** (2-4):
+For each persona, describe: who they are, what characterises them, what they care about, and what frustrates them. Ground these in the actual product, not generic archetypes.
+
+**Jobs** (3-8):
+For each job:
+- A job statement: "Help [persona] [accomplish goal] when [situation]"
+- Whether it's functional, emotional, or social
+- Priority (must-have, important, nice-to-have)
+
+**Job Stories** (1-2 per job):
+"When [situation], I want to [motivation], so I can [expected outcome]"
+
+**Desired Outcomes** (per job):
+What does success look like? How would the user measure it?
+
+**Current Solutions**:
+How do users currently accomplish these jobs without (or with competitors to) this product?
+
+### 4. Confirm with the user
+
+You MUST use the AskUserQuestion tool to collect user confirmation.
+
+Present:
+1. The drafted personas and ask if they're accurate
+2. The jobs identified and ask if they cover the core value proposition
+3. The job stories and ask if the situations and motivations ring true
+4. Whether any user segments or jobs are missing
+
+### 5. Write docs/JOBS_TO_BE_DONE.md
+
+Write the document including:
+- A header with "Last reviewed" date (today's date)
+- All sections from step 3, refined based on user feedback from step 4
+- A note that the wr-jtbd:agent reads this file to review UI changes against user jobs
+
+If updating rather than creating:
+- Preserve existing content the user hasn't asked to change
+- Show the user a diff of what changed
+- Update the "Last reviewed" date
+
+$ARGUMENTS