safeword 0.2.2 → 0.2.4

package/.claude/commands/arch-review.md

@@ -0,0 +1,32 @@
+Run an architecture review on staged or recent changes.
+
+## Steps:
+
+1. Get changed files:
+```bash
+git diff --cached --name-only --diff-filter=ACM 2>/dev/null || git diff HEAD~1 --name-only
+```
+
+2. Read the project's `ARCHITECTURE.md` if it exists
+
+3. Read the changed files
+
+4. Review for these issues:
+   - **Misplaced logic** - Business rules in wrong layer?
+   - **God module** - Too many responsibilities (>10 dependents or >500 lines)?
+   - **Leaky abstraction** - Implementation details exposed to callers?
+   - **Tight coupling** - Changes would cascade unnecessarily?
+   - **Boundary violation** - Import from disallowed layer?
+
+5. Return verdict:
+```json
+{
+  "issues": [],
+  "verdict": "clean | minor | refactor_needed"
+}
+```
+
+Verdicts:
+- **clean**: No architectural issues
+- **minor**: Small issues, doesn't block commit
+- **refactor_needed**: Address before committing

package/.claude/commands/lint.md

@@ -0,0 +1,6 @@
+Run linting on all project files.
+
+Execute:
+```bash
+bash .claude/hooks/run-linters.sh .
+```

package/.claude/commands/quality-review.md

@@ -0,0 +1,13 @@
+Trigger a quality review to double-check your work.
+
+Execute:
+```bash
+bash .claude/hooks/run-quality-review.sh
+```
+
+This will prompt you to:
+- Verify correctness
+- Check elegance
+- Validate against latest docs and best practices
+- Consider asking clarifying questions
+- Think deeply and avoid bloat

package/.claude/commands/setup-linting.md

@@ -0,0 +1,6 @@
+Re-run SAFEWORD linting setup (auto-detects frameworks, regenerates base config).
+
+Execute:
+```bash
+bash .safeword/scripts/setup-linting.sh
+```

package/.claude/hooks/auto-lint.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+# PostToolUse hook - auto-lint changed files
+input=$(cat)
+file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.notebook_path // empty')
+[ -n "$file_path" ] && [ -f "$file_path" ] && "$CLAUDE_PROJECT_DIR/.claude/hooks/run-linters.sh" "$file_path"
+exit 0

package/.claude/hooks/auto-quality-review.sh

