specweave 0.26.11 → 0.26.14

package/plugins/specweave/lib/hooks/us-completion-orchestrator.js

@@ -3,6 +3,59 @@ import { USCompletionDetector } from "../../../../dist/src/core/us-completion-de
 import { LivingDocsSync } from "../../../../dist/src/core/living-docs/living-docs-sync.js";
 import { USSyncThrottle } from "../../../../dist/src/core/us-sync-throttle.js";
 import { consoleLogger } from "../vendor/utils/logger.js";
+import { spawn } from "child_process";
+import { existsSync } from "fs";
+import * as path from "path";
+async function triggerUserStoryCompleteHook(incrementId, usId, projectRoot) {
+  const hookPaths = [
+    path.join(projectRoot, "plugins/specweave/hooks/post-user-story-complete.sh"),
+    path.join(projectRoot, ".claude/hooks/post-user-story-complete.sh")
+  ];
+  let hookPath = null;
+  for (const p of hookPaths) {
+    if (existsSync(p)) {
+      hookPath = p;
+      break;
+    }
+  }
+  if (!hookPath) {
+    console.log(`   \u2139\uFE0F  post-user-story-complete.sh hook not found (skipping external sync)`);
+    return;
+  }
+  return new Promise((resolve, reject) => {
+    const hookProcess = spawn("bash", [hookPath, incrementId, usId], {
+      cwd: projectRoot,
+      env: {
+        ...process.env,
+        SPECWEAVE_INCREMENT_ID: incrementId,
+        SPECWEAVE_USER_STORY_ID: usId
+      },
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    hookProcess.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+    hookProcess.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+    hookProcess.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Hook exited with code ${code}: ${stderr || stdout}`));
+      }
+    });
+    hookProcess.on("error", (error) => {
+      reject(new Error(`Hook spawn failed: ${error.message}`));
+    });
+    setTimeout(() => {
+      hookProcess.kill("SIGTERM");
+      reject(new Error("Hook timed out after 30s"));
+    }, 3e4);
+  });
+}
 async function syncCompletedUserStories(incrementId) {
   try {
     console.log(`
@@ -52,7 +105,15 @@ async function syncCompletedUserStories(incrementId) {
       console.log(`   Feature: ${syncResult.featureId}`);
       console.log(`   Files updated: ${syncResult.filesCreated.length + syncResult.filesUpdated.length}`);
       console.log(`
-\u{1F4E1} External tool sync completed (GitHub/JIRA/ADO updated if configured)`);
+\u{1F4E1} Triggering external tool updates for ${newlyCompleted.length} completed user stories...`);
+      for (const us of newlyCompleted) {
+        try {
+          await triggerUserStoryCompleteHook(incrementId, us.usId, projectRoot);
+          console.log(`   \u2705 ${us.usId}: External tool updated`);
+        } catch (hookError) {
+          console.warn(`   \u26A0\uFE0F  ${us.usId}: Hook failed (${hookError.message})`);
+        }
+      }
       throttle.recordSync(incrementId);
       console.log(`   \u23F1\uFE0F  Throttle recorded (next sync allowed in 60s)`);
     } else {

package/plugins/specweave/lib/hooks/us-completion-orchestrator.ts

@@ -39,6 +39,88 @@ import { USCompletionDetector } from '../../../../dist/src/core/us-completion-de
 import { LivingDocsSync } from '../../../../dist/src/core/living-docs/living-docs-sync.js';
 import { USSyncThrottle } from '../../../../dist/src/core/us-sync-throttle.js';
 import { consoleLogger } from '../vendor/utils/logger.js';
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import * as path from 'path';
+
+/**
+ * Trigger post-user-story-complete hook for external tool updates
+ *
+ * This bridges the orchestrator to the shell hook that handles:
+ * - GitHub issue closure with completion comment
+ * - JIRA story transition (if implemented)
+ * - ADO work item completion (if implemented)
+ *
+ * @param incrementId - Increment ID (e.g., "0059-context-optimization")
+ * @param usId - User story ID (e.g., "US-003")
+ * @param projectRoot - Project root path
+ */
+async function triggerUserStoryCompleteHook(
+  incrementId: string,
+  usId: string,
+  projectRoot: string
+): Promise<void> {
+  // Find the hook in multiple possible locations
+  const hookPaths = [
+    path.join(projectRoot, 'plugins/specweave/hooks/post-user-story-complete.sh'),
+    path.join(projectRoot, '.claude/hooks/post-user-story-complete.sh'),
+  ];
+
+  let hookPath: string | null = null;
+  for (const p of hookPaths) {
+    if (existsSync(p)) {
+      hookPath = p;
+      break;
+    }
+  }
+
+  if (!hookPath) {
+    console.log(`   ℹ️  post-user-story-complete.sh hook not found (skipping external sync)`);
+    return;
+  }
+
+  return new Promise((resolve, reject) => {
+    // Call hook with spec-id and user-story-id as arguments
+    const hookProcess = spawn('bash', [hookPath, incrementId, usId], {
+      cwd: projectRoot,
+      env: {
+        ...process.env,
+        SPECWEAVE_INCREMENT_ID: incrementId,
+        SPECWEAVE_USER_STORY_ID: usId,
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    hookProcess.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    hookProcess.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    hookProcess.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Hook exited with code ${code}: ${stderr || stdout}`));
+      }
+    });
+
+    hookProcess.on('error', (error) => {
+      reject(new Error(`Hook spawn failed: ${error.message}`));
+    });
+
+    // Timeout after 30 seconds
+    setTimeout(() => {
+      hookProcess.kill('SIGTERM');
+      reject(new Error('Hook timed out after 30s'));
+    }, 30000);
+  });
+}
 
 export interface USSyncResult {
   success: boolean;
@@ -146,9 +228,30 @@ export async function syncCompletedUserStories(incrementId: string): Promise<USS
       console.log(`   Feature: ${syncResult.featureId}`);
       console.log(`   Files updated: ${syncResult.filesCreated.length + syncResult.filesUpdated.length}`);
 
-      // External tool sync happens automatically inside livingDocsSync.syncIncrement()
-      // It calls syncToExternalTools() which handles GitHub/JIRA/ADO
-      console.log(`\n📡 External tool sync completed (GitHub/JIRA/ADO updated if configured)`);
+      // ========================================================================
+      // EXTERNAL TOOL SYNC: Close issues for completed user stories (v0.26.15)
+      // ========================================================================
+      // livingDocsSync.syncIncrement() updates CONTENT but doesn't CLOSE issues.
+      // We need to explicitly trigger post-user-story-complete hook for each US.
+      //
+      // Flow:
+      // 1. For each newly completed US
+      // 2. Call post-user-story-complete.sh with spec-id and us-id
+      // 3. Hook handles: find issue, add completion comment, close issue
+      //
+      // Gate checks happen inside the hook based on config flags.
+
+      console.log(`\n📡 Triggering external tool updates for ${newlyCompleted.length} completed user stories...`);
+
+      for (const us of newlyCompleted) {
+        try {
+          await triggerUserStoryCompleteHook(incrementId, us.usId, projectRoot);
+          console.log(`   ✅ ${us.usId}: External tool updated`);
+        } catch (hookError: any) {
+          // Non-blocking: Log but continue with next US
+          console.warn(`   ⚠️  ${us.usId}: Hook failed (${hookError.message})`);
+        }
+      }
 
       // Record successful sync for throttling
       throttle.recordSync(incrementId);

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

@@ -1,256 +1,100 @@
 # SpecWeave Skills Index
 
-**Purpose**: Quick reference for all available skills. Read this file BEFORE starting any task.
+**Purpose**: Lightweight skill manifest for lazy loading. Load SKILL.md only when triggers match.
 
-**Last Updated**: 2025-11-20 (added increment-quality-judge-v2 as dual skill/agent)
-
-**Total Skills**: 19
-
----
-
-## 🚀 Quick Start (Progressive Disclosure)
-
-**MANDATORY**: Skills are your expert manuals. Always check for relevant skills BEFORE starting implementation.
-
-### Progressive Disclosure Pattern
-
-1. **Scan this index** to find skills matching your task
-2. **Match activation keywords** to your current request
-3. **Load full SKILL.md** for matching skills
-4. **Follow the workflow** in SKILL.md precisely
-
-### Example Workflow
-
-```
-User asks: "Plan a new feature for user authentication"
-
-Step 1: Scan this index → Find "increment-planner" skill
-Step 2: Check keywords → Matches "feature planning", "create increment"
-Step 3: Load skill → cat .claude/skills/increment-planner/SKILL.md
-Step 4: Execute → Follow the increment planning workflow
-```
-
----
-
-## 📚 All Available Skills
-
-
-### Framework Core
-
-#### plugin-expert
-
-**Description**: Expert knowledge of Claude Code's plugin system, marketplace management, and installation commands. Activates for plugin installation, marketplace setup, plugin troubleshooting, plugin commands. Keywords plugin install, plugin marketplace, claude code plugins, plugin management, plugin errors, marketplace add, plugin list.
-
-**Activates for**: plugin installation, marketplace setup, plugin troubleshooting, plugin commands, plugin install, plugin marketplace
-
-**Location**: `.claude/skills/plugin-expert/SKILL.md`
-
----
-
-#### context-loader
-
-**Description**: Explains how SpecWeave achieves context efficiency through Claude's native progressive disclosure mechanism and sub-agent parallelization. Skills load only when relevant, sub-agents isolate context. Activates when users ask about context loading, token usage, or how SpecWeave scales. Keywords: context loading, progressive disclosure, token efficiency, sub-agents, context management.
-
-**Location**: `.claude/skills/context-loader/SKILL.md`
-
----
-
-#### context-optimizer
-
-**Description**: Second-pass context optimization that analyzes user prompts and removes irrelevant specs, agents, and skills from loaded context. Achieves 80%+ token reduction through smart cleanup. Activates for optimize context, reduce tokens, clean context, smart context, precision loading.
-
-**Location**: `.claude/skills/context-optimizer/SKILL.md`
-
-**Allowed tools**: Read, Grep, Glob
-
----
-
-#### increment-planner
-
-**Description**: Creates comprehensive implementation plans for SpecWeave increments (aka features - both terms are interchangeable). This skill should be used when planning new increments/features, creating specifications, or organizing implementation work. Activates for: increment planning, feature planning, implementation plan, create increment, create feature, plan increment, plan feature, organize work, break down increment, break down feature, new product, build project, MVP, SaaS, app development, product description, tech stack planning, feature list.
-
-**Activates for**: increment planning, feature planning, implementation plan, create increment, create feature, plan increment, plan feature, organize work, break down increment, break down feature, new product, build project, MVP, SaaS, app development, product description, tech stack planning, feature list
-
-**Location**: `.claude/skills/increment-planner/SKILL.md`
-
----
-
-#### specweave-detector
-
-**Description**: Detects SpecWeave context (.specweave/ directory exists) and provides workflow documentation. Explains available slash commands and workflow. Keywords slash commands, /specweave:increment, /increment, /specweave:do, /specweave:progress, /specweave:validate, /specweave:done, specweave commands, workflow help, specweave folder.
-
-**Note**: Auto-detection of product descriptions is handled by the `project-kickstarter` skill.
-
-**Location**: `.claude/skills/specweave-detector/SKILL.md`
-
----
-
-#### 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.
-
-**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
-
-**Location**: `.claude/skills/specweave-framework/SKILL.md`
-
-**Allowed tools**: Read, Grep, Glob
-
----
-
-
-### Orchestration & Planning
-
-#### role-orchestrator
-
-**Description**: Multi-agent orchestration system that coordinates specialized agents (PM, Architect, DevOps, QA, Tech Lead, Security) to work together on complex tasks. Implements hierarchical orchestrator-worker pattern. Activates for complex multi-step requests requiring multiple roles/skills. Keywords: build product, create SaaS, full implementation, end-to-end, multi-agent, orchestrate, coordinate roles, complex project.
-
-**Location**: `.claude/skills/role-orchestrator/SKILL.md`
-
----
-
-
-### Quality & Testing
-
-#### increment-quality-judge-v2
-
-**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
-
-**Location**: `.claude/skills/increment-quality-judge-v2/SKILL.md`
-
-**Allowed tools**: Read, Grep, Glob
-
-**Special Note**: This exists as BOTH a skill and an agent:
-- **Skill** (this file) → Provides documentation and reference material
-- **Agent** (`plugins/specweave/agents/increment-quality-judge-v2/AGENT.md`) → Provides execution via Task tool
-
-Use **Skill tool** or **/specweave:qa** slash command for quality assessments.
-Use **Task tool** only when programmatically invoking from code (rare).
-
-**Related**: `/specweave:qa` command, `qa-lead` agent
-
----
-
-
-### Documentation
-
-#### brownfield-analyzer
-
-**Description**: Analyzes existing brownfield projects to map documentation structure to SpecWeave's PRD/HLD/Spec/Runbook pattern. Scans folders, classifies documents, detects external tools (Jira, ADO, GitHub), and generates migration plan. Activates for brownfield, existing project, migrate, analyze structure, legacy documentation.
-
-**Location**: `.claude/skills/brownfield-analyzer/SKILL.md`
-
----
-
-#### translator
-
-**Description**: LLM-native translation skill for SpecWeave content. Activates when translation is needed for CLI messages, templates, documentation, or living docs. Uses the current LLM session for zero-cost translation. Keywords: translate, translation, language, multilingual, i18n, internationalization, Russian, Spanish, Chinese, German, French, localization, translate to.
-
-**Location**: `.claude/skills/translator/SKILL.md`
-
-**Allowed tools**: Read, Write, Edit, Grep, Glob
+**Total Skills**: 27 | **Last Updated**: 2025-11-24
 
 ---
 
+## Lazy Loading Pattern
 
-### Other
-
-#### brownfield-onboarder
-
-**Description**: Intelligently onboards brownfield projects by merging existing CLAUDE.md backups into SpecWeave structure. Extracts project-specific knowledge, domain context, team conventions, and technical details from backup CLAUDE.md files, then distributes content to appropriate SpecWeave folders without bloating CLAUDE.md. Activates for: merge docs, merge claude, onboard brownfield, import existing docs, claude backup, specweave merge-docs.
-
-**Activates for**: merge docs, merge claude, onboard brownfield, import existing docs, claude backup, specweave merge-docs
-
-**Location**: `.claude/skills/brownfield-onboarder/SKILL.md`
+1. **Match triggers** below to user intent
+2. **Load SKILL.md** only for matched skill
+3. **Follow workflow** in loaded skill
 
 ---
 
-#### project-kickstarter
-
-**Description**: Proactively detects product/project descriptions and guides users through SpecWeave increment planning. Activates when user provides product name, features, tech stack, timeline, or problem description. Keywords: project, product, SaaS, app, MVP, build, new project, features, tech stack, core functionality, monetization, timeline, I want to build, let's build, quick build, core features.
-
-**Location**: `.claude/skills/project-kickstarter/SKILL.md`
+## Skills by Category
 
----
-
-#### tdd-workflow
+### Planning & Workflow
 
-**Description**: Test-Driven Development workflow coordinator. Detects TDD intent and offers guided red-green-refactor cycle. Activates for TDD, test-driven, red-green-refactor, write tests first, test-first development, Kent Beck, TDD cycle.
+| Skill | Triggers | Location |
+|-------|----------|----------|
+| **increment-planner** | increment, feature, plan, create increment, new feature, organize work, MVP, SaaS, product, build project, tech stack | `skills/increment-planner/SKILL.md` |
+| **increment-work-router** | implement, complete, build, develop, work on, continue, resume, finish, fix, resolve, let's implement, start working | `skills/increment-work-router/SKILL.md` |
+| **spec-generator** | specification, spec.md, plan.md, tasks.md, generate spec, create tasks, requirements, acceptance criteria | `skills/spec-generator/SKILL.md` |
+| **project-kickstarter** | project, product, SaaS, app, MVP, build, new project, features, I want to build, let's build, quick build | `skills/project-kickstarter/SKILL.md` |
+| **roadmap-planner** | roadmap, prioritization, RICE, MoSCoW, Kano, product planning, feature ranking, KPIs, Q1 Q2 Q3 Q4, release planning | `skills/roadmap-planner/SKILL.md` |
+| **role-orchestrator** | multi-agent, orchestrate, coordinate roles, complex project, end-to-end, full implementation, build product | `skills/role-orchestrator/SKILL.md` |
 
-**Location**: `.claude/skills/tdd-workflow/SKILL.md`
+### Quality & Validation
 
----
+| Skill | Triggers | Location |
+|-------|----------|----------|
+| **increment-quality-judge-v2** | quality check, assess spec, risk assessment, qa check, quality gate, /specweave:qa, validate quality, evaluate increment | `skills/increment-quality-judge-v2/SKILL.md` |
+| **pm-closure-validation** | /done, close increment, validate increment, completion check, quality gate, PM approval, ready to close, scope creep | `skills/pm-closure-validation/SKILL.md` |
+| **code-reviewer** | code review, security vulnerabilities, performance optimization, static analysis, code quality, pull request review | `skills/code-reviewer/SKILL.md` |
+| **code-standards-analyzer** | coding standards, conventions, code style, naming conventions, linting rules, best practices, standards audit, anti-patterns | `skills/code-standards-analyzer/SKILL.md` |
+| **tdd-workflow** | TDD, test-driven, red-green-refactor, write tests first, test-first, Kent Beck, TDD cycle | `skills/tdd-workflow/SKILL.md` |
 
+### Synchronization
 
-## 💡 How Skills Work
+| Skill | Triggers | Location |
+|-------|----------|----------|
+| **external-sync-wizard** | GitHub sync, Jira integration, Azure DevOps, ADO, issue tracking sync, bidirectional sync, import issues, export increments | `skills/external-sync-wizard/SKILL.md` |
+| **progress-sync** | sync progress, update progress, sync everything, sync all systems, sync to GitHub, sync to JIRA, /specweave:sync-progress | `skills/progress-sync/SKILL.md` |
+| **multi-project-spec-mapper** | multi-project, project mapping, spec splitting, JIRA projects, multiple projects, microservices, FE/BE/MOBILE split | `skills/multi-project-spec-mapper/SKILL.md` |
 
-**Level 1 - Discovery (this file)**:
-- Scan activation keywords
-- Match to your current task
-- Identify 1-3 relevant skills
+### Framework & Context
 
-**Level 2 - Deep Dive (SKILL.md)**:
-- Load full skill documentation
-- Read required prerequisites
-- Follow step-by-step workflow
+| Skill | Triggers | Location |
+|-------|----------|----------|
+| **specweave-detector** | slash commands, /specweave:increment, /specweave:do, /specweave:progress, /specweave:done, specweave commands, workflow help | `skills/specweave-detector/SKILL.md` |
+| **specweave-framework** | specweave rules, how does specweave work, framework structure, increment lifecycle, source of truth, tasks.md format | `skills/specweave-framework/SKILL.md` |
+| **context-loader** | context loading, progressive disclosure, token efficiency, sub-agents, context management, how SpecWeave scales | `skills/context-loader/SKILL.md` |
+| **context-optimizer** | optimize context, reduce tokens, clean context, smart context, precision loading, 80% reduction | `skills/context-optimizer/SKILL.md` |
+| **plugin-validator** | plugin validation, validate plugins, check plugins, specweave init, fresh setup, marketplace registration | `skills/plugin-validator/SKILL.md` |
 
-**Level 3 - Execution**:
-- Apply skill's instructions
-- Use recommended tools
-- Follow SpecWeave best practices
+### Maintenance & Migration
 
----
+| Skill | Triggers | Location |
+|-------|----------|----------|
+| **archive-increments** | archive, clean workspace, too many increments, archive old, archive completed, _archive folder, preserve history | `skills/archive-increments/SKILL.md` |
+| **smart-reopen-detector** | not working, broken, bug, issue, problem, failing, error, crash, regression, still broken, incorrect, missing | `skills/smart-reopen-detector/SKILL.md` |
+| **brownfield-analyzer** | brownfield, existing project, migrate, analyze structure, legacy documentation, PRD/HLD mapping | `skills/brownfield-analyzer/SKILL.md` |
+| **brownfield-onboarder** | merge docs, merge claude, onboard brownfield, import existing docs, claude backup, CLAUDE.md merge | `skills/brownfield-onboarder/SKILL.md` |
+| **translator** | translate, translation, language, multilingual, i18n, internationalization, Russian, Spanish, Chinese, localization | `skills/translator/SKILL.md` |
 
-## 🎯 Task → Skill Matching Guide
+### Infrastructure & Compliance
 
-| Your Task | Relevant Skill | Keywords |
-|-----------|---------------|----------|
-| "Plan a new feature" | `increment-planner` | "feature planning", "create increment" |
-| "Implement feature" | `increment-work-router` | "implement", "complete", "build", "work on" |
-| "Sync to JIRA" | `jira-sync` | "JIRA sync", "create JIRA issue" |
-| "Create diagram" | `diagrams-architect` | "architecture diagram", "C4 diagram" |
-| "Build React UI" | `frontend` | "React", "components", "UI" |
-| "Deploy to cloud" | `hetzner-provisioner` | "deploy", "infrastructure" |
-| "Quality check" | `increment-quality-judge-v2` | "quality check", "assess spec", "risk assessment" |
-| "E2E testing" | `e2e-playwright` | "E2E test", "browser test" |
-| "Generate docs site" | `docusaurus` | "documentation site", "docs" |
+| Skill | Triggers | Location |
+|-------|----------|----------|
+| **serverless-recommender** | serverless, AWS Lambda, Azure Functions, GCP Cloud Functions, Firebase, Supabase, which platform, serverless cost | `skills/serverless-recommender/SKILL.md` |
+| **compliance-architecture** | compliance, HIPAA, SOC2, SOC 2, GDPR, PCI-DSS, regulatory, healthcare data, payment card, audit, security standards | `skills/compliance-architecture/SKILL.md` |
 
 ---
 
-## ⚡ Why Skills Matter
-
-**Without skills**:
-- ❌ Reinvent workflows every session
-- ❌ Inconsistent increment structure
-- ❌ Miss SpecWeave conventions
-- ❌ Waste tokens on irrelevant docs
+## Quick Lookup Table
 
-**With skills**:
-- ✅ Proven workflows ready to use
-- ✅ Consistent high-quality output
-- ✅ SpecWeave best practices enforced
-- ✅ Efficient token usage (load only what's needed)
+| User Intent | Best Skill |
+|-------------|-----------|
+| "Plan a new feature" | `increment-planner` |
+| "Implement X" / "Build Y" | `increment-work-router` |
+| "Quality check" / "Review spec" | `increment-quality-judge-v2` |
+| "Close increment" / "/done" | `pm-closure-validation` |
+| "Sync to GitHub/JIRA" | `external-sync-wizard` |
+| "Archive old increments" | `archive-increments` |
+| "Bug/issue/broken" | `smart-reopen-detector` |
+| "AWS vs Azure vs GCP" | `serverless-recommender` |
+| "SOC2/HIPAA compliance" | `compliance-architecture` |
+| "Review my code" | `code-reviewer` |
 
 ---
 
-## 🔧 For AI Tool Developers
-
-This index simulates Claude Code's native progressive disclosure:
-- Claude pre-loads skill metadata at startup (name + description)
-- Other tools read this index file for same benefit
-- Single file read replaces 12 individual file scans
-- Token savings: ~97% (1 file vs 12 files)
-
-**How to use in your AI tool**:
-1. Load this file at session start
-2. Parse activation keywords
-3. Match user requests to keywords
-4. Load full SKILL.md when matched
-5. Execute skill workflow
-
----
+## Token Efficiency
 
-**Generated by**: `src/utils/generate-skills-index.ts`
+- **This index**: ~200 lines (~4KB)
+- **All skills loaded**: ~2,500 lines (~50KB)
+- **Savings**: ~92% by loading skills on-demand
 
-**Regenerate with**: `npm run generate-skills-index`
+**Pattern**: Load this index → Match triggers → Load only matched SKILL.md

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

@@ -100,7 +100,7 @@ const allProjects = result.projects;
 import { AreaPathMapper } from '../../../src/integrations/ado/area-path-mapper.js';
 
 const { selectedProject } = await inquirer.prompt([{
-  type: 'list',
+  type: 'select',
   name: 'selectedProject',
   message: 'Select ADO project to import area paths from:',
   choices: allProjects.map(p => ({ name: p.name, value: p.name }))

package/plugins/specweave-ado/lib/project-selector.js

@@ -33,7 +33,7 @@ async function selectAdoProjects(client, options = {}) {
 `);
   const { selectionMethod } = await inquirer.prompt([
     {
-      type: "list",
+      type: "select",
       name: "selectionMethod",
       message: "How would you like to select projects?",
       choices: [

package/plugins/specweave-ado/lib/project-selector.ts

@@ -103,7 +103,7 @@ export async function selectAdoProjects(
   // Decide selection method
   const { selectionMethod } = await inquirer.prompt([
     {
-      type: 'list',
+      type: 'select',
       name: 'selectionMethod',
       message: 'How would you like to select projects?',
       choices: [

package/plugins/specweave-ado/skills/ado-resource-validator/SKILL.md

@@ -428,7 +428,7 @@ export async function validateAzureDevOpsResources(
    ```typescript
    const { action } = await inquirer.prompt([
      {
-       type: 'list',
+       type: 'select',
        name: 'action',
        message: `Project "${projectName}" not found. What would you like to do?`,
        choices: [

package/plugins/specweave-github/lib/completion-calculator.js

@@ -99,8 +99,11 @@ class CompletionCalculator {
    * Process:
    * 1. Find increment link in user story's "Implementation" section
    * 2. Read increment's tasks.md
-   * 3. Filter tasks that reference this user story's ACs
+   * 3. Filter tasks that reference this user story (via **User Story** field OR AC-IDs)
    * 4. Extract completion status from **Status**: [x] or [ ]
+   *
+   * IMPORTANT: Checks **User Story** field FIRST (handles multi-story tasks like "US-001, US-002"),
+   * then falls back to AC-based filtering. Also handles "Satisfies ACs: All" correctly.
    */
   async extractTasks(userStoryContent, userStoryId) {
     const tasks = [];
@@ -125,33 +128,48 @@ class CompletionCalculator {
       return tasks;
     }
     const tasksContent = await readFile(tasksPath, "utf-8");
+    const normalizeUsId = (id) => {
+      const num = id.replace(/^US-?0*/, "");
+      return `US-${num.padStart(3, "0")}`;
+    };
+    const normalizedCurrentUs = normalizeUsId(userStoryId);
     const taskPattern = /###?\s+(T-\d+):\s*([^\n]+)\n([\s\S]*?)(?=\n###?\s+T-\d+:|$)/g;
     let match;
     while ((match = taskPattern.exec(tasksContent)) !== null) {
       const taskId = match[1];
       const taskTitle = match[2].trim();
       const taskBody = match[3];
-      const acMatch = taskBody.match(/\*\*(?:Satisfies ACs?|AC)\*\*:\s*([^\n]+)/);
-      if (!acMatch) {
-        continue;
+      const userStoryFieldMatch = taskBody.match(/\*\*User Story\*\*:\s*([^\n]+)/);
+      let belongsToThisUS = false;
+      if (userStoryFieldMatch) {
+        const userStoryList = userStoryFieldMatch[1].trim();
+        const userStoryIds = userStoryList.split(",").map((us) => us.trim());
+        belongsToThisUS = userStoryIds.some((usId) => {
+          return normalizeUsId(usId) === normalizedCurrentUs;
+        });
+      }
+      if (!belongsToThisUS) {
+        const acMatch2 = taskBody.match(/\*\*(?:Satisfies ACs?|AC)\*\*:\s*([^\n]+)/);
+        if (acMatch2) {
+          const acList = acMatch2[1].trim();
+          if (acList.toLowerCase() !== "all") {
+            const acIds2 = acList.split(",").map((ac) => ac.trim());
+            belongsToThisUS = acIds2.some((acId) => {
+              const usMatch = acId.match(/AC-([A-Z]+\d+)-/);
+              if (!usMatch) return false;
+              const extractedUsId = usMatch[1];
+              return normalizeUsId(extractedUsId) === normalizedCurrentUs;
+            });
+          }
+        }
       }
-      const acList = acMatch[1].trim();
-      const acIds = acList.split(",").map((ac) => ac.trim());
-      const belongsToThisUS = acIds.some((acId) => {
-        const usMatch = acId.match(/AC-([A-Z]+\d+)-/);
-        if (!usMatch) return false;
-        const extractedUsId = usMatch[1];
-        const extractedNum = extractedUsId.replace(/^US/, "");
-        const normalizedExtracted = `US-${extractedNum.padStart(3, "0")}`;
-        const currentNum = userStoryId.replace(/^US-?/, "");
-        const normalizedCurrent = `US-${currentNum.padStart(3, "0")}`;
-        return normalizedExtracted === normalizedCurrent;
-      });
       if (!belongsToThisUS) {
         continue;
       }
       const statusMatch = taskBody.match(/\*\*Status\*\*:\s*\[([x ])\]/);
       const completed = statusMatch ? statusMatch[1] === "x" : false;
+      const acMatch = taskBody.match(/\*\*(?:Satisfies ACs?|AC)\*\*:\s*([^\n]+)/);
+      const acIds = acMatch ? acMatch[1].trim().split(",").map((ac) => ac.trim()) : [];
       tasks.push({
         id: taskId,
         title: taskTitle,