@windyroad/retrospective 0.2.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "wr-retrospective",
+  "version": "0.1.0",
+  "description": "Session retrospective reminders and plan review for Claude Code"
+}

package/bin/check-deps.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# Shared dependency checker for windyroad-plugins marketplace.
+# Called by each plugin's SessionStart hook with a list of required plugins.
+#
+# Usage: check-deps.sh <this-plugin-name> <required-plugin-1> [required-plugin-2] ...
+#
+# Checks if required sibling plugins are installed by looking for their
+# .claude-plugin/plugin.json in the plugin cache. Outputs a warning to
+# stderr (which surfaces as hook output) if any are missing.
+
+set -euo pipefail
+
+PLUGIN_NAME="${1:?Usage: check-deps.sh <plugin-name> <dep1> [dep2] ...}"
+shift
+
+MISSING=()
+
+for DEP in "$@"; do
+  # Check if the dependency plugin is installed by looking for its marker.
+  # Installed plugins have their hooks loaded, so we check if the dep's
+  # hooks are present in the session. Simplest check: look for the plugin
+  # name in the installed plugins list.
+  FOUND=false
+
+  # Method 1: Check installed_plugins.json
+  if [ -f "$HOME/.claude/plugins/installed_plugins.json" ]; then
+    if python3 -c "
+import json, sys
+data = json.load(open('$HOME/.claude/plugins/installed_plugins.json'))
+plugins = data.get('plugins', {})
+for key in plugins:
+    if key.startswith('${DEP}@'):
+        sys.exit(0)
+sys.exit(1)
+" 2>/dev/null; then
+      FOUND=true
+    fi
+  fi
+
+  # Method 2: Check if plugin dir exists in cache
+  if [ "$FOUND" = false ]; then
+    for dir in "$HOME/.claude/plugins/cache/"*/"$DEP"/*/; do
+      if [ -f "${dir}.claude-plugin/plugin.json" ] 2>/dev/null; then
+        FOUND=true
+        break
+      fi
+    done
+  fi
+
+  # Method 3: Check if loaded via --plugin-dir (plugin hooks would be active)
+  # We can't easily check this, so we rely on methods 1 and 2.
+
+  if [ "$FOUND" = false ]; then
+    MISSING+=("$DEP")
+  fi
+done
+
+if [ ${#MISSING[@]} -gt 0 ]; then
+  echo ""
+  echo "WARNING: Plugin '$PLUGIN_NAME' requires the following plugins that may not be installed:"
+  for m in "${MISSING[@]}"; do
+    echo "  - $m (install with: /plugin install $m@windyroad-plugins)"
+  done
+  echo ""
+fi

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, "../../shared/install-utils.mjs"));
+
+const PLUGIN = "wr-retrospective";
+const DEPS = ["wr-problem", "wr-risk-scorer"];
+
+const flags = utils.parseStandardArgs(process.argv);
+
+if (flags.help) {
+  console.log(`
+Usage: npx @windyroad/retrospective [options]
+
+Session retrospectives that update briefings and create problem tickets
+
+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,13 @@
+{
+  "hooks": {
+    "SessionStart": [
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/bin/check-deps.sh wr-retrospective wr-problem wr-risk-scorer" }] }
+    ],
+    "PreToolUse": [
+      { "matcher": "ExitPlanMode", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/review-plan-enforce.sh" }] }
+    ],
+    "Stop": [
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/retrospective-reminder.sh" }] }
+    ]
+  }
+}

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

@@ -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/hooks/retrospective-reminder.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+# Stop hook: Reminds the user to run /retrospective before ending the session.
+
+cat <<'EOF'
+{
+  "stopReason": "Before ending: run /retrospective to capture session learnings, update docs/BRIEFING.md, and use the /problem skill to create problem tickets for anything that failed or was harder than it should have been."
+}
+EOF
+exit 0

package/hooks/review-plan-enforce.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# PreToolUse hook: Denies ExitPlanMode until review specialists have
+# reviewed the plan. Skips UI specialists (a11y, voice-tone, style-guide,
+# jtbd) when the plan only touches non-UI files (P008 optimization).
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/review-gate.sh"
+source "$SCRIPT_DIR/lib/gate-helpers.sh"
+
+INPUT=$(cat)
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
+
+if [ -z "$SESSION_ID" ]; then
+  review_gate_parse_error
+  exit 0
+fi
+
+# Detect if the plan touches UI files by checking uncommitted changes
+# UI patterns: *.html, *.jsx, *.tsx, *.vue, *.svelte, *.astro, *.css, *.scss
+HAS_UI_FILES=false
+UI_PATTERNS='\.html$|\.jsx$|\.tsx$|\.vue$|\.svelte$|\.astro$|\.css$|\.scss$|\.ejs$|\.hbs$|\.erb$|\.leaf$'
+if git diff --cached --name-only 2>/dev/null | grep -qE "$UI_PATTERNS"; then
+    HAS_UI_FILES=true
+elif git diff --name-only 2>/dev/null | grep -qE "$UI_PATTERNS"; then
+    HAS_UI_FILES=true
+elif git ls-files --others --exclude-standard 2>/dev/null | grep -qE "$UI_PATTERNS"; then
+    HAS_UI_FILES=true
+fi
+
+# Also check the plan file itself for mentions of UI files
+PLAN_DIR="$HOME/.claude/plans"
+if [ -d "$PLAN_DIR" ] && [ "$HAS_UI_FILES" = false ]; then
+    LATEST_PLAN=$(ls -t "$PLAN_DIR"/*.md 2>/dev/null | head -1)
+    if [ -n "$LATEST_PLAN" ] && grep -qiE '\.html|\.jsx|\.tsx|\.vue|\.svelte|\.css|component|page|form|modal|dialog' "$LATEST_PLAN" 2>/dev/null; then
+        HAS_UI_FILES=true
+    fi
+fi
+
+MISSING=""
+
+if [ "$HAS_UI_FILES" = true ]; then
+    # UI files detected — require all specialists
+    for SYSTEM in a11y voice-tone style-guide jtbd; do
+      MARKER="/tmp/${SYSTEM}-plan-reviewed-${SESSION_ID}"
+      if [ ! -f "$MARKER" ]; then
+        case "$SYSTEM" in
+          a11y)       AGENT="accessibility-agents:accessibility-lead" ;;
+          voice-tone) AGENT="voice-and-tone-lead" ;;
+          style-guide) AGENT="style-guide-lead" ;;
+          jtbd)       AGENT="jtbd-lead" ;;
+        esac
+        if [ -z "$MISSING" ]; then
+          MISSING="$AGENT"
+        else
+          MISSING="${MISSING}, ${AGENT}"
+        fi
+      fi
+    done
+else
+    # No UI files — skip a11y, voice-tone, style-guide, jtbd
+    # Auto-create their markers so the gate passes
+    for SYSTEM in a11y voice-tone style-guide jtbd; do
+        touch "/tmp/${SYSTEM}-plan-reviewed-${SESSION_ID}"
+    done
+fi
+
+if [ -n "$MISSING" ]; then
+  review_gate_deny "BLOCKED: Cannot approve plan without specialist review. Missing: ${MISSING}. Delegate to each agent to review the plan."
+  exit 0
+fi
+
+exit 0

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@windyroad/retrospective",
+  "version": "0.2.0",
+  "description": "Session retrospectives that update briefings and create problem tickets",
+  "bin": {
+    "windyroad-retrospective": "./bin/install.mjs"
+  },
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/windyroad/agent-plugins.git",
+    "directory": "packages/retrospective"
+  },
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "ai-agent",
+    "ai-coding"
+  ],
+  "files": [
+    "bin/",
+    "agents/",
+    "hooks/",
+    "skills/",
+    ".claude-plugin/"
+  ]
+}

package/skills/wr:retrospective/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: wr:retrospective
+description: Run a session retrospective. Updates docs/BRIEFING.md with learnings and creates problem tickets for failures and friction.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill
+---
+
+# Session Retrospective
+
+Reflect on the current session, update the project briefing, and create problem tickets for failures and friction.
+
+## Steps
+
+### 1. Read the current briefing
+
+Read `docs/BRIEFING.md` to understand what previous sessions already captured.
+
+### 2. Reflect on this session
+
+Consider the work done in this session and identify:
+
+**What you wish you'd been told up front** — things that were non-obvious and caused wasted effort or wrong assumptions. These should be added to BRIEFING.md "What You Need to Know" if they aren't already there.
+
+**What surprised you** — things that contradicted reasonable expectations. These should be added to BRIEFING.md "What Will Surprise You" if they aren't already there.
+
+**What was harder than it should have been** — friction points, tool limitations, process overhead, confusing code. These should become problem tickets via the `/problem` skill.
+
+**What failed** — things that broke, bugs encountered, hooks that errored, tests that failed unexpectedly. These should become problem tickets via the `/problem` skill.
+
+**What should we make easier or automate** — repetitive manual steps, missing tooling, things that could be scripted. These should become problem tickets via the `/problem` skill.
+
+### 3. Update BRIEFING.md
+
+Edit `docs/BRIEFING.md`:
+
+- **Add** new learnings to the appropriate section ("What You Need to Know" or "What Will Surprise You")
+- **Remove** stale items that are no longer true. A learning is stale when:
+  - The issue has been fixed (e.g., "CI doesn't test v2" after v2 tests are added)
+  - It's now documented elsewhere (e.g., in an ADR, CLAUDE.md, or README)
+  - The codebase has changed enough that it's no longer relevant
+- **Update** items where the details have changed
+- Keep the file concise — under 2000 tokens. Each item should be 1-2 lines.
+
+Use the AskUserQuestion tool to confirm any removals: "I'd like to remove [item] from BRIEFING.md because [reason]. Is this correct?"
+
+### 4. Create or update problem tickets
+
+For each item identified in "What was harder than it should have been", "What failed", and "What should we make easier or automate", use the `/problem` skill to:
+
+- Check if a problem ticket already exists in `docs/problems/`
+- If yes: update it with new evidence from this session
+- If no: create a new problem ticket
+
+### 5. Summary
+
+Present a summary to the user:
+
+```
+## Session Retrospective
+
+### BRIEFING.md Changes
+- Added: [items added]
+- Removed: [items removed with reasons]
+- Updated: [items modified]
+
+### Problems Created/Updated
+- [problem ticket]: [summary]
+
+### No Action Needed
+- [learnings that were already captured]
+```
+
+$ARGUMENTS