specweave 0.4.0 → 0.6.0

package/plugins/specweave-core/hooks/post-task-completion.sh

@@ -0,0 +1,265 @@
+#!/bin/bash
+
+# SpecWeave Post-Task-Completion Hook
+# Runs automatically after ANY task is marked complete via TodoWrite
+#
+# SMART SESSION-END DETECTION (v2.0):
+# =====================================
+# Problem: Claude creates multiple todo lists in one conversation
+# - List 1: [A, B, C] → completes → sound plays
+# - List 2: [D, E] → completes 30s later → sound plays again
+# - User hears sounds while Claude is still working!
+#
+# Solution: Inactivity-based detection
+# - Track time gaps BETWEEN TodoWrite calls
+# - If all tasks complete AND gap > INACTIVITY_THRESHOLD (15s)
+#   → Session is winding down → Play sound
+# - If rapid completions (gap < threshold)
+#   → Claude still actively working → Skip sound
+#
+# Example:
+# 10:00:00 - Task done (gap: 5s) → skip sound
+# 10:00:05 - Task done (gap: 5s) → skip sound
+# 10:00:10 - All done (gap: 5s) → skip sound (rapid work)
+# ...
+# 10:01:00 - All done (gap: 50s) → PLAY SOUND! (session ending)
+#
+# DEBOUNCING: Prevents duplicate fires (Claude Code calls hooks twice)
+
+set -e
+
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$PROJECT_ROOT" 2>/dev/null || true
+
+# ============================================================================
+# CONFIGURATION
+# ============================================================================
+
+# Debounce window to prevent duplicate hook fires
+DEBOUNCE_SECONDS=2
+
+# Inactivity threshold to detect session end
+# If gap between TodoWrite calls > this value, assume session is ending
+INACTIVITY_THRESHOLD=15  # seconds (configurable)
+
+# File paths
+LOGS_DIR=".specweave/logs"
+LAST_FIRE_FILE="$LOGS_DIR/last-hook-fire"
+LAST_TODOWRITE_FILE="$LOGS_DIR/last-todowrite-time"
+DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
+TASKS_LOG="$LOGS_DIR/tasks.log"
+
+mkdir -p "$LOGS_DIR" 2>/dev/null || true
+
+# ============================================================================
+# DEBOUNCING
+# ============================================================================
+
+CURRENT_TIME=$(date +%s)
+
+# Skip if hook fired within last N seconds (prevents duplicates)
+if [ -f "$LAST_FIRE_FILE" ]; then
+  LAST_FIRE=$(cat "$LAST_FIRE_FILE" 2>/dev/null || echo "0")
+  TIME_DIFF=$((CURRENT_TIME - LAST_FIRE))
+
+  if [ "$TIME_DIFF" -lt "$DEBOUNCE_SECONDS" ]; then
+    echo "[$(date)] ⏭️  Debounced (last fire: ${TIME_DIFF}s ago)" >> "$DEBUG_LOG" 2>/dev/null || true
+    cat <<EOF
+{
+  "continue": true
+}
+EOF
+    exit 0
+  fi
+fi
+
+echo "$CURRENT_TIME" > "$LAST_FIRE_FILE"
+
+# ============================================================================
+# CAPTURE INPUT
+# ============================================================================
+
+STDIN_DATA=$(mktemp)
+cat > "$STDIN_DATA"
+
+echo "[$(date)] 📋 TodoWrite hook fired" >> "$DEBUG_LOG" 2>/dev/null || true
+echo "[$(date)] Input JSON:" >> "$DEBUG_LOG" 2>/dev/null || true
+cat "$STDIN_DATA" >> "$DEBUG_LOG" 2>/dev/null || true
+echo "" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# INACTIVITY DETECTION
+# ============================================================================
+
+INACTIVITY_GAP=0
+PREVIOUS_TODOWRITE_TIME=0
+
+if [ -f "$LAST_TODOWRITE_FILE" ]; then
+  PREVIOUS_TODOWRITE_TIME=$(cat "$LAST_TODOWRITE_FILE" 2>/dev/null || echo "0")
+  INACTIVITY_GAP=$((CURRENT_TIME - PREVIOUS_TODOWRITE_TIME))
+  echo "[$(date)] ⏱️  Inactivity gap: ${INACTIVITY_GAP}s (threshold: ${INACTIVITY_THRESHOLD}s)" >> "$DEBUG_LOG" 2>/dev/null || true
+else
+  echo "[$(date)] 🆕 First TodoWrite in session" >> "$DEBUG_LOG" 2>/dev/null || true
+fi
+
+# Save current timestamp for next call
+echo "$CURRENT_TIME" > "$LAST_TODOWRITE_FILE"
+
+# ============================================================================
+# PARSE TASK COMPLETION STATE
+# ============================================================================
+
+ALL_COMPLETED=false
+
+if command -v jq >/dev/null 2>&1; then
+  # Use jq if available (more reliable)
+  PENDING_COUNT=$(jq -r '.tool_input.todos // [] | map(select(.status != "completed")) | length' "$STDIN_DATA" 2>/dev/null || echo "1")
+  TOTAL_COUNT=$(jq -r '.tool_input.todos // [] | length' "$STDIN_DATA" 2>/dev/null || echo "0")
+
+  echo "[$(date)] 📊 Tasks: $((TOTAL_COUNT - PENDING_COUNT))/$TOTAL_COUNT completed" >> "$DEBUG_LOG" 2>/dev/null || true
+
+  if [ "$PENDING_COUNT" = "0" ] && [ "$TOTAL_COUNT" != "0" ]; then
+    ALL_COMPLETED=true
+  fi
+else
+  # Fallback: Simple grep check (less reliable but works without jq)
+  if grep -q '"status":"pending"\|"status":"in_progress"' "$STDIN_DATA" 2>/dev/null; then
+    ALL_COMPLETED=false
+  else
+    ALL_COMPLETED=true
+  fi
+fi
+
+rm -f "$STDIN_DATA"
+
+# ============================================================================
+# SESSION-END DETECTION LOGIC
+# ============================================================================
+
+SESSION_ENDING=false
+DECISION_REASON=""
+
+if [ "$ALL_COMPLETED" = "true" ]; then
+  if [ "$INACTIVITY_GAP" -ge "$INACTIVITY_THRESHOLD" ]; then
+    SESSION_ENDING=true
+    DECISION_REASON="All tasks complete + ${INACTIVITY_GAP}s inactivity ≥ ${INACTIVITY_THRESHOLD}s threshold"
+    echo "[$(date)] 🎉 SESSION ENDING DETECTED! ($DECISION_REASON)" >> "$DEBUG_LOG" 2>/dev/null || true
+  else
+    DECISION_REASON="All tasks complete, but rapid activity (${INACTIVITY_GAP}s < ${INACTIVITY_THRESHOLD}s) - Claude likely creating more work"
+    echo "[$(date)] ⚡ $DECISION_REASON (no sound)" >> "$DEBUG_LOG" 2>/dev/null || true
+  fi
+else
+  DECISION_REASON="Tasks remaining in current list"
+  echo "[$(date)] 🔄 $DECISION_REASON (no sound)" >> "$DEBUG_LOG" 2>/dev/null || true
+fi
+
+# ============================================================================
+# UPDATE TASKS.MD (NEW in v0.6.1)
+# ============================================================================
+
+if command -v node &> /dev/null; then
+  # Detect current increment (latest non-backlog increment)
+  CURRENT_INCREMENT=$(ls -t .specweave/increments/ 2>/dev/null | grep -v "_backlog" | head -1)
+
+  if [ -n "$CURRENT_INCREMENT" ] && [ -f ".specweave/increments/$CURRENT_INCREMENT/tasks.md" ]; then
+    echo "[$(date)] 📝 Updating tasks.md for $CURRENT_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    # Run task updater (non-blocking, best-effort)
+    node dist/hooks/lib/update-tasks-md.js "$CURRENT_INCREMENT" 2>&1 | tee -a "$DEBUG_LOG" >/dev/null || {
+      echo "[$(date)] ⚠️  Failed to update tasks.md (non-blocking)" >> "$DEBUG_LOG" 2>/dev/null || true
+    }
+  else
+    echo "[$(date)] ℹ️  No current increment or tasks.md found, skipping tasks.md update" >> "$DEBUG_LOG" 2>/dev/null || true
+  fi
+else
+  echo "[$(date)] ⚠️  Node.js not found, skipping tasks.md update" >> "$DEBUG_LOG" 2>/dev/null || true
+fi
+
+# ============================================================================
+# SYNC LIVING DOCS (NEW in v0.6.1)
+# ============================================================================
+
+if command -v node &> /dev/null; then
+  if [ -n "$CURRENT_INCREMENT" ]; then
+    echo "[$(date)] 📚 Checking living docs sync for $CURRENT_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    # Run living docs sync (non-blocking, best-effort)
+    node dist/hooks/lib/sync-living-docs.js "$CURRENT_INCREMENT" 2>&1 | tee -a "$DEBUG_LOG" >/dev/null || {
+      echo "[$(date)] ⚠️  Failed to sync living docs (non-blocking)" >> "$DEBUG_LOG" 2>/dev/null || true
+    }
+  fi
+fi
+
+# ============================================================================
+# TRANSLATE LIVING DOCS (NEW in v0.6.0 - i18n)
+# ============================================================================
+
+if command -v node &> /dev/null; then
+  if [ -n "$CURRENT_INCREMENT" ]; then
+    echo "[$(date)] 🌐 Checking if living docs translation is needed for $CURRENT_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    # Run living docs translation (non-blocking, best-effort)
+    node dist/hooks/lib/translate-living-docs.js "$CURRENT_INCREMENT" 2>&1 | tee -a "$DEBUG_LOG" >/dev/null || {
+      echo "[$(date)] ⚠️  Failed to translate living docs (non-blocking)" >> "$DEBUG_LOG" 2>/dev/null || true
+    }
+  fi
+fi
+
+# ============================================================================
+# PLAY SOUND (only if session is truly ending)
+# ============================================================================
+
+play_sound() {
+  case "$(uname -s)" in
+    Darwin)
+      afplay /System/Library/Sounds/Glass.aiff 2>/dev/null || true
+      ;;
+    Linux)
+      paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null || \
+      aplay /usr/share/sounds/alsa/Front_Center.wav 2>/dev/null || true
+      ;;
+    MINGW*|MSYS*|CYGWIN*)
+      powershell -c "(New-Object Media.SoundPlayer 'C:\Windows\Media\chimes.wav').PlaySync();" 2>/dev/null || true
+      ;;
+  esac
+}
+
+if [ "$SESSION_ENDING" = "true" ]; then
+  echo "[$(date)] 🔔 Playing completion sound" >> "$DEBUG_LOG" 2>/dev/null || true
+  play_sound
+fi
+
+# ============================================================================
+# LOGGING
+# ============================================================================
+
+echo "[$(date)] Status: All_completed=$ALL_COMPLETED, Session_ending=$SESSION_ENDING, Inactivity=${INACTIVITY_GAP}s" >> "$TASKS_LOG" 2>/dev/null || true
+echo "[$(date)] Reason: $DECISION_REASON" >> "$TASKS_LOG" 2>/dev/null || true
+echo "---" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# ============================================================================
+# OUTPUT TO CLAUDE
+# ============================================================================
+
+if [ "$SESSION_ENDING" = "true" ]; then
+  cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "🎉 ALL WORK COMPLETED! Session ending detected (${INACTIVITY_GAP}s inactivity). Remember to update documentation with inline edits to CLAUDE.md and README.md as needed."
+}
+EOF
+elif [ "$ALL_COMPLETED" = "true" ]; then
+  cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "✅ Task batch completed (${INACTIVITY_GAP}s since last activity). Continuing work..."
+}
+EOF
+else
+  cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "✅ Task completed. More tasks remaining - keep going!"
+}
+EOF
+fi

