specweave 0.23.14 → 0.23.18

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"

package/plugins/specweave-github/hooks/.specweave/logs/hooks-debug.log

@@ -0,0 +1,16 @@
+[Sat Nov 22 02:20:23 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Sat Nov 22 02:20:23 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Sat Nov 22 02:20:26 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Sat Nov 22 02:20:26 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Sat Nov 22 02:20:26 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Sat Nov 22 02:20:26 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Sat Nov 22 02:20:28 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Sat Nov 22 02:20:28 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Sat Nov 22 02:20:31 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Sat Nov 22 02:20:31 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Sat Nov 22 02:20:31 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Sat Nov 22 02:20:31 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Sat Nov 22 02:20:33 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Sat Nov 22 02:20:33 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Sat Nov 22 02:20:36 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Sat Nov 22 02:20:36 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Projects/github/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync

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

@@ -26,6 +26,53 @@ if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
   exit 0
 fi
 
+# ============================================================================
+# CIRCUIT BREAKER & FILE LOCKING
+# ============================================================================
+
+# CIRCUIT BREAKER: Auto-disable after consecutive failures
+CIRCUIT_BREAKER_FILE=".specweave/state/.hook-circuit-breaker-github"
+CIRCUIT_BREAKER_THRESHOLD=3
+
+mkdir -p ".specweave/state" 2>/dev/null || true
+
+if [[ -f "$CIRCUIT_BREAKER_FILE" ]]; then
+  FAILURE_COUNT=$(cat "$CIRCUIT_BREAKER_FILE" 2>/dev/null || echo 0)
+  if (( FAILURE_COUNT >= CIRCUIT_BREAKER_THRESHOLD )); then
+    # Circuit breaker is OPEN - hooks are disabled
+    exit 0
+  fi
+fi
+
+# FILE LOCK: Only allow 1 GitHub sync hook at a time
+LOCK_FILE=".specweave/state/.hook-github-sync.lock"
+LOCK_TIMEOUT=15  # seconds (GitHub sync can take longer)
+
+LOCK_ACQUIRED=false
+for i in {1..15}; do
+  if mkdir "$LOCK_FILE" 2>/dev/null; then
+    LOCK_ACQUIRED=true
+    trap 'rmdir "$LOCK_FILE" 2>/dev/null || true' EXIT
+    break
+  fi
+
+  # Check for stale lock
+  if [[ -d "$LOCK_FILE" ]]; then
+    LOCK_AGE=$(($(date +%s) - $(stat -f "%m" "$LOCK_FILE" 2>/dev/null || echo 0)))
+    if (( LOCK_AGE > LOCK_TIMEOUT )); then
+      rmdir "$LOCK_FILE" 2>/dev/null || true
+      continue
+    fi
+  fi
+
+  sleep 0.2
+done
+
+if [[ "$LOCK_ACQUIRED" == "false" ]]; then
+  # Another instance is running, skip
+  exit 0
+fi
+
 # ============================================================================
 # PROJECT ROOT DETECTION
 # ============================================================================
@@ -252,6 +299,12 @@ else
   echo "[$(date)] [GitHub] ℹ️  Epic sync disabled (sync at User Story level only)" >> "$DEBUG_LOG" 2>/dev/null || true
 fi
 
+# ============================================================================
+# CIRCUIT BREAKER UPDATE
+# ============================================================================
+# Reset circuit breaker on successful completion (all errors are caught above)
+echo "0" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true
+
 # ============================================================================
 # OUTPUT TO CLAUDE
 # ============================================================================

package/plugins/specweave-github/lib/github-spec-content-sync.js

@@ -85,6 +85,17 @@ async function syncSpecContentToGitHub(options) {
 async function createGitHubIssue(client, spec, options) {
   const { specPath, dryRun, verbose } = options;
   try {
+    const permissions = await loadSyncPermissions(specPath);
+    if (!permissions.canCreate) {
+      if (verbose) {
+        console.log("   \u26A0\uFE0F  Skipping create - canUpsertInternalItems is disabled in config");
+      }
+      return {
+        success: false,
+        action: "skipped",
+        error: "canUpsertInternalItems is disabled in .specweave/config.json"
+      };
+    }
     const titleId = spec.project === "_features" ? spec.identifier.display : spec.identifier.compact;
     const title = `[${titleId}] ${spec.title}`;
     const body = buildExternalDescription(spec);
@@ -141,6 +152,17 @@ ${body}`);
 async function updateGitHubIssue(client, spec, issueNumber, options) {
   const { specPath, dryRun, verbose } = options;
   try {
+    const permissions = await loadSyncPermissions(specPath);
+    if (!permissions.canUpdate) {
+      if (verbose) {
+        console.log("   \u26A0\uFE0F  Skipping update - canUpdateExternalItems is disabled in config");
+      }
+      return {
+        success: false,
+        action: "skipped",
+        error: "canUpdateExternalItems is disabled in .specweave/config.json"
+      };
+    }
     const issue = await client.getIssue(issueNumber);
     if (verbose) {
       console.log(`
@@ -234,6 +256,33 @@ function countUserStoriesInBody(body) {
   const matches = body.match(/###\s+US-\d+:/g);
   return matches ? matches.length : 0;
 }
+async function loadSyncPermissions(specPath) {
+  try {
+    let currentDir = path.dirname(specPath);
+    let configPath = path.join(currentDir, ".specweave", "config.json");
+    while (!await fs.access(configPath).then(() => true).catch(() => false)) {
+      const parentDir = path.dirname(currentDir);
+      if (parentDir === currentDir) {
+        return { canCreate: true, canUpdate: true, canUpdateStatus: true };
+      }
+      currentDir = parentDir;
+      configPath = path.join(currentDir, ".specweave", "config.json");
+    }
+    const configContent = await fs.readFile(configPath, "utf-8");
+    const config = JSON.parse(configContent);
+    const settings = config.sync?.settings || {};
+    return {
+      canCreate: settings.canUpsertInternalItems !== false,
+      // Default: true
+      canUpdate: settings.canUpdateExternalItems !== false,
+      // Default: true
+      canUpdateStatus: settings.canUpdateStatus !== false
+      // Default: true
+    };
+  } catch {
+    return { canCreate: true, canUpdate: true, canUpdateStatus: true };
+  }
+}
 async function isContentSyncEnabled(projectRoot) {
   try {
     const configPath = path.join(projectRoot, ".specweave", "config.json");

package/plugins/specweave-github/lib/github-spec-content-sync.ts

@@ -153,6 +153,19 @@ async function createGitHubIssue(
   const { specPath, dryRun, verbose } = options;
 
   try {
+    // Check permission: canUpsertInternalItems (CREATE permission)
+    const permissions = await loadSyncPermissions(specPath);
+    if (!permissions.canCreate) {
+      if (verbose) {
+        console.log('   ⚠️  Skipping create - canUpsertInternalItems is disabled in config');
+      }
+      return {
+        success: false,
+        action: 'skipped',
+        error: 'canUpsertInternalItems is disabled in .specweave/config.json',
+      };
+    }
+
     // Build issue title and body using compact format
     // Examples: [BE-JIRA-AUTH-123] User Authentication, [FE-user-login-ui] Login UI
     // Use display ID for cleaner titles (FS-043 instead of _F-FS-043)
@@ -234,6 +247,19 @@ async function updateGitHubIssue(
   const { specPath, dryRun, verbose } = options;
 
   try {
+    // Check permission: canUpdateExternalItems (UPDATE permission)
+    const permissions = await loadSyncPermissions(specPath);
+    if (!permissions.canUpdate) {
+      if (verbose) {
+        console.log('   ⚠️  Skipping update - canUpdateExternalItems is disabled in config');
+      }
+      return {
+        success: false,
+        action: 'skipped',
+        error: 'canUpdateExternalItems is disabled in .specweave/config.json',
+      };
+    }
+
     // Get current issue
     const issue = await client.getIssue(issueNumber);
 
@@ -383,6 +409,47 @@ function countUserStoriesInBody(body: string): number {
   return matches ? matches.length : 0;
 }
 
+/**
+ * Load sync permissions from config
+ */
+async function loadSyncPermissions(specPath: string): Promise<{
+  canCreate: boolean;
+  canUpdate: boolean;
+  canUpdateStatus: boolean;
+}> {
+  try {
+    // Find project root
+    let currentDir = path.dirname(specPath);
+    let configPath = path.join(currentDir, '.specweave', 'config.json');
+
+    // Search upward for .specweave/config.json
+    while (!await fs.access(configPath).then(() => true).catch(() => false)) {
+      const parentDir = path.dirname(currentDir);
+      if (parentDir === currentDir) {
+        // Default: all enabled
+        return { canCreate: true, canUpdate: true, canUpdateStatus: true };
+      }
+      currentDir = parentDir;
+      configPath = path.join(currentDir, '.specweave', 'config.json');
+    }
+
+    // Read config
+    const configContent = await fs.readFile(configPath, 'utf-8');
+    const config = JSON.parse(configContent);
+
+    const settings = config.sync?.settings || {};
+
+    return {
+      canCreate: settings.canUpsertInternalItems !== false,  // Default: true
+      canUpdate: settings.canUpdateExternalItems !== false,  // Default: true
+      canUpdateStatus: settings.canUpdateStatus !== false    // Default: true
+    };
+  } catch {
+    // Default: all enabled
+    return { canCreate: true, canUpdate: true, canUpdateStatus: true };
+  }
+}
+
 /**
  * Check if spec content sync is enabled
  */

package/plugins/specweave-infrastructure/agents/devops/AGENT.md

@@ -10,6 +10,32 @@ fallback_behavior: flexible
 
 # DevOps Agent - Infrastructure & Deployment Expert
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-infrastructure:devops:devops`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-infrastructure:devops:devops",
+  prompt: "Deploy application to AWS ECS Fargate with Terraform and configure CI/CD pipeline with GitHub Actions",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
+- **Plugin**: specweave-infrastructure
+- **Directory**: devops
+- **Agent Name**: devops
+
+**When to Use**:
+- You need to design and implement cloud infrastructure (AWS, Azure, GCP)
+- You want to create Infrastructure as Code with Terraform or CloudFormation
+- You need to set up CI/CD pipelines for automated deployment
+- You're deploying containerized applications to Kubernetes or Docker Compose
+- You need to implement monitoring, logging, and observability infrastructure
+
 ## Purpose
 
 The devops-agent is SpecWeave's **infrastructure and deployment specialist** that:

package/plugins/specweave-infrastructure/agents/network-engineer/AGENT.md

@@ -9,6 +9,32 @@ fallback_behavior: flexible
 
 You are a network engineer specializing in modern cloud networking, security, and performance optimization.
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-infrastructure:network-engineer:network-engineer`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-infrastructure:network-engineer:network-engineer",
+  prompt: "Design secure multi-cloud network architecture with zero-trust connectivity and service mesh",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
+- **Plugin**: specweave-infrastructure
+- **Directory**: network-engineer
+- **Agent Name**: network-engineer
+
+**When to Use**:
+- You need to design cloud networking architectures (VPCs, subnets, routing)
+- You want to implement zero-trust security and network policies
+- You need to configure load balancing, DNS, and SSL/TLS
+- You're troubleshooting connectivity issues or performance problems
+- You need to set up service mesh or advanced networking topologies
+
 ## Purpose
 Expert network engineer with comprehensive knowledge of cloud networking, modern protocols, security architectures, and performance optimization. Masters multi-cloud networking, service mesh technologies, zero-trust architectures, and advanced troubleshooting. Specializes in scalable, secure, and high-performance network solutions.
 

package/plugins/specweave-infrastructure/agents/observability-engineer/AGENT.md

@@ -9,6 +9,32 @@ fallback_behavior: flexible
 
 You are an observability engineer specializing in production-grade monitoring, logging, tracing, and reliability systems for enterprise-scale applications.
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-infrastructure:observability-engineer:observability-engineer`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-infrastructure:observability-engineer:observability-engineer",
+  prompt: "Design comprehensive monitoring stack with Prometheus, Grafana, and OpenTelemetry for microservices with SLI/SLO tracking",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
+- **Plugin**: specweave-infrastructure
+- **Directory**: observability-engineer
+- **Agent Name**: observability-engineer
+
+**When to Use**:
+- You need to design monitoring and observability architecture
+- You want to set up distributed tracing for microservices
+- You need to configure alerting and SLO tracking
+- You're troubleshooting performance issues or anomalies
+- You want to implement comprehensive log aggregation and analysis
+
 ## Purpose
 Expert observability engineer specializing in comprehensive monitoring strategies, distributed tracing, and production reliability systems. Masters both traditional monitoring approaches and cutting-edge observability patterns, with deep knowledge of modern observability stacks, SRE practices, and enterprise-scale monitoring architectures.
 

package/plugins/specweave-infrastructure/agents/performance-engineer/AGENT.md

@@ -9,6 +9,32 @@ fallback_behavior: flexible
 
 You are a performance engineer specializing in modern application optimization, observability, and scalable system performance.
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-infrastructure:performance-engineer:performance-engineer`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-infrastructure:performance-engineer:performance-engineer",
+  prompt: "Analyze and optimize API performance with distributed tracing, implement multi-tier caching, and load testing",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
+- **Plugin**: specweave-infrastructure
+- **Directory**: performance-engineer
+- **Agent Name**: performance-engineer
+
+**When to Use**:
+- You need to profile and optimize application performance
+- You want to implement caching strategies across layers
+- You need to conduct load testing and capacity planning
+- You're optimizing database queries or API response times
+- You want to improve Core Web Vitals or frontend performance
+
 ## Purpose
 Expert performance engineer with comprehensive knowledge of modern observability, application profiling, and system optimization. Masters performance testing, distributed tracing, caching architectures, and scalability patterns. Specializes in end-to-end performance optimization, real user monitoring, and building performant, scalable systems.
 

package/plugins/specweave-infrastructure/agents/sre/AGENT.md

@@ -10,6 +10,32 @@ fallback_behavior: auto
 
 # SRE Agent - Site Reliability Engineering Expert
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-infrastructure:sre:sre`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-infrastructure:sre:sre",
+  prompt: "Diagnose why dashboard loading is slow (10 seconds) and provide immediate and long-term mitigation plans",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
+- **Plugin**: specweave-infrastructure
+- **Directory**: sre
+- **Agent Name**: sre
+
+**When to Use**:
+- You have an active production incident and need rapid diagnosis
+- You need to analyze root causes of system failures
+- You want to create runbooks for recurring issues
+- You need to write post-mortems after incidents
+- You're troubleshooting performance, availability, or reliability issues
+
 **Purpose**: Holistic incident response, root cause analysis, and production system reliability.
 
 ## Core Capabilities

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

@@ -1,5 +1,31 @@
 # Jira Manager Agent
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-jira:jira-manager:jira-manager`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-jira:jira-manager:jira-manager",
+  prompt: "Create Jira epic for increment 0005 and sync all tasks from spec.md and tasks.md",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
+- **Plugin**: specweave-jira
+- **Directory**: jira-manager
+- **Agent Name**: jira-manager
+
+**When to Use**:
+- You need to sync SpecWeave increments to Jira epics
+- You want bidirectional synchronization between SpecWeave and Jira
+- You need to update Jira issues with task completion status
+- You're creating Jira stories from SpecWeave specifications
+- You need to manage cross-system consistency between SpecWeave and Jira
+
 **Role**: Jira integration specialist for SpecWeave increments
 
 **Expertise**: Jira REST API, Epic/Story/Task management, JQL, automation, webhooks, custom fields

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

@@ -5,6 +5,32 @@ description: Kafka architecture and design specialist. Expert in system design,
 
 # Kafka Architect Agent
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-kafka:kafka-architect:kafka-architect`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-kafka:kafka-architect:kafka-architect",
+  prompt: "Design event-driven architecture for e-commerce with Kafka microservices and CQRS pattern",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
+- **Plugin**: specweave-kafka
+- **Directory**: kafka-architect
+- **Agent Name**: kafka-architect
+
+**When to Use**:
+- You're designing Kafka infrastructure for event-driven systems
+- You need guidance on partition strategy and topic design
+- You want to implement event sourcing or CQRS patterns
+- You're planning capacity for a Kafka cluster
+- You need to design scalable real-time data pipelines
+
 I'm a specialized architecture agent with deep expertise in designing scalable, reliable, and performant Apache Kafka systems.
 
 ## My Expertise

package/plugins/specweave-kafka/agents/kafka-devops/AGENT.md

@@ -5,6 +5,32 @@ description: Kafka DevOps and SRE specialist. Expert in infrastructure deploymen
 
 # Kafka DevOps Agent
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-kafka:kafka-devops:kafka-devops`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-kafka:kafka-devops:kafka-devops",
+  prompt: "Deploy production Kafka cluster on AWS with Terraform, configure monitoring with Prometheus and Grafana",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
+- **Plugin**: specweave-kafka
+- **Directory**: kafka-devops
+- **Agent Name**: kafka-devops
+
+**When to Use**:
+- You need to deploy and manage Kafka infrastructure
+- You want to set up CI/CD pipelines for Kafka upgrades
+- You're configuring Kafka cluster monitoring and alerting
+- You have operational issues or need incident response
+- You need to implement disaster recovery and backup strategies
+
 I'm a specialized DevOps/SRE agent with deep expertise in Apache Kafka operations, deployment automation, and production reliability.
 
 ## My Expertise

package/plugins/specweave-kafka/agents/kafka-observability/AGENT.md

@@ -5,6 +5,32 @@ description: Kafka observability and monitoring specialist. Expert in Prometheus
 
 # Kafka Observability Agent
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-kafka:kafka-observability:kafka-observability`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-kafka:kafka-observability:kafka-observability",
+  prompt: "Set up Kafka monitoring with Prometheus JMX exporter and create Grafana dashboards with alerting rules",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
+- **Plugin**: specweave-kafka
+- **Directory**: kafka-observability
+- **Agent Name**: kafka-observability
+
+**When to Use**:
+- You need to set up monitoring for Kafka clusters
+- You want to configure alerting for critical Kafka metrics
+- You're troubleshooting high latency, consumer lag, or performance issues
+- You need to analyze Kafka performance bottlenecks
+- You're implementing SLOs for Kafka availability and latency
+
 I'm a specialized observability agent with deep expertise in monitoring, alerting, and troubleshooting Apache Kafka in production.
 
 ## My Expertise

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

@@ -9,6 +9,32 @@ fallback_behavior: strict
 
 You are a Kubernetes architect specializing in cloud-native infrastructure, modern GitOps workflows, and enterprise container orchestration at scale.
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-kubernetes:kubernetes-architect:kubernetes-architect`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-kubernetes:kubernetes-architect:kubernetes-architect",
+  prompt: "Design multi-cluster Kubernetes platform with GitOps using ArgoCD and progressive delivery with Argo Rollouts",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
+- **Plugin**: specweave-kubernetes
+- **Directory**: kubernetes-architect
+- **Agent Name**: kubernetes-architect
+
+**When to Use**:
+- You're designing Kubernetes clusters and container orchestration platforms
+- You need to implement GitOps workflows with ArgoCD or Flux
+- You want to set up service mesh (Istio, Linkerd) for microservices
+- You're planning progressive delivery and canary deployments
+- You need to design multi-tenancy and resource isolation strategies
+
 ## Purpose
 Expert Kubernetes architect with comprehensive knowledge of container orchestration, cloud-native technologies, and modern GitOps practices. Masters Kubernetes across all major providers (EKS, AKS, GKE) and on-premises deployments. Specializes in building scalable, secure, and cost-effective platform engineering solutions that enhance developer productivity.
 

package/plugins/specweave-ml/.claude-plugin/plugin.json

@@ -3,8 +3,8 @@
   "version": "0.22.14",
   "description": "Complete ML/AI workflow integration for SpecWeave - from experiment tracking to production deployment. Includes 13 comprehensive skills covering the full ML lifecycle: pipeline orchestration, experiment tracking, model evaluation, explainability, deployment, feature engineering, AutoML, computer vision, NLP, time series forecasting, anomaly detection, data visualization, and model registry.",
   "author": {
-    "name": "SpecWeave Team",
-    "email": "[email protected]",
+    "name": "Anton Abyzov",
+    "email": "anton.abyzov@gmail.com",
     "url": "https://spec-weave.com"
   },
   "homepage": "https://spec-weave.com",

package/plugins/specweave-ml/agents/data-scientist/AGENT.md

@@ -9,6 +9,32 @@ fallback_behavior: strict
 
 You are a data scientist specializing in advanced analytics, machine learning, statistical modeling, and data-driven business insights.
 
+## 🚀 How to Invoke This Agent
+
+**Subagent Type**: `specweave-ml:data-scientist:data-scientist`
+
+**Usage Example**:
+
+```typescript
+Task({
+  subagent_type: "specweave-ml:data-scientist:data-scientist",
+  prompt: "Analyze customer churn patterns and build predictive model to identify at-risk customers",
+  model: "haiku" // optional: haiku, sonnet, opus
+});
+```
+
+**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
+- **Plugin**: specweave-ml
+- **Directory**: data-scientist
+- **Agent Name**: data-scientist
+
+**When to Use**:
+- You need to perform exploratory data analysis and statistical analysis
+- You want to build machine learning models for prediction or classification
+- You need to design A/B tests or experiments
+- You want to create data visualizations and dashboards
+- You need actionable insights from complex data
+
 ## Purpose
 Expert data scientist combining strong statistical foundations with modern machine learning techniques and business acumen. Masters the complete data science workflow from exploratory data analysis to production model deployment, with deep expertise in statistical methods, ML algorithms, and data visualization for actionable business insights.