@@ -0,0 +1,170 @@
+#!/bin/bash
+# Generated by setup-quality.sh v1.0.0
+# To upgrade: Re-run setup script in this project
+#
+# Auto Quality Review Stop Hook
+# Triggers quality review when changes are proposed or made
+# Only runs for projects with SAFEWORD.md or CLAUDE.md (searches upward)
+# Looks for {"proposedChanges": ..., "madeChanges": ...} JSON blob
+
+# Debug logging (persistent across reboots, user-specific)
+DEBUG_DIR="$HOME/.cache/claude-hooks"
+mkdir -p "$DEBUG_DIR" 2>/dev/null || DEBUG_DIR="/tmp"
+DEBUG_LOG="$DEBUG_DIR/auto-quality-review-debug.log"
+echo "=== Hook triggered at $(date) ===" >> "$DEBUG_LOG"
+echo "PWD: $PWD" >> "$DEBUG_LOG"
+
+# Read hook input from stdin
+input=$(cat)
+echo "Input: $input" >> "$DEBUG_LOG"
+
+# Check for project-level SAFEWORD.md or CLAUDE.md
+# Search upward from current directory (supports monorepos)
+current_dir="$PWD"
+echo "Searching for SAFEWORD.md or CLAUDE.md..." >> "$DEBUG_LOG"
+while true; do
+  if [ -f "$current_dir/SAFEWORD.md" ] || [ -f "$current_dir/CLAUDE.md" ]; then
+    echo "Found context file in: $current_dir" >> "$DEBUG_LOG"
+    break  # Found context file
+  fi
+
+  # Reached root without finding context file
+  if [ "$current_dir" = "/" ]; then
+    echo "No SAFEWORD.md or CLAUDE.md found, exiting" >> "$DEBUG_LOG"
+    exit 0
+  fi
+
+  current_dir=$(dirname "$current_dir")
+done
+
+# Read project config (defaults: enabled=true, ask_questions=true)
+config_file="$current_dir/.auto-quality-review.config"
+enabled=true
+ask_questions=true
+
+if [ -f "$config_file" ]; then
+  while IFS='=' read -r key value; do
+    # Skip empty lines and comments
+    [[ -z "$key" || "$key" =~ ^# ]] && continue
+    # Trim whitespace
+    key=$(echo "$key" | xargs)
+    value=$(echo "$value" | xargs)
+
+    case "$key" in
+      enabled)
+        enabled="$value"
+        ;;
+      ask_questions)
+        ask_questions="$value"
+        ;;
+    esac
+  done < "$config_file"
+fi
+
+# Exit if disabled for this project
+echo "Config: enabled=$enabled, ask_questions=$ask_questions" >> "$DEBUG_LOG"
+if [ "$enabled" != "true" ]; then
+  echo "Hook disabled for this project, exiting" >> "$DEBUG_LOG"
+  exit 0
+fi
+
+# Get transcript path
+if ! transcript_path=$(echo "$input" | jq -r '.transcript_path // empty' 2>/dev/null); then
+  echo "ERROR: jq failed to extract transcript_path from hook input." >&2
+  echo "ERROR: jq failed to parse input" >> "$DEBUG_LOG"
+  exit 2
+fi
+
+echo "Transcript path: $transcript_path" >> "$DEBUG_LOG"
+if [ -z "$transcript_path" ] || [ ! -f "$transcript_path" ]; then
+  echo "No transcript or file doesn't exist, exiting" >> "$DEBUG_LOG"
+  exit 0
+fi
+
+# Extract last assistant message from transcript
+# Transcript is JSONL format - each line is a message
+last_assistant_msg=$(grep '"role":"assistant"' "$transcript_path" | tail -1)
+
+echo "Last assistant message length: ${#last_assistant_msg}" >> "$DEBUG_LOG"
+if [ -z "$last_assistant_msg" ]; then
+  # Normal case: No assistant messages yet
+  echo "No assistant messages found, exiting" >> "$DEBUG_LOG"
+  exit 0
+fi
+
+# Extract the text content from the message
+# Looking for the final JSON blob: {"proposedChanges": ..., "madeChanges": ...}
+if ! msg_text=$(echo "$last_assistant_msg" | jq -r '.message.content[]? | select(.type == "text") | .text' 2>/dev/null); then
+  echo "ERROR: jq failed to parse assistant message structure. Transcript format may have changed." >&2
+  echo "DEBUG: Message structure: $(echo "$last_assistant_msg" | jq -r '.message.content[].type' 2>/dev/null)" >> "$DEBUG_LOG"
+  exit 2
+fi
+
+if [ -z "$msg_text" ]; then
+  # Normal case: Message has no text content
+  exit 0
+fi
+
+# Extract the JSON blob from the end of the message
+# Pattern: {"proposedChanges": boolean, "madeChanges": boolean, "askedQuestion": boolean}
+json_blob=$(echo "$msg_text" | grep -oE '\{"proposedChanges":\s*(true|false)\s*,\s*"madeChanges":\s*(true|false)\s*,\s*"askedQuestion":\s*(true|false)\s*\}' | tail -1)
+
+echo "JSON blob: $json_blob" >> "$DEBUG_LOG"
+if [ -z "$json_blob" ]; then
+  # Check if this looks like a substantive response (>100 chars)
+  # If so, remind agent to include JSON payload
+  msg_length=${#msg_text}
+  echo "No JSON blob found, message length: $msg_length" >> "$DEBUG_LOG"
+
+  if [ "$msg_length" -gt 100 ]; then
+    echo "Substantive response without JSON payload, sending reminder" >> "$DEBUG_LOG"
+    echo "Missing required JSON response format. Please include: {\"proposedChanges\": bool, \"madeChanges\": bool, \"askedQuestion\": bool}" >&2
+    exit 2
+  fi
+
+  # Short message without JSON is fine (acknowledgments, etc)
+  echo "Short message without JSON, exiting" >> "$DEBUG_LOG"
+  exit 0
+fi
+
+# Parse the boolean values
+if ! proposed_changes=$(echo "$json_blob" | jq -r '.proposedChanges // false' 2>/dev/null); then
+  echo "ERROR: jq failed to parse proposedChanges field from JSON blob." >&2
+  exit 2
+fi
+
+if ! made_changes=$(echo "$json_blob" | jq -r '.madeChanges // false' 2>/dev/null); then
+  echo "ERROR: jq failed to parse madeChanges field from JSON blob." >&2
+  exit 2
+fi
+
+if ! asked_question=$(echo "$json_blob" | jq -r '.askedQuestion // false' 2>/dev/null); then
+  echo "ERROR: jq failed to parse askedQuestion field from JSON blob." >&2
+  exit 2
+fi
+
+# If asked question, skip quality review (waiting for user response)
+echo "proposedChanges=$proposed_changes, madeChanges=$made_changes, askedQuestion=$asked_question" >> "$DEBUG_LOG"
+if [ "$asked_question" = "true" ]; then
+  echo "Agent asked question, skipping quality review" >> "$DEBUG_LOG"
+  exit 0
+fi
+
+# If either proposed or made changes, trigger quality review
+if [ "$proposed_changes" = "true" ] || [ "$made_changes" = "true" ]; then
+  # Block and request quality review
+  echo "TRIGGERING QUALITY REVIEW" >> "$DEBUG_LOG"
+
+  # Find the shared quality review script (same directory as this hook)
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+  # Call shared quality review script
+  if [ "$ask_questions" = "true" ]; then
+    exec "$SCRIPT_DIR/run-quality-review.sh"
+  else
+    exec "$SCRIPT_DIR/run-quality-review.sh" --no-questions
+  fi
+fi
+
+# No changes proposed or made - allow continuation
+exit 0

package/.claude/hooks/check-linting-sync.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# SessionStart hook - reminds user to re-run setup if frameworks changed
+[ ! -f ".safeword/eslint/eslint-base.mjs" ] || [ ! -f "package.json" ] && exit 0
+DEPS=$(jq -r '(.dependencies//{}),(.devDependencies//{}) | keys[]' package.json 2>/dev/null || grep -oE '"[^"]+":' package.json | tr -d '":')
+HAS_TS=false; HAS_REACT=false; HAS_ASTRO=false
+{ [ -f "tsconfig.json" ] || echo "$DEPS" | grep -qx "typescript"; } && HAS_TS=true
+echo "$DEPS" | grep -qx "react" && HAS_REACT=true
+echo "$DEPS" | grep -qx "astro" && HAS_ASTRO=true
+CFG_TS=$(grep -q "typescript-eslint" .safeword/eslint/eslint-base.mjs && echo true || echo false)
+CFG_REACT=$(grep -q "@eslint-react" .safeword/eslint/eslint-base.mjs && echo true || echo false)
+CFG_ASTRO=$(grep -q "eslint-plugin-astro" .safeword/eslint/eslint-base.mjs && echo true || echo false)
+MSG=""
+[ "$HAS_TS" != "$CFG_TS" ] && MSG+="TypeScript "
+[ "$HAS_REACT" != "$CFG_REACT" ] && MSG+="React "
+[ "$HAS_ASTRO" != "$CFG_ASTRO" ] && MSG+="Astro "
+[ -n "$MSG" ] && echo "⚠️ ESLint config out of sync (${MSG% }changed). Run: bash .safeword/scripts/setup-linting.sh"
+exit 0

package/.claude/hooks/inject-timestamp.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+# Inject Timestamp - Notification Hook
+# Outputs current Unix timestamp at session start for Claude's context awareness
+# Helps with accurate ticket timestamps and time-based reasoning
+
+echo "Current time: $(date +%s) ($(date -u +%Y-%m-%dT%H:%M:%SZ))"

package/.claude/hooks/question-protocol.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Pre-hook: Question-asking protocol
+# Triggers on UserPromptSubmit (20+ chars) to guide clarifying questions
+
+cat <<'EOF'
+{
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "<question-protocol>Research first. Ask 1-3 questions ONLY about what to build (not how) that only user knows. Skip searchable things. Unsure? Ask.</question-protocol>"
+  }
+}
+EOF

