specweave 0.11.0 → 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:

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

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

@@ -40,8 +40,6 @@ description: DEPRECATED - This skill is no longer needed. All plugins are now in
 
 | User Keywords | Required Plugin | Installation Command |
 |--------------|----------------|---------------------|
-| **Documentation Preview** |
-| "preview docs", "browse docs locally", "documentation UI", "Docusaurus server", "local docs preview" | `specweave-docs-preview` | `/plugin install specweave-docs-preview` |
 | **Frontend Development** |
 | "React", "Next.js", "Vue", "Angular", "frontend", "UI component", "design system", "Tailwind" | `specweave-frontend` | `/plugin install specweave-frontend` |
 | **Kubernetes/DevOps** |
@@ -77,10 +75,10 @@ When user mentions keywords from the map above, **IMMEDIATELY** check if the req
 
 **Example**:
 ```
-User: "Can you preview the internal docs locally?"
+User: "Can you help me build a React component?"
 
-Keywords detected: "preview", "docs", "locally"
-→ Required plugin: specweave-docs-preview
+Keywords detected: "React", "component"
+→ Required plugin: specweave-frontend
 ```
 
 ### Step 2: Check if Plugin is Installed
@@ -101,7 +99,7 @@ If the plugin is NOT installed:
 /plugin install <plugin-name>
 
 # Example:
-/plugin install specweave-docs-preview
+/plugin install specweave-frontend
 ```
 
 ### Step 4: Notify User (Clear and Friendly)
@@ -123,9 +121,9 @@ Proceeding with your request...
 **Example**:
 
 ```
-🔌 Detected need for specweave-docs-preview plugin
+🔌 Detected need for specweave-frontend plugin
 
-📦 Installing specweave-docs-preview...
+📦 Installing specweave-frontend...
    This plugin provides: Beautiful Docusaurus UI for browsing .specweave/docs/
 
 ✅ Plugin installed successfully!
@@ -145,25 +143,25 @@ Proceeding to launch docs preview server...
 
 ## Common Scenarios
 
-### Scenario 1: Documentation Preview
+### Scenario 1: React Component Development
 
-**User Request**: "Show me the internal docs in a nice UI"
+**User Request**: "Build a React component with TypeScript"
 
 **Workflow**:
 ```
-1. Detect keywords: "docs", "UI"
-   → Required: specweave-docs-preview
+1. Detect keywords: "React", "component", "TypeScript"
+   → Required: specweave-frontend
 
 2. Check installed: /plugin list --installed
    → Not found
 
-3. Install: /plugin install specweave-docs-preview
+3. Install: /plugin install specweave-frontend
 
 4. Notify user:
-   🔌 Installing specweave-docs-preview for beautiful docs UI...
+   🔌 Installing specweave-frontend for React development...
    ✅ Installed!
 
-5. Launch: /specweave:docs preview
+5. Create component using frontend skills
 ```
 
 ### Scenario 2: Kubernetes Deployment
@@ -280,16 +278,16 @@ When increment-planner detects plugin requirements (Step 6), it should:
 3. **Auto-install missing plugins** (via this skill)
 4. **Then proceed** with increment planning
 
-### Example: docs-preview skill (hypothetical)
+### Example: frontend skill (hypothetical)
 
 ```markdown
-# BEFORE using Docusaurus features:
+# BEFORE using React features:
 
-1. Check if specweave-docs-preview is installed
+1. Check if specweave-frontend is installed
    → If not: Invoke plugin-installer skill
-   → Auto-install specweave-docs-preview
+   → Auto-install specweave-frontend
 
-2. Then launch Docusaurus server
+2. Then proceed with component creation
 ```
 
 ---
@@ -311,7 +309,7 @@ When increment-planner detects plugin requirements (Step 6), it should:
 User: "Show me the internal documentation in a browser"
 
 Expected:
-1. Detects "documentation", "browser" → specweave-docs-preview
+1. Detects "React", "component" → specweave-frontend
 2. Checks installed
 3. Auto-installs if missing
 4. Launches preview

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

@@ -92,7 +92,6 @@ This skill ensures that your SpecWeave environment is properly configured with a
 - **specweave-backend-nodejs**: nodejs, express, fastify, nestjs, backend
 - **specweave-backend-python**: python, fastapi, django, flask
 - **specweave-backend-dotnet**: dotnet, .net, aspnet, c#
-- **specweave-docs-preview**: documentation, docs, preview, docusaurus
 - **specweave-e2e-testing**: playwright, e2e, end-to-end, browser
 
 ## Usage Examples

package/plugins/specweave/skills/project-kickstarter/SKILL.md

@@ -115,7 +115,7 @@ Let's start: [Ask 1 clarifying question if needed, otherwise proceed]"
 
 Once I have these details, I'll guide you through SpecWeave's increment planning process."
 
-[Wait for response, then route to increment-planner or spec-driven-brainstorming]
+[Wait for response, then route to the planning workflow]
 ```
 
 **Low Confidence:**
@@ -331,8 +331,8 @@ User message → specweave-detector (checks .specweave/ exists)
 **Calls:**
 - `specweave-detector` - Checks if .specweave/ directory exists (SpecWeave context)
 - `/specweave:inc` - For clear requirements (high confidence)
-- `spec-driven-brainstorming` - For unclear requirements (medium confidence)
-- `increment-planner` - Directly if enough detail provided
+- Spec-driven brainstorming - For unclear requirements (medium confidence)
+- Planning workflow - Directly if enough detail provided
 
 **Called By:**
 - Automatically when pattern detected in SpecWeave folder

package/plugins/specweave/skills/spec-generator/SKILL.md

@@ -350,9 +350,9 @@ spec_generator:
 
 ## Related Skills
 
-- **increment-planner**: Guides increment planning (uses Spec Generator internally)
-- **context-loader**: Loads relevant context for specification generation
-- **increment-quality-judge**: Validates generated specifications for completeness
+- **Planning workflow**: Guides increment planning (uses Spec Generator internally)
+- **Context loading**: Loads relevant context for specification generation
+- **Quality validation**: Validates generated specifications for completeness
 
 ---
 

package/plugins/specweave-docs-preview/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "specweave-docs-preview",
+  "description": "Interactive documentation preview with Docusaurus. Launch local dev server to view living documentation in beautiful UI with hot reload, auto-generated sidebar, and Mermaid diagrams. Build static sites for deployment.",
+  "version": "1.0.0",
+  "author": {
+    "name": "SpecWeave Team",
+    "url": "https://spec-weave.com"
+  },
+  "homepage": "https://spec-weave.com",
+  "repository": "https://github.com/anton-abyzov/specweave",
+  "license": "MIT",
+  "keywords": [
+    "docusaurus",
+    "documentation",
+    "preview",
+    "docs-server",
+    "hot-reload",
+    "static-site",
+    "specweave"
+  ]
+}