specweave 0.10.1 → 0.12.0

package/plugins/specweave/lib/hooks/types/reflection-types.ts

@@ -0,0 +1,193 @@
+/**
+ * Type definitions for AI Self-Reflection System
+ * @module reflection-types
+ */
+
+/**
+ * Severity levels for identified issues
+ */
+export enum IssueSeverity {
+  CRITICAL = 'CRITICAL',
+  HIGH = 'HIGH',
+  MEDIUM = 'MEDIUM',
+  LOW = 'LOW'
+}
+
+/**
+ * Issue categories
+ */
+export enum IssueCategory {
+  SECURITY = 'SECURITY',
+  QUALITY = 'QUALITY',
+  TESTING = 'TESTING',
+  PERFORMANCE = 'PERFORMANCE',
+  TECHNICAL_DEBT = 'TECHNICAL_DEBT'
+}
+
+/**
+ * Reflection depth modes
+ */
+export enum ReflectionDepth {
+  QUICK = 'quick',       // <15s, critical issues only
+  STANDARD = 'standard', // <30s, full analysis (default)
+  DEEP = 'deep'          // <60s, detailed + architectural
+}
+
+/**
+ * AI model selection for reflection
+ */
+export enum ReflectionModel {
+  HAIKU = 'haiku',     // Fast, cheap (~$0.01/task)
+  SONNET = 'sonnet',   // Balanced (~$0.05/task)
+  OPUS = 'opus'        // Deep analysis (~$0.15/task)
+}
+
+/**
+ * Reflection execution mode
+ */
+export enum ReflectionMode {
+  AUTO = 'auto',       // Automatic after task completion
+  MANUAL = 'manual',   // User-triggered only
+  DISABLED = 'disabled' // Reflection disabled
+}
+
+/**
+ * Issue identified during reflection
+ */
+export interface ReflectionIssue {
+  severity: IssueSeverity;
+  category: IssueCategory;
+  description: string;
+  impact: string;
+  recommendation: string;
+  location?: {
+    file: string;
+    line?: number;
+    snippet?: string;
+  };
+}
+
+/**
+ * Lesson learned from task execution
+ */
+export interface LessonLearned {
+  whatWentWell: string[];
+  whatCouldImprove: string[];
+  forNextTime: string[];
+}
+
+/**
+ * Quality metrics from reflection
+ */
+export interface ReflectionMetrics {
+  codeQuality: number;      // 1-10 rating
+  security: number;         // 1-10 rating
+  testCoverage?: number;    // Percentage or null
+  technicalDebt: 'LOW' | 'MEDIUM' | 'HIGH';
+  performance: 'GOOD' | 'ACCEPTABLE' | 'NEEDS_WORK';
+}
+
+/**
+ * Complete reflection result
+ */
+export interface ReflectionResult {
+  taskName: string;
+  completed: string;        // ISO timestamp
+  duration?: string;
+  filesModified: {
+    count: number;
+    linesAdded: number;
+    linesRemoved: number;
+  };
+  accomplishments: string[];
+  strengths: string[];
+  issues: ReflectionIssue[];
+  recommendedActions: {
+    priority1: string[];  // MUST FIX
+    priority2: string[];  // SHOULD FIX
+    priority3: string[];  // NICE TO HAVE
+  };
+  lessonsLearned: LessonLearned;
+  metrics: ReflectionMetrics;
+  relatedTasks?: string[];
+  metadata: {
+    model: ReflectionModel;
+    reflectionTime: number; // seconds
+    estimatedCost: number;  // USD
+  };
+}
+
+/**
+ * Configuration for reflection system
+ */
+export interface ReflectionConfig {
+  enabled: boolean;
+  mode: ReflectionMode;
+  depth: ReflectionDepth;
+  model: ReflectionModel;
+  categories: {
+    security: boolean;
+    quality: boolean;
+    testing: boolean;
+    performance: boolean;
+    technicalDebt: boolean;
+  };
+  criticalThreshold: IssueSeverity;
+  storeReflections: boolean;
+  autoCreateFollowUpTasks: boolean;
+  soundNotifications?: boolean;
+}
+
+/**
+ * Git diff information for modified files
+ */
+export interface GitDiffInfo {
+  file: string;
+  linesAdded: number;
+  linesRemoved: number;
+  content: string;
+}
+
+/**
+ * Context for reflection execution
+ */
+export interface ReflectionContext {
+  incrementId: string;
+  taskId: string;
+  modifiedFiles: GitDiffInfo[];
+  config: ReflectionConfig;
+}
+
+/**
+ * Reflection execution result (success or failure)
+ */
+export interface ReflectionExecutionResult {
+  success: boolean;
+  result?: ReflectionResult;
+  error?: {
+    message: string;
+    code: string;
+    details?: any;
+  };
+}
+
+/**
+ * Default reflection configuration
+ */
+export const DEFAULT_REFLECTION_CONFIG: ReflectionConfig = {
+  enabled: true,
+  mode: ReflectionMode.AUTO,
+  depth: ReflectionDepth.STANDARD,
+  model: ReflectionModel.HAIKU,
+  categories: {
+    security: true,
+    quality: true,
+    testing: true,
+    performance: true,
+    technicalDebt: true
+  },
+  criticalThreshold: IssueSeverity.MEDIUM,
+  storeReflections: true,
+  autoCreateFollowUpTasks: false,
+  soundNotifications: false
+};