package/.claude/hooks/run-linters.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+# Shared Linting Script - runs Prettier + ESLint on files
+if [ -n "$CLAUDE_PROJECT_DIR" ]; then cd "$CLAUDE_PROJECT_DIR" || exit 1; fi
+for target in "$@"; do
+  [ -e "$target" ] || continue
+  npx prettier --write "$target" 2>&1 || true
+  npx eslint --fix "$target" 2>&1 || true
+done

package/.claude/hooks/run-quality-review.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+# Generated by setup-quality.sh v1.0.0
+# To upgrade: Re-run setup script in this project
+#
+# Shared Quality Review Script
+#
+# Prompts for a quality review with configurable questions.
+# Used by both Stop hooks and manual /quality-review command.
+#
+# Usage:
+#   run-quality-review.sh               # With questions enabled
+#   run-quality-review.sh --no-questions  # Without "ask me" prompt
+#
+# Environment variables:
+#   CLAUDE_PROJECT_DIR - Project root (for finding config and prompts)
+
+# Default: ask questions enabled
+ask_questions=true
+
+# Parse command line arguments
+for arg in "$@"; do
+  case "$arg" in
+    --no-questions)
+      ask_questions=false
+      ;;
+  esac
+done
+
+# Try to read project config if CLAUDE_PROJECT_DIR is set
+if [ -n "$CLAUDE_PROJECT_DIR" ]; then
+  config_file="$CLAUDE_PROJECT_DIR/.auto-quality-review.config"
+
+  if [ -f "$config_file" ]; then
+    while IFS='=' read -r key value; do
+      # Skip empty lines and comments
+      [[ -z "$key" || "$key" =~ ^# ]] && continue
+      # Trim whitespace
+      key=$(echo "$key" | xargs)
+      value=$(echo "$value" | xargs)
+
+      case "$key" in
+        ask_questions)
+          ask_questions="$value"
+          ;;
+      esac
+    done < "$config_file"
+  fi
+fi
+
+# Try to read prompt from .safeword/prompts/quality-review.md
+PROMPT_FILE=""
+if [ -n "$CLAUDE_PROJECT_DIR" ] && [ -f "$CLAUDE_PROJECT_DIR/.safeword/prompts/quality-review.md" ]; then
+  PROMPT_FILE="$CLAUDE_PROJECT_DIR/.safeword/prompts/quality-review.md"
+fi
+
+if [ -n "$PROMPT_FILE" ]; then
+  # Read prompt from file, skip the header line
+  tail -n +3 "$PROMPT_FILE" >&2
+else
+  # Fallback to hardcoded prompt
+  echo "Double check and critique your work just in case." >&2
+  echo "" >&2
+  echo "- Is it correct?" >&2
+  echo "- Is it elegant?" >&2
+  echo "- Does it adhere to the latest documentation and best practices for the relevant stack items, UX principles, domain requirements, and testing practices?" >&2
+
+  if [ "$ask_questions" = "true" ]; then
+    echo "- Ask me any non-obvious questions you can't research yourself in the codebase or online." >&2
+  fi
+
+  echo "- Think hard." >&2
+  echo "- Avoid bloat." >&2
+fi
+
+# Exit with code 2 to block (Stop hook behavior)
+exit 2

package/.claude/hooks/version-check.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# Generated by setup-quality.sh v1.0.0
+# To upgrade: Re-run setup script in this project
+#
+# SAFE WORD Claude Config - SessionStart Hook
+# Injects version and status into Claude's context (silent - not displayed to user)
+
+echo "SAFE WORD Claude Config v1.0.0 installed - auto-linting and quality review active"
+
+exit 0

package/.claude/mcp/README.md

@@ -0,0 +1,96 @@
+# MCP Server Configurations
+
+Sample configurations for Model Context Protocol (MCP) servers.
+
+## Available Servers
+
+| Server | Package | API Key | Purpose |
+|--------|---------|---------|---------|
+| **Context7** | `@upstash/context7-mcp` | Required (free) | Library docs lookups |
+| **Playwright** | `@playwright/mcp` | None | Browser automation (Microsoft) |
+| **Arcade** | Arcade MCP Gateway | Required | Tool gateway |
+
+## API Keys
+
+| Server | Get Key |
+|--------|---------|
+| Context7 | [context7.com/dashboard](https://context7.com/dashboard) (free tier) |
+| Arcade | [arcade.dev](https://arcade.dev) |
+
+## Setup
+
+### 1. Set Environment Variables
+
+Add to `~/.zshrc` (or `~/.bashrc`):
+
+```bash
+export CONTEXT7_API_KEY="your-key-here"
+export ARCADE_API_KEY="your-key-here"
+```
+
+Then reload: `source ~/.zshrc`
+
+### 2. Add MCP Config
+
+**Claude Desktop** — Add to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+**Cursor** — Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+MCP servers inherit environment variables from your shell automatically.
+
+## Playwright Options
+
+| Arg | Description |
+|-----|-------------|
+| `--browser chromium\|firefox\|webkit` | Browser type |
+| `--headless` | Run headless |
+| `--user-data-dir <path>` | Persist browser profile |
+
+Example:
+
+```json
+{
+  "command": "npx",
+  "args": ["@playwright/mcp@latest", "--browser", "chromium", "--headless"]
+}
+```
+
+## Context7 Usage
+
+Once configured, use in prompts:
+
+```
+use context7 to look up the latest React 19 useOptimistic hook documentation
+```
+
+Context7 fetches current docs directly from source repositories.

package/.claude/mcp/arcade.sample.json

@@ -0,0 +1,9 @@
+{
+  "name": "arcade",
+  "transport": "http",
+  "url": "https://mcp.arcade.dev",
+  "headers": {
+    "Authorization": "Bearer YOUR_ARCADE_API_KEY"
+  }
+}
+

package/.claude/mcp/context7.sample.json

@@ -0,0 +1,7 @@
+{
+  "name": "context7",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["-y", "@upstash/context7-mcp@latest"]
+}
+

package/.claude/mcp/playwright.sample.json

@@ -0,0 +1,7 @@
+{
+  "name": "playwright",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["@playwright/mcp@latest"]
+}
+

package/.claude/settings.json

@@ -0,0 +1,62 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": ".{20,}",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/question-protocol.sh"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/inject-timestamp.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/auto-quality-review.sh"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.safeword/hooks/agents-md-check.sh"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/version-check.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.safeword/hooks/post-tool.sh"
+          }
+        ]
+      }
+    ]
+  }
+}