specweave 0.32.0 → 0.32.3

package/plugins/specweave/scripts/progress.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * Instant Increment Progress
+ *
+ * Executed by UserPromptSubmit hook for /specweave:progress
+ * Bypasses LLM entirely - output shown directly to user
+ *
+ * Usage: node progress.js [incrementId] [--help]
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// Handle --help
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log(`
+SpecWeave Instant Progress
+
+USAGE
+  node plugins/specweave/scripts/progress.js [incrementId] [options]
+  specweave status --verbose
+
+OPTIONS
+  --help, -h     Show this help message
+  [incrementId]  Show progress for specific increment (e.g., 0045)
+
+DESCRIPTION
+  Shows task completion progress for active increments with visual progress bars.
+  This script bypasses LLM processing for instant results (<100ms).
+
+EXECUTION PATHS
+  1. Claude Code:  /specweave:progress  (hook intercepts, <100ms)
+  2. Any LLM:      Skill instructs to run this script (~2s)
+  3. Terminal:     specweave status --verbose (~500ms)
+
+EXAMPLES
+  node plugins/specweave/scripts/progress.js
+  node plugins/specweave/scripts/progress.js 0045
+  specweave status --verbose
+`);
+  process.exit(0);
+}
+
+const cwd = process.cwd();
+const incrementsDir = path.join(cwd, '.specweave/increments');
+const args = process.argv.slice(2);
+const specificId = args[0];
+
+// Check if increments directory exists
+if (!fs.existsSync(incrementsDir)) {
+  console.log('No SpecWeave project found (missing .specweave/increments/)');
+  process.exit(0);
+}
+
+// Find increments
+const entries = fs.readdirSync(incrementsDir, { withFileTypes: true });
+const incrementFolders = entries
+  .filter(e => e.isDirectory() && !e.name.startsWith('_') && /^\d{4}/.test(e.name))
+  .map(e => e.name);
+
+if (incrementFolders.length === 0) {
+  console.log('No increments found.');
+  process.exit(0);
+}
+
+// Parse increment data
+function parseIncrement(folder) {
+  const metaPath = path.join(incrementsDir, folder, 'metadata.json');
+  const tasksPath = path.join(incrementsDir, folder, 'tasks.md');
+  
+  let metadata = { status: 'unknown' };
+  if (fs.existsSync(metaPath)) {
+    try {
+      metadata = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+    } catch {}
+  }
+  
+  let totalTasks = 0;
+  let completedTasks = 0;
+  
+  if (fs.existsSync(tasksPath)) {
+    const content = fs.readFileSync(tasksPath, 'utf-8');
+    const taskMatches = content.match(/### T-\d+/g);
+    totalTasks = taskMatches ? taskMatches.length : 0;
+    
+    const completedMatches = content.match(/\*\*Status\*\*:\s*\[x\]/gi);
+    completedTasks = completedMatches ? completedMatches.length : 0;
+  }
+  
+  return {
+    id: folder,
+    status: metadata.status || 'unknown',
+    type: metadata.type || 'feature',
+    totalTasks,
+    completedTasks,
+    percentage: totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0
+  };
+}
+
+// If specific increment requested
+if (specificId) {
+  const folder = incrementFolders.find(f => f === specificId || f.startsWith(specificId));
+  if (!folder) {
+    console.log(`Increment not found: ${specificId}`);
+    process.exit(1);
+  }
+  
+  const inc = parseIncrement(folder);
+  const bar = createProgressBar(inc.percentage);
+  
+  console.log(`\n📊 Progress: ${inc.id}\n`);
+  console.log(`Status: ${formatStatus(inc.status)}`);
+  console.log(`Type: ${inc.type}`);
+  console.log(`Tasks: ${inc.completedTasks}/${inc.totalTasks} (${inc.percentage}%)`);
+  console.log(`Progress: ${bar}`);
+  process.exit(0);
+}
+
+// Show all active increments
+const increments = incrementFolders.map(parseIncrement);
+const active = increments.filter(i => ['active', 'planning', 'in-progress'].includes(i.status));
+const paused = increments.filter(i => i.status === 'paused');
+
+console.log('\n📊 Increment Progress\n');
+
+if (active.length > 0) {
+  console.log(`🔄 Active (${active.length}):`);
+  for (const inc of active) {
+    const bar = createProgressBar(inc.percentage, 15);
+    console.log(`  ${inc.id}`);
+    console.log(`     ${bar} ${inc.completedTasks}/${inc.totalTasks} (${inc.percentage}%)`);
+  }
+  console.log('');
+}
+
+if (paused.length > 0) {
+  console.log(`⏸️  Paused (${paused.length}):`);
+  for (const inc of paused) {
+    console.log(`  ${inc.id} - ${inc.percentage}%`);
+  }
+  console.log('');
+}
+
+if (active.length === 0 && paused.length === 0) {
+  console.log('No active increments.');
+  const completed = increments.filter(i => i.status === 'completed');
+  if (completed.length > 0) {
+    console.log(`${completed.length} completed increment(s).`);
+  }
+}
+
+console.log('💡 For details: /specweave:progress <incrementId>');
+
+// Helpers
+function createProgressBar(pct, width = 20) {
+  const filled = Math.round((pct / 100) * width);
+  const empty = width - filled;
+  return `[${'█'.repeat(filled)}${'░'.repeat(empty)}]`;
+}
+
+function formatStatus(status) {
+  const icons = {
+    'active': '🔄 active',
+    'planning': '📝 planning',
+    'paused': '⏸️ paused',
+    'completed': '✅ completed',
+    'abandoned': '❌ abandoned'
+  };
+  return icons[status] || status;
+}

package/plugins/specweave/scripts/read-costs.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# read-costs.sh - Pure bash reader for /specweave:costs
+#
+# Shows cost/token tracking dashboard.
+# Reads from pre-computed dashboard cache for <10ms response time.
+#
+# Usage: bash read-costs.sh [incrementId]
+#
+# Compatible with bash 3.x (macOS default)
+
+set -e
+
+INCREMENT_ID="${1:-}"
+
+# Find project root
+PROJECT_ROOT="$PWD"
+while [[ "$PROJECT_ROOT" != "/" ]] && [[ ! -d "$PROJECT_ROOT/.specweave" ]]; do
+  PROJECT_ROOT=$(dirname "$PROJECT_ROOT")
+done
+
+if [[ ! -d "$PROJECT_ROOT/.specweave" ]]; then
+  echo "No SpecWeave project found (missing .specweave/)"
+  exit 0
+fi
+
+CACHE_FILE="$PROJECT_ROOT/.specweave/state/dashboard.json"
+SCRIPTS_DIR="$(dirname "${BASH_SOURCE[0]}")"
+
+# Check if jq is available
+if ! command -v jq >/dev/null 2>&1; then
+  echo "❌ jq required for costs command. Install with: brew install jq"
+  exit 1
+fi
+
+# If cache doesn't exist or is corrupted, rebuild it
+NEED_REBUILD=false
+if [[ ! -f "$CACHE_FILE" ]]; then
+  NEED_REBUILD=true
+elif ! jq -e '.' "$CACHE_FILE" >/dev/null 2>&1; then
+  # Cache exists but is corrupted (invalid JSON)
+  NEED_REBUILD=true
+fi
+
+if [[ "$NEED_REBUILD" == "true" ]]; then
+  bash "$SCRIPTS_DIR/rebuild-dashboard-cache.sh" --quiet 2>/dev/null || true
+fi
+
+if [[ ! -f "$CACHE_FILE" ]] || ! jq -e '.' "$CACHE_FILE" >/dev/null 2>&1; then
+  echo "❌ Cache unavailable. Try: bash plugins/specweave/scripts/rebuild-dashboard-cache.sh"
+  exit 1
+fi
+
+echo ""
+echo "💰 SpecWeave Cost Dashboard"
+echo ""
+
+# Read costs from cache
+TOTAL_TOKENS=$(jq '.costs.totalTokens // 0' "$CACHE_FILE")
+TOTAL_COST=$(jq '.costs.totalCost // 0' "$CACHE_FILE")
+TOTAL_SAVINGS=$(jq '.costs.totalSavings // 0' "$CACHE_FILE")
+
+if [[ "$TOTAL_TOKENS" -eq 0 ]] && [[ "$TOTAL_COST" == "0" ]]; then
+  echo "📊 No cost data yet"
+  echo ""
+  echo "Cost tracking starts when you run agents with model hints."
+  echo ""
+  echo "💡 Tips:"
+  echo "   • Use ⚡ haiku for simple tasks (3x faster, 20x cheaper)"
+  echo "   • Use 💎 opus for complex reasoning (default, best quality)"
+  echo "   • Use 🧠 sonnet only for legacy compatibility (rarely needed)"
+  echo ""
+  echo "Model hints in tasks.md:"
+  echo "   ### T-001: Setup project structure ⚡"
+  echo "   ### T-002: Design architecture 💎"
+  exit 0
+fi
+
+# Format numbers
+format_tokens() {
+  local tokens=$1
+  if [[ "$tokens" -ge 1000000 ]]; then
+    echo "$((tokens / 1000000))M"
+  elif [[ "$tokens" -ge 1000 ]]; then
+    echo "$((tokens / 1000))k"
+  else
+    echo "$tokens"
+  fi
+}
+
+format_cost() {
+  local cost=$1
+  if [[ "${cost%.*}" -ge 100 ]]; then
+    printf "\$%.0f" "$cost"
+  else
+    printf "\$%.2f" "$cost"
+  fi
+}
+
+# Display totals
+echo "📈 Totals:"
+echo "   Tokens: $(format_tokens "$TOTAL_TOKENS")"
+echo "   Cost: $(format_cost "$TOTAL_COST")"
+echo "   Savings: $(format_cost "$TOTAL_SAVINGS") (vs all-Sonnet)"
+echo ""
+
+# If specific increment requested
+if [[ -n "$INCREMENT_ID" ]]; then
+  INC_COSTS=$(jq --arg id "$INCREMENT_ID" '.costs.byIncrement[$id] // empty' "$CACHE_FILE" 2>/dev/null)
+  if [[ -n "$INC_COSTS" ]]; then
+    INC_TOKENS=$(echo "$INC_COSTS" | jq -r '.tokens // 0')
+    INC_COST=$(echo "$INC_COSTS" | jq -r '.cost // 0')
+    INC_SAVINGS=$(echo "$INC_COSTS" | jq -r '.savings // 0')
+    echo "📦 Increment: $INCREMENT_ID"
+    echo "   Tokens: $(format_tokens "$INC_TOKENS")"
+    echo "   Cost: $(format_cost "$INC_COST")"
+    echo "   Savings: $(format_cost "$INC_SAVINGS")"
+    echo ""
+  else
+    echo "No cost data for increment: $INCREMENT_ID"
+    echo ""
+  fi
+fi
+
+# Show top increments by cost
+echo "📊 Cost by Increment (top 5):"
+jq -r '.costs.byIncrement | to_entries | sort_by(-.value.cost) | .[0:5][] |
+  "   \(.key): $\(.value.cost | tostring | .[0:6])"' "$CACHE_FILE" 2>/dev/null || echo "   (no data)"
+echo ""
+
+echo "💡 Commands:"
+echo "   /specweave:costs <id>     View increment costs"
+echo "   /specweave:progress       View task progress"

package/plugins/specweave/scripts/read-jobs.sh

@@ -0,0 +1,324 @@
+#!/usr/bin/env bash
+# read-jobs.sh - Pure bash reader for /specweave:jobs
+#
+# Shows current work status (increments) + background jobs + helpful context.
+# Reads from pre-computed dashboard cache for <10ms response time.
+#
+# Usage: bash read-jobs.sh [--all] [--id <jobId>]
+#
+# Compatible with bash 3.x (macOS default)
+
+set -e
+
+# Parse arguments
+SHOW_ALL=false
+SPECIFIC_ID=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --all) SHOW_ALL=true; shift ;;
+    --id) SPECIFIC_ID="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+# Find project root
+PROJECT_ROOT="$PWD"
+while [[ "$PROJECT_ROOT" != "/" ]] && [[ ! -d "$PROJECT_ROOT/.specweave" ]]; do
+  PROJECT_ROOT=$(dirname "$PROJECT_ROOT")
+done
+
+if [[ ! -d "$PROJECT_ROOT/.specweave" ]]; then
+  echo "No SpecWeave project found (missing .specweave/)"
+  exit 0
+fi
+
+CACHE_FILE="$PROJECT_ROOT/.specweave/state/dashboard.json"
+JOBS_FILE="$PROJECT_ROOT/.specweave/state/background-jobs.json"
+SCRIPTS_DIR="$PROJECT_ROOT/plugins/specweave/scripts"
+
+# Check if jq is available, fall back to Node if not
+if ! command -v jq >/dev/null 2>&1; then
+  if [[ -f "$SCRIPTS_DIR/jobs.js" ]]; then
+    echo "⚠️  Install jq for instant status commands: brew install jq"
+    exec node "$SCRIPTS_DIR/jobs.js" "$@"
+  else
+    echo "❌ jq not found and no fallback script available"
+    exit 1
+  fi
+fi
+
+# ============================================================================
+# If specific job ID requested, show details and exit
+# ============================================================================
+
+if [[ -n "$SPECIFIC_ID" ]] && [[ -f "$JOBS_FILE" ]]; then
+  JOB=$(jq --arg id "$SPECIFIC_ID" '
+    .jobs[] | select(.id == $id or (.id | startswith($id)))
+  ' "$JOBS_FILE" 2>/dev/null)
+
+  if [[ -z "$JOB" ]]; then
+    echo "Job not found: $SPECIFIC_ID"
+    exit 1
+  fi
+
+  ID=$(echo "$JOB" | jq -r '.id')
+  TYPE=$(echo "$JOB" | jq -r '.type')
+  STATUS=$(echo "$JOB" | jq -r '.status')
+  STARTED=$(echo "$JOB" | jq -r '.startedAt')
+  UPDATED=$(echo "$JOB" | jq -r '.updatedAt')
+  CURRENT=$(echo "$JOB" | jq -r '.progress.current // 0')
+  TOTAL=$(echo "$JOB" | jq -r '.progress.total // 0')
+  ERROR=$(echo "$JOB" | jq -r '.error // empty')
+
+  if [[ "$TOTAL" -gt 0 ]]; then
+    PCT=$((CURRENT * 100 / TOTAL))
+  else
+    PCT=0
+  fi
+
+  echo ""
+  echo "📦 Job Details: $ID"
+  echo ""
+  echo "Type: $TYPE"
+  echo "Status: $STATUS"
+  echo "Started: $STARTED"
+  echo "Updated: $UPDATED"
+  echo "Progress: $CURRENT/$TOTAL ($PCT%)"
+
+  if [[ -n "$ERROR" ]]; then
+    echo "Error: $ERROR"
+  fi
+  exit 0
+fi
+
+# ============================================================================
+# SECTION 1: Current Work Status (from dashboard cache)
+# ============================================================================
+
+echo ""
+echo "📊 Current Work Status"
+echo "────────────────────────────────────────"
+
+# Rebuild cache if needed
+if [[ ! -f "$CACHE_FILE" ]] || ! jq -e '.' "$CACHE_FILE" >/dev/null 2>&1; then
+  if [[ -f "$SCRIPTS_DIR/rebuild-dashboard-cache.sh" ]]; then
+    bash "$SCRIPTS_DIR/rebuild-dashboard-cache.sh" --quiet 2>/dev/null || true
+  fi
+fi
+
+if [[ -f "$CACHE_FILE" ]] && jq -e '.' "$CACHE_FILE" >/dev/null 2>&1; then
+  # Show active increments
+  ACTIVE=$(jq -r '
+    .increments | to_entries[] |
+    select(.value.status == "active" or .value.status == "planning" or .value.status == "in-progress") |
+    "\(.key)|\(.value.status)|\(.value.tasks.completed)|\(.value.tasks.total)"
+  ' "$CACHE_FILE" 2>/dev/null)
+
+  if [[ -n "$ACTIVE" ]]; then
+    echo ""
+    echo "🔄 In Progress:"
+    while IFS='|' read -r id status completed total; do
+      [[ -z "$id" ]] && continue
+      if [[ "$total" -gt 0 ]]; then
+        pct=$((completed * 100 / total))
+      else
+        pct=0
+      fi
+      echo "   $id ($status)"
+      echo "      Tasks: $completed/$total ($pct%)"
+    done <<< "$ACTIVE"
+  fi
+
+  # Show paused increments
+  PAUSED_INC=$(jq -r '
+    .increments | to_entries[] |
+    select(.value.status == "paused") |
+    "\(.key)|\(.value.tasks.completed)|\(.value.tasks.total)"
+  ' "$CACHE_FILE" 2>/dev/null)
+
+  if [[ -n "$PAUSED_INC" ]]; then
+    echo ""
+    PAUSED_INC_COUNT=$(echo "$PAUSED_INC" | wc -l | tr -d ' ')
+    echo "⏸️  Paused Increments ($PAUSED_INC_COUNT):"
+    while IFS='|' read -r id completed total; do
+      [[ -z "$id" ]] && continue
+      if [[ "$total" -gt 0 ]]; then
+        pct=$((completed * 100 / total))
+      else
+        pct=0
+      fi
+      echo "   $id - $pct% done"
+    done <<< "$PAUSED_INC"
+  fi
+
+  # Show ready for review
+  READY=$(jq -r '
+    .increments | to_entries[] |
+    select(.value.status == "ready_for_review") |
+    .key
+  ' "$CACHE_FILE" 2>/dev/null)
+
+  if [[ -n "$READY" ]]; then
+    echo ""
+    echo "👀 Ready for Review:"
+    while read -r id; do
+      [[ -z "$id" ]] && continue
+      echo "   $id"
+    done <<< "$READY"
+  fi
+
+  # Summary stats
+  TOTAL_INC=$(jq '.summary.total // 0' "$CACHE_FILE")
+  ACTIVE_COUNT=$(jq '.summary.active // 0' "$CACHE_FILE")
+  COMPLETED_INC_COUNT=$(jq '.summary.completed // 0' "$CACHE_FILE")
+
+  if [[ -z "$ACTIVE" ]] && [[ -z "$PAUSED_INC" ]] && [[ -z "$READY" ]]; then
+    echo ""
+    echo "   No active increments."
+    if [[ "$COMPLETED_INC_COUNT" -gt 0 ]]; then
+      echo "   $COMPLETED_INC_COUNT increment(s) completed."
+    fi
+  fi
+
+  echo ""
+  echo "   Summary: $TOTAL_INC total | $ACTIVE_COUNT active | $COMPLETED_INC_COUNT completed"
+else
+  echo ""
+  echo "   No increment data available (cache not found)."
+  echo "   Run /specweave:status to rebuild cache."
+fi
+
+echo ""
+echo "────────────────────────────────────────"
+
+# ============================================================================
+# SECTION 2: Background Jobs
+# ============================================================================
+
+echo ""
+echo "⚙️  Background Jobs"
+echo "────────────────────────────────────────"
+
+# Check if jobs file exists and has jobs
+HAS_JOBS=false
+if [[ -f "$JOBS_FILE" ]] && jq -e '.jobs | length > 0' "$JOBS_FILE" >/dev/null 2>&1; then
+  HAS_JOBS=true
+fi
+
+if [[ "$HAS_JOBS" == "false" ]]; then
+  echo ""
+  echo "   No background jobs."
+  echo ""
+  echo "   Background jobs are created for:"
+  echo "   • Large issue imports (1000+ items from GitHub/JIRA/ADO)"
+  echo "   • Multi-repository cloning (umbrella setup)"
+  echo "   • Brownfield analysis (documentation gap detection)"
+  echo ""
+  echo "   Start jobs with:"
+  echo "   • /specweave:import-external  - Import from external tools"
+  echo "   • specweave init              - May spawn background jobs"
+else
+  echo ""
+
+  # Running jobs
+  RUNNING=$(jq -r '.jobs[] | select(.status == "running") | "\(.id)|\(.type)|\(.progress.current)|\(.progress.total)|\(.startedAt)"' "$JOBS_FILE" 2>/dev/null)
+
+  if [[ -n "$RUNNING" ]]; then
+    RUNNING_COUNT=$(echo "$RUNNING" | wc -l | tr -d ' ')
+    echo "🔄 Running ($RUNNING_COUNT):"
+    while IFS='|' read -r id type current total started; do
+      [[ -z "$id" ]] && continue
+      if [[ "$total" -gt 0 ]]; then
+        pct=$((current * 100 / total))
+      else
+        pct=0
+      fi
+      echo "   [${id:0:8}] $type"
+      echo "      Progress: $current/$total ($pct%)"
+    done <<< "$RUNNING"
+    echo ""
+  fi
+
+  # Paused jobs
+  PAUSED=$(jq -r '.jobs[] | select(.status == "paused") | "\(.id)|\(.type)|\(.progress.current)|\(.progress.total)"' "$JOBS_FILE" 2>/dev/null)
+
+  if [[ -n "$PAUSED" ]]; then
+    PAUSED_COUNT=$(echo "$PAUSED" | wc -l | tr -d ' ')
+    echo "⏸️  Paused ($PAUSED_COUNT):"
+    while IFS='|' read -r id type current total; do
+      [[ -z "$id" ]] && continue
+      if [[ "$total" -gt 0 ]]; then
+        pct=$((current * 100 / total))
+      else
+        pct=0
+      fi
+      echo "   [${id:0:8}] $type - $pct%"
+    done <<< "$PAUSED"
+    echo ""
+  fi
+
+  # Failed jobs
+  FAILED=$(jq -r '.jobs[] | select(.status == "failed") | "\(.id)|\(.type)|\(.error // "unknown")"' "$JOBS_FILE" 2>/dev/null)
+
+  if [[ -n "$FAILED" ]]; then
+    FAILED_COUNT=$(echo "$FAILED" | wc -l | tr -d ' ')
+    echo "❌ Failed ($FAILED_COUNT):"
+    while IFS='|' read -r id type error; do
+      [[ -z "$id" ]] && continue
+      echo "   [${id:0:8}] $type"
+      if [[ -n "$error" ]] && [[ "$error" != "null" ]]; then
+        echo "      Error: $error"
+      fi
+    done <<< "$FAILED"
+    echo ""
+  fi
+
+  # Completed jobs (only with --all)
+  if [[ "$SHOW_ALL" == "true" ]]; then
+    COMPLETED=$(jq -r '.jobs[] | select(.status == "completed") | "\(.id)|\(.type)|\(.progress.current)"' "$JOBS_FILE" 2>/dev/null)
+
+    if [[ -n "$COMPLETED" ]]; then
+      COMPLETED_COUNT=$(echo "$COMPLETED" | wc -l | tr -d ' ')
+      echo "✅ Completed ($COMPLETED_COUNT):"
+      COUNT=0
+      while IFS='|' read -r id type items; do
+        [[ -z "$id" ]] && continue
+        if [[ $COUNT -lt 10 ]]; then
+          echo "   [${id:0:8}] $type - $items items"
+          COUNT=$((COUNT + 1))
+        fi
+      done <<< "$COMPLETED"
+      if [[ $COMPLETED_COUNT -gt 10 ]]; then
+        echo "   ... and $((COMPLETED_COUNT - 10)) more"
+      fi
+      echo ""
+    fi
+  fi
+
+  # Summary if no active jobs
+  RUNNING_COUNT=$(jq '[.jobs[] | select(.status == "running")] | length' "$JOBS_FILE" 2>/dev/null || echo "0")
+  PAUSED_COUNT=$(jq '[.jobs[] | select(.status == "paused")] | length' "$JOBS_FILE" 2>/dev/null || echo "0")
+  FAILED_COUNT=$(jq '[.jobs[] | select(.status == "failed")] | length' "$JOBS_FILE" 2>/dev/null || echo "0")
+  COMPLETED_COUNT=$(jq '[.jobs[] | select(.status == "completed")] | length' "$JOBS_FILE" 2>/dev/null || echo "0")
+
+  if [[ "$RUNNING_COUNT" -eq 0 ]] && [[ "$PAUSED_COUNT" -eq 0 ]] && [[ "$FAILED_COUNT" -eq 0 ]]; then
+    if [[ "$COMPLETED_COUNT" -gt 0 ]]; then
+      echo "   No active jobs. $COMPLETED_COUNT completed (use --all to see)."
+    fi
+  fi
+fi
+
+# ============================================================================
+# SECTION 3: Commands Help
+# ============================================================================
+
+echo ""
+echo "────────────────────────────────────────"
+echo ""
+echo "💡 Commands:"
+echo "   /specweave:do               Execute current tasks"
+echo "   /specweave:progress         Show task progress details"
+echo "   /specweave:done <id>        Close increment"
+echo "   /specweave:jobs --id <id>   View background job details"
+echo "   /specweave:jobs --all       Show completed jobs"
+echo ""