package/plugins/specweave/lib/hooks/update-tasks-md.ts

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+
+/**
+ * SpecWeave Tasks.md Auto-Updater
+ *
+ * Automatically updates tasks.md completion status after TodoWrite completes tasks.
+ *
+ * Usage:
+ *   node dist/hooks/lib/update-tasks-md.js <incrementId>
+ *
+ * Example:
+ *   node dist/hooks/lib/update-tasks-md.js 0006-llm-native-i18n
+ *
+ * What it does:
+ * 1. Reads tasks.md for the given increment
+ * 2. Finds recently completed tasks from TodoWrite
+ * 3. Updates "[ ]" to "[x]" for completed tasks
+ * 4. Updates "Status: ⏳ Pending" to "Status: [x] Completed"
+ * 5. Recalculates progress percentage
+ * 6. Writes back to tasks.md
+ *
+ * @author SpecWeave Team
+ * @version 1.0.0
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+
+interface TaskMatch {
+  taskId: string;
+  lineNumber: number;
+  currentStatus: 'pending' | 'in_progress' | 'completed';
+}
+
+/**
+ * Main function - update tasks.md for given increment
+ */
+async function updateTasksMd(incrementId: string): Promise<void> {
+  try {
+    console.log(`\n🔄 Updating tasks.md for increment: ${incrementId}`);
+
+    // 1. Validate increment exists
+    const incrementDir = path.join(process.cwd(), '.specweave', 'increments', incrementId);
+    if (!fs.existsSync(incrementDir)) {
+      console.error(`❌ Increment directory not found: ${incrementDir}`);
+      process.exit(1);
+    }
+
+    const tasksPath = path.join(incrementDir, 'tasks.md');
+    if (!fs.existsSync(tasksPath)) {
+      console.error(`❌ tasks.md not found: ${tasksPath}`);
+      process.exit(1);
+    }
+
+    // 2. Read tasks.md
+    const originalContent = await fs.readFile(tasksPath, 'utf-8');
+    const lines = originalContent.split('\n');
+
+    console.log(`📖 Read tasks.md (${lines.length} lines)`);
+
+    // 3. Parse task completion status
+    const tasks = parseTaskStatus(lines);
+    console.log(`📋 Found ${tasks.length} tasks`);
+
+    // 4. Get recently completed tasks from environment (passed by hook)
+    // For now, we'll mark tasks as complete if they match a heuristic
+    // TODO: In future, hook will pass completed task IDs via env var
+    const completedTasks = detectCompletedTasks(lines);
+
+    if (completedTasks.length === 0) {
+      console.log('✅ No new task completions detected');
+      return;
+    }
+
+    console.log(`🎯 Detected ${completedTasks.length} completed task(s):`, completedTasks);
+
+    // 5. Update task status in content
+    let updatedContent = originalContent;
+
+    for (const taskId of completedTasks) {
+      updatedContent = markTaskComplete(updatedContent, taskId);
+    }
+
+    // 6. Recalculate progress
+    const updatedLines = updatedContent.split('\n');
+    const totalTasks = countTotalTasks(updatedLines);
+    const completedCount = countCompletedTasks(updatedLines);
+    const progress = Math.round((completedCount / totalTasks) * 100);
+
+    console.log(`📊 Progress: ${completedCount}/${totalTasks} (${progress}%)`);
+
+    // 7. Update header with new progress
+    updatedContent = updateProgressHeader(updatedContent, completedCount, totalTasks, progress);
+
+    // 8. Write back to tasks.md
+    await fs.writeFile(tasksPath, updatedContent, 'utf-8');
+
+    console.log(`✅ Updated ${tasksPath}`);
+    console.log(`   Completed: ${completedCount}/${totalTasks}`);
+    console.log(`   Progress: ${progress}%\n`);
+
+  } catch (error) {
+    console.error('❌ Error updating tasks.md:', error);
+    process.exit(1);
+  }
+}
+
+/**
+ * Parse task status from lines
+ */
+function parseTaskStatus(lines: string[]): TaskMatch[] {
+  const tasks: TaskMatch[] = [];
+  const taskPattern = /^###\s+(T-?\d+[-A-Z]*):?\s+(.+)/; // Matches "### T-001: Task Name" or "### T-001-DISCIPLINE:"
+
+  lines.forEach((line, index) => {
+    const match = line.match(taskPattern);
+    if (match) {
+      const taskId = match[1];
+
+      // Look ahead for status line
+      let status: 'pending' | 'in_progress' | 'completed' = 'pending';
+
+      for (let i = index + 1; i < Math.min(index + 5, lines.length); i++) {
+        const nextLine = lines[i];
+        if (nextLine.includes('**Status**:')) {
+          if (nextLine.includes('[x] Completed')) {
+            status = 'completed';
+          } else if (nextLine.includes('⏳ Pending') || nextLine.includes('[ ] Pending')) {
+            status = 'pending';
+          } else if (nextLine.includes('🔄 In Progress') || nextLine.includes('in_progress')) {
+            status = 'in_progress';
+          }
+          break;
+        }
+      }
+
+      tasks.push({
+        taskId,
+        lineNumber: index,
+        currentStatus: status,
+      });
+    }
+  });
+
+  return tasks;
+}
+
+/**
+ * Detect which tasks are completed (heuristic-based for now)
+ * TODO: In future, hook will pass completed task IDs via env var
+ */
+function detectCompletedTasks(lines: string[]): string[] {
+  // For now, this is a placeholder - we'll mark tasks as complete
+  // if they have implementation sections or "COMPLETE" markers
+  const completedTasks: string[] = [];
+
+  // This function will be enhanced in future versions
+  // For MVP, we'll rely on manual marking in tasks.md
+
+  return completedTasks;
+}
+
+/**
+ * Mark a specific task as complete
+ */
+function markTaskComplete(content: string, taskId: string): string {
+  let updated = content;
+
+  // Pattern: "**Status**: [ ] Pending" or "**Status**: ⏳ Pending"
+  const statusPattern = new RegExp(
+    `(###\\s+${taskId.replace(/[-]/g, '\\-')}[^\\n]*[\\s\\S]*?\\*\\*Status\\*\\*:)\\s*\\[?\\s*\\]?\\s*⏳?\\s*Pending`,
+    'i'
+  );
+
+  updated = updated.replace(statusPattern, '$1 [x] Completed');
+
+  return updated;
+}
+
+/**
+ * Count total tasks
+ */
+function countTotalTasks(lines: string[]): number {
+  let count = 0;
+  const taskPattern = /^###\s+(T-?\d+[-A-Z]*):?\s+/;
+
+  for (const line of lines) {
+    if (taskPattern.test(line)) {
+      count++;
+    }
+  }
+
+  return count;
+}
+
+/**
+ * Count completed tasks
+ */
+function countCompletedTasks(lines: string[]): number {
+  let count = 0;
+  const taskPattern = /^###\s+(T-?\d+[-A-Z]*):?\s+/;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (taskPattern.test(line)) {
+      // Look ahead for status line
+      for (let j = i + 1; j < Math.min(i + 5, lines.length); j++) {
+        const nextLine = lines[j];
+        if (nextLine.includes('**Status**:') && nextLine.includes('[x] Completed')) {
+          count++;
+          break;
+        }
+      }
+    }
+  }
+
+  return count;
+}
+
+/**
+ * Update progress header
+ */
+function updateProgressHeader(content: string, completed: number, total: number, progress: number): string {
+  let updated = content;
+
+  // Update "**Completed**: X"
+  updated = updated.replace(/\*\*Completed\*\*:\s*\d+/, `**Completed**: ${completed}`);
+
+  // Update "**Progress**: X%"
+  updated = updated.replace(/\*\*Progress\*\*:\s*\d+%/, `**Progress**: ${progress}%`);
+
+  // Update "**Total Tasks**: X"
+  updated = updated.replace(/\*\*Total Tasks\*\*:\s*\d+/, `**Total Tasks**: ${total}`);
+
+  return updated;
+}
+
+// CLI entry point
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+
+if (isMainModule) {
+  const incrementId = process.argv[2];
+
+  if (!incrementId) {
+    console.error('❌ Usage: update-tasks-md <incrementId>');
+    console.error('   Example: update-tasks-md 0006-llm-native-i18n');
+    process.exit(1);
+  }
+
+  updateTasksMd(incrementId).catch((error) => {
+    console.error('❌ Fatal error:', error);
+    process.exit(1);
+  });
+}
+
+export { updateTasksMd };

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

