specweave 0.23.18 → 0.24.0

package/plugins/specweave/hooks/pre-increment-start.sh

@@ -0,0 +1,168 @@
+#!/bin/bash
+#
+# Pre-Increment-Start Hook
+#
+# Validates increment readiness before allowing `/specweave:do` to start work.
+#
+# **Critical Checks**:
+# 1. spec.md contains Acceptance Criteria
+# 2. AC count matches metadata.json
+# 3. No duplicate task files (tasks.md, tasks-detailed.md)
+# 4. Increment structure is valid
+#
+# **Triggered by**: /specweave:do command (before starting implementation)
+#
+# **Exit codes**:
+# - 0: Validation passed, safe to start
+# - 1: Validation failed, BLOCK start
+#
+# **See**: ADR-0062 (AC Embedding Architecture)
+#
+
+set -euo pipefail
+
+# Get increment path from environment or argument
+INCREMENT_PATH="${1:-}"
+
+if [ -z "$INCREMENT_PATH" ]; then
+  echo "❌ Error: INCREMENT_PATH not provided"
+  echo "Usage: $0 <increment-path>"
+  exit 1
+fi
+
+if [ ! -d "$INCREMENT_PATH" ]; then
+  echo "❌ Error: Increment path not found: $INCREMENT_PATH"
+  exit 1
+fi
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "PRE-START VALIDATION: $(basename "$INCREMENT_PATH")"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+VALIDATION_PASSED=true
+
+# Check 1: spec.md exists
+if [ ! -f "$INCREMENT_PATH/spec.md" ]; then
+  echo "❌ CRITICAL: spec.md not found"
+  VALIDATION_PASSED=false
+fi
+
+# Check 2: Acceptance Criteria section exists
+if [ -f "$INCREMENT_PATH/spec.md" ]; then
+  if ! grep -q "## Acceptance Criteria" "$INCREMENT_PATH/spec.md"; then
+    echo "❌ CRITICAL: spec.md missing '## Acceptance Criteria' section"
+    echo ""
+    echo "   spec.md MUST contain inline Acceptance Criteria for AC sync to work."
+    echo "   Even when using 'structure: user-stories', ACs must be embedded in spec.md."
+    echo ""
+    echo "   💡 SUGGESTED FIX:"
+    echo "      Run: /specweave:embed-acs $(basename "$INCREMENT_PATH")"
+    echo ""
+    VALIDATION_PASSED=false
+  fi
+fi
+
+# Check 3: Count ACs in spec.md
+AC_COUNT=0
+if [ -f "$INCREMENT_PATH/spec.md" ]; then
+  AC_COUNT=$(grep -cE "^- \[[x ]\] \*\*AC-US[0-9]+-[0-9]+\*\*:" "$INCREMENT_PATH/spec.md" || true)
+fi
+
+if [ "$AC_COUNT" -eq 0 ]; then
+  echo "❌ CRITICAL: spec.md contains 0 Acceptance Criteria"
+  echo ""
+  echo "   Cannot start increment with no ACs defined."
+  echo ""
+  echo "   💡 SUGGESTED FIX:"
+  echo "      1. Add ACs manually to spec.md, OR"
+  echo "      2. Run: /specweave:embed-acs $(basename "$INCREMENT_PATH") (auto-embed from living docs)"
+  echo ""
+  VALIDATION_PASSED=false
+else
+  echo "✅ Acceptance Criteria: $AC_COUNT ACs found in spec.md"
+fi
+
+# Check 4: Validate AC count matches metadata.json
+if [ -f "$INCREMENT_PATH/metadata.json" ]; then
+  EXPECTED_AC_COUNT=$(jq -r '.total_acs // 0' "$INCREMENT_PATH/metadata.json")
+
+  if [ "$EXPECTED_AC_COUNT" -ne "$AC_COUNT" ]; then
+    echo "⚠️  WARNING: AC count mismatch"
+    echo "   spec.md: $AC_COUNT ACs"
+    echo "   metadata.json: $EXPECTED_AC_COUNT ACs"
+    echo ""
+    echo "   This may cause status line desyncs."
+    echo ""
+    # Don't block, just warn (metadata.json may be stale)
+  else
+    echo "✅ AC Count: Matches metadata.json ($EXPECTED_AC_COUNT ACs)"
+  fi
+fi
+
+# Check 5: No duplicate task files
+TASK_FILES=$(find "$INCREMENT_PATH" -maxdepth 1 -name "tasks*.md" -type f | wc -l)
+if [ "$TASK_FILES" -gt 1 ]; then
+  echo "❌ CRITICAL: Multiple task files detected (MUST be only ONE tasks.md)"
+  find "$INCREMENT_PATH" -maxdepth 1 -name "tasks*.md" -type f -exec basename {} \;
+  echo ""
+  echo "   💡 SUGGESTED FIX:"
+  echo "      Keep tasks.md, move others to reports/ directory"
+  echo ""
+  VALIDATION_PASSED=false
+else
+  echo "✅ Structure: Single tasks.md file (no duplicates)"
+fi
+
+# Check 6: Validate frontmatter for 'structure: user-stories' pattern
+if [ -f "$INCREMENT_PATH/spec.md" ]; then
+  if grep -q "structure: user-stories" "$INCREMENT_PATH/spec.md"; then
+    if [ "$AC_COUNT" -eq 0 ]; then
+      echo ""
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      echo "🚨 CRITICAL ARCHITECTURE VIOLATION"
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      echo ""
+      echo "spec.md uses 'structure: user-stories' but contains NO inline ACs."
+      echo ""
+      echo "**Why this is critical**:"
+      echo "  - AC sync hooks expect ACs in spec.md (not living docs)"
+      echo "  - Without inline ACs, status line will show 0% completion"
+      echo "  - Tasks-to-AC traceability will be broken"
+      echo ""
+      echo "**Architecture requirement (ADR-0062)**:"
+      echo "  spec.md is ALWAYS the source of truth for ACs,"
+      echo "  even when living docs exist as documentation layer."
+      echo ""
+      echo "**IMMEDIATE ACTION REQUIRED**:"
+      echo "  Run: /specweave:embed-acs $(basename "$INCREMENT_PATH")"
+      echo ""
+      echo "This will auto-embed ACs from living docs into spec.md."
+      echo ""
+      VALIDATION_PASSED=false
+    else
+      echo "✅ Living Docs Structure: ACs properly embedded in spec.md"
+    fi
+  fi
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+if [ "$VALIDATION_PASSED" = true ]; then
+  echo "✅ PRE-START VALIDATION: PASSED"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo ""
+  echo "Increment is ready to start. Proceeding with /specweave:do..."
+  exit 0
+else
+  echo "❌ PRE-START VALIDATION: FAILED"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo ""
+  echo "Cannot start increment due to validation failures above."
+  echo ""
+  echo "Fix the issues and try again, or run validation manually:"
+  echo "  /specweave:validate $(basename "$INCREMENT_PATH")"
+  echo ""
+  exit 1
+fi

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

