specweave 0.23.1 → 0.23.2

package/.claude-plugin/marketplace.json

@@ -73,28 +73,6 @@
         "email": "anton.abyzov@gmail.com"
       }
     },
-    {
-      "name": "specweave-figma",
-      "description": "Figma design system - MCP integration, design tokens, code generation",
-      "source": "./plugins/specweave-figma",
-      "category": "development",
-      "version": "1.0.0",
-      "author": {
-        "name": "Anton Abyzov",
-        "email": "anton.abyzov@gmail.com"
-      }
-    },
-    {
-      "name": "specweave-frontend",
-      "description": "Frontend development - React, Vue, Angular, Next.js, design systems",
-      "source": "./plugins/specweave-frontend",
-      "category": "development",
-      "version": "1.0.0",
-      "author": {
-        "name": "Anton Abyzov",
-        "email": "anton.abyzov@gmail.com"
-      }
-    },
     {
       "name": "specweave-backend",
       "description": "Backend development - Node.js, Python, .NET, REST APIs",
@@ -128,28 +106,6 @@
         "email": "anton.abyzov@gmail.com"
       }
     },
-    {
-      "name": "specweave-testing",
-      "description": "Test execution infrastructure - Playwright E2E, browser automation, visual regression",
-      "source": "./plugins/specweave-testing",
-      "category": "development",
-      "version": "1.0.0",
-      "author": {
-        "name": "Anton Abyzov",
-        "email": "anton.abyzov@gmail.com"
-      }
-    },
-    {
-      "name": "specweave-docs",
-      "description": "Documentation - Docusaurus generation, spec-driven workflows",
-      "source": "./plugins/specweave-docs",
-      "category": "productivity",
-      "version": "1.0.0",
-      "author": {
-        "name": "Anton Abyzov",
-        "email": "anton.abyzov@gmail.com"
-      }
-    },
     {
       "name": "specweave-docs-preview",
       "description": "Interactive documentation preview - Launch Docusaurus dev server with hot reload, auto-generated sidebar, Mermaid diagrams. Build static sites for deployment.",
@@ -161,50 +117,6 @@
         "email": "anton.abyzov@gmail.com"
       }
     },