@@ -39,9 +39,9 @@ Step 4: Execute → Follow the increment planning workflow
 
 #### plugin-installer
 
-**Description**: Proactive just-in-time plugin installation. Auto-detects when specialized plugins are needed (docs-preview, frontend, kubernetes, ML, payments, testing, etc.) and installs them automatically before use. Activates for preview docs, Docusaurus, React, Next.js, K8s, Kubernetes, Helm, TensorFlow, PyTorch, ML model, Stripe, billing, payment, Playwright, E2E testing, Figma, design system, ADO, Azure DevOps, infrastructure, Prometheus, Grafana, monitoring, Node.js, Python backend, REST API, cloud deployment, diagram, Mermaid, C4, architecture diagram.
+**Description**: Proactive just-in-time plugin installation. Auto-detects when specialized plugins are needed (frontend, kubernetes, ML, payments, testing, etc.) and installs them automatically before use. Activates for React, Next.js, K8s, Kubernetes, Helm, TensorFlow, PyTorch, ML model, Stripe, billing, payment, Playwright, E2E testing, Figma, design system, ADO, Azure DevOps, infrastructure, Prometheus, Grafana, monitoring, Node.js, Python backend, REST API, cloud deployment, diagram, Mermaid, C4, architecture diagram.
 
-**Activates for**: preview docs, documentation UI, Docusaurus, React, Next.js, frontend, UI component, K8s, Kubernetes, deploy, TensorFlow, ML model, Stripe, billing, E2E testing, Figma, diagram, architecture diagram
+**Activates for**: React, Next.js, frontend, UI component, K8s, Kubernetes, deploy, TensorFlow, ML model, Stripe, billing, E2E testing, Figma, diagram, architecture diagram
 
 **Location**: `.claude/skills/plugin-installer/SKILL.md`
 

