specweave 0.17.16 → 0.18.0

package/plugins/specweave/lib/hooks/sync-living-docs.ts

@@ -87,10 +87,11 @@ async function syncLivingDocs(incrementId: string): Promise<void> {
       specCopied = result.success;
       changedDocs = result.changedFiles;
     } else {
-      // Simple mode: Copy spec to living docs (legacy)
-      console.log('📋 Using simple sync mode (legacy)');
-      specCopied = await copyIncrementSpecToLivingDocs(incrementId);
-      changedDocs = detectChangedDocs();
+      // Hierarchical distribution mode: Epic + User Stories (v2.1)
+      console.log('📊 Using hierarchical distribution mode (v2.1 - Epic + User Stories)');
+      const result = await hierarchicalDistribution(incrementId);
+      specCopied = result.success;
+      changedDocs = result.changedFiles;
     }
 
     if (changedDocs.length === 0 && !specCopied) {
@@ -113,58 +114,81 @@ async function syncLivingDocs(incrementId: string): Promise<void> {
 
 /**
  * Intelligent sync using the new architecture (v0.18.0+)
+ *
+ * NOTE: syncIncrement not yet implemented, fallback to hierarchical distribution
  */
 async function intelligentSyncLivingDocs(
   incrementId: string,
   config: Config
+): Promise<{ success: boolean; changedFiles: string[] }> {
+  console.log('   ⚠️  Intelligent sync not yet fully implemented');
+  console.log('   Falling back to hierarchical distribution mode...');
+
+  // Fallback to hierarchical distribution
+  return await hierarchicalDistribution(incrementId);
+}
+
+/**
+ * Hierarchical distribution using new architecture (v2.1 - Epic + User Stories)
+ *
+ * Distributes increment spec into hierarchical structure:
+ * - Epic file (SPEC-###.md) - High-level summary (50-80 lines)
+ * - User story files (us-###.md) - Detailed requirements (80-120 lines each)
+ * - Links to tasks.md for implementation details
+ */
+async function hierarchicalDistribution(
+  incrementId: string
 ): Promise<{ success: boolean; changedFiles: string[] }> {
   try {
     // Dynamic import to avoid circular dependencies
-    const { syncIncrement } = await import('../../../../src/core/living-docs/index.js');
-
-    console.log('   📖 Parsing and classifying spec sections...');
-
-    const result = await syncIncrement(incrementId, {
-      verbose: false, // We'll log our own summary
-      dryRun: false,
-      parser: {
-        preserveCodeBlocks: true,
-        preserveLinks: true,
-        preserveImages: true,
-      },
-      distributor: {
-        generateFrontmatter: true,
-        preserveOriginal: config.livingDocs?.intelligent?.preserveOriginal ?? true,
-      },
-      linker: {
-        generateBacklinks: config.livingDocs?.intelligent?.generateCrossLinks ?? true,
-        updateExisting: true,
-      },
+    const { SpecDistributor } = await import('../../../../src/core/living-docs/index.js');
+
+    console.log('   📊 Parsing and distributing spec into hierarchical structure...');
+
+    const projectRoot = process.cwd();
+    const distributor = new SpecDistributor(projectRoot, {
+      overwriteExisting: false,
+      createBackups: true,
     });
 
+    const result = await distributor.distribute(incrementId);
+
+    if (!result.success) {
+      console.error(`   ❌ Distribution failed with errors:`);
+      for (const error of result.errors) {
+        console.error(`      - ${error}`);
+      }
+      return { success: false, changedFiles: [] };
+    }
+
     // Log summary
-    console.log(`   ✅ Intelligent sync complete:`);
-    console.log(`      Project: ${result.project.name} (${(result.project.confidence * 100).toFixed(0)}% confidence)`);
-    console.log(`      Files created: ${result.distribution.summary.filesCreated}`);
-    console.log(`      Files updated: ${result.distribution.summary.filesUpdated}`);
-    console.log(`      Cross-links: ${result.links.length}`);
-    console.log(`      Duration: ${result.duration}ms`);
+    console.log(`   ✅ Hierarchical distribution complete:`);
+    console.log(`      Epic ID: ${result.specId}`);
+    console.log(`      User Stories: ${result.totalStories}`);
+    console.log(`      Files created: ${result.totalFiles}`);
+    console.log(`      Epic: ${path.basename(result.epicPath)}`);
+    console.log(`      User story files: ${result.userStoryPaths.length}`);
+
+    if (result.warnings.length > 0) {
+      console.log(`   ⚠️  Warnings:`);
+      for (const warning of result.warnings) {
+        console.log(`      - ${warning}`);
+      }
+    }
 
     // Collect changed file paths
-    const changedFiles = [
-      ...result.distribution.created.map((f) => f.path),
-      ...result.distribution.updated.map((f) => f.path),
-    ];
+    const changedFiles = [result.epicPath, ...result.userStoryPaths];
 
     return {
-      success: result.success,
+      success: true,
       changedFiles,
     };
   } catch (error) {
-    console.error(`   ❌ Intelligent sync failed: ${error}`);
-    console.error('   Falling back to simple sync mode...');
+    console.error(`   ❌ Hierarchical distribution failed: ${error}`);
+    console.error((error as Error).stack);
 
     // Fallback to simple mode
+    console.error('   Falling back to simple sync mode...');
     const copied = await copyIncrementSpecToLivingDocs(incrementId);
     return {
       success: copied,
@@ -174,10 +198,182 @@ async function intelligentSyncLivingDocs(
 }
 
 /**
- * Copy increment spec to living docs (legacy/simple mode)
+ * Extract and merge living docs (v2.0 - NO DUPLICATION!)
+ *
+ * NEW ARCHITECTURE:
+ * - Living docs = Permanent EPIC (GitHub Project, Jira Epic, ADO Feature)
+ * - Increment spec = Temporary ITERATION (GitHub Issue, Jira Story, ADO User Story)
+ *
+ * What this does:
+ * 1. Parse increment spec (extract user stories ONLY)
+ * 2. Check if living docs spec exists
+ * 3. If exists: Merge new user stories (avoid duplicates)
+ * 4. If not: Create new living docs spec
+ * 5. Generate links to architecture/ADRs (NO duplication!)
+ * 6. Update implementation history
+ *
+ * What this DOESN'T do:
+ * - ❌ Copy architecture details (those live in architecture/)
+ * - ❌ Copy ADR content (those live in architecture/adr/)
+ * - ❌ Copy success metrics (those live in increment reports)
+ * - ❌ Copy future enhancements (those live in roadmap)
+ *
+ * Returns true if living docs updated, false if skipped
+ */
+async function extractAndMergeLivingDocs(incrementId: string): Promise<boolean> {
+  try {
+    // Import parser utilities
+    const {
+      parseIncrementSpec,
+      parseLivingDocsSpec,
+      extractSpecId,
+      mergeUserStories,
+      generateRelatedDocsLinks,
+      writeLivingDocsSpec,
+    } = await import('../../../../src/utils/spec-parser.js');
+
+    const projectRoot = process.cwd();
+    const incrementSpecPath = path.join(projectRoot, '.specweave', 'increments', incrementId, 'spec.md');
+
+    // Check if increment spec exists
+    if (!fs.existsSync(incrementSpecPath)) {
+      console.log(`⚠️  Increment spec not found: ${incrementSpecPath}`);
+      return false;
+    }
+
+    console.log(`   📖 Parsing increment spec: ${incrementId}`);
+
+    // 1. Parse increment spec (extract user stories)
+    const incrementSpec = await parseIncrementSpec(incrementSpecPath);
+
+    if (incrementSpec.userStories.length === 0) {
+      console.log(`ℹ️  No user stories found in increment spec, skipping sync`);
+      return false;
+    }
+
+    console.log(`   ✅ Found ${incrementSpec.userStories.length} user stories in increment`);
+
+    // 2. Determine living docs spec ID
+    const specId = incrementSpec.implementsSpec || extractSpecId(incrementId);
+    const livingDocsDir = path.join(projectRoot, '.specweave', 'docs', 'internal', 'specs', 'default');
+    const livingDocsPath = path.join(livingDocsDir, `${specId}-${incrementId.replace(/^\d+-/, '')}.md`);
+
+    // 3. Check if living docs spec exists
+    const livingDocsExists = fs.existsSync(livingDocsPath);
+
+    if (livingDocsExists) {
+      console.log(`   📚 Living docs spec exists, merging user stories...`);
+
+      // MERGE MODE: Add new user stories to existing spec
+      const livingSpec = await parseLivingDocsSpec(livingDocsPath);
+
+      // Merge user stories (adds new, updates existing)
+      const mergedStories = mergeUserStories(
+        livingSpec.userStories,
+        incrementSpec.userStories,
+        incrementId
+      );
+
+      const newStoriesCount = mergedStories.length - livingSpec.userStories.length;
+
+      // Update implementation history
+      const existingEntry = livingSpec.implementationHistory.find(e => e.increment === incrementId);
+
+      if (!existingEntry) {
+        livingSpec.implementationHistory.push({
+          increment: incrementId,
+          stories: incrementSpec.userStories.map(s => s.id),
+          status: 'complete',
+          date: new Date().toISOString().split('T')[0],
+        });
+      } else {
+        // Update existing entry
+        existingEntry.status = 'complete';
+        existingEntry.date = new Date().toISOString().split('T')[0];
+      }
+
+      // Update user stories
+      livingSpec.userStories = mergedStories;
+
+      // Update last_updated
+      livingSpec.lastUpdated = new Date().toISOString().split('T')[0];
+
+      // Write updated spec
+      await writeLivingDocsSpec(livingDocsPath, livingSpec);
+
+      console.log(`   ✅ Merged ${newStoriesCount} new user stories into living docs`);
+      console.log(`   ✅ Updated implementation history for ${incrementId}`);
+
+    } else {
+      console.log(`   📝 Creating new living docs spec: ${specId}`);
+
+      // CREATE MODE: First increment for this spec
+      const relatedDocs = generateRelatedDocsLinks(incrementSpec, projectRoot);
+
+      const livingSpec = {
+        id: specId,
+        title: incrementSpec.title,
+        featureArea: extractFeatureArea(incrementSpec.title),
+        overview: incrementSpec.overview,
+        userStories: incrementSpec.userStories.map(story => ({
+          ...story,
+          implementedIn: incrementId,
+          status: 'complete' as const,
+        })),
+        implementationHistory: [
+          {
+            increment: incrementId,
+            stories: incrementSpec.userStories.map(s => s.id),
+            status: 'complete' as const,
+            date: new Date().toISOString().split('T')[0],
+          },
+        ],
+        relatedDocs,
+        externalLinks: {} as { github?: string; jira?: string; ado?: string },
+        priority: incrementSpec.priority,
+        status: 'active',
+        created: new Date().toISOString().split('T')[0],
+        lastUpdated: new Date().toISOString().split('T')[0],
+      };
+
+      // Ensure directory exists
+      await fs.ensureDir(livingDocsDir);
+
+      // Write new spec
+      await writeLivingDocsSpec(livingDocsPath, livingSpec);
+
+      console.log(`   ✅ Created new living docs spec: ${specId}`);
+      console.log(`   ✅ Added ${incrementSpec.userStories.length} user stories`);
+      console.log(`   ✅ Generated links to ${relatedDocs.architecture.length} architecture docs`);
+      console.log(`   ✅ Generated links to ${relatedDocs.adrs.length} ADRs`);
+    }
+
+    return true;
+
+  } catch (error) {
+    console.error(`❌ Error extracting/merging living docs: ${error}`);
+    console.error((error as Error).stack);
+    return false;
+  }
+}
+
+/**
+ * Extract feature area from title
+ */
+function extractFeatureArea(title: string): string {
+  // Simple heuristic: Use title as feature area
+  // Can be customized later based on keywords
+  return title.replace(/^(Increment \d+:\s*)?/, '').trim();
+}
+
+/**
+ * Copy increment spec to living docs (DEPRECATED - use extractAndMergeLivingDocs instead)
  * Returns true if spec was copied, false if skipped
  */
 async function copyIncrementSpecToLivingDocs(incrementId: string): Promise<boolean> {
+  console.warn('⚠️  Using deprecated copyIncrementSpecToLivingDocs (simple mode)');
+  console.warn('   Consider enabling intelligent mode to avoid duplication');
+
   try {
     const incrementSpecPath = path.join(process.cwd(), '.specweave', 'increments', incrementId, 'spec.md');
     const livingDocsPath = path.join(process.cwd(), '.specweave', 'docs', 'internal', 'specs', `spec-${incrementId}.md`);

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

@@ -2,9 +2,9 @@
 
 **Purpose**: Quick reference for all available skills. Read this file BEFORE starting any task.
 
-**Last Updated**: 2025-11-10 (manually updated to include plugin-installer and plugin-expert)
+**Last Updated**: 2025-11-13 (removed deprecated skills: plugin-installer, increment-quality-judge v1)
 
-**Total Skills**: 14
+**Total Skills**: 18
 
 ---
 
@@ -37,16 +37,6 @@ Step 4: Execute → Follow the increment planning workflow
 
 ### Framework Core
 
-#### plugin-installer
-
-**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**: 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`
-
----
-
 #### 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.
@@ -85,16 +75,6 @@ Step 4: Execute → Follow the increment planning workflow
 
 ---
 
-#### increment-quality-judge
-
-**Description**: Optional AI-powered quality assessment for specifications, plans, and tests. Goes beyond rule-based validation to evaluate clarity, testability, edge cases, and architecture soundness. Activates for validate quality, quality check, assess spec, evaluate increment, spec review, quality score.
-
-**Location**: `.claude/skills/increment-quality-judge/SKILL.md`
-
-**Allowed tools**: Read, Grep, Glob
-
----
-
 #### 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.
@@ -202,13 +182,13 @@ Step 4: Execute → Follow the increment planning workflow
 
 | Your Task | Relevant Skill | Keywords |
 |-----------|---------------|----------|
-| "Preview internal docs" | `plugin-installer` | "preview docs", "Docusaurus", "documentation UI" |
 | "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` | "quality check", "assess spec" |
+| "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" |
 

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

@@ -34,6 +34,56 @@ The increment-planner skill automates the creation of implementation plans for A
 - Separation of WHAT/WHY (spec) from HOW (plan) from STEPS (tasks with test plans)
 - **v0.7.0+**: Test-Aware Planning (bidirectional AC↔Task↔Test linking)
 - **v0.8.0+**: Multi-Project Support (specs organized by project/team)
+- **v0.18.0+**: Bidirectional Task↔User Story Linking (automatic during `/specweave:done`)
+
+## Bidirectional Linking (v0.18.0+)
+
+**CRITICAL FEATURE**: When you create tasks, ensure they have **AC**: fields so bidirectional links can be created automatically.
+
+### How It Works
+
+1. **During Planning**: Create tasks with AC-IDs
+   ```markdown
+   ## T-001: Implement User Login
+
+   **AC**: AC-US1-01, AC-US1-02, AC-US1-03   ← CRITICAL!
+   ```
+
+2. **During Completion**: `/specweave:done` automatically:
+   - Extracts user stories to `.specweave/docs/internal/specs/{project}/{feature}/`
+   - Parses tasks.md for AC-IDs
+   - **Injects bidirectional links** into tasks.md
+   - Creates complete traceability (Tasks ↔ User Stories)
+
+3. **Result**: Tasks now link back to user stories:
+   ```markdown
+   ## T-001: Implement User Login
+
+   **User Story**: [US-001: User Authentication](../../docs/internal/specs/default/auth-service/us-001-user-authentication.md)
+
+   **AC**: AC-US1-01, AC-US1-02, AC-US1-03
+   ```
+
+### Requirements
+
+**MUST HAVE** for bidirectional linking:
+- ✅ Tasks with **AC**: field
+- ✅ AC-IDs in format: `AC-US{number}-{criteria}` (e.g., `AC-US1-01`)
+- ✅ Matching user stories in spec.md (e.g., `### US-001:` or `#### US-001:`)
+
+**Multi-Project Support**:
+- Works with `specs/default/`, `specs/backend/`, `specs/frontend/`, etc.
+- Paths automatically adapt to project structure
+- No additional configuration needed
+
+### Benefits
+
+- ✅ **Complete Traceability**: Navigate from tasks to user stories and back
+- ✅ **Automatic**: Zero manual linking during `/specweave:done`
+- ✅ **LLM-Friendly**: AI can understand relationships bidirectionally
+- ✅ **Multi-Project Aware**: Works across all projects
+
+**For complete details**: See `.specweave/docs/public/guides/bidirectional-linking.md`
 
 ## Increment Types (v0.7.0+)
 
@@ -80,6 +130,50 @@ Do NOT activate if:
 - ❌ User is already in an active increment planning workflow
 - ❌ Increment files (spec.md, plan.md, tasks.md) are currently being created
 
+---
+
+## Increment Naming Convention
+
+**CRITICAL**: All increments MUST use descriptive names, not just numbers.
+
+**Format**: `####-descriptive-kebab-case-name`
+
+**Examples**:
+- ✅ `0001-core-framework`
+- ✅ `0002-core-enhancements`
+- ✅ `0003-intelligent-model-selection`
+- ❌ `0003` (too generic, rejected)
+- ❌ `0004` (no description, rejected)
+
+**Rationale**:
+- **Clear intent at a glance** - "0003-intelligent-model-selection" tells you exactly what it does
+- **Easy to reference** - "the model selection increment" vs "increment 3"
+- **Better git history** - Commit messages naturally include feature name
+- **Searchable by feature** - `git log --grep="model-selection"` works
+- **Self-documenting** - Increment folders are readable without opening files
+
+**Rules**:
+- `####` = Zero-padded 4-digit number (0001, 0002, 0003, ...)
+- `-descriptive-name` = Kebab-case description (lowercase, hyphens)
+- Max 50 chars total (for readability)
+- No special characters except hyphens
+
+**When Creating Increments**:
+```bash
+# ❌ Wrong
+/specweave:increment "0004"
+
+# ✅ Correct
+/specweave:increment "0004-cost-optimization"
+/specweave:increment "0005-github-sync-enhancements"
+```
+
+**Enforcement**:
+- `/specweave:increment` command validates naming (rejects bare numbers)
+- Code review requirement (descriptive names mandatory)
+
+---
+
 ## 🔗 External Sync Architecture (CRITICAL)
 
 **Source of Truth**: `.specweave/docs/specs/` (LOCAL) is the permanent source of truth. External tools (GitHub, Jira, ADO) are **MIRRORS**.