package/plugins/specweave-core/hooks/pre-task-plugin-detect.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+
+#
+# Pre-Task Plugin Detection Hook (T-020)
+#
+# Runs BEFORE task execution to suggest plugins based on task description
+# This is Phase 3 of the 4-phase plugin detection system
+#
+# Trigger: Before executing any task via `/specweave.do`
+# Output: Non-blocking plugin suggestions
+#
+
+# Exit on error
+set -e
+
+# Get project root (assumes hook runs from project directory)
+PROJECT_ROOT=$(pwd)
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+GRAY='\033[0;37m'
+NC='\033[0m' # No Color
+
+# Check if SpecWeave is installed
+if ! command -v specweave &> /dev/null; then
+    # Silent exit if SpecWeave not installed (development mode)
+    exit 0
+fi
+
+# Get current task being executed (passed as argument)
+TASK_FILE="$1"
+
+if [ -z "$TASK_FILE" ] || [ ! -f "$TASK_FILE" ]; then
+    # No task file provided, skip detection
+    exit 0
+fi
+
+# Extract task description
+TASK_DESCRIPTION=$(grep -A 5 "^### T-[0-9]" "$TASK_FILE" | head -1 || echo "")
+
+if [ -z "$TASK_DESCRIPTION" ]; then
+    # No description found, skip
+    exit 0
+fi
+
+# Keyword-based plugin detection
+declare -A PLUGIN_KEYWORDS=(
+    ["specweave-github"]="github|gh|issue|pull request|pr"
+    ["specweave-kubernetes"]="kubernetes|k8s|kubectl|helm|pod|deployment"
+    ["specweave-frontend-stack"]="react|vue|angular|nextjs|frontend|ui|component"
+    ["specweave-backend-stack"]="express|fastapi|django|flask|nestjs|backend|api|server"
+    ["specweave-ml-ops"]="tensorflow|pytorch|sklearn|ml|machine learning|model|training"
+    ["specweave-payment-processing"]="stripe|paypal|payment|billing|subscription"
+    ["specweave-figma"]="figma|design|mockup|prototype"
+    ["specweave-jira"]="jira|atlassian|ticket"
+    ["specweave-observability"]="prometheus|grafana|datadog|monitoring|metrics|tracing"
+)
+
+# Detect plugins based on keywords
+SUGGESTED_PLUGINS=()
+
+for plugin in "${!PLUGIN_KEYWORDS[@]}"; do
+    keywords="${PLUGIN_KEYWORDS[$plugin]}"
+
+    # Check if any keyword matches (case-insensitive)
+    if echo "$TASK_DESCRIPTION" | grep -qi -E "$keywords"; then
+        # Check if plugin is already enabled
+        if ! specweave plugin list --enabled 2>/dev/null | grep -q "$plugin"; then
+            SUGGESTED_PLUGINS+=("$plugin")
+        fi
+    fi
+done
+
+# Output suggestions if any found
+if [ ${#SUGGESTED_PLUGINS[@]} -gt 0 ]; then
+    echo ""
+    echo -e "${CYAN}💡 Plugin Detection${NC}"
+    echo ""
+    echo -e "${GRAY}Task mentions: ${TASK_DESCRIPTION}${NC}"
+    echo ""
+    echo -e "${YELLOW}Suggested plugins:${NC}"
+
+    for plugin in "${SUGGESTED_PLUGINS[@]}"; do
+        echo -e "   • ${GREEN}${plugin}${NC}"
+    done
+
+    echo ""
+    echo -e "${GRAY}This task might benefit from these plugins.${NC}"
+    echo -e "${GRAY}Run: ${CYAN}specweave plugin enable <name>${GRAY} to install${NC}"
+    echo ""
+fi
+
+# Always exit successfully (non-blocking)
+exit 0

package/plugins/specweave-core/skills/SKILLS-INDEX.md

@@ -0,0 +1,229 @@
+# SpecWeave Skills Index
+
+**Purpose**: Quick reference for all available skills. Read this file BEFORE starting any task.
+
+**Last Updated**: 2025-11-03T04:18:05.042Z (auto-generated, do not edit manually)
+
+**Total Skills**: 12
+
+---
+
+## 🚀 Quick Start (Progressive Disclosure)
+
+**MANDATORY**: Skills are your expert manuals. Always check for relevant skills BEFORE starting implementation.
+
+### Progressive Disclosure Pattern
+
+1. **Scan this index** to find skills matching your task
+2. **Match activation keywords** to your current request
+3. **Load full SKILL.md** for matching skills
+4. **Follow the workflow** in SKILL.md precisely
+
+### Example Workflow
+
+```
+User asks: "Plan a new feature for user authentication"
+
+Step 1: Scan this index → Find "increment-planner" skill
+Step 2: Check keywords → Matches "feature planning", "create increment"
+Step 3: Load skill → cat .claude/skills/increment-planner/SKILL.md
+Step 4: Execute → Follow the increment planning workflow
+```
+
+---
+
+## 📚 All Available Skills
+
+
+### Framework Core
+
+#### context-loader
+
+**Description**: Explains how SpecWeave achieves context efficiency through Claude's native progressive disclosure mechanism and sub-agent parallelization. Skills load only when relevant, sub-agents isolate context. Activates when users ask about context loading, token usage, or how SpecWeave scales. Keywords: context loading, progressive disclosure, token efficiency, sub-agents, context management.
+
+**Location**: `.claude/skills/context-loader/SKILL.md`
+
+---
+
+#### context-optimizer
+
+**Description**: Second-pass context optimization that analyzes user prompts and removes irrelevant specs, agents, and skills from loaded context. Achieves 80%+ token reduction through smart cleanup. Activates for optimize context, reduce tokens, clean context, smart context, precision loading.
+
+**Location**: `.claude/skills/context-optimizer/SKILL.md`
+
+**Allowed tools**: Read, Grep, Glob
+
+---
+
+#### increment-planner
+
+**Description**: Creates comprehensive implementation plans for SpecWeave increments (aka features - both terms are interchangeable). This skill should be used when planning new increments/features, creating specifications, or organizing implementation work. Activates for: increment planning, feature planning, implementation plan, create increment, create feature, plan increment, plan feature, organize work, break down increment, break down feature, new product, build project, MVP, SaaS, app development, product description, tech stack planning, feature list.
+
+**Activates for**: increment planning, feature planning, implementation plan, create increment, create feature, plan increment, plan feature, organize work, break down increment, break down feature, new product, build project, MVP, SaaS, app development, product description, tech stack planning, feature list
+
+**Location**: `.claude/skills/increment-planner/SKILL.md`
+
+---
+
+#### increment-quality-judge
+
+**Description**: Optional AI-powered quality assessment for specifications, plans, and tests. Goes beyond rule-based validation to evaluate clarity, testability, edge cases, and architecture soundness. Activates for validate quality, quality check, assess spec, evaluate increment, spec review, quality score.
+
+**Location**: `.claude/skills/increment-quality-judge/SKILL.md`
+
+**Allowed tools**: Read, Grep, Glob
+
+---
+
+#### specweave-detector
+
+**Description**: Detects SpecWeave context (.specweave/ directory exists) and provides workflow documentation. v0.3.8+ features PROACTIVE auto-detection - when in SpecWeave folder, product descriptions automatically trigger increment planning. Explicit slash commands still work (/inc, /do, /progress, /validate, /done, /sync-docs, /sync-github). Keywords slash commands, /inc, /increment, /do, /progress, /validate, /done, specweave commands, smart workflow, auto-detection, specweave folder.
+
+**Location**: `.claude/skills/specweave-detector/SKILL.md`
+
+---
+
+#### specweave-framework
+
+**Description**: Expert knowledge of SpecWeave framework structure, rules, conventions, and increment lifecycle. Deep understanding of source-of-truth discipline, increment naming, hook system, and plugin architecture. Activates for: specweave rules, how does specweave work, framework structure, increment lifecycle, what is specweave, specweave conventions, specweave discipline, specweave architecture, where do files go, source of truth, increment naming, tasks.md format, spec.md structure, living docs sync, hook system, plugin architecture, how to use specweave, specweave best practices.
+
+**Activates for**: specweave rules, how does specweave work, framework structure, increment lifecycle, what is specweave, specweave conventions, specweave discipline, specweave architecture, where do files go, source of truth, increment naming, tasks
+
+**Location**: `.claude/skills/specweave-framework/SKILL.md`
+
+**Allowed tools**: Read, Grep, Glob
+
+---
+
+
+### Orchestration & Planning
+
+#### role-orchestrator
+
+**Description**: Multi-agent orchestration system that coordinates specialized agents (PM, Architect, DevOps, QA, Tech Lead, Security) to work together on complex tasks. Implements hierarchical orchestrator-worker pattern. Activates for complex multi-step requests requiring multiple roles/skills. Keywords: build product, create SaaS, full implementation, end-to-end, multi-agent, orchestrate, coordinate roles, complex project.
+
+**Location**: `.claude/skills/role-orchestrator/SKILL.md`
+
+---
+
+
+### Documentation
+
+#### brownfield-analyzer
+
+**Description**: Analyzes existing brownfield projects to map documentation structure to SpecWeave's PRD/HLD/RFC/Runbook pattern. Scans folders, classifies documents, detects external tools (Jira, ADO, GitHub), and generates migration plan. Activates for brownfield, existing project, migrate, analyze structure, legacy documentation.
+
+**Location**: `.claude/skills/brownfield-analyzer/SKILL.md`
+
+---
+
+#### translator
+
+**Description**: LLM-native translation skill for SpecWeave content. Activates when translation is needed for CLI messages, templates, documentation, or living docs. Uses the current LLM session for zero-cost translation. Keywords: translate, translation, language, multilingual, i18n, internationalization, Russian, Spanish, Chinese, German, French, localization, translate to.
+
+**Location**: `.claude/skills/translator/SKILL.md`
+
+**Allowed tools**: Read, Write, Edit, Grep, Glob
+
+---
+
+
+### Other
+
+#### brownfield-onboarder
+
+**Description**: Intelligently onboards brownfield projects by merging existing CLAUDE.md backups into SpecWeave structure. Extracts project-specific knowledge, domain context, team conventions, and technical details from backup CLAUDE.md files, then distributes content to appropriate SpecWeave folders without bloating CLAUDE.md. Activates for: merge docs, merge claude, onboard brownfield, import existing docs, claude backup, specweave merge-docs.
+
+**Activates for**: merge docs, merge claude, onboard brownfield, import existing docs, claude backup, specweave merge-docs
+
+**Location**: `.claude/skills/brownfield-onboarder/SKILL.md`
+
+---
+
+#### project-kickstarter
+
+**Description**: Proactively detects product/project descriptions and guides users through SpecWeave increment planning. Activates when user provides product name, features, tech stack, timeline, or problem description. Keywords: project, product, SaaS, app, MVP, build, new project, features, tech stack, core functionality, monetization, timeline, I want to build, let's build, quick build, core features.
+
+**Location**: `.claude/skills/project-kickstarter/SKILL.md`
+
+---
+
+#### tdd-workflow
+
+**Description**: Test-Driven Development workflow coordinator. Detects TDD intent and offers guided red-green-refactor cycle. Activates for TDD, test-driven, red-green-refactor, write tests first, test-first development, Kent Beck, TDD cycle.
+
+**Location**: `.claude/skills/tdd-workflow/SKILL.md`
+
+---
+
+
+## 💡 How Skills Work
+
+**Level 1 - Discovery (this file)**:
+- Scan activation keywords
+- Match to your current task
+- Identify 1-3 relevant skills
+
+**Level 2 - Deep Dive (SKILL.md)**:
+- Load full skill documentation
+- Read required prerequisites
+- Follow step-by-step workflow
+
+**Level 3 - Execution**:
+- Apply skill's instructions
+- Use recommended tools
+- Follow SpecWeave best practices
+
+---
+
+## 🎯 Task → Skill Matching Guide
+
+| Your Task | Relevant Skill | Keywords |
+|-----------|---------------|----------|
+| "Plan a new feature" | `increment-planner` | "feature planning", "create increment" |
+| "Sync to JIRA" | `jira-sync` | "JIRA sync", "create JIRA issue" |
+| "Create diagram" | `diagrams-architect` | "architecture diagram", "C4 diagram" |
+| "Build React UI" | `frontend` | "React", "components", "UI" |
+| "Deploy to cloud" | `hetzner-provisioner` | "deploy", "infrastructure" |
+| "Quality check" | `increment-quality-judge` | "quality check", "assess spec" |
+| "E2E testing" | `e2e-playwright` | "E2E test", "browser test" |
+| "Generate docs site" | `docusaurus` | "documentation site", "docs" |
+
+---
+
+## ⚡ Why Skills Matter
+
+**Without skills**:
+- ❌ Reinvent workflows every session
+- ❌ Inconsistent increment structure
+- ❌ Miss SpecWeave conventions
+- ❌ Waste tokens on irrelevant docs
+
+**With skills**:
+- ✅ Proven workflows ready to use
+- ✅ Consistent high-quality output
+- ✅ SpecWeave best practices enforced
+- ✅ Efficient token usage (load only what's needed)
+
+---
+
+## 🔧 For AI Tool Developers
+
+This index simulates Claude Code's native progressive disclosure:
+- Claude pre-loads skill metadata at startup (name + description)
+- Other tools read this index file for same benefit
+- Single file read replaces 12 individual file scans
+- Token savings: ~97% (1 file vs 12 files)
+
+**How to use in your AI tool**:
+1. Load this file at session start
+2. Parse activation keywords
+3. Match user requests to keywords
+4. Load full SKILL.md when matched
+5. Execute skill workflow
+
+---
+
+**Generated by**: `src/utils/generate-skills-index.ts`
+
+**Regenerate with**: `npm run generate-skills-index`