package/plugins/specweave/skills/increment-planner/SKILL.md

@@ -72,6 +72,14 @@ Use this skill when:
 - **Experiments**: Structuring POCs and technical spikes
 - **Brownfield**: Structuring modifications to existing codebases
 
+## When NOT to Use This Skill
+
+Do NOT activate if:
+- ❌ User is asking general questions about SpecWeave (use documentation instead)
+- ❌ Another skill (e.g., `project-kickstarter`) is already handling the request
+- ❌ User is already in an active increment planning workflow
+- ❌ Increment files (spec.md, plan.md, tasks.md) are currently being created
+
 ## Activation Triggers
 
 This skill activates automatically when users say:
@@ -522,99 +530,24 @@ created: YYYY-MM-DD
 - Measurable acceptance criteria
 - Prioritized user stories (P1/P2/P3)
 
-### Step 6: Detect Required Plugins & Check PM Tool (INTELLIGENT AUTO-LOADING + PM SYNC)
-
-**Purpose**: Analyze spec content to identify required SpecWeave plugins AND check if external PM tool sync is configured.
-
-**⚠️ CRITICAL**: For ALL plugin installations, consult the `plugin-expert` skill for correct syntax. NEVER use `@marketplace` suffix!
-
-**Why This Matters**:
-1. SpecWeave's plugin system enables context efficiency (70%+ reduction) by loading only relevant capabilities
-2. PM tool integration enables automatic sync of increment progress to external systems (GitHub Issues, Jira, Azure DevOps)
-
-**Detection Algorithm**:
-
-1. **Scan spec.md for keywords**:
-   ```
-   Keywords → Plugin Mapping:
-   - "GitHub", "issue", "pull request", "PR" → specweave-github
-   - "Jira", "ticket", "epic" → specweave-jira
-   - "Azure DevOps", "ADO", "work item" → specweave-ado
-   - "Kubernetes", "K8s", "Helm", "kubectl" → specweave-kubernetes
-   - "Figma", "design system", "design tokens" → specweave-figma
-   - "Stripe", "PayPal", "billing", "subscriptions" → specweave-payments
-   - "React", "Next.js", "Vue", "Angular" → specweave-frontend
-   - "Express", "Fastify", "NestJS", "FastAPI" → specweave-backend
-   - "TensorFlow", "PyTorch", "ML", "training" → specweave-ml
-   - "Prometheus", "Grafana", "monitoring" → specweave-infrastructure
-   - "Playwright", "E2E", "browser tests" → specweave-testing
-   - "Mermaid", "C4", "diagrams", "architecture diagrams" → specweave-diagrams
-   ```
-
-2. **Check External PM Tool Configuration** (NEW v0.8.0):
-   - Read `.specweave/config.json`
-   - If `externalPM.enabled = true` and `externalPM.tool` is set:
-     - Check if corresponding plugin installed (specweave-github, specweave-jira, or specweave-ado)
-     - Prepare to auto-create external issue/work item after increment creation
-   - If `externalPM.enabled = false` or not configured:
-     - Skip PM tool sync (local-only mode)
-
-3. **Check if plugins are already installed**:
-   - For Claude Code: Check if plugin available via `/plugin list --installed`
-   - Skip already-installed plugins
-
-4. **🚨 AUTOMATIC PLUGIN INSTALLATION** (if plugins detected):
-
-   **IMPORTANT**: When you detect required plugins, you MUST:
-   - ✅ Proactively offer to install them (not just suggest)
-   - ✅ Explain WHY each plugin is needed (based on detected keywords)
-   - ✅ Show clear install commands
-   - ✅ Remind user that plugins provide expert AI agents and capabilities
+### Step 6: Check PM Tool Configuration (PM SYNC)
 
