specweave 1.0.77 → 1.0.78

package/CLAUDE.md

@@ -1017,6 +1017,8 @@ For **contributors to SpecWeave itself** (not users).
 
 ## Marketplace Installation (CRITICAL)
 
+### For SpecWeave Contributors (Development)
+
 **ALWAYS use GitHub marketplace mode. NEVER use local symlinks or directory mode.**
 
 ```bash
@@ -1037,6 +1039,32 @@ bash scripts/refresh-marketplace.sh --github
 bash scripts/refresh-marketplace.sh  # Defaults to --github
 ```
 
+### For End Users (Production)
+
+**Users install SpecWeave globally and use CLI commands:**
+
+```bash
+# Install SpecWeave globally
+npm install -g specweave
+
+# Initialize project (first time)
+specweave init .
+
+# Update marketplace plugins (gets latest from GitHub)
+specweave refresh-marketplace
+
+# Update instruction files (CLAUDE.md, AGENTS.md)
+specweave update-instructions
+```
+
+**After marketplace updates**: Restart Claude Code for changes to take effect.
+
+**Verify installation**:
+```bash
+specweave --version              # Check SpecWeave version
+/plugin list --installed         # In Claude Code - check plugins loaded
+```
+
 ---
 
 ## Critical Safety Rules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "1.0.77",
+  "version": "1.0.78",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

package/plugins/specweave/commands/auto.md

@@ -354,6 +354,28 @@ Pure Ralph Wiggum behavior:
 - **Max Iterations**: Prevents runaway loops (2500 default)
 - **Max Hours**: Time boxing (600 hours / 25 days default)
 - **stop_hook_active**: Prevents infinite continuation loops
+- **Sound Notifications** (v2.6): Audible alerts when Claude stops working
+
+## 🔔 Sound Notifications (NEW in v2.6!)
+
+**Auto mode plays a satisfying sound when work completes successfully!**
+
+### When Sound Plays
+
+| Event | Sound | Platforms | Meaning |
+|-------|-------|-----------|---------|
+| **Session Complete (Success)** ✅ | Glass.aiff (macOS)<br>complete.oga (Linux)<br>Windows Notify (Windows) | All | All tasks done, tests passing - work finished! |
+
+**Sound plays ONLY on complete success** - when all tasks are done AND all tests pass. This way you know when to check back without being interrupted during ongoing work.
+
+### Cross-Platform Support
+
+The sound notification works automatically on:
+- **macOS**: Glass.aiff (satisfying chime)
+- **Linux**: PulseAudio/ALSA/speaker-test fallbacks
+- **Windows**: PowerShell beeps
+
+Sounds fail gracefully on systems without audio support.
 
 ## 🔧 v2.3 Per-Agent Stop Hook Behavior (NEW!)
 

package/plugins/specweave/hooks/README.md

@@ -117,6 +117,36 @@ Core hooks automate SpecWeave's fundamental workflows:
 
 ---
 
+### 5. `stop-auto.sh` (Auto Mode)
+**Triggers**: When Claude tries to exit during autonomous execution (`/sw:auto`)
+
+**Actions**:
+1. Checks if all tasks are complete
+2. Validates test execution (unit + E2E)
+3. Verifies completion criteria met
+4. Blocks exit if work incomplete
+5. Re-feeds prompt to continue iteration
+
+**Configuration**: Registered in `hooks/hooks.json`:
+```json
+{
+  "hooks": {
+    "Stop": [{
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop-auto.sh"
+      }]
+    }]
+  }
+}
+```
+
+**Use case**: Enables autonomous execution loops. Claude works until ALL tasks complete and tests pass, then gracefully exits.
+
+**See**: `/sw:auto` command documentation for full auto mode details.
+
+---
+
 ## How Hooks Work (Claude Code Native)
 
 **CRITICAL**: Hooks are **NOT copied** to `.claude/hooks/`. They stay in `plugins/specweave/hooks/` and Claude Code discovers them automatically.

package/plugins/specweave/hooks/hooks.json

@@ -31,6 +31,16 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop-auto.sh"
+          }
+        ]
+      }
     ]
   }
 }

package/plugins/specweave/hooks/stop-auto.sh

@@ -570,6 +570,54 @@ detect_command_timeout() {
     fi
 }
 
+# ================================================================
+# SOUND NOTIFICATION HELPER (v2.6)
+# Cross-platform sound notification for user awareness
+# ================================================================
+play_notification_sound() {
+    local sound_type="${1:-attention}"  # "success" or "attention"
+
+    # Detect OS and play appropriate sound
+    case "$(uname -s)" in
+        Darwin)
+            # macOS - use afplay with system sounds
+            if [ "$sound_type" = "success" ]; then
+                afplay /System/Library/Sounds/Glass.aiff 2>/dev/null &
+            else
+                afplay /System/Library/Sounds/Ping.aiff 2>/dev/null &
+            fi
+            ;;
+        Linux)
+            # Linux - try multiple sound systems (paplay, aplay, speaker-test)
+            if command -v paplay >/dev/null 2>&1; then
+                # PulseAudio (most common on modern Linux)
+                if [ "$sound_type" = "success" ]; then
+                    paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null &
+                else
+                    paplay /usr/share/sounds/freedesktop/stereo/bell.oga 2>/dev/null &
+                fi
+            elif command -v aplay >/dev/null 2>&1; then
+                # ALSA fallback
+                aplay /usr/share/sounds/alsa/Front_Center.wav 2>/dev/null &
+            elif command -v speaker-test >/dev/null 2>&1; then
+                # Last resort - system beep
+                speaker-test -t sine -f 1000 -l 1 >/dev/null 2>&1 &
+            fi
+            ;;
+        MINGW*|MSYS*|CYGWIN*)
+            # Windows (Git Bash, WSL, Cygwin)
+            if command -v powershell.exe >/dev/null 2>&1; then
+                # Use PowerShell to play sound
+                if [ "$sound_type" = "success" ]; then
+                    powershell.exe -c "(New-Object Media.SoundPlayer 'C:\Windows\Media\Windows Notify System Generic.wav').PlaySync();" 2>/dev/null &
+                else
+                    powershell.exe -c "[console]::beep(800, 300)" 2>/dev/null &
+                fi
+            fi
+            ;;
+    esac
+}
+
 # Helper: Output approve decision
 # ALWAYS log why we're stopping for debugging
 # Enhanced v2.4: Agent-aware labeling with clear hierarchy
@@ -644,12 +692,13 @@ approve() {
             echo "┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛"
 
             # ================================================================
-            # SUCCESS SOUND NOTIFICATION (NEW - v2.5)
-            # Play a satisfying sound when auto session completes successfully
-            # Glass.aiff is a clean, satisfying completion sound on macOS
+            # SOUND NOTIFICATION ON SUCCESS (v2.6)
+            # Play sound ONLY when session completes successfully
+            # This lets users know they can check back - work is done!
+            # Cross-platform support via helper function
             # ================================================================
             if [ "$is_success" = "true" ]; then
-                afplay /System/Library/Sounds/Glass.aiff 2>/dev/null &
+                play_notification_sound "success"
             fi
         else
             # Subagent stopping - this is a RETURN TO PARENT
@@ -742,6 +791,9 @@ block() {
         echo ""
     } >&2
 
+    # NOTE: No sound notification on block - sounds only play on SUCCESS
+    # When Claude is continuing work, user doesn't need to be notified
+
     if [ -n "$system_message" ]; then
         # Escape special characters for JSON
         local escaped_message=$(echo "$system_message" | jq -Rs .)