specweave 0.9.1 → 0.10.0

package/plugins/specweave/commands/specweave-increment.md

@@ -11,6 +11,88 @@ You are helping the user create a new SpecWeave increment with automatic closure
 
 ## Steps:
 
+### Step 0: Plugin Validation (MANDATORY - ALWAYS FIRST! v0.9.4+)
+
+🚨 **CRITICAL**: Before ANY planning or execution, validate SpecWeave plugin installation.
+
+**Why This Matters**:
+- Ensures SpecWeave marketplace is registered in Claude Code
+- Ensures core `specweave` plugin is installed
+- Detects and suggests context-specific plugins based on your increment description
+- Prevents cryptic "command not found" errors
+- Enables seamless environment migration (local → VM → Cloud IDE)
+
+**Implementation**:
+
+Use the Bash tool to run:
+```bash
+npx specweave validate-plugins --auto-install --context="$(cat <<'EOF'
+$USER_INCREMENT_DESCRIPTION
+EOF
+)"
+```
+
+**Replace `$USER_INCREMENT_DESCRIPTION`** with the actual increment description provided by the user.
+
+**Expected Output (Success)**:
+```
+✅ All plugins validated!
+   • Core plugin: installed (v0.9.4)
+   • Context plugins: specweave-github (detected from "GitHub sync")
+```
+
+**Expected Output (Missing Components)**:
+```
+❌ Missing components detected:
+   • SpecWeave marketplace not registered
+   • Core plugin (specweave) not installed
+   • Context plugin (specweave-github) not installed
+
+📦 Installing missing components...
+   ✅ Marketplace registered (.claude/settings.json)
+   ✅ Core plugin installed (specweave)
+   ✅ Context plugin installed (specweave-github)
+
+🎉 Environment ready! Proceeding with increment planning...
+```
+
+**What to Do After Validation**:
+
+1. ✅ **If validation passes**: Proceed to Step 0A
+2. ⚠️ **If validation fails with errors**: Show error messages and STOP (do NOT proceed)
+3. 🔄 **If auto-install succeeded**: Proceed to Step 0A
+4. ⚠️ **If auto-install failed**: Show manual instructions (see below) and STOP
+
+**Manual Installation Instructions** (if auto-install fails):
+```
+❌ Auto-install failed. Please install manually:
+
+1. Register SpecWeave marketplace:
+   Edit ~/.claude/settings.json and add:
+   {
+     "extraKnownMarketplaces": {
+       "specweave": {
+         "source": {
+           "source": "github",
+           "repo": "anton-abyzov/specweave",
+           "path": ".claude-plugin"
+         }
+       }
+     }
+   }
+
+2. Install core plugin:
+   Run: /plugin install specweave
+
+3. Restart Claude Code
+
+4. Re-run this command
+```
+
+**DO NOT PROCEED** to Step 0A until plugin validation passes!
+
+---
+
 ### Step 0A: STRICT Pre-Flight Check (MANDATORY - v0.6.0+)
 
 **⛔ THE IRON RULE: Cannot start increment N+1 until increment N is DONE**

package/plugins/specweave/commands/specweave-next.md

@@ -32,6 +32,53 @@ The `/specweave:next` command is your **workflow continuation** command. It:
 
 ## Workflow
 
