specweave 0.23.16 → 0.24.0

package/plugins/specweave-jira/commands/specweave-jira-import-projects.md

@@ -0,0 +1,298 @@
+---
+name: specweave-jira:import-projects
+description: Import additional JIRA projects post-init with filtering, resume support, and dry-run preview
+---
+
+# Import JIRA Projects Command
+
+You are a JIRA project import expert. Help users add additional JIRA projects to their SpecWeave workspace after initial setup.
+
+## Purpose
+
+This command allows users to import additional JIRA projects **after** initial SpecWeave setup (`specweave init`), with advanced filtering, resume capability, and dry-run preview.
+
+**Use Cases**:
+- Adding new JIRA projects to existing workspace
+- Importing archived/paused projects later
+- Selective import with filters (active only, specific types, custom JQL)
+
+## Command Syntax
+
+```bash
+# Basic import (interactive)
+/specweave-jira:import-projects
+
+# With filters
+/specweave-jira:import-projects --filter active
+/specweave-jira:import-projects --type agile --lead "john.doe@company.com"
+/specweave-jira:import-projects --jql "project IN (BACKEND, FRONTEND) AND status != Archived"
+
+# Dry-run (preview)
+/specweave-jira:import-projects --dry-run
+
+# Resume interrupted import
+/specweave-jira:import-projects --resume
+
+# Combined
+/specweave-jira:import-projects --filter active --dry-run
+```
+
+## Your Task
+
+When the user runs this command:
+
+### Step 1: Validate Prerequisites
+```typescript
+import { readEnvFile, parseEnvFile } from '../../../src/utils/env-file.js';
+
+// 1. Check if Jira credentials exist
+const envContent = readEnvFile(process.cwd());
+const parsed = parseEnvFile(envContent);
+
+if (!parsed.JIRA_API_TOKEN || !parsed.JIRA_EMAIL || !parsed.JIRA_DOMAIN) {
+  console.log('❌ Missing Jira credentials. Run `specweave init` first.');
+  return;
+}
+
+// 2. Get existing projects
+const existingProjects = parsed.JIRA_PROJECTS?.split(',') || [];
+console.log(`\n📋 Current projects: ${existingProjects.join(', ') || 'None'}\n`);
+```
+
+### Step 2: Fetch Available Projects
+```typescript
+import { getProjectCount } from '../../../src/cli/helpers/project-count-fetcher.js';
+import { AsyncProjectLoader } from '../../../src/cli/helpers/async-project-loader.js';
+
+// Count check (< 1 second)
+const countResult = await getProjectCount({
+  provider: 'jira',
+  credentials: {
+    domain: parsed.JIRA_DOMAIN,
+    email: parsed.JIRA_EMAIL,
+    token: parsed.JIRA_API_TOKEN,
+    instanceType: 'cloud'
+  }
+});
+
+console.log(`✓ Found ${countResult.accessible} accessible projects`);
+
+// Fetch all projects (with smart pagination)
+const loader = new AsyncProjectLoader(
+  {
+    domain: parsed.JIRA_DOMAIN,
+    email: parsed.JIRA_EMAIL,
+    token: parsed.JIRA_API_TOKEN,
+    instanceType: 'cloud'
+  },
+  'jira',
+  {
+    batchSize: 50,
+    updateFrequency: 5,
+    showEta: true
+  }
+);
+
+const result = await loader.fetchAllProjects(countResult.accessible);
+let allProjects = result.projects;
+```
+
+### Step 3: Apply Filters (if specified)
+```typescript
+import { FilterProcessor } from '../../../src/integrations/jira/filter-processor.js';
+
+const options = {
+  filter: args.filter,       // 'active' | 'all'
+  type: args.type,           // 'agile' | 'software' | 'business'
+  lead: args.lead,           // Email address
+  jql: args.jql              // Custom JQL
+};
+
+const filterProcessor = new FilterProcessor({ domain: parsed.JIRA_DOMAIN, token: parsed.JIRA_API_TOKEN });
+const filteredProjects = await filterProcessor.applyFilters(allProjects, options);
+
+console.log(`\n🔍 Filters applied:`);
+if (options.filter === 'active') console.log(`   • Active projects only`);
+if (options.type) console.log(`   • Type: ${options.type}`);
+if (options.lead) console.log(`   • Lead: ${options.lead}`);
+if (options.jql) console.log(`   • JQL: ${options.jql}`);
+console.log(`\n📊 Results: ${filteredProjects.length} projects (down from ${allProjects.length})\n`);
+```
+
+### Step 4: Exclude Existing Projects
+```typescript
+const newProjects = filteredProjects.filter(p => !existingProjects.includes(p.key));
+
+if (newProjects.length === 0) {
+  console.log('✅ No new projects to import. All filtered projects are already configured.');
+  return;
+}
+
+console.log(`📥 ${newProjects.length} new project(s) available for import:\n`);
+newProjects.forEach(p => {
+  console.log(`   ✨ ${p.key} - ${p.name} (${p.projectTypeKey}, lead: ${p.lead?.displayName || 'N/A'})`);
+});
+```
+
+### Step 5: Dry-Run or Execute
+```typescript
+if (args.dryRun) {
+  console.log('\n🔎 DRY RUN: No changes will be made.\n');
+  console.log('The following projects would be imported:');
+  newProjects.forEach(p => {
+    const status = p.archived ? '⏭️  (archived - skipped)' : '✨';
+    console.log(`   ${status} ${p.key} - ${p.name}`);
+  });
+  console.log(`\nTotal: ${newProjects.filter(p => !p.archived).length} projects would be imported\n`);
+  return;
+}
+
+// Confirm import
+const { confirmed } = await inquirer.prompt([{
+  type: 'confirm',
+  name: 'confirmed',
+  message: `Import ${newProjects.length} project(s)?`,
+  default: true
+}]);
+
+if (!confirmed) {
+  console.log('⏭️  Import cancelled.');
+  return;
+}
+```
+
+### Step 6: Merge with Existing
+```typescript
+import { updateEnvFile, mergeProjectList } from '../../../src/utils/env-manager.js';
+
+const newKeys = newProjects.map(p => p.key);
+const mergedProjects = mergeProjectList(existingProjects, newKeys);
+
+// Update .env file (atomic write)
+await updateEnvFile('JIRA_PROJECTS', mergedProjects.join(','));
+
+console.log('\n✅ Projects imported successfully!\n');
+console.log(`Updated: ${existingProjects.length} → ${mergedProjects.length} projects`);
+console.log(`\nCurrent projects:\n   ${mergedProjects.join(', ')}\n`);
+```
+
+### Step 7: Resume Support
+```typescript
+if (args.resume) {
+  const { CacheManager } = await import('../../../src/core/cache/cache-manager.js');
+  const cacheManager = new CacheManager(process.cwd());
+
+  const importState = await cacheManager.get('jira-import-state');
+
+  if (!importState) {
+    console.log('⚠️  No import state found. Use without --resume to start fresh.');
+    return;
+  }
+
+  console.log(`\n📂 Resuming from: ${importState.lastProject} (${importState.completed}/${importState.total})`);
+
+  // Skip already-imported projects
+  const remainingProjects = allProjects.filter(p => !importState.succeeded.includes(p.key));
+
+  // Continue import with remaining projects
+  // (use same logic as Step 6)
+}
+```
+
+## Examples
+
+### Example 1: Basic Import
+**User**: `/specweave-jira:import-projects`
+
+**Output**:
+```
+📋 Current projects: BACKEND, FRONTEND
+
+✓ Found 127 accessible projects
+📥 5 new project(s) available for import:
+
+   ✨ MOBILE - Mobile App (agile, lead: John Doe)
+   ✨ INFRA - Infrastructure (software, lead: Jane Smith)
+   ✨ QA - Quality Assurance (business, lead: Bob Wilson)
+   ✨ DOCS - Documentation (business, lead: Alice Cooper)
+   ✨ LEGACY - Legacy System (archived - skipped)
+
+Import 5 project(s)? (Y/n)
+
+✅ Projects imported successfully!
+
+Updated: 2 → 6 projects
+
+Current projects:
+   BACKEND, FRONTEND, MOBILE, INFRA, QA, DOCS
+```
+
+### Example 2: Filter Active Only
+**User**: `/specweave-jira:import-projects --filter active`
+
+**Output**:
+```
+🔍 Filters applied:
+   • Active projects only
+
+📊 Results: 120 projects (down from 127)
+
+📥 4 new project(s) available for import:
+   (LEGACY project excluded because it's archived)
+```
+
+### Example 3: Dry-Run
+**User**: `/specweave-jira:import-projects --dry-run`
+
+**Output**:
+```
+🔎 DRY RUN: No changes will be made.
+
+The following projects would be imported:
+   ✨ MOBILE - Mobile App
+   ✨ INFRA - Infrastructure
+   ✨ QA - Quality Assurance
+   ⏭️  LEGACY - Legacy System (archived - skipped)
+
+Total: 3 projects would be imported
+```
+
+### Example 4: Custom JQL Filter
+**User**: `/specweave-jira:import-projects --jql "project IN (MOBILE, INFRA) AND status != Archived"`
+
+**Output**:
+```
+🔍 Filters applied:
+   • JQL: project IN (MOBILE, INFRA) AND status != Archived
+
+📊 Results: 2 projects (down from 127)
+
+📥 2 new project(s) available for import:
+   ✨ MOBILE - Mobile App
+   ✨ INFRA - Infrastructure
+```
+
+## Important Notes
+
+- **Merge Logic**: No duplicates. Existing projects are preserved.
+- **Atomic Updates**: Uses temp file + rename to prevent corruption.
+- **Progress Tracking**: Shows progress bar for large imports (> 50 projects).
+- **Resume Support**: Interrupted imports can be resumed with `--resume`.
+- **Backup**: Creates `.env.backup` before modifying `.env`.
+
+## Related Commands
+
+- `/specweave:init` - Initial SpecWeave setup
+- `/specweave-jira:sync` - Sync increments with Jira epics
+- `/specweave-jira:refresh-cache` - Clear cached project data
+
+## Error Handling
+
+- **Missing Credentials**: Prompt user to run `specweave init` first
+- **API Errors**: Show clear error message with suggestion
+- **No New Projects**: Inform user all projects already imported
+- **Permission Errors**: Check `.env` file permissions
+
+---
+
+**Post-Init Flexibility**: This command provides flexibility to add projects after initial setup, supporting evolving team structures and project lifecycles.

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

@@ -1,7 +1,7 @@
 {
   "name": "specweave-kafka",
   "description": "Apache Kafka event streaming integration with MCP servers, CLI tools (kcat), Terraform modules, and comprehensive observability stack",
-  "version": "0.22.14",
+  "version": "0.24.0",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"

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-kafka-streams/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave-kafka-streams",
   "description": "Kafka Streams library integration for SpecWeave - Stream processing with Java/Kotlin, topology patterns, state stores, windowing, joins, and testing frameworks",
-  "version": "0.22.14",
+  "version": "0.24.0",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"

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.