-    {
-      "name": "specweave-tooling",
-      "description": "SpecWeave tooling - skill creation, skill routing",
-      "source": "./plugins/specweave-tooling",
-      "category": "development",
-      "version": "1.0.0",
-      "author": {
-        "name": "Anton Abyzov",
-        "email": "anton.abyzov@gmail.com"
-      }
-    },
-    {
-      "name": "specweave-alternatives",
-      "description": "Framework alternative experts - Compare SpecWeave with BMAD, spec-kit, openspec. Gap analysis and recommendations.",
-      "source": "./plugins/specweave-alternatives",
-      "category": "learning",
-      "version": "1.0.0",
-      "author": {
-        "name": "Anton Abyzov",
-        "email": "anton.abyzov@gmail.com"
-      }
-    },
-    {
-      "name": "specweave-ui",
-      "description": "UI components and design systems - Reusable component libraries",
-      "source": "./plugins/specweave-ui",
-      "category": "development",
-      "version": "1.0.0",
-      "author": {
-        "name": "Anton Abyzov",
-        "email": "anton.abyzov@gmail.com"
-      }
-    },
-    {
-      "name": "specweave-cost-optimizer",
-      "description": "Cost optimization - cloud platform comparison, cost breakdown",
-      "source": "./plugins/specweave-cost-optimizer",
-      "category": "productivity",
-      "version": "1.0.0",
-      "author": {
-        "name": "Anton Abyzov",
-        "email": "anton.abyzov@gmail.com"
-      }
-    },
     {
       "name": "specweave-diagrams",
       "description": "Architecture diagrams - Mermaid, C4 Model, sequence, ER diagrams",

package/CLAUDE.md

@@ -662,6 +662,106 @@ const isArchived = archivedList.some(item => item === searchId);
 
 **See Also**: `.specweave/increments/0047-us-task-linkage/reports/CRITICAL-ARCHIVING-BUGS-FIX.md`
 
+### 14. Marketplace Plugin Completeness (CRITICAL!)
+
+**NEVER add incomplete plugins to `.claude-plugin/marketplace.json`**
+
+**Rule**: ONLY plugins with complete implementation (agents/, commands/, or lib/) may be listed in marketplace.json.
+
+**Why This Matters**:
+When users install `npm i -g specweave`, Claude Code loads ALL plugins listed in marketplace.json. Incomplete plugins (skeleton-only with just skills/) cause loading errors that confuse users and damage the framework's reputation.
+
+**Incomplete Plugin Definition**:
+A plugin is considered INCOMPLETE if it ONLY has:
+- `.claude-plugin/` directory
+- `skills/` directory
+
+A plugin is COMPLETE if it has ANY of:
+- `agents/` directory (specialized Claude Code agents)
+- `commands/` directory (slash commands)
+- `lib/` directory (shared utilities, TypeScript implementations)
+
+**Validation Process** (MANDATORY before ANY marketplace.json changes):
+
+```bash
+# 1. Run validation script
+bash scripts/validate-marketplace-plugins.sh
+
+# Expected output: "✅ VALIDATION PASSED!"
+# If FAILED: Remove incomplete plugins from marketplace.json
+```
+
+**Examples**:
+
+```bash
+# ✅ COMPLETE plugins (may be listed in marketplace.json):
+plugins/specweave-github/
+  ├── .claude-plugin/
+  ├── agents/          ← Has agents
+  ├── commands/        ← Has commands
+  ├── lib/             ← Has lib
+  └── skills/
+
+plugins/specweave-kafka/
+  ├── .claude-plugin/
+  ├── agents/          ← Has agents
+  ├── lib/             ← Has lib
+  └── skills/
+
+# ✗ INCOMPLETE plugins (MUST NOT be listed in marketplace.json):
+plugins/specweave-cost-optimizer/
+  ├── .claude-plugin/
+  └── skills/          ← ONLY skills!
+
+plugins/specweave-figma/
+  ├── .claude-plugin/
+  └── skills/          ← ONLY skills!
+```
+
+**Adding New Plugins**:
+
+```bash
+# 1. Create plugin with COMPLETE structure
+mkdir -p plugins/specweave-newplugin/{.claude-plugin,agents,skills}
+
+# 2. Implement at least ONE of: agents/, commands/, or lib/
+# (Don't just create empty directories!)
+
+# 3. Add to marketplace.json
+vim .claude-plugin/marketplace.json
+
+# 4. VALIDATE (this is CRITICAL!)
+bash scripts/validate-marketplace-plugins.sh
+
+# 5. Update bin/fix-marketplace-errors.sh
+vim bin/fix-marketplace-errors.sh
+# Add "specweave-newplugin" to plugins=(...) array
+
+# 6. Commit
+git add .claude-plugin/marketplace.json bin/fix-marketplace-errors.sh
+git commit -m "feat: add specweave-newplugin to marketplace"
+```
+
+**Pre-Commit Hook** (TODO - add this):
+```bash
+# .git/hooks/pre-commit should run:
+bash scripts/validate-marketplace-plugins.sh
+# Block commit if validation fails
+```
+
+**Incident History**:
+- **2025-11-20**: Global npm install caused 8 incomplete plugins to fail loading, generating confusing errors for users. Root cause: marketplace.json listed skeleton plugins that weren't ready for distribution.
+
+**Prevention**:
+1. Run `bash scripts/validate-marketplace-plugins.sh` before EVERY marketplace.json change
+2. NEVER add plugins to marketplace.json until they have agents/, commands/, or lib/
+3. Update bin/fix-marketplace-errors.sh whenever marketplace.json changes
+4. Test global npm install (`npm pack && npm i -g ./specweave-*.tgz`) before releases
+
+**See Also**:
+- Validation script: `scripts/validate-marketplace-plugins.sh`
+- Fix script: `bin/fix-marketplace-errors.sh`
+
 ---
 
 ## Project Structure

package/bin/fix-marketplace-errors.sh

@@ -63,6 +63,8 @@ else
 fi
 
 print_info "Step 6: Installing SpecWeave plugins..."
+# IMPORTANT: Only list COMPLETE plugins (those with agents/, commands/, or lib/)
+# NEVER add plugins that only have skills/ directory - they will fail to load!
 plugins=(
     "specweave"
     "specweave-github"
@@ -70,19 +72,17 @@ plugins=(
     "specweave-ado"
     "specweave-kubernetes"
     "specweave-infrastructure"
-    "specweave-figma"
-    "specweave-frontend"
     "specweave-backend"
     "specweave-payments"
     "specweave-ml"
-    "specweave-testing"
-    "specweave-docs"
-    "specweave-tooling"
-    "specweave-alternatives"
-    "specweave-ui"
-    "specweave-cost-optimizer"
     "specweave-diagrams"
     "specweave-docs-preview"
+    "specweave-release"
+    "specweave-mobile"
+    "specweave-kafka"
+    "specweave-kafka-streams"
+    "specweave-confluent"
+    "specweave-n8n"
 )
 
 installed=0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.23.1",
+  "version": "0.23.2",
   "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/.claude-plugin/plugin.json

@@ -38,6 +38,11 @@
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-edit-spec.sh",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-metadata-change.sh",
+            "timeout": 10
           }
         ]
       },