+### Step 0: Plugin Validation (MANDATORY - ALWAYS FIRST! v0.9.4+)
+
+🚨 **CRITICAL**: Before ANY workflow transition, validate SpecWeave plugin installation.
+
+**Why This Matters**:
+- Ensures SpecWeave marketplace is registered in Claude Code
+- Ensures core `specweave` plugin is installed
+- Prevents workflow interruptions from missing dependencies
+- Enables seamless environment migration (local → VM → Cloud IDE)
+
+**Implementation**:
+
+Use the Bash tool to run:
+```bash
+npx specweave validate-plugins --auto-install
+```
+
+**Expected Output (Success)**:
+```
+✅ All plugins validated!
+   • Core plugin: installed (v0.9.4)
+```
+
+**Expected Output (Missing Components)**:
+```
+❌ Missing components detected:
+   • SpecWeave marketplace not registered
+   • Core plugin (specweave) not installed
+
+📦 Installing missing components...
+   ✅ Marketplace registered (.claude/settings.json)
+   ✅ Core plugin installed (specweave)
+
+🎉 Environment ready! Proceeding with workflow transition...
+```
+
+**What to Do After Validation**:
+
+1. ✅ **If validation passes**: Proceed to Step 1
+2. ⚠️ **If validation fails with errors**: Show error messages and STOP (do NOT proceed)
+3. 🔄 **If auto-install succeeded**: Proceed to Step 1
+4. ⚠️ **If auto-install failed**: Show manual instructions and STOP
+
+**DO NOT PROCEED** to Step 1 until plugin validation passes!
+
+---
+
 ### Step 1: Find Active Increment
 
 ```bash

package/plugins/specweave/hooks/post-increment-planning.sh

@@ -191,6 +191,83 @@ translate_file() {
   fi
 }
 
+# ============================================================================
+# LIVING DOCS TRANSLATION
+# ============================================================================
+
+translate_living_docs_specs() {
+  local increment_id="$1"
+
+  log_debug "Checking for newly created living docs specs for increment $increment_id..."
+
+  # Directories to check for living docs
+  local specs_dir="$SPECWEAVE_DIR/docs/internal/specs"
+  local strategy_dir="$SPECWEAVE_DIR/docs/internal/strategy"
+  local architecture_dir="$SPECWEAVE_DIR/docs/internal/architecture"
+
+  local translated_count=0
+  local total_checked=0
+
+  # Find living docs files created in last 5 minutes (recently created by PM agent)
+  # macOS and Linux compatible find command
+  for dir in "$specs_dir" "$strategy_dir" "$architecture_dir"; do
+    if [ ! -d "$dir" ]; then
+      log_debug "Directory does not exist: $dir"
+      continue
+    fi
+
+    # Find markdown files modified in last 5 minutes
+    # Using -mmin -5 (last 5 minutes) to catch files created during increment planning
+    local files=$(find "$dir" -type f -name "*.md" -mmin -5 2>/dev/null)
+
+    if [ -z "$files" ]; then
+      log_debug "No recently modified files in $dir"
+      continue
+    fi
+
+    while IFS= read -r file; do
+      # Skip empty lines
+      [ -z "$file" ] && continue
+
+      ((total_checked++))
+
+      # Skip legacy folder
+      if [[ "$file" == *"/legacy/"* ]]; then
+        log_debug "Skipping legacy file: $file"
+        continue
+      fi
+
+      # Detect language
+      local file_lang=$(detect_file_language "$file")
+
+      if [ "$file_lang" = "non-en" ]; then
+        local basename_file=$(basename "$file")
+        log_info "  📄 Living docs detected: $basename_file"
+
+        if translate_file "$file"; then
+          ((translated_count++))
+          log_debug "Successfully translated living docs: $file"
+        else
+          log_debug "Failed to translate living docs: $file"
+        fi
+      else
+        log_debug "File already in English: $file"
+      fi
+    done <<< "$files"
+  done
+
+  log_debug "Living docs check complete: $translated_count/$total_checked files translated"
+
+  if [ "$translated_count" -gt 0 ]; then
+    log_info ""
+    log_info "  ✅ Translated $translated_count living docs file(s) to English"
+  else
+    log_debug "No living docs files needed translation"
+  fi
+
+  return 0
+}
+
 # ============================================================================
 # MAIN LOGIC
 # ============================================================================
@@ -273,57 +350,59 @@ EOF
     fi
   fi
 
-  # 4. If no translation needed, exit early
-  if [ "$needs_translation" = "false" ] || [ ${#files_to_translate[@]} -eq 0 ]; then
-    log_info "✅ All increment files already in English, skipping translation"
-    cat <<EOF
-{
-  "continue": true,
-  "message": "All files already in English"
-}
-EOF
-    exit 0
-  fi
+  # 4. Translate increment files (if needed)
+  local increment_success_count=0
+  local increment_total_count=${#files_to_translate[@]}
 
-  # 5. Perform translation
-  log_info ""
-  log_info "🌐 Detected non-English content in increment $increment_id"
-  log_info "   Translating to English for maintainability..."
-  log_info ""
+  if [ "$needs_translation" = "true" ] && [ ${#files_to_translate[@]} -gt 0 ]; then
+    # 5. Perform translation of increment files
+    log_info ""
+    log_info "🌐 Detected non-English content in increment $increment_id"
+    log_info "   Translating increment files to English..."
+    log_info ""
 
-  local success_count=0
-  local total_count=${#files_to_translate[@]}
+    for file in "${files_to_translate[@]}"; do
+      if translate_file "$file"; then
+        ((increment_success_count++))
+      fi
+    done
 
-  for file in "${files_to_translate[@]}"; do
-    if translate_file "$file"; then
-      ((success_count++))
+    log_info ""
+    if [ "$increment_success_count" -eq "$increment_total_count" ]; then
+      log_info "✅ Increment files translation complete! All $increment_total_count file(s) now in English"
+    else
+      log_error "Increment files translation completed with errors: $increment_success_count/$increment_total_count files translated"
     fi
-  done
+  else
+    log_info "✅ All increment files already in English"
+  fi
+
+  # 6. Translate living docs specs (if any were created)
+  log_info ""
+  log_info "🌐 Checking living docs for translation..."
+
+  translate_living_docs_specs "$increment_id"
 
-  # 6. Summary
+  # 7. Final summary
   log_info ""
-  if [ "$success_count" -eq "$total_count" ]; then
-    log_info "✅ Translation complete! All $total_count file(s) now in English"
-    log_info "   Cost: ~\$0.01 (using Haiku)"
+  local total_translated=$((increment_success_count))
+
+  if [ "$increment_total_count" -gt 0 ] || [ "$total_translated" -gt 0 ]; then
+    log_info "✅ Translation complete!"
+    log_info "   Increment files: $increment_success_count/$increment_total_count"
+    log_info "   Living docs: See above"
+    log_info "   Estimated cost: ~\$0.01-0.02 (using Haiku)"
     log_info ""
+  fi
 
-    cat <<EOF
+  # Return success JSON
+  cat <<EOF
 {
   "continue": true,
-  "message": "Translated $total_count file(s) to English",
+  "message": "Translation complete (increment: $increment_success_count/$increment_total_count files)",
   "files": $(printf '%s\n' "${files_to_translate[@]}" | jq -R . | jq -s .)
 }
 EOF
-  else
-    log_error "Translation completed with errors: $success_count/$total_count files translated"
-    cat <<EOF
-{
-  "continue": true,
-  "warning": "Translation partially failed: $success_count/$total_count files",
-  "files": $(printf '%s\n' "${files_to_translate[@]}" | jq -R . | jq -s .)
-}
-EOF
-  fi
 
   log_debug "=== POST-INCREMENT-PLANNING HOOK END ==="
 }

package/plugins/specweave/hooks/pre-tool-use.sh

@@ -0,0 +1,133 @@
+#!/bin/bash
+
+# SpecWeave Pre-Tool-Use Hook
+# Runs BEFORE Claude calls any tool (PreToolUse event)
+#
+# PURPOSE: Detect when Claude asks questions via AskUserQuestion
+# - Plays sound IMMEDIATELY when question is about to be asked
+# - Complements post-task-completion hook (which only fires after TodoWrite)
+# - Ensures user is always notified when Claude needs input
+#
+# SCOPE:
+# - This hook fires for ALL tool calls (Read, Edit, Write, AskUserQuestion, etc.)
+# - We filter for AskUserQuestion specifically to play sound
+# - Non-blocking and fast (<10ms overhead)
+
+set -e
+
+# ============================================================================
+# CONFIGURATION
+# ============================================================================
+
+# Find project root
+find_project_root() {
+  local dir="$1"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.specweave" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  # Fallback
+  if [ -d "$(pwd)/.specweave" ]; then
+    pwd
+  else
+    echo "$(pwd)"
+  fi
+}
+
+PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")"
+cd "$PROJECT_ROOT" 2>/dev/null || true
+
+LOGS_DIR=".specweave/logs"
+DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
+
+mkdir -p "$LOGS_DIR" 2>/dev/null || true
+
+# ============================================================================
+# CAPTURE INPUT (Tool Call Details)
+# ============================================================================
+
+STDIN_DATA=$(mktemp)
+cat > "$STDIN_DATA"
+
+# Log the tool call for debugging
+echo "[$(date)] 🔧 PreToolUse hook fired" >> "$DEBUG_LOG" 2>/dev/null || true
+echo "[$(date)] Tool call JSON:" >> "$DEBUG_LOG" 2>/dev/null || true
+cat "$STDIN_DATA" >> "$DEBUG_LOG" 2>/dev/null || true
+echo "" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# DETECT AskUserQuestion TOOL
+# ============================================================================
+
+TOOL_NAME=""
+
+if command -v jq >/dev/null 2>&1; then
+  # Use jq if available (most reliable)
+  TOOL_NAME=$(jq -r '.tool_name // empty' "$STDIN_DATA" 2>/dev/null)
+else
+  # Fallback: grep-based detection
+  if grep -q '"tool_name"' "$STDIN_DATA" 2>/dev/null; then
+    TOOL_NAME=$(grep -o '"tool_name":"[^"]*"' "$STDIN_DATA" | cut -d'"' -f4)
+  fi
+fi
+
+echo "[$(date)] Tool name: $TOOL_NAME" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# PLAY SOUND IF AskUserQuestion
+# ============================================================================
+
+play_sound() {
+  case "$(uname -s)" in
+    Darwin)
+      # macOS: Use afplay with a distinctive sound for questions
+      afplay /System/Library/Sounds/Tink.aiff 2>/dev/null || true
+      ;;
+    Linux)
+      # Linux: Use paplay or aplay
+      paplay /usr/share/sounds/freedesktop/stereo/dialog-question.oga 2>/dev/null || \
+      paplay /usr/share/sounds/freedesktop/stereo/message-new-instant.oga 2>/dev/null || \
+      aplay /usr/share/sounds/alsa/Front_Center.wav 2>/dev/null || true
+      ;;
+    MINGW*|MSYS*|CYGWIN*)
+      # Windows: Use PowerShell
+      powershell -c "(New-Object Media.SoundPlayer 'C:\Windows\Media\Windows Notify.wav').PlaySync();" 2>/dev/null || true
+      ;;
+  esac
+}
+
+if [ "$TOOL_NAME" = "AskUserQuestion" ]; then
+  echo "[$(date)] 🔔 QUESTION DETECTED! Playing notification sound" >> "$DEBUG_LOG" 2>/dev/null || true
+  play_sound
+
+  # Log this event
+  echo "[$(date)] Claude is asking for user input via AskUserQuestion" >> "$DEBUG_LOG" 2>/dev/null || true
+fi
+
+# ============================================================================
+# CLEANUP
+# ============================================================================
+
+rm -f "$STDIN_DATA"
+
+# ============================================================================
+# OUTPUT TO CLAUDE (Always continue)
+# ============================================================================
+
+if [ "$TOOL_NAME" = "AskUserQuestion" ]; then
+  cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "🔔 Sound played - user notified of question request"
+}
+EOF
+else
+  cat <<EOF
+{
+  "continue": true
+}
+EOF
+fi

package/plugins/specweave/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "specweave",
+  "description": "SpecWeave framework. Provides increment planning (PM, Architect, Tech Lead agents), specification generation, TDD workflow, living docs sync, and brownfield support. Essential for all SpecWeave projects.",
+  "version": "0.8.0",
+  "author": {
+    "name": "SpecWeave Team",
+    "url": "https://spec-weave.com"
+  },
+  "homepage": "https://spec-weave.com",
+  "repository": "https://github.com/anton-abyzov/specweave",
+  "license": "MIT",
+  "keywords": [
+    "specweave",
+    "core",
+    "increment-planning",
+    "specifications",
+    "tdd",
+    "pm",
+    "architect",
+    "living-docs"
+  ]
+}