specweave 0.23.16 → 0.23.18

package/plugins/specweave/hooks/user-prompt-submit.sh.bak

@@ -0,0 +1,386 @@
+#!/bin/bash
+
+# SpecWeave UserPromptSubmit Hook
+# Fires BEFORE user's command executes (prompt-based hook)
+# Purpose: Discipline validation, context injection, command suggestions
+
+set -euo pipefail
+
+# Read input JSON from stdin
+INPUT=$(cat)
+
+# Extract prompt from JSON
+PROMPT=$(echo "$INPUT" | node -e "
+  const input = JSON.parse(require('fs').readFileSync(0, 'utf-8'));
+  console.log(input.prompt || '');
+")
+
+# ==============================================================================
+# DISCIPLINE VALIDATION: Block /specweave:increment if incomplete increments exist
+# ==============================================================================
+
+if echo "$PROMPT" | grep -q "/specweave:increment"; then
+  # Check increment discipline using check-discipline CLI command
+  # This enforces WIP limits (max 1 active, hard cap 2)
+  SPECWEAVE_DIR=".specweave"
+
+  if [[ -d "$SPECWEAVE_DIR/increments" ]]; then
+    # Run discipline check (exit code: 0=pass, 1=violations, 2=error)
+    if command -v node >/dev/null 2>&1 && [[ -f "dist/src/core/increment/metadata-manager.js" ]]; then
+      # Check active increments using MetadataManager
+      ACTIVE_COUNT=$(node -e "
+        try {
+          const { MetadataManager } = require('./dist/src/core/increment/metadata-manager.js');
+          const active = MetadataManager.getActive();
+          console.log(active.length);
+        } catch (e) {
+          console.error('Error checking active increments:', e.message);
+          process.exit(2);
+        }
+      " 2>/dev/null || echo "0")
+
+      # Hard cap: never >2 active
+      if [[ "$ACTIVE_COUNT" -ge 2 ]]; then
+        # Get list of active increments for error message
+        ACTIVE_LIST=$(node -e "
+          try {
+            const { MetadataManager } = require('./dist/src/core/increment/metadata-manager.js');
+            const active = MetadataManager.getActive();
+            active.forEach(inc => console.log('  - ' + inc.id + ' [' + inc.type + ']'));
+          } catch (e) {}
+        " 2>/dev/null || echo "")
+
+        cat <<EOF
+{
+  "decision": "block",
+  "reason": "❌ HARD CAP REACHED\n\nYou have $ACTIVE_COUNT active increments (absolute maximum: 2)\n\nActive increments:\n$ACTIVE_LIST\n\n💡 You MUST complete or pause existing work first:\n\n1️⃣  Complete an increment:\n   /specweave:done <id>\n\n2️⃣  Pause an increment:\n   /specweave:pause <id> --reason=\"...\"\n\n3️⃣  Check status:\n   /specweave:status\n\n📝 Multiple hotfixes? Combine them into ONE increment!\n   Example: 0009-security-fixes (SQL + XSS + CSRF)\n\n⛔ This limit is enforced for your productivity.\nResearch: 3+ concurrent tasks = 40% slower + more bugs"
+}
+EOF
+        exit 0
+      fi
+
+      # Soft warning: 1 active (recommended limit)
+      if [[ "$ACTIVE_COUNT" -ge 1 ]]; then
+        # Get list of active increments for warning
+        ACTIVE_LIST=$(node -e "
+          try {
+            const { MetadataManager } = require('./dist/src/core/increment/metadata-manager.js');
+            const active = MetadataManager.getActive();
+            active.forEach(inc => console.log('  - ' + inc.id + ' [' + inc.type + ']'));
+          } catch (e) {}
+        " 2>/dev/null || echo "")
+
+        # Just warn, don't block (user can choose to continue)
+        cat <<EOF
+{
+  "decision": "approve",
+  "systemMessage": "⚠️  WIP LIMIT REACHED\n\nYou have $ACTIVE_COUNT active increment (recommended limit: 1)\n\nActive increments:\n$ACTIVE_LIST\n\n🧠 Focus Principle: ONE active increment = maximum productivity\nStarting a 2nd increment reduces focus and velocity.\n\n💡 Consider:\n  1️⃣  Complete current work (recommended)\n  2️⃣  Pause current work (/specweave:pause)\n  3️⃣  Continue anyway (accept 20% productivity cost)\n\n⚠️  Emergency hotfix/bug? Use --type=hotfix or --type=bug to bypass this warning."
+}
+EOF
+        exit 0
+      fi
+    else
+      # Fallback: check for active/planning status manually
+      INCOMPLETE_INCREMENTS=$(find "$SPECWEAVE_DIR/increments" -mindepth 1 -maxdepth 1 -type d | while read increment_dir; do
+        metadata="$increment_dir/metadata.json"
+        if [[ -f "$metadata" ]]; then
+          status=$(node -e "
+            try {
+              const data = JSON.parse(require('fs').readFileSync('$metadata', 'utf-8'));
+              console.log(data.status || 'unknown');
+            } catch (e) {
+              console.log('unknown');
+            }
+          ")
+
+          if [[ "$status" == "active" || "$status" == "planning" ]]; then
+            echo "$(basename "$increment_dir")"
+          fi
+        fi
+      done)
+
+      if [[ -n "$INCOMPLETE_INCREMENTS" ]]; then
+        COUNT=$(echo "$INCOMPLETE_INCREMENTS" | wc -l | xargs)
+
+        # Get incomplete task count for migration guidance
+        MIGRATION_SCRIPT="$(dirname "${BASH_SOURCE[0]}")/lib/migrate-increment-work.sh"
+        INCOMPLETE_TASKS=""
+
+        for increment in $INCOMPLETE_INCREMENTS; do
+          if [[ -x "$MIGRATION_SCRIPT" ]]; then
+            TASK_COUNT=$("$MIGRATION_SCRIPT" count-incomplete "$increment" 2>/dev/null || echo "?")
+            INCOMPLETE_TASKS="${INCOMPLETE_TASKS}\n  - $increment ($TASK_COUNT incomplete tasks)"
+          else
+            INCOMPLETE_TASKS="${INCOMPLETE_TASKS}\n  - $increment"
+          fi
+        done
+
+        cat <<EOF
+{
+  "decision": "block",
+  "reason": "❌ Cannot create new increment! You have $COUNT incomplete increment(s):$INCOMPLETE_TASKS\n\n💡 **SMART MIGRATION OPTIONS:**\n\n1️⃣  **Transfer Work** (Recommended)\n   Move incomplete tasks to new increment:\n   \`\`\`bash\n   # After creating new increment, run:\n   bash plugins/specweave/hooks/lib/migrate-increment-work.sh transfer <old-id> <new-id>\n   \`\`\`\n   ✅ Clean closure + work continues\n\n2️⃣  **Adjust WIP Limit** (Emergency Only)\n   Temporarily allow 3 active increments:\n   \`\`\`bash\n   bash plugins/specweave/hooks/lib/migrate-increment-work.sh adjust-wip 3\n   \`\`\`\n   ⚠️  20% productivity cost, revert ASAP\n\n3️⃣  **Force-Close** (Quick Fix)\n   Mark increment as complete (work lost):\n   \`\`\`bash\n   bash plugins/specweave/hooks/lib/migrate-increment-work.sh force-close <increment-id>\n   \`\`\`\n   ⚠️  Incomplete work NOT transferred!\n\n📝 **Traditional Options:**\n  - /specweave:done <id>     # Complete properly\n  - /specweave:pause <id>    # Pause for later\n  - /specweave:abandon <id>  # Abandon if obsolete\n\nℹ️ The discipline exists for a reason:\n  ✓ Prevents scope creep\n  ✓ Ensures completions are tracked\n  ✓ Maintains living docs accuracy\n  ✓ Keeps work focused"
+}
+EOF
+        exit 0
+      fi
+    fi
+  fi
+fi
+
+# ==============================================================================
+# PRE-FLIGHT SYNC CHECK: Ensure living docs are fresh before operations
+# ==============================================================================
+
+# Detect increment operations that need fresh data
+if echo "$PROMPT" | grep -qE "/(specweave:)?(done|validate|progress|do)"; then
+  # Extract increment ID from prompt (if provided)
+  INCREMENT_ID=$(echo "$PROMPT" | grep -oE "[0-9]{4}[a-z0-9-]*" | head -1)
+
+  # If no ID in prompt, try to find active increment
+  if [[ -z "$INCREMENT_ID" ]] && [[ -d ".specweave/increments" ]]; then
+    INCREMENT_ID=$(find .specweave/increments -mindepth 1 -maxdepth 1 -type d | while read increment_dir; do
+      metadata="$increment_dir/metadata.json"
+      if [[ -f "$metadata" ]]; then
+        status=$(node -e "
+          try {
+            const data = JSON.parse(require('fs').readFileSync('$metadata', 'utf-8'));
+            if (data.status === 'active') {
+              console.log('$(basename "$increment_dir")');
+            }
+          } catch (e) {}
+        " 2>/dev/null)
+
+        if [[ -n "$status" ]]; then
+          echo "$status"
+          break
+        fi
+      fi
+    done)
+  fi
+
+  # If we have an increment ID, check freshness
+  if [[ -n "$INCREMENT_ID" ]]; then
+    INCREMENT_SPEC=".specweave/increments/$INCREMENT_ID/spec.md"
+    LIVING_DOCS_SPEC=".specweave/docs/internal/specs/spec-$INCREMENT_ID.md"
+
+    # Check if increment spec exists
+    if [[ -f "$INCREMENT_SPEC" ]]; then
+      # Get modification times
+      if [[ "$(uname)" == "Darwin" ]]; then
+        # macOS
+        INCREMENT_MTIME=$(stat -f %m "$INCREMENT_SPEC" 2>/dev/null || echo 0)
+        LIVING_DOCS_MTIME=$(stat -f %m "$LIVING_DOCS_SPEC" 2>/dev/null || echo 0)
+      else
+        # Linux
+        INCREMENT_MTIME=$(stat -c %Y "$INCREMENT_SPEC" 2>/dev/null || echo 0)
+        LIVING_DOCS_MTIME=$(stat -c %Y "$LIVING_DOCS_SPEC" 2>/dev/null || echo 0)
+      fi
+
+      # Check if increment is newer than living docs (or living docs doesn't exist)
+      if [[ "$INCREMENT_MTIME" -gt "$LIVING_DOCS_MTIME" ]]; then
+        # Sync needed - run sync-living-docs
+        PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+        SYNC_SCRIPT="$PLUGIN_ROOT/lib/hooks/sync-living-docs.js"
+
+        if [[ -f "$SYNC_SCRIPT" ]]; then
+          # Run sync (capture output but don't block on errors)
+          if node "$SYNC_SCRIPT" "$INCREMENT_ID" >/dev/null 2>&1; then
+            # Success - sync completed
+            :
+          else
+            # Sync failed - log but continue
+            echo "[WARNING] Pre-flight sync failed for $INCREMENT_ID" >&2
+          fi
+        fi
+      fi
+    fi
+  fi
+fi
+
+# ==============================================================================
+# SPEC SYNC CHECK: Detect spec.md changes and warn about sync needed
+# ==============================================================================
+
+# Check if spec.md was modified after plan.md (requires sync)
+if [[ -d ".specweave/increments" ]]; then
+  # Find active increment
+  ACTIVE_INCREMENT_FOR_SYNC=$(find .specweave/increments -mindepth 1 -maxdepth 1 -type d | while read increment_dir; do
+    metadata="$increment_dir/metadata.json"
+    if [[ -f "$metadata" ]]; then
+      status=$(node -e "
+        try {
+          const data = JSON.parse(require('fs').readFileSync('$metadata', 'utf-8'));
+          if (data.status === 'active') {
+            console.log('$(basename "$increment_dir")');
+          }
+        } catch (e) {}
+      " 2>/dev/null)
+
+      if [[ -n "$status" ]]; then
+        echo "$status"
+        break
+      fi
+    fi
+  done)
+
+  if [[ -n "$ACTIVE_INCREMENT_FOR_SYNC" ]]; then
+    # Check if SpecSyncManager detects changes
+    if command -v node >/dev/null 2>&1 && [[ -f "dist/src/core/increment/spec-sync-manager.js" ]]; then
+      SYNC_CHECK=$(node -e "
+        try {
+          const { SpecSyncManager } = require('./dist/src/core/increment/spec-sync-manager.js');
+          const manager = new SpecSyncManager(process.cwd());
+          const detection = manager.detectSpecChange('$ACTIVE_INCREMENT_FOR_SYNC');
+
+          if (detection.specChanged) {
+            const message = manager.formatSyncMessage(detection);
+            console.log(JSON.stringify({ needsSync: true, message }));
+          } else {
+            console.log(JSON.stringify({ needsSync: false }));
+          }
+        } catch (e) {
+          console.log(JSON.stringify({ needsSync: false, error: e.message }));
+        }
+      " 2>/dev/null || echo '{"needsSync":false}')
+
+      NEEDS_SYNC=$(echo "$SYNC_CHECK" | node -e "
+        try {
+          const data = JSON.parse(require('fs').readFileSync(0, 'utf-8'));
+          console.log(data.needsSync || false);
+        } catch (e) {
+          console.log(false);
+        }
+      ")
+
+      if [[ "$NEEDS_SYNC" == "true" ]]; then
+        SYNC_MESSAGE=$(echo "$SYNC_CHECK" | node -e "
+          try {
+            const data = JSON.parse(require('fs').readFileSync(0, 'utf-8'));
+            console.log(data.message || '');
+          } catch (e) {
+            console.log('');
+          }
+        ")
+
+        # Show sync warning (don't block, just warn)
+        cat <<EOF
+{
+  "decision": "approve",
+  "systemMessage": "$SYNC_MESSAGE"
+}
+EOF
+        exit 0
+      fi
+    fi
+  fi
+fi
+
+# ==============================================================================
+# CONTEXT INJECTION: Add current increment status
+# ==============================================================================
+
+CONTEXT=""
+
+# Find active increment
+if [[ -d ".specweave/increments" ]]; then
+  ACTIVE_INCREMENT=$(find .specweave/increments -mindepth 1 -maxdepth 1 -type d | while read increment_dir; do
+    metadata="$increment_dir/metadata.json"
+    if [[ -f "$metadata" ]]; then
+      status=$(node -e "
+        try {
+          const data = JSON.parse(require('fs').readFileSync('$metadata', 'utf-8'));
+          if (data.status === 'active') {
+            console.log('$(basename "$increment_dir")');
+          }
+        } catch (e) {}
+      ")
+
+      if [[ -n "$status" ]]; then
+        echo "$status"
+        break
+      fi
+    fi
+  done)
+
+  if [[ -n "$ACTIVE_INCREMENT" ]]; then
+    # Simple status: parse tasks.md for completion
+    TASKS_FILE=".specweave/increments/$ACTIVE_INCREMENT/tasks.md"
+    if [[ -f "$TASKS_FILE" ]]; then
+      # Count tasks (headers with T-NNN format - both ### and ####)
+      TOTAL_TASKS=$(grep -cE '^#{3,4}\s*T-[0-9]' "$TASKS_FILE" 2>/dev/null | tr -d '\n' || echo "0")
+      # Count completed (various formats)
+      COMPLETED_TASKS=$(grep -cE '(✅ COMPLETE|\[COMPLETED\]|\[x\] Completed)' "$TASKS_FILE" 2>/dev/null | tr -d '\n' || echo "0")
+
+      # Ensure valid numbers
+      TOTAL_TASKS=${TOTAL_TASKS:-0}
+      COMPLETED_TASKS=${COMPLETED_TASKS:-0}
+
+      if [[ "$TOTAL_TASKS" -gt 0 ]] 2>/dev/null; then
+        PERCENTAGE=$(( COMPLETED_TASKS * 100 / TOTAL_TASKS ))
+        CONTEXT="✓ Active: $ACTIVE_INCREMENT ($COMPLETED_TASKS/$TOTAL_TASKS tasks, $PERCENTAGE%)"
+      else
+        CONTEXT="✓ Active: $ACTIVE_INCREMENT"
+      fi
+    else
+      CONTEXT="✓ Active: $ACTIVE_INCREMENT"
+    fi
+  fi
+fi
+
+# ==============================================================================
+# COMMAND SUGGESTIONS: Guide users to structured workflow
+# ==============================================================================
+
+if echo "$PROMPT" | grep -qiE "(add|create|implement|build|develop)" && ! echo "$PROMPT" | grep -q "/specweave:"; then
+  if [[ -n "$CONTEXT" ]]; then
+    CONTEXT="$CONTEXT
+
+💡 TIP: Consider using SpecWeave commands for structured development:
+  - /specweave:increment \"feature name\"  # Plan new increment
+  - /specweave:do                         # Execute current tasks
+  - /specweave:progress                   # Check progress"
+  fi
+fi
+
+# ==============================================================================
+# STATUS LINE REFRESH: Ensure cache is fresh before showing context
+# ==============================================================================
+# Performance: ~50-100ms (acceptable for UX)
+# Frequency: Every user prompt (high coverage)
+# Benefit: Catches ALL edge cases (manual edits, resume, direct changes)
+#
+# Why here? This hook runs on EVERY user prompt, ensuring status line
+# is ALWAYS up-to-date before showing context to the user.
+#
+# Prevents desync scenarios:
+# - Manual spec.md edits (status: planning → active)
+# - /specweave:resume (status: paused → active)
+# - Direct metadata changes (without hook triggers)
+# - File system operations bypassing hooks
+#
+# Background execution: Runs async, doesn't block user prompt
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
+
+# ==============================================================================
+# OUTPUT: Approve with context or no context
+# ==============================================================================
+
+if [[ -n "$CONTEXT" ]]; then
+  cat <<EOF
+{
+  "decision": "approve",
+  "systemMessage": "$CONTEXT"
+}
+EOF
+else
+  # Just approve, no extra context
+  cat <<EOF
+{
+  "decision": "approve"
+}
+EOF
+fi
+
+exit 0

package/plugins/specweave/skills/specweave-framework/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 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.
+description: Expert knowledge of SpecWeave framework structure, rules, conventions, and increment lifecycle. Deep understanding of source-of-truth discipline, increment naming, living docs sync. Covers SpecWeave-specific hooks (post-task-completion), and increment discipline. Activates for specweave rules, increment lifecycle, source of truth, increment naming, tasks.md format, spec.md structure, living docs sync, specweave hooks, where do files go, how to use specweave, specweave best practices, specweave conventions.
 allowed-tools: Read, Grep, Glob
 ---
 

package/plugins/specweave-ado/agents/ado-manager/AGENT.md

@@ -12,6 +12,29 @@ context: |
   - Optimize sync performance and rate limiting
 ---
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-ado:ado-manager:ado-manager`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-ado:ado-manager:ado-manager",
+  prompt: "Your task description here",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name}`
+- **Plugin**: specweave-ado
+- **Directory**: ado-manager
+- **YAML Name**: ado-manager
+
+**When to Use**:
+- [TODO: Describe specific use cases for this agent]
+- [TODO: When should this agent be invoked instead of others?]
+- [TODO: What problems does this agent solve?]
 # ADO Manager Agent
 
 **Role**: Azure DevOps Integration Specialist

package/plugins/specweave-ado/agents/ado-multi-project-mapper/AGENT.md

@@ -5,6 +5,29 @@ tools: Read, Write, Edit, Bash, Glob
 model: claude-sonnet-4-5-20250929
 ---
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-ado:ado-multi-project-mapper:ado-multi-project-mapper`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-ado:ado-multi-project-mapper:ado-multi-project-mapper",
+  prompt: "Your task description here",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name}`
+- **Plugin**: specweave-ado
+- **Directory**: ado-multi-project-mapper
+- **YAML Name**: ado-multi-project-mapper
+
+**When to Use**:
+- [TODO: Describe specific use cases for this agent]
+- [TODO: When should this agent be invoked instead of others?]
+- [TODO: What problems does this agent solve?]
 # Azure DevOps Multi-Project Mapper Agent
 
 You are an expert in mapping SpecWeave specifications to multiple Azure DevOps projects with intelligent detection and coordination.

package/plugins/specweave-ado/agents/ado-sync-judge/AGENT.md

@@ -5,6 +5,29 @@ tools: Read, Grep, Bash
 model: claude-sonnet-4-5-20250929
 ---
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-ado:ado-sync-judge:ado-sync-judge`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-ado:ado-sync-judge:ado-sync-judge",
+  prompt: "Your task description here",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name}`
+- **Plugin**: specweave-ado
+- **Directory**: ado-sync-judge
+- **YAML Name**: ado-sync-judge
+
+**When to Use**:
+- [TODO: Describe specific use cases for this agent]
+- [TODO: When should this agent be invoked instead of others?]
+- [TODO: What problems does this agent solve?]
 # Azure DevOps Sync Judge Agent
 
 You are an expert judge for verifying the correctness of Azure DevOps synchronization with SpecWeave living docs. Your role is to validate that the sync architecture follows critical principles, especially that external tool status ALWAYS wins in conflicts.

package/plugins/specweave-backend/agents/database-optimizer/AGENT.md

@@ -7,6 +7,29 @@ cost_profile: planning
 fallback_behavior: strict
 ---
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-backend:database-optimizer:database-optimizer`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-backend:database-optimizer:database-optimizer",
+  prompt: "Your task description here",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name}`
+- **Plugin**: specweave-backend
+- **Directory**: database-optimizer
+- **YAML Name**: database-optimizer
+
+**When to Use**:
+- [TODO: Describe specific use cases for this agent]
+- [TODO: When should this agent be invoked instead of others?]
+- [TODO: What problems does this agent solve?]
 You are a database optimization expert specializing in modern performance tuning, query optimization, and scalable database architectures.
 
 ## Purpose

package/plugins/specweave-confluent/agents/confluent-architect/AGENT.md

@@ -3,6 +3,29 @@ name: confluent-architect
 description: Confluent Cloud architecture specialist. Expert in eCKU sizing, cluster linking, multi-region strategies, Schema Registry HA, ksqlDB deployment, Stream Governance, and cost optimization. Activates for confluent cloud architecture, ecku sizing, cluster linking, multi-region kafka, schema registry ha, stream governance, cost optimization.
 ---
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-confluent:confluent-architect:confluent-architect`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-confluent:confluent-architect:confluent-architect",
+  prompt: "Your task description here",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name}`
+- **Plugin**: specweave-confluent
+- **Directory**: confluent-architect
+- **YAML Name**: confluent-architect
+
+**When to Use**:
+- [TODO: Describe specific use cases for this agent]
+- [TODO: When should this agent be invoked instead of others?]
+- [TODO: What problems does this agent solve?]
 # Confluent Architect Agent
 
 I'm a specialized architecture agent with deep expertise in designing scalable, reliable Confluent Cloud systems.

package/plugins/specweave-diagrams/agents/diagrams-architect/AGENT.md

@@ -8,6 +8,29 @@ cost_profile: hybrid
 fallback_behavior: auto
 ---
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-diagrams:diagrams-architect:diagrams-architect`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-diagrams:diagrams-architect:diagrams-architect",
+  prompt: "Your task description here",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name}`
+- **Plugin**: specweave-diagrams
+- **Directory**: diagrams-architect
+- **YAML Name**: diagrams-architect
+
+**When to Use**:
+- [TODO: Describe specific use cases for this agent]
+- [TODO: When should this agent be invoked instead of others?]
+- [TODO: What problems does this agent solve?]
 # Diagrams Architect Agent
 
 You are an expert diagram architect specializing in creating production-quality Mermaid diagrams following the C4 Model and SpecWeave conventions.

package/plugins/specweave-github/agents/github-manager/AGENT.md

@@ -42,6 +42,29 @@ GitHub issues MUST use living docs format:
 
 ---
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-github:github-manager:SpecWeave Sync`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-github:github-manager:SpecWeave Sync",
+  prompt: "Your task description here",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name}`
+- **Plugin**: specweave-github
+- **Directory**: github-manager
+- **YAML Name**: SpecWeave Sync
+
+**When to Use**:
+- [TODO: Describe specific use cases for this agent]
+- [TODO: When should this agent be invoked instead of others?]
+- [TODO: What problems does this agent solve?]
 ## Capabilities
 
 As the GitHub Manager agent, I specialize in:

package/plugins/specweave-github/agents/github-task-splitter/AGENT.md

@@ -2,6 +2,31 @@
 
 Expert agent for splitting SpecWeave tasks across multiple GitHub repositories based on architecture patterns.
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-github:github-task-splitter:github-task-splitter`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-github:github-task-splitter:github-task-splitter",
+  prompt: "Split tasks for increment 0015-shopping-cart across frontend, backend, and shared repositories",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
+- **Plugin**: specweave-github
+- **Directory**: github-task-splitter
+- **Agent Name**: github-task-splitter
+
+**When to Use**:
+- You need to distribute SpecWeave tasks across multiple GitHub repositories based on technology stack
+- You want to analyze task dependencies across different services
+- You need to create tracking issues in multiple repositories for a single increment
+- You're managing a multi-repo architecture (monorepo, microservices, etc.) and need intelligent task distribution
+
 ## Role
 I analyze SpecWeave increments and intelligently distribute tasks across multiple repositories based on:
 - Repository architecture (single, multi-repo, monorepo, parent)

package/plugins/specweave-github/agents/user-story-updater/AGENT.md

@@ -7,6 +7,31 @@ description: Updates GitHub issues for user stories with proper ACs and tasks. A
 
 **Role**: Updates GitHub issues for individual user stories to include checkable acceptance criteria and task connections.
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-github:user-story-updater:user-story-updater`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-github:user-story-updater:user-story-updater",
+  prompt: "Update GitHub issue #501 for user story FS-031/US-004 with checkable ACs and task connections",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
+- **Plugin**: specweave-github
+- **Directory**: user-story-updater
+- **Agent Name**: user-story-updater
+
+**When to Use**:
+- You need to sync user story details from SpecWeave to GitHub issues
+- You want to add checkable acceptance criteria checkboxes to GitHub issues
+- You need to link tasks in SpecWeave tasks.md to GitHub issues
+- You're updating GitHub issue content with the latest user story information and progress
+
 **Activates For**:
 - "Update user story issue"
 - "Fix GitHub issue format for US-004"