-   **Output Format**:
-   ```
-   🔌 Detected plugin requirements from spec content:
+**Purpose**: Check if external PM tool sync is configured for automatic increment tracking.
 
-   REQUIRED (will significantly improve implementation):
-   • specweave-github - GitHub Issues integration
-     Detected: "sync tasks to GitHub issues", "create pull requests"
-     Provides: GitHub sync, PR automation, issue tracking
-     → Without this: Manual GitHub sync required
+**Why This Matters**: PM tool integration enables automatic sync of increment progress to external systems (GitHub Issues, Jira, Azure DevOps).
 
-   • specweave-kubernetes - Kubernetes deployment
-     Detected: "deploy to production cluster", "kubectl apply"
-     Provides: K8s expert agent, Helm chart generation, deployment validation
-     → Without this: Manual K8s configuration, no validation
+**⚠️ NOTE**: All SpecWeave plugins (19+) are already installed during `specweave init`. No plugin detection or installation needed!
 
-   OPTIONAL (helpful but not critical):
-   • specweave-diagrams - Architecture diagrams
-     Detected: "system architecture", "component diagram"
-     Provides: Mermaid + C4 diagram generation
-     → Without this: Manual diagram creation
+**Check External PM Tool Configuration**:
 
-   📦 Install recommended plugins:
-     /plugin install specweave-github
-     /plugin install specweave-kubernetes
-
-   📦 Install optional plugins:
-     /plugin install specweave-diagrams
-
-   💡 Benefits:
-     • Plugins provide specialized AI agents (GitHub expert, K8s expert, etc.)
-     • Skills auto-activate based on context (zero manual invocation)
-     • 70%+ context reduction (only load what you need)
-     • Best practices built-in (from real-world experience)
-
-   Would you like me to wait while you install these plugins? (Recommended)
-   Or shall I continue without them? (Limited capabilities)
-   ```
-
-   **User Decision Points**:
-   - If user installs plugins → continue with full capabilities
-   - If user skips → continue but remind about limitations later
-   - NEVER block increment creation (plugins are enhancements, not requirements)
+1. **Read `.specweave/config.json`**:
+   - If `externalPM.enabled = true` and `externalPM.tool` is set:
+     - Corresponding plugin is already installed (specweave-github, specweave-jira, or specweave-ado)
+     - Prepare to auto-create external issue/work item after increment creation
+   - If `externalPM.enabled = false` or not configured:
+     - Skip PM tool sync (local-only mode)
 