@@ -48,6 +53,11 @@
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-write-spec.sh",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-metadata-change.sh",
+            "timeout": 10
           }
         ]
       }

package/plugins/specweave/hooks/post-metadata-change.sh

@@ -0,0 +1,160 @@
+#!/bin/bash
+#
+# Post-Metadata-Change Hook: Dispatcher for Increment Lifecycle Events
+#
+# Triggers: After Write/Edit modifies metadata.json
+# Purpose: Detect WHAT changed in metadata and call appropriate lifecycle hook
+#
+# Architecture:
+# - metadata.json is the source of truth for increment state
+# - Different state changes require different actions:
+#   * status: "completed" → Call post-increment-completion.sh
+#   * status: "paused"|"resumed"|"abandoned" → Call post-increment-status-change.sh
+#   * other changes → Update status line only
+#
+# This fixes the critical bug where status line never updates on increment closure
+# because post-increment-completion.sh was orphaned (never registered or called).
+#
+# Related Incident: 2025-11-20 - Increment 0047 completed but status line still shows active
+# Root Cause: metadata.json writes don't trigger status line refresh
+# Fix: This hook dispatches to post-increment-completion.sh which updates status line
+
+set -e
+
+# Find project root
+find_project_root() {
+  local dir="$PWD"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -d "$dir/.specweave" ]]; then
+      echo "$dir"
+      return 0
+    fi
+    dir=$(dirname "$dir")
+  done
+  echo "$PWD"
+}
+
+PROJECT_ROOT=$(find_project_root)
+LOGS_DIR="$PROJECT_ROOT/.specweave/logs"
+DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Ensure logs directory exists
+mkdir -p "$LOGS_DIR" 2>/dev/null || true
+
+# Extract modified file from environment variables (Claude Code provides this)
+MODIFIED_FILE=""
+
+# Method 1: TOOL_USE_CONTENT environment variable (primary for Write)
+if [[ -n "${TOOL_USE_CONTENT:-}" ]]; then
+  MODIFIED_FILE="$TOOL_USE_CONTENT"
+fi
+
+# Method 2: TOOL_RESULT environment variable (fallback)
+if [[ -z "$MODIFIED_FILE" ]] && [[ -n "${TOOL_RESULT:-}" ]]; then
+  MODIFIED_FILE=$(echo "$TOOL_RESULT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+fi
+
+# Method 3: Parse tool use arguments (last resort for Edit)
+if [[ -z "$MODIFIED_FILE" ]] && [[ -n "${TOOL_USE_ARGS:-}" ]]; then
+  MODIFIED_FILE=$(echo "$TOOL_USE_ARGS" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "")
+fi
+
+echo "[$(date)] post-metadata-change: Detected file: ${MODIFIED_FILE:-<none>}" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# Check if this is a metadata.json change in an increment folder
+if [[ -z "$MODIFIED_FILE" ]] || [[ "$MODIFIED_FILE" != *"/metadata.json" ]] || [[ "$MODIFIED_FILE" != *"/.specweave/increments/"* ]]; then
+  # Not a metadata.json change in increments folder - exit silently
+  exit 0
+fi
+
+# Exclude archived increments (shouldn't affect status line)
+if [[ "$MODIFIED_FILE" == *"/_archive/"* ]]; then
+  echo "[$(date)] post-metadata-change: Archived increment - skipping" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0
+fi
+
+echo "[$(date)] post-metadata-change: metadata.json changed - analyzing..." >> "$DEBUG_LOG" 2>/dev/null || true
+
+# Extract increment ID from path
+# Path format: /path/to/project/.specweave/increments/0047-name/metadata.json
+INCREMENT_ID=$(echo "$MODIFIED_FILE" | grep -o '\.specweave/increments/[^/]*' | sed 's/\.specweave\/increments\///')
+
+if [[ -z "$INCREMENT_ID" ]]; then
+  echo "[$(date)] post-metadata-change: Could not extract increment ID from path: $MODIFIED_FILE" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0
+fi
+
+echo "[$(date)] post-metadata-change: Increment ID: $INCREMENT_ID" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# Read the metadata.json to detect what changed
+METADATA_PATH="$PROJECT_ROOT/.specweave/increments/$INCREMENT_ID/metadata.json"
+
+if [[ ! -f "$METADATA_PATH" ]]; then
+  echo "[$(date)] post-metadata-change: metadata.json not found at $METADATA_PATH" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0
+fi
+
+# Check if jq is available for parsing JSON
+if ! command -v jq &> /dev/null; then
+  echo "[$(date)] post-metadata-change: jq not found - updating status line as fallback" >> "$DEBUG_LOG" 2>/dev/null || true
+  bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
+  exit 0
+fi
+
+# Extract current status
+CURRENT_STATUS=$(jq -r '.status // "unknown"' "$METADATA_PATH" 2>/dev/null)
+
+echo "[$(date)] post-metadata-change: Current status: $CURRENT_STATUS" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# Dispatch to appropriate lifecycle hook based on status
+case "$CURRENT_STATUS" in
+  completed)
+    # Increment completed - call post-increment-completion.sh
+    # This hook handles:
+    # - Closing GitHub issues
+    # - Syncing living docs
+    # - Updating status line
+    echo "[$(date)] post-metadata-change: Increment completed - calling post-increment-completion.sh" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    if [[ -x "$HOOK_DIR/post-increment-completion.sh" ]]; then
+      bash "$HOOK_DIR/post-increment-completion.sh" "$INCREMENT_ID" 2>&1 | tee -a "$DEBUG_LOG" >/dev/null || {
+        echo "[$(date)] post-metadata-change: post-increment-completion.sh failed (non-blocking)" >> "$DEBUG_LOG" 2>/dev/null || true
+      }
+    else
+      echo "[$(date)] post-metadata-change: post-increment-completion.sh not found or not executable" >> "$DEBUG_LOG" 2>/dev/null || true
+      # Fallback: Update status line directly
+      bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
+    fi
+    ;;
+
+  paused|resumed|abandoned)
+    # Status change - call post-increment-status-change.sh
+    # Note: This typically gets called manually by /specweave:pause commands
+    # But we handle it here for completeness
+    echo "[$(date)] post-metadata-change: Status changed to $CURRENT_STATUS - calling post-increment-status-change.sh" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    if [[ -x "$HOOK_DIR/post-increment-status-change.sh" ]]; then
+      # Extract reason if available
+      REASON=$(jq -r '.statusReason // "Not specified"' "$METADATA_PATH" 2>/dev/null)
+      bash "$HOOK_DIR/post-increment-status-change.sh" "$INCREMENT_ID" "$CURRENT_STATUS" "$REASON" 2>&1 | tee -a "$DEBUG_LOG" >/dev/null || {
+        echo "[$(date)] post-metadata-change: post-increment-status-change.sh failed (non-blocking)" >> "$DEBUG_LOG" 2>/dev/null || true
+      }
+    else
+      echo "[$(date)] post-metadata-change: post-increment-status-change.sh not found" >> "$DEBUG_LOG" 2>/dev/null || true
+      # Fallback: Update status line directly
+      bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
+    fi
+    ;;
+
+  *)
+    # Other metadata changes (e.g., task completion count, AC count)
+    # Just update status line to reflect new progress
+    echo "[$(date)] post-metadata-change: Status is $CURRENT_STATUS - updating status line only" >> "$DEBUG_LOG" 2>/dev/null || true
+    bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
+    ;;
+esac
+
+echo "[$(date)] post-metadata-change: Complete" >> "$DEBUG_LOG" 2>/dev/null || true
+
+exit 0