specweave 0.17.16 → 0.17.19

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**.

package/plugins/specweave/skills/increment-work-router/SKILL.md

@@ -0,0 +1,466 @@
+---
+name: increment-work-router
+description: Smart work continuation system that detects implementation intent and routes to active increment or creates new one. Activates for implement, complete, build, add, develop, work on, continue, resume, finish, fix, resolve, address, let's implement, let's build, start working, begin implementation, add feature, create feature.
+---
+
+# Increment Work Router - Smart Work Continuation
+
+## Purpose
+
+The increment-work-router skill is an **intelligent work continuation system** that:
+- ✅ Detects implementation/continuation intent (not just new projects)
+- ✅ Checks for active increments automatically
+- ✅ Routes to existing increment OR creates new one
+- ✅ Bridges the gap between planning and execution
+
+**Key Insight**: When user says "implement X" or "complete Y", they expect the system to handle routing intelligently without manual commands.
+
+## When to Activate
+
+This skill activates when user expresses **implementation/continuation intent**:
+
+### High-Confidence Triggers (Auto-Route)
+
+**Action Verbs** (with specific target):
+- "Implement [feature]"
+- "Complete [task]"
+- "Build [component]"
+- "Add [functionality]"
+- "Develop [module]"
+- "Create [feature]"
+
+**Continuation Phrases**:
+- "Work on [feature]"
+- "Continue [increment]"
+- "Resume [work]"
+- "Finish [task]"
+- "Let's implement [X]"
+- "Let's build [Y]"
+- "Start working on [Z]"
+
+**Bug/Fix Intent**:
+- "Fix [issue]"
+- "Resolve [bug]"
+- "Address [problem]"
+
+### Medium-Confidence Triggers (Clarify)
+
+**Vague Intent** (needs target clarification):
+- "Let's continue"
+- "Keep working"
+- "What's next?"
+- "Continue where we left off"
+
+### Don't Activate For
+
+**Planning/Discussion** (let other skills handle):
+- "What should we build?" → project-kickstarter
+- "How does X work?" → Regular conversation
+- "Should we use Y?" → Technical discussion
+- "Plan a new feature" → increment-planner
+
+**Already in Workflow**:
+- User is already executing `/specweave:do`
+- Increment planning is in progress
+- Another skill is handling the request
+
+## Core Algorithm
+
+### Step 1: Detect Intent
+
+Scan user message for implementation keywords:
+```
+Action verbs: implement, complete, build, add, develop, create
+Continuation: work on, continue, resume, finish, start
+Bug/Fix: fix, resolve, address
+```
+
+Calculate confidence:
+- **High (>80%)**: Action verb + specific target ("implement user auth")
+- **Medium (50-80%)**: Action verb only ("let's continue")
+- **Low (<50%)**: No clear intent
+
+### Step 2: Check Active Increments
+
+**Read increment state:**
+```bash
+# Find all increments with status = "active"
+find .specweave/increments -name "metadata.json" -type f \
+  -exec jq -r 'select(.status == "active") | .id' {} \;
+```
+
+**Three scenarios:**
+1. **One active increment** → Check relevance and route
+2. **Multiple active increments** → Ask user to select
+3. **No active increments** → Suggest creating new one
+
+### Step 3: Check Relevance (if active increment exists)
+
+**Relatedness Analysis:**
+Compare user's request against active increment:
+- Check increment title/description
+- Check task list (tasks.md)
+- Check spec.md for related features
+
+**Scoring:**
+- **High match (>70%)**: Same feature area → Auto-resume
+- **Medium match (40-70%)**: Related area → Ask confirmation
+- **Low match (<40%)**: Unrelated → Suggest new increment
+
+### Step 4: Route Intelligently
+
+**Scenario A: High relevance to active increment**
+```
+User: "Implement user authentication"
+Active: 0031-user-authentication-system
+
+✅ High match → Auto-resume:
+
+"I see you have an active increment for user authentication (0031).
+Resuming work on that increment now with /specweave:do..."
+
+[Automatically invokes /specweave:do]
+```
+
+**Scenario B: Unrelated to active increment**
+```
+User: "Implement payment processing"
+Active: 0031-user-authentication-system
+
+⚠️  Low match → Ask:
+
+"I see you have an active increment (0031-user-authentication-system).
+
+Your request for payment processing seems unrelated. Would you like to:
+1. **Create new increment** for payment processing (recommended)
+2. **Continue current increment** (0031) and add payment to it
+3. **Pause current** and create new increment
+
+What would you prefer?"
+```
+
+**Scenario C: No active increment**
+```
+User: "Implement user authentication"
+Active: None
+
+→ Suggest new increment:
+
+"No active increment found. Let's create one for user authentication.
+
+I'm going to create a SpecWeave increment with:
+- Specification (WHAT & WHY)
+- Technical plan (HOW)
+- Task breakdown (STEPS with embedded tests)
+
+Creating increment now with /specweave:increment..."
+
+[Automatically invokes /specweave:increment "user authentication"]
+```
+
+**Scenario D: Multiple active increments**
+```
+User: "Continue working"
+Active: 0031-user-auth, 0032-payment-system
+
+→ Ask to clarify:
+
+"You have 2 active increments:
+1. **0031-user-authentication-system** (3/10 tasks complete)
+2. **0032-payment-processing** (1/8 tasks complete)
+
+Which one would you like to work on?"
+```
+
+**Scenario E: Vague continuation intent**
+```
+User: "Let's continue"
+Active: 0031-user-authentication-system
+
+✅ Auto-resume (only one active):
+
+"Resuming increment 0031-user-authentication-system...
+Progress: 3/10 tasks complete (30%)
+
+Next task: T-004 Implement password hashing
+
+[Automatically invokes /specweave:do]"
+```
+
+## Integration Architecture
+
+**Workflow:**
+```
+User: "Implement [feature]"
+        ↓
+increment-work-router (detects intent)
+        ↓
+[Check .specweave/increments/*/metadata.json]
+        ↓
+┌───────────────────┬──────────────────┬────────────────┐
+│ Active increment  │ Multiple active  │ No active      │
+│ (relevant)        │ (ambiguous)      │ (none)         │
+└─────┬─────────────┴──────┬───────────┴──────┬─────────┘
+      │                    │                  │
+      ↓                    ↓                  ↓
+/specweave:do        Ask to select    /specweave:increment
+(auto-resume)        (clarify)        (create new)
+```
+
+**Calls:**
+- `/specweave:do` - Resume active increment
+- `/specweave:increment` - Create new increment
+- `/specweave:status` - Check increment state (if needed)
+
+**Called By:**
+- Automatically when implementation intent detected
+- Works alongside `project-kickstarter` (projects) and `increment-planner` (planning)
+
+## Decision Matrix
+
+| User Intent | Active Increments | Relevance | Action |
+|-------------|------------------|-----------|--------|
+| "Implement auth" | 1 (auth-related) | High (>70%) | Auto `/specweave:do` |
+| "Implement auth" | 1 (unrelated) | Low (<40%) | Ask: New or add to current? |
+| "Implement auth" | 0 | N/A | Auto `/specweave:increment` |
+| "Implement auth" | 2+ | N/A | Ask which increment |
+| "Let's continue" | 1 | N/A | Auto `/specweave:do` |
+| "Let's continue" | 2+ | N/A | Ask which increment |
+| "Let's continue" | 0 | N/A | "No active increment. What should we build?" |
+
+## Relevance Matching Logic
+
+**How to determine if request relates to active increment:**
+
+```typescript
+function calculateRelevance(userRequest: string, increment: Increment): number {
+  let score = 0;
+
+  // 1. Title/ID match (strongest signal)
+  if (increment.title.toLowerCase().includes(extractKeywords(userRequest))) {
+    score += 40;
+  }
+
+  // 2. Tasks match (check tasks.md)
+  const tasks = readTasksFile(increment);
+  const matchingTasks = tasks.filter(t =>
+    t.title.toLowerCase().includes(extractKeywords(userRequest))
+  );
+  score += (matchingTasks.length / tasks.length) * 30;
+
+  // 3. Spec match (check spec.md user stories)
+  const spec = readSpecFile(increment);
+  if (spec.includes(extractKeywords(userRequest))) {
+    score += 20;
+  }
+
+  // 4. Type match (feature vs bug vs hotfix)
+  const requestType = detectType(userRequest);
+  if (requestType === increment.type) {
+    score += 10;
+  }
+
+  return score; // 0-100
+}
+```
+
+**Example:**
+```
+User: "Implement JWT token refresh"
+Active: 0031-user-authentication-system
+
+Checks:
+✅ Title contains "authentication" (user mentions "JWT token") → +40 points
+✅ Tasks.md has "T-005: Implement JWT refresh logic" → +30 points
+✅ Spec.md mentions "token management" → +20 points
+✅ Both are "feature" type → +10 points
+
+Total: 100/100 → High relevance → Auto-resume
+```
+
+## Examples
+
+### Example 1: Auto-Resume (High Relevance)
+
+**Context:**
+```
+Active: 0031-user-authentication-system
+Progress: 3/10 tasks complete
+```
+
+**User:**
+```
+Implement JWT token refresh
+```
+
+**increment-work-router:**
+```
+✅ Intent detected: "implement" + specific target
+✅ Active increment found: 0031-user-authentication-system
+✅ Relevance check: 95% match (authentication-related)
+
+→ AUTO-RESUME
+
+"I see you have an active increment for user authentication (0031).
+Task T-005 'Implement JWT token refresh' is already in your plan.
+
+Resuming increment 0031 now with /specweave:do...
+
+[Automatically invokes /specweave:do]
+```
+
+### Example 2: Create New (No Active Increment)
+
+**Context:**
+```
+Active: None
+```
+
+**User:**
+```
+Implement payment processing with Stripe
+```
+
+**increment-work-router:**
+```
+✅ Intent detected: "implement" + specific target
+❌ No active increment found
+
+→ CREATE NEW
+
+"No active increment found. Let's create one for payment processing.
+
+I'm going to create a SpecWeave increment with:
+- Specification (Stripe integration requirements)
+- Technical plan (API integration, webhooks, security)
+- Task breakdown (implementation steps with tests)
+
+Creating increment now with /specweave:increment...
+
+[Automatically invokes /specweave:increment "payment processing with Stripe"]
+```
+
+### Example 3: Unrelated Request (Ask)
+
+**Context:**
+```
+Active: 0031-user-authentication-system
+Progress: 3/10 tasks complete
+```
+
+**User:**
+```
+Implement email notifications
+```
+
+**increment-work-router:**
+```
+✅ Intent detected: "implement" + specific target
+✅ Active increment found: 0031-user-authentication-system
+⚠️  Relevance check: 15% match (unrelated)
+
+→ ASK FOR CLARIFICATION
+
+"I see you have an active increment (0031-user-authentication-system) with 3/10 tasks complete.
+
+Your request for email notifications seems unrelated. Would you like to:
+1. **Create new increment** for email notifications (recommended - keeps work focused)
+2. **Add to current increment** (0031) - if notifications are for auth emails
+3. **Pause current increment** and start notifications
+
+SpecWeave works best with focused increments. What would you prefer?"
+```
+
+### Example 4: Multiple Active (Clarify)
+
+**Context:**
+```
+Active: 0031-user-authentication-system (3/10 tasks)
+Active: 0032-payment-processing (1/8 tasks)
+```
+
+**User:**
+```
+Let's continue working
+```
+
+**increment-work-router:**
+```
+✅ Intent detected: "continue" (vague)
+✅ Multiple active increments found: 2
+
+→ ASK TO SELECT
+
+"You have 2 active increments:
+
+1. **0031-user-authentication-system**
+   - Progress: 3/10 tasks (30%)
+   - Next: T-004 Implement password hashing
+
+2. **0032-payment-processing**
+   - Progress: 1/8 tasks (12%)
+   - Next: T-002 Set up Stripe SDK
+
+Which one would you like to work on?"
+
+[Wait for user selection, then invoke /specweave:do {selected-id}]
+```
+
+### Example 5: Vague Intent + Single Active (Auto-Resume)
+
+**Context:**
+```
+Active: 0031-user-authentication-system (3/10 tasks)
+```
+
+**User:**
+```
+What's next?
+```
+
+**increment-work-router:**
+```
+✅ Intent detected: "what's next" (continuation)
+✅ One active increment: 0031-user-authentication-system
+
+→ AUTO-RESUME
+
+"Resuming increment 0031-user-authentication-system...
+Progress: 3/10 tasks complete (30%)
+
+Next task: **T-004 Implement password hashing**
+
+[Automatically invokes /specweave:do]"
+```
+
+## Opt-Out Mechanism
+
+Users can override auto-routing with explicit instructions:
+- "Don't resume, create new" → Forces new increment
+- "Just discuss first" → Regular conversation
+- "Plan without implementing" → Routes to `/specweave:increment` only
+- "Show me the current state" → Uses `/specweave:status` instead
+
+## Success Criteria
+
+- ✅ Users can say "implement X" and work starts automatically
+- ✅ Smart routing to active increments (no manual `/specweave:do`)
+- ✅ Detects unrelated requests and prevents scope creep
+- ✅ No "which increment?" confusion (auto-handles single active)
+- ✅ Clear choices when ambiguous (multiple active or unrelated)
+- ✅ Seamless integration with existing skills (project-kickstarter, increment-planner)
+
+## Related Skills
+
+- **project-kickstarter**: For NEW project descriptions (complements, doesn't overlap)
+- **increment-planner**: For creating increment structure (invoked by this skill)
+- **specweave-detector**: For checking SpecWeave context
+
+---
+
+**Key Distinction:**
+- `project-kickstarter` = "I want to BUILD a new product" (project-level)
+- `increment-work-router` = "IMPLEMENT this feature/task" (execution-level)
+- `increment-planner` = "PLAN this increment" (planning-level)
+
+This skill bridges planning → execution by auto-detecting implementation intent.

package/plugins/specweave-ado/commands/specweave-ado-sync-spec.md

@@ -1,5 +1,5 @@
 ---
-name: specweave-ado-sync-spec
+name: specweave-ado:sync-spec
 description: Sync SpecWeave spec to Azure DevOps Feature (bidirectional). Use when syncing .specweave/docs/internal/specs/spec-*.md files with ADO Features for permanent feature tracking.
 ---
 

package/plugins/specweave-ado/lib/ado-spec-content-sync.js

@@ -4,8 +4,9 @@ import {
   hasExternalLink,
   updateSpecWithExternalLink
 } from "../../../src/core/spec-content-sync.js";
-import path from "path";
-import fs from "fs/promises";
+import { SpecIncrementMapper } from "../../../src/core/sync/spec-increment-mapper.js";
+import * as path from "path";
+import * as fs from "fs/promises";
 async function syncSpecContentToAdo(options) {
   const { specPath, client, dryRun = false, verbose = false } = options;
   try {
@@ -44,8 +45,9 @@ async function syncSpecContentToAdo(options) {
 async function createAdoFeature(client, spec, options) {
   const { specPath, dryRun, verbose } = options;
   try {
+    const tasks = await getTaskMappings(specPath, spec.id);
     const title = `[${spec.id.toUpperCase()}] ${spec.title}`;
-    const description = buildAdoDescription(spec);
+    const description = buildAdoDescription(spec, tasks);
     if (verbose) {
       console.log(`
 \u{1F4DD} Creating ADO feature:`);
@@ -125,8 +127,9 @@ async function updateAdoFeature(client, spec, workItemId, options) {
         console.log(`      - ${change}`);
       }
     }
+    const tasks = await getTaskMappings(specPath, spec.id);
     const newTitle = `[${spec.id.toUpperCase()}] ${spec.title}`;
-    const newDescription = buildAdoDescription(spec);
+    const newDescription = buildAdoDescription(spec, tasks);
     if (dryRun) {
       console.log("\n\u{1F50D} Dry run - would update feature:");
       console.log(`   Title: ${newTitle}`);
@@ -160,7 +163,7 @@ ${newDescription}`);
     };
   }
 }
-function buildAdoDescription(spec) {
+function buildAdoDescription(spec, tasks) {
   let html = "";
   if (spec.description) {
     html += `<p>${escapeHtml(spec.description)}</p>`;
@@ -179,11 +182,52 @@ function buildAdoDescription(spec) {
       }
     }
   }
+  if (tasks && tasks.length > 0) {
+    html += "<h2>Implementation Tasks</h2>";
+    html += "<ul>";
+    for (const task of tasks) {
+      html += `<li><strong>${task.id}</strong>: ${escapeHtml(task.title)}`;
+      if (task.userStories && task.userStories.length > 0) {
+        html += ` (${task.userStories.join(", ")})`;
+      }
+      html += "</li>";
+    }
+    html += "</ul>";
+  }
   if (spec.metadata.priority) {
     html += `<p><strong>Priority:</strong> ${spec.metadata.priority}</p>`;
   }
   return html;
 }
+async function getTaskMappings(specPath, specId) {
+  try {
+    const rootDir = await findSpecWeaveRoot(specPath);
+    const mapper = new SpecIncrementMapper(rootDir);
+    const mapping = await mapper.mapSpecToIncrements(specId);
+    if (mapping.increments.length > 0) {
+      return mapping.increments[0].tasks;
+    }
+    return void 0;
+  } catch (error) {
+    return void 0;
+  }
+}
+async function findSpecWeaveRoot(specPath) {
+  let currentDir = path.dirname(specPath);
+  while (true) {
+    const specweaveDir = path.join(currentDir, ".specweave");
+    try {
+      await fs.access(specweaveDir);
+      return currentDir;
+    } catch {
+      const parentDir = path.dirname(currentDir);
+      if (parentDir === currentDir) {
+        throw new Error(".specweave directory not found");
+      }
+      currentDir = parentDir;
+    }
+  }
+}
 function escapeHtml(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
 }