-5. **Auto-Sync to PM Tool** (v0.8.0+):
+2. **Auto-Sync to PM Tool** (v0.8.0+):
 
    **🚨 CRITICAL: SpecWeave Repo Dog-Food Requirement**:
    - IF repo = "anton-abyzov/specweave"
@@ -683,10 +616,6 @@ Files:
 • plan.md (technical architecture)
 • tasks.md (implementation steps with embedded tests)
 
-🔌 Plugin Detection:
-   Detected: "user authentication", "JWT tokens", "session management"
-   → No additional plugins required
-
 🔗 External PM Tool Sync:
    Tool: GitHub Issues
    Plugin: specweave-github ✅ Installed
@@ -706,7 +635,7 @@ Next steps:
 ```
 
 **Integration with Existing Workflow**:
-- Plugin detection is a **suggestion step** (not blocking)
+- All plugins are already installed during `specweave init` (no detection needed)
 - PM tool sync is **automatic** if configured (zero manual intervention)
 - Increment creation continues regardless of PM tool status
 - This implements the "seamless integration" philosophy

package/plugins/specweave/skills/plugin-expert/SKILL.md

@@ -178,10 +178,6 @@ For contributors working on SpecWeave itself:
   - Install: `/plugin install specweave-diagrams`
   - Provides: Architecture diagram generation, C4 model support
 
-- **specweave-docs-preview** - Docusaurus documentation preview
-  - Install: `/plugin install specweave-docs-preview`
-  - Provides: Beautiful docs UI, hot reload, Mermaid rendering
-
 ---
 
 ## Common Mistakes to Avoid