Windy Road Agent Plugins

Governance guardrails for AI coding agents. Architecture reviews, risk scoring, TDD enforcement, and delivery quality gates that run automatically inside Claude Code.

Built by Windy Road Technology.

Read the documentation to choose plugins, find skills and follow installation guidance for your runtime. Start with outcome-led planning to confirm an objective and deliver through Now, Next and Later, with optional GitHub Issues for shared outcomes, increments and agent tasks.

The Problem

AI coding agents are fast. Sometimes too fast. They skip architecture reviews, introduce risk without assessment, ignore your design system, and write implementation before tests. The same governance that keeps human teams shipping safely gets bypassed when an agent writes code.

These plugins bring that governance back -- automatically. They hook into Claude Code's plugin system and enforce your team's standards on every edit, commit, and push. No manual checks. No hoping the agent remembers.

Quick Start

Install all plugins with one command:

npx @windyroad/agent-plugins

Restart Claude Code. That's it. The plugins activate automatically based on what they find in your project.

Install only what you need:

npx @windyroad/agent-plugins --plugin architect tdd risk-scorer

Or install a single plugin directly:

npx @windyroad/architect

Plugins install to your project by default (not globally), so they won't affect your other projects. Pass --scope user to install globally.

After installing, type /wr- in Claude Code to see all available skills.

How It Works

Governance plugins use Claude Code's hook system to intercept actions at the right moment:

1. Detect -- A UserPromptSubmit hook scans for relevant project files (e.g., docs/decisions/ for architect, RISK-POLICY.md for risk-scorer)
2. Gate -- A PreToolUse hook blocks edits to relevant files until the review agent has been consulted
3. Review -- The agent reviews the proposed change against your project's policy documents
4. Unlock -- A PostToolUse hook marks the review as complete, allowing edits to proceed

Policy files are generated for you. When a plugin detects that its policy file is missing, it blocks edits and directs you to the setup skill (e.g., /wr-voice-tone:update-guide).

Plugins

Governance and Quality Gates

These plugins enforce review workflows. They block edits to relevant files until the appropriate review agent has been consulted.

Package	What it enforces
@windyroad/architect	Architecture decisions reviewed before code changes
@windyroad/risk-scorer	Pipeline risk scoring, commit/push gates, secret leak detection
@windyroad/tdd	Red-Green-Refactor TDD cycle for implementation code
@windyroad/voice-tone	User-facing copy reviewed against voice and tone guide
@windyroad/style-guide	CSS and UI components reviewed against style guide
@windyroad/jtbd	UI changes reviewed against jobs-to-be-done document

Process Tools

Package	What it does
@windyroad/planning	Confirm SMART outcomes and deliver through reviewed Now, Next and Later increments, with optional GitHub Issues for shared outcomes, increments and agent tasks; installs one skill without hooks
@windyroad/itil	ITIL-aligned IT service management — problem management (WSJF-prioritised) and evidence-first incident management with automatic handoff
@windyroad/retrospective	Session retrospectives that update briefings and create problem tickets
@windyroad/connect	Cross-repo agent collaboration via Discord channels (experimental — see plugin README)

Diagram Generation

Package	What it does
@windyroad/c4	C4 architecture diagram generation and validation
@windyroad/wardley	Wardley Map generation from source code analysis

Meta-Installer

Package	What it does
@windyroad/agent-plugins	One-command installer for all plugins

Dependencies Between Plugins

Most plugins are standalone. Two have dependencies:

@windyroad/retrospective
  └── @windyroad/itil
        └── @windyroad/risk-scorer

The installer warns if dependencies are missing.

Jobs to be Done

Each plugin's value framing is anchored to documented Jobs to be Done — persona-grouped jobs that describe what user pain the plugin removes, not just what features it ships. Per ADR-051, every @windyroad/* plugin README cites at least one current JTBD job ID so the README is a navigable index into the JTBD research, not just a feature list.

Persona	Primary jobs	Plugins serving this persona
Developer — uses AI agents solo, in a small team, or on a larger software development team	JTBD-001 Enforce Governance Without Slowing Down, JTBD-002 Ship with Confidence, JTBD-003 Compose Only the Guardrails I Need, JTBD-006 Progress the Backlog While I'm Away, JTBD-007 Keep Plugins Current Across Projects	architect, risk-scorer, tdd, jtbd, voice-tone, style-guide, retrospective, agent-plugins
Tech lead / consultant — accountable for code quality across teams or client engagements	JTBD-201 Restore Service Fast with an Audit Trail, JTBD-202 Pre-Flight Governance Checks Before Release	itil, architect, risk-scorer, c4, wardley
Plugin developer — extends the suite with new plugins

See docs/jtbd/README.md for the full index.

Risk Management

This suite follows ISO 31000 / ISO 27001 risk management practice. Risk criteria, impact and likelihood scales, appetite, and the matrix are defined in RISK-POLICY.md. Standing risks the suite tolerates and treats are tracked in the risk register. Per-change pipeline risk is scored on every commit, push, and release by @windyroad/risk-scorer and snapshotted to .risk-reports/ for audit purposes.

Updating and Uninstalling

# Update everything
npx @windyroad/agent-plugins --update

# Update a single plugin
npx @windyroad/architect --update

# Remove everything
npx @windyroad/agent-plugins --uninstall

# Remove a single plugin
npx @windyroad/architect --uninstall

Development

For plugin development, load directly from source with --plugin-dir:

claude --plugin-dir ~/Projects/windyroad-agent-plugins/packages/architect

Or load all plugins at once:

./claude-wr.sh

Changes take effect on session restart -- no install or update step needed.

Running Tests

Hook tests use BATS (Bash Automated Testing System):

npm test

Releasing

This monorepo uses Changesets for versioning:

npx changeset        # Create a changeset
npm run release      # Publish to npm
npm run push:watch   # Push and watch CI

Monorepo Structure

packages/
  agent-plugins/    Meta-installer for all plugins
  architect/        Architecture decision enforcement
  risk-scorer/      Pipeline risk scoring and gates
  tdd/              TDD state machine enforcement
  voice-tone/       Voice and tone review
  style-guide/      Style guide review
  jtbd/             Jobs-to-be-done review
  itil/             ITIL problem and incident management
  retrospective/    Session retrospectives
  connect/          Cross-repo agent collaboration via Discord
  c4/               C4 diagram generation
  wardley/          Wardley Map generation
  shared/           Shared install utilities (internal)

Licence

MIT