@windyroad/jtbd 0.2.1 → 0.3.0-preview.36

package/agents/agent.md

@@ -1,7 +1,7 @@
 ---
 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
+description: Jobs To Be Done reviewer. Use before editing any project file.
+  Reads docs/jtbd/ (or docs/JOBS_TO_BE_DONE.md) and reviews proposed changes
   against documented jobs, persona constraints, and screen mappings. Reports alignment
   or gaps.
 tools:
@@ -12,7 +12,7 @@ tools:
 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.
+You are the JTBD Lead. You review proposed changes against the project's Jobs To Be Done documentation and persona definitions before project files are edited. You are a reviewer, not an editor.
 
 ## Your Role
 
@@ -91,7 +91,7 @@ After completing your review, write your verdict to `/tmp/jtbd-verdict`:
 ## Constraints
 
 - You are read-only. You do not edit files (except writing the verdict file).
-- You review user-facing UI files.
+- You review all project files (not just 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).

package/hooks/jtbd-enforce-edit.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
 # JTBD - PreToolUse enforcement hook
 # BLOCKS Edit/Write to project files until jtbd-lead is consulted.
+# Supports both docs/jtbd/ directory (preferred) and docs/JOBS_TO_BE_DONE.md (legacy).
 # Uses shared review-gate.sh for TTL, drift detection, and fail-closed.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -63,20 +64,30 @@ case "$FILE_PATH" in
     exit 0 ;;
   */docs/problems/*.md|docs/problems/*.md)
     exit 0 ;;
+  */docs/jtbd/*|docs/jtbd/*)
+    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
 
-# 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:update-guide to generate a JTBD document for this project, then delegate to wr-jtbd:agent for review."
+# Determine JTBD path — prefer directory, fall back to single file
+JTBD_PATH=""
+if [ -d "docs/jtbd" ]; then
+  JTBD_PATH="docs/jtbd"
+elif [ -f "docs/JOBS_TO_BE_DONE.md" ]; then
+  JTBD_PATH="docs/JOBS_TO_BE_DONE.md"
+fi
+
+# If no JTBD docs exist, block and direct to create skill
+if [ -z "$JTBD_PATH" ]; then
+  review_gate_deny "BLOCKED: Cannot edit '${BASENAME}' because no JTBD documentation exists. Run /wr-jtbd:update-guide to generate JTBD docs 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
+if check_review_gate "$SESSION_ID" "jtbd" "$JTBD_PATH"; then
   exit 0
 fi
 

package/hooks/jtbd-eval.sh

@@ -1,9 +1,30 @@
 #!/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 update-guide skill.
+# Detects JTBD docs in the project and injects delegation instruction.
+# Supports both docs/jtbd/ directory (preferred) and docs/JOBS_TO_BE_DONE.md (legacy).
+# If neither exists, instructs Claude to create via the update-guide skill.
 
-if [ -f "docs/JOBS_TO_BE_DONE.md" ]; then
+if [ -f "docs/jtbd/README.md" ]; then
+  cat <<'HOOK_OUTPUT'
+INSTRUCTION: MANDATORY JTBD CHECK. YOU MUST FOLLOW THIS.
+DETECTED: docs/jtbd/ exists in this project.
+
+This is a NON-OPTIONAL instruction. You MUST use the jtbd-lead agent
+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/jtbd/ persona
+   and job definitions
+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: All project files.
+Does NOT apply to: CSS, images, fonts, lockfiles, changesets, memory files, plan files.
+HOOK_OUTPUT
+elif [ -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.
@@ -25,7 +46,7 @@ Does NOT apply to: CSS, images, fonts, lockfiles, changesets, memory files, plan
 HOOK_OUTPUT
 else
   cat <<'HOOK_OUTPUT'
-NOTE: This project has no docs/JOBS_TO_BE_DONE.md.
+NOTE: This project has no docs/jtbd/ directory or 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

package/hooks/jtbd-mark-reviewed.sh

@@ -1,7 +1,7 @@
 #!/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.
+# Supports both docs/jtbd/ directory (preferred) and docs/JOBS_TO_BE_DONE.md (legacy).
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/review-gate.sh"
@@ -15,6 +15,12 @@ if [ -z "$SESSION_ID" ]; then
   exit 0
 fi
 
+# Determine JTBD path — prefer directory, fall back to single file
+JTBD_PATH="docs/JOBS_TO_BE_DONE.md"
+if [ -d "docs/jtbd" ]; then
+  JTBD_PATH="docs/jtbd"
+fi
+
 case "$SUBAGENT" in
   *jtbd-lead*|*wr-jtbd*)
     # Check for edit review verdict
@@ -28,7 +34,7 @@ case "$SUBAGENT" in
     case "$VERDICT" in
       PASS)
         touch "/tmp/jtbd-reviewed-${SESSION_ID}"
-        store_review_hash "$SESSION_ID" "jtbd" "docs/JOBS_TO_BE_DONE.md"
+        store_review_hash "$SESSION_ID" "jtbd" "$JTBD_PATH"
         ;;
       FAIL)
         # Do NOT create marker — review found issues
@@ -36,13 +42,11 @@ case "$SUBAGENT" in
       *)
         # No verdict file — backward compat, allow with marker
         touch "/tmp/jtbd-reviewed-${SESSION_ID}"
-        store_review_hash "$SESSION_ID" "jtbd" "docs/JOBS_TO_BE_DONE.md"
+        store_review_hash "$SESSION_ID" "jtbd" "$JTBD_PATH"
         ;;
     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

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

@@ -1,19 +1,36 @@
 #!/usr/bin/env bats
 
 # Tests for jtbd-enforce-edit.sh — verifies broadened scope with exclusions
+# Mix of grep-based pattern tests and functional execution tests.
 
 setup() {
   SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
   HOOK="$SCRIPT_DIR/jtbd-enforce-edit.sh"
+  ORIG_DIR="$PWD"
+  TEST_DIR=$(mktemp -d)
+  cd "$TEST_DIR"
 }
 
-# Helper: check if a file extension is in the exclusion list by grepping the hook
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+}
+
+# Helper: check if a pattern 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"
 }
 
+# Helper: run the hook with a mock JSON input for a given file path
+run_hook_with_file() {
+  local file_path="$1"
+  local json="{\"tool_input\":{\"file_path\":\"${file_path}\"},\"session_id\":\"test-session-$$\"}"
+  echo "$json" | bash "$HOOK"
+}
+
+# --- Pattern-based exclusion tests (grep) ---
+
 @test "enforce: excludes CSS files" {
   file_is_excluded '\.css'
 }
@@ -50,17 +67,48 @@ file_is_excluded() {
   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: does NOT have UI-only case guard" {
+  ! grep -q '\*) exit 0 ;;' "$HOOK"
 }
 
-@test "enforce: excludes PRODUCT_DISCOVERY.md" {
-  file_is_excluded 'PRODUCT_DISCOVERY.md'
+# --- Functional tests (execute hook with mock JSON) ---
+
+@test "functional: exempts docs/jtbd/ files" {
+  run run_hook_with_file "docs/jtbd/solo-developer/persona.md"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
 }
 
-@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"
+@test "functional: exempts docs/jtbd/ job files" {
+  run run_hook_with_file "docs/jtbd/solo-developer/JTBD-001-governance.proposed.md"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "functional: exempts docs/jtbd/README.md" {
+  run run_hook_with_file "docs/jtbd/README.md"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "functional: exempts docs/JOBS_TO_BE_DONE.md (backward compat)" {
+  run run_hook_with_file "docs/JOBS_TO_BE_DONE.md"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "functional: blocks src/index.ts when no JTBD docs exist" {
+  run run_hook_with_file "src/index.ts"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"BLOCKED"* ]]
+  [[ "$output" == *"wr-jtbd:update-guide"* ]]
+}
+
+@test "functional: blocks src/index.ts when docs/jtbd exists (needs review)" {
+  mkdir -p docs/jtbd
+  echo "# Index" > docs/jtbd/README.md
+  run run_hook_with_file "src/index.ts"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"BLOCKED"* ]]
+  [[ "$output" == *"wr-jtbd:agent"* ]]
 }

package/hooks/test/jtbd-eval.bats

@@ -38,9 +38,25 @@ teardown() {
   [[ "$output" == *"MANDATORY JTBD CHECK"* ]]
 }
 
+@test "eval: injects enforcement when docs/jtbd/README.md exists" {
+  mkdir -p docs/jtbd
+  echo "# Index" > docs/jtbd/README.md
+  run bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"MANDATORY JTBD CHECK"* ]]
+}
+
+@test "eval: prefers docs/jtbd/ over docs/JOBS_TO_BE_DONE.md when both exist" {
+  mkdir -p docs/jtbd
+  echo "# Index" > docs/jtbd/README.md
+  echo "# Jobs" > docs/JOBS_TO_BE_DONE.md
+  run bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"docs/jtbd"* ]]
+}
+
 @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

@@ -1,20 +1,19 @@
 #!/usr/bin/env bats
 
-# Tests for JTBD mark-reviewed hook — verifies hash path matches enforce hook
+# Tests for JTBD mark-reviewed hook — verifies hash path supports both formats
 
-@test "mark-reviewed uses docs/JOBS_TO_BE_DONE.md path" {
+@test "mark-reviewed supports docs/jtbd directory path" {
   SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
-  grep -q 'docs/JOBS_TO_BE_DONE.md' "$SCRIPT_DIR/jtbd-mark-reviewed.sh"
+  grep -q '"docs/jtbd"' "$SCRIPT_DIR/jtbd-mark-reviewed.sh"
 }
 
-@test "mark-reviewed does NOT use docs/jtbd path" {
+@test "mark-reviewed supports docs/JOBS_TO_BE_DONE.md fallback" {
   SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
-  ! grep -q '"docs/jtbd"' "$SCRIPT_DIR/jtbd-mark-reviewed.sh"
+  grep -q 'docs/JOBS_TO_BE_DONE.md' "$SCRIPT_DIR/jtbd-mark-reviewed.sh"
 }
 
-@test "enforce-edit and mark-reviewed use same policy path" {
+@test "enforce-edit and mark-reviewed both support docs/jtbd" {
   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" ]
+  grep -q '"docs/jtbd"' "$SCRIPT_DIR/jtbd-enforce-edit.sh"
+  grep -q '"docs/jtbd"' "$SCRIPT_DIR/jtbd-mark-reviewed.sh"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/jtbd",
-  "version": "0.2.1",
+  "version": "0.3.0-preview.36",
   "description": "Jobs-to-be-done enforcement for UI changes",
   "bin": {
     "windyroad-jtbd": "./bin/install.mjs"

package/skills/update-guide/SKILL.md

@@ -1,21 +1,24 @@
 ---
 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.
+description: Create or update the project's docs/jtbd/ directory with per-persona directories and individual job files. Migrates from docs/JOBS_TO_BE_DONE.md if present.
 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.
+Create or update `docs/jtbd/` with per-persona directories and individual job files.
+The wr-jtbd:agent reads these files to review changes against user jobs.
 
-## What belongs in docs/JOBS_TO_BE_DONE.md
+## Directory Structure
 
-- **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
+```
+docs/jtbd/
+  README.md                              # Index — tables of personas and jobs by status
+  <persona-name>/
+    persona.md                           # Persona definition
+    JTBD-NNN-<kebab-title>.proposed.md   # Proposed job
+    JTBD-NNN-<kebab-title>.validated.md  # Validated job
+```
 
 ## Steps
 
@@ -36,61 +39,138 @@ Examine the project to understand what it does and who uses it.
 - 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 JTBD artefacts
 
-### 2. Check for existing document
+Check in order of preference:
 
-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)
+1. `docs/jtbd/README.md` — directory structure already exists. Read and update.
+2. `docs/JOBS_TO_BE_DONE.md` — legacy single file. Offer to migrate to directory structure.
+3. Neither — fresh creation.
 
-### 3. Draft the JTBD document
+If migrating from `docs/JOBS_TO_BE_DONE.md`, extract existing personas and jobs and
+convert them into the directory structure. Ask the user before proceeding.
 
-Based on project discovery, draft sections covering:
+### 3. Draft personas
 
-**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.
+For each persona (2-4), create a file at `docs/jtbd/<persona-name>/persona.md`:
 
-**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)
+```markdown
+---
+name: <persona-name>
+description: <one-line description>
+---
+
+# <Persona Display Name>
+
+## Who
+<who this persona is>
+
+## Context Constraints
+<bullet list of constraints relevant to using this product>
+
+## Pain Points
+<bullet list of frustrations this product addresses>
+```
+
+Use kebab-case for the directory name (e.g., `solo-developer`, `tech-lead`).
+
+### 4. Confirm personas with the user
+
+Use AskUserQuestion to present the drafted personas and ask:
+- Are these the right personas?
+- Any missing user segments?
+- Any constraints or pain points to add?
+
+### 5. Draft jobs
+
+For each job (3-8 per persona), create a file at
+`docs/jtbd/<persona-name>/JTBD-NNN-<kebab-title>.proposed.md`:
+
+```markdown
+---
+status: proposed
+job-id: <kebab-case-id>
+persona: <persona-name>
+date-created: YYYY-MM-DD
+screens:
+  - <route or screen path, if applicable>
+---
+
+# JTBD-NNN: <Title>
+
+## Job Statement
+When [situation], I want to [motivation], so I can [expected outcome].
+
+## Desired Outcomes
+<bullet list of measurable outcomes>
+
+## Persona Constraints
+<relevant constraints from persona definition>
+
+## Current Solutions
+<how users currently accomplish this without the product>
+```
+
+**ID ranges** — assign non-overlapping ranges per persona:
+- First persona: 001-099
+- Second persona: 100-199
+- Third persona: 200-299
+
+**Status** — new jobs start as `proposed`. They become `validated` when confirmed
+by user research or production use. To validate: rename the file from
+`.proposed.md` to `.validated.md` and update the status field.
+
+### 6. Confirm jobs with the user
+
+Use AskUserQuestion to present the drafted jobs and ask:
+- Do these jobs cover the core value proposition?
+- Do the job statements ring true?
+- Any missing jobs or user flows?
+
+### 7. Generate README.md index
+
+Write `docs/jtbd/README.md` with tables grouping jobs by persona and status:
+
+```markdown
+# Jobs To Be Done (JTBD) Index
+
+## <Persona Name>
+
+<one-line description>
+
+[Persona definition](<persona-name>/persona.md)
+
+### Validated
 
-**Job Stories** (1-2 per job):
-"When [situation], I want to [motivation], so I can [expected outcome]"
+| ID | Job | File |
+|----|-----|------|
+| JTBD-NNN | <title> | [JTBD-NNN-<title>.validated.md](<path>) |
 
-**Desired Outcomes** (per job):
-What does success look like? How would the user measure it?
+### Proposed
 
-**Current Solutions**:
-How do users currently accomplish these jobs without (or with competitors to) this product?
+| ID | Job | File |
+|----|-----|------|
+| JTBD-NNN | <title> | [JTBD-NNN-<title>.proposed.md](<path>) |
+```
 
-### 4. Confirm with the user
+### 8. Handle legacy file
 
-You MUST use the AskUserQuestion tool to collect user confirmation.
+If `docs/JOBS_TO_BE_DONE.md` exists, replace its content with a pointer:
 
-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
+```markdown
+# Jobs To Be Done
 
-### 5. Write docs/JOBS_TO_BE_DONE.md
+Job definitions have been migrated to individual files in `docs/jtbd/`.
+Each persona has its own directory with a persona definition and individual
+job files. See `docs/jtbd/README.md` for the full index.
+```
 
-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
+### 9. Summary
 
-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
+Report what was created:
+- Number of personas and their names
+- Number of jobs and their IDs
+- Files created/updated
+- Whether migration from legacy file was performed
 
 $ARGUMENTS