@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. Maturity: Experimental (suite-bootstrap window; 729 invocations / 30d).

Part of Windy Road Agent Plugins.

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/jtbd/ directory (per-persona job files)
4. Reports alignment gaps -- features that don't map to a documented job, or that conflict with persona constraints

Install

npx @windyroad/jtbd

Restart Claude Code after installing.

Usage

The plugin works automatically. On first use in a project without a JTBD directory, 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 docs/jtbd/<persona>/persona.md plus per-job files at docs/jtbd/<persona>/JTBD-NNN-<title>.<status>.md. If a legacy docs/JOBS_TO_BE_DONE.md exists, it is migrated into the directory structure on first run (per ADR-008).

Confirm jobs and personas that lack human oversight:

/wr-jtbd:confirm-jobs-and-personas

The confirm-jobs-and-personas skill drains the set of jobs/personas that were recorded without a human confirming they reflect real user/business need (per ADR-068). It surfaces each via AskUserQuestion so you confirm, amend, or reject it, then writes a human-oversight: confirmed marker. Detection is a token-cheap grep over docs/jtbd/ frontmatter; a session-start nudge reports the unoversighted count. Jobs/personas created through update-guide are born oversighted, so the unconfirmed set only shrinks. This is the read-write oversight drain — distinct from the read-only /wr-jtbd:review-jobs alignment reviewer.

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 (TTL: 3600s) | | jtbd-slide-marker.sh | Agent or Bash | Slides the review marker forward across non-edit operations so an active review session is not invalidated by intervening Bash or sub-agent calls | | jtbd-oversight-nudge.sh | Session start | Reports how many jobs/personas lack human oversight and points to /wr-jtbd:confirm-jobs-and-personas; silent when none, and self-suppressed inside AFK iterations |

Agent

The wr-jtbd:agent reads your docs/jtbd/ directory and reviews proposed UI changes against:

• Documented user jobs (per persona) and their success criteria
• Persona definitions and constraints
• Screen-to-job mappings

Updating and Uninstalling

npx @windyroad/jtbd --update
npx @windyroad/jtbd --uninstall

Licence

MIT