@@ -113,7 +113,7 @@ Step 4: Execute → Follow the increment planning workflow
 
 #### increment-quality-judge-v2
 
-**Description**: Enhanced AI-powered quality assessment with RISK SCORING (BMAD pattern) and quality gate decisions. Evaluates specifications, plans, and tests for clarity, testability, completeness, feasibility, maintainability, edge cases, and RISKS. Provides PASS/CONCERNS/FAIL decisions. Activates for validate quality, quality check, assess spec, evaluate increment, spec review, quality score, risk assessment, qa check, quality gate, /specweave:qa command.
+**Description**: Enhanced AI-powered quality assessment with RISK SCORING (Probability × Impact method) and quality gate decisions. Evaluates specifications, plans, and tests for clarity, testability, completeness, feasibility, maintainability, edge cases, and RISKS. Provides PASS/CONCERNS/FAIL decisions. Activates for validate quality, quality check, assess spec, evaluate increment, spec review, quality score, risk assessment, qa check, quality gate, /specweave:qa command.
 
 **Activates for**: validate quality, quality check, assess spec, evaluate increment, spec review, quality score, risk assessment, qa check, quality gate
 

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

@@ -1,6 +1,6 @@
 {
   "name": "specweave-ado",
-  "version": "0.22.14",
+  "version": "0.24.0",
   "description": "Azure DevOps integration for SpecWeave - sync increments with ADO work items, track progress, and manage project workflows",
   "author": {
     "name": "SpecWeave Team",

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

@@ -0,0 +1,331 @@
+---
+name: specweave-ado:import-projects
+description: Import additional Azure DevOps projects post-init with area path mapping, filtering, and dry-run preview
+---
+
+# Import Azure DevOps Projects Command
+
+You are an Azure DevOps project import expert. Help users add additional ADO projects to their SpecWeave workspace after initial setup.
+
+## Purpose
+
+This command allows users to import additional Azure DevOps projects **after** initial SpecWeave setup (`specweave init`), with area path mapping, filtering, and dry-run preview.
+
+**Use Cases**:
+- Adding new ADO projects to existing workspace
+- Importing projects from different organizations
+- Selective import with area path granularity
+- Multi-project organization (Backend, Frontend, Mobile, Infrastructure)
+
+## Command Syntax
+
+```bash
+# Basic import (interactive)
+/specweave-ado:import-projects
+
+# With area path granularity
+/specweave-ado:import-projects --granularity two-level
+
+# Dry-run (preview)
+/specweave-ado:import-projects --dry-run
+
+# Resume interrupted import
+/specweave-ado:import-projects --resume
+
+# Combined
+/specweave-ado:import-projects --granularity top-level --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 ADO credentials exist
+const envContent = readEnvFile(process.cwd());
+const parsed = parseEnvFile(envContent);
+
+if (!parsed.AZURE_DEVOPS_PAT || !parsed.AZURE_DEVOPS_ORG) {
+  console.log('❌ Missing Azure DevOps credentials. Run `specweave init` first.');
+  return;
+}
+
+// 2. Get existing configuration
+const org = parsed.AZURE_DEVOPS_ORG;
+const existingProject = parsed.AZURE_DEVOPS_PROJECT;
+
+console.log(`\n📋 Organization: ${org}`);
+console.log(`   Current project: ${existingProject || '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: 'ado',
+  credentials: {
+    organization: org,
+    pat: parsed.AZURE_DEVOPS_PAT
+  }
+});
+
+console.log(`✓ Found ${countResult.accessible} accessible project(s)`);
+
+// Fetch all projects (with smart pagination)
+const loader = new AsyncProjectLoader(
+  {
+    organization: org,
+    pat: parsed.AZURE_DEVOPS_PAT
+  },
+  'ado',
+  {
+    batchSize: 50,
+    updateFrequency: 5,
+    showEta: true
+  }
+);
+
+const result = await loader.fetchAllProjects(countResult.accessible);
+const allProjects = result.projects;
+```
+
+### Step 3: Area Path Mapping (Multi-Project Organization)
+```typescript
+import { AreaPathMapper } from '../../../src/integrations/ado/area-path-mapper.js';
+
+const { selectedProject } = await inquirer.prompt([{
+  type: 'list',
+  name: 'selectedProject',
+  message: 'Select ADO project to import area paths from:',
+  choices: allProjects.map(p => ({ name: p.name, value: p.name }))
+}]);
+
+const mapper = new AreaPathMapper({
+  credentials: { organization: org, pat: parsed.AZURE_DEVOPS_PAT },
+  project: selectedProject
+});
+
+// Fetch area path tree
+const areaPathTree = await mapper.fetchAreaPaths();
+
+// Get granularity suggestion
+const suggestion = mapper.suggestGranularity(areaPathTree);
+console.log(`\n💡 Suggestion: ${suggestion.suggested}`);
+console.log(`   ${suggestion.reasoning}\n`);
+
+// Prompt for granularity (if not provided via CLI)
+const granularity = args.granularity || await mapper.promptAreaPathGranularity(areaPathTree);
+
+// Flatten area paths with selected granularity
+const areaPaths = mapper.flattenAreaPaths(areaPathTree, granularity);
+
+console.log(`\n📊 ${areaPaths.length} project(s) will be created from area paths:\n`);
+areaPaths.forEach(ap => {
+  const projectId = mapper.mapToProjectId(ap.path);
+  console.log(`   ✨ ${ap.path} → ${projectId}`);
+});
+```
+
+### Step 4: 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 configured:');
+  areaPaths.forEach(ap => {
+    const projectId = mapper.mapToProjectId(ap.path);
+    console.log(`   ✨ ${projectId} (${ap.path})`);
+  });
+  console.log(`\nTotal: ${areaPaths.length} projects would be configured\n`);
+  return;
+}
+
+// Confirm import
+const { confirmed } = await inquirer.prompt([{
+  type: 'confirm',
+  name: 'confirmed',
+  message: `Configure ${areaPaths.length} project(s) from area paths?`,
+  default: true
+}]);
+
+if (!confirmed) {
+  console.log('⏭️  Import cancelled.');
+  return;
+}
+```
+
+### Step 5: Update Configuration
+```typescript
+import { getConfigManager } from '../../../src/core/config/index.js';
+
+const configManager = getConfigManager(process.cwd());
+
+// Build area path configuration
+const areaPathConfig: Record<string, string[]> = {};
+
+for (const ap of areaPaths) {
+  const projectId = mapper.mapToProjectId(ap.path);
+  areaPathConfig[projectId] = [ap.path];
+}
+
+// Update configuration
+await configManager.update({
+  issueTracker: {
+    provider: 'ado',
+    ado: {
+      organization: org,
+      project: selectedProject,
+      areaPathMapping: areaPathConfig,
+      granularity
+    }
+  }
+});
+
+// Update .env file
+import { updateEnvFile } from '../../../src/utils/env-manager.js';
+
+await updateEnvFile('AZURE_DEVOPS_PROJECT', selectedProject);
+
+// Write area paths to .env (comma-separated)
+const areaPathList = areaPaths.map(ap => ap.path).join(',');
+await updateEnvFile('AZURE_DEVOPS_AREA_PATHS', areaPathList);
+
+console.log('\n✅ Projects configured successfully!\n');
+console.log(`Organization: ${org}`);
+console.log(`Project: ${selectedProject}`);
+console.log(`Granularity: ${granularity}`);
+console.log(`\nArea paths configured:\n   ${areaPathList.split(',').join('\n   ')}\n`);
+```
+
+### Step 6: 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('ado-import-state');
+
+  if (!importState) {
+    console.log('⚠️  No import state found. Use without --resume to start fresh.');
+    return;
+  }
+
+  console.log(`\n📂 Resuming from: ${importState.lastAreaPath} (${importState.completed}/${importState.total})`);
+
+  // Skip already-processed area paths
+  const remainingPaths = areaPaths.filter(ap => !importState.processed.includes(ap.path));
+
+  // Continue import with remaining paths
+  // (use same logic as Step 5)
+}
+```
+
+## Examples
+
+### Example 1: Basic Import with Area Paths
+**User**: `/specweave-ado:import-projects`
+
+**Output**:
+```
+📋 Organization: mycompany
+   Current project: Platform
+
+✓ Found 5 accessible project(s)
+
+Select ADO project to import area paths from:
+> Platform
+
+💡 Suggestion: two-level
+   Balanced hierarchy (8 two-level areas). Recommended granularity.
+
+Select area path granularity for project organization:
+> Two-level (8 projects) - e.g., Backend-API, Backend-Database
+
+📊 8 project(s) will be created from area paths:
+
+   ✨ Platform/Backend/API → backend-api
+   ✨ Platform/Backend/Database → backend-database
+   ✨ Platform/Frontend/Web → frontend-web
+   ✨ Platform/Frontend/Admin → frontend-admin
+   ✨ Platform/Mobile/iOS → mobile-ios
+   ✨ Platform/Mobile/Android → mobile-android
+   ✨ Platform/Infrastructure/Cloud → infrastructure-cloud
+   ✨ Platform/Infrastructure/Network → infrastructure-network
+
+Configure 8 project(s) from area paths? (Y/n)
+
+✅ Projects configured successfully!
+
+Organization: mycompany
+Project: Platform
+Granularity: two-level
+
+Area paths configured:
+   Platform/Backend/API
+   Platform/Backend/Database
+   Platform/Frontend/Web
+   Platform/Frontend/Admin
+   Platform/Mobile/iOS
+   Platform/Mobile/Android
+   Platform/Infrastructure/Cloud
+   Platform/Infrastructure/Network
+```
+
+### Example 2: Top-Level Only
+**User**: `/specweave-ado:import-projects --granularity top-level`
+
+**Output**:
+```
+Select area path granularity: top-level (forced via CLI)
+
+📊 3 project(s) will be created from area paths:
+
+   ✨ Platform/Backend → backend
+   ✨ Platform/Frontend → frontend
+   ✨ Platform/Mobile → mobile
+```
+
+### Example 3: Dry-Run
+**User**: `/specweave-ado:import-projects --dry-run`
+
+**Output**:
+```
+🔎 DRY RUN: No changes will be made.
+
+The following projects would be configured:
+   ✨ backend-api (Platform/Backend/API)
+   ✨ backend-database (Platform/Backend/Database)
+   ✨ frontend-web (Platform/Frontend/Web)
+
+Total: 8 projects would be configured
+```
+
+## Important Notes
+
+- **Multi-Project Organization**: Uses area paths to create logical project separation
+- **Granularity Control**: Top-level, two-level, or full-tree based on hierarchy complexity
+- **Atomic Updates**: Uses temp file + rename to prevent corruption
+- **Progress Tracking**: Shows progress bar for large hierarchies (> 50 area paths)
+- **Resume Support**: Interrupted imports can be resumed with `--resume`
+
+## Related Commands
+
+- `/specweave:init` - Initial SpecWeave setup
+- `/specweave-ado:sync` - Sync increments with ADO work items
+- `/specweave-ado:refresh-cache` - Clear cached ADO data
+
+## Error Handling
+
+- **Missing Credentials**: Prompt user to run `specweave init` first
+- **API Errors**: Show clear error message with suggestion
+- **No Area Paths**: Fallback to single-project mode
+- **Permission Errors**: Check ADO PAT scopes
+
+---
+
+**Multi-Project Excellence**: This command enables sophisticated multi-project organization in Azure DevOps using area paths, perfect for large teams with complex hierarchies.

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

@@ -0,0 +1,10 @@
+{
+  "name": "specweave-alternatives",
+  "version": "0.24.0",
+  "description": "Technology stack alternatives analysis using BMAD method - Best, Most Appropriate, Design decisions for architecture choices",
+  "author": {
+    "name": "Anton Abyzov",
+    "email": "anton.abyzov@gmail.com"
+  },
+  "hooks": {}
+}