specweave 0.28.17 → 0.28.20

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

@@ -0,0 +1,358 @@
+---
+name: specweave-ado:import-areas
+description: Import Azure DevOps area paths from a project and map them to SpecWeave projects. Creates 2-level directory structure with area path-based organization.
+---
+
+# Import ADO Area Paths Command
+
+You are an Azure DevOps integration expert. Help the user import area paths from an ADO project and map them to SpecWeave projects.
+
+## Command Usage
+
+```bash
+/specweave-ado:import-areas                         # Interactive mode (prompts for project)
+/specweave-ado:import-areas --project MyProduct     # Specific ADO project
+/specweave-ado:import-areas --dry-run               # Preview without creating directories
+/specweave-ado:import-areas --include-children      # Include child area paths
+```
+
+## Your Task
+
+When the user runs this command:
+
+### Step 1: Validate Prerequisites
+
+1. **Check ADO credentials** exist in `.env`:
+   - `AZURE_DEVOPS_PAT`
+   - `AZURE_DEVOPS_ORG`
+   - `AZURE_DEVOPS_PROJECT`
+
+2. **Check config.json** for existing area path mapping:
+   - If `sync.profiles.*.config.areaPathMapping` exists, warn user
+
+### Step 2: Get Project Name
+
+**If `--project` flag provided:**
+- Use the provided project name
+
+**If no flag (interactive mode):**
+```
+🔷 Azure DevOps Area Path Import
+
+Enter the ADO project name to import area paths from:
+> MyProduct
+
+Fetching area paths from project MyProduct...
+```
+
+### Step 3: Fetch and Display Area Paths
+
+```typescript
+import { fetchAreaPathsForProject } from '../lib/ado-board-resolver';
+
+const areaPaths = await fetchAreaPathsForProject(
+  process.env.AZURE_DEVOPS_ORG,
+  'MyProduct',
+  process.env.AZURE_DEVOPS_PAT
+);
+```
+
+**Display area paths:**
+```
+Found 6 area paths in project MyProduct:
+
+  1. ☑ MyProduct\Frontend (45 active items)
+  2. ☑ MyProduct\Backend (78 active items)
+  3. ☑ MyProduct\Mobile (23 active items)
+  4. ☑ MyProduct\DevOps (12 active items)
+  5. ☐ MyProduct\Archive (0 items) [deselected - archive]
+  6. ☐ MyProduct (root) [deselected - root level]
+
+Select area paths to import (Space to toggle, Enter to confirm)
+```
+
+### Step 4: Map Area Paths to SpecWeave Projects
+
+For each selected area path, prompt for SpecWeave project ID:
+
+```
+🏷️  Mapping area paths to SpecWeave projects:
+
+Area path "MyProduct\Frontend" → SpecWeave project ID: [fe]
+  → Include child area paths? [Y/n]: y
+  → Keywords for auto-classification (optional): frontend, ui, angular, css
+
+Area path "MyProduct\Backend" → SpecWeave project ID: [be]
+  → Include child area paths? [Y/n]: y
+  → Keywords for auto-classification (optional): api, server, database, c#
+
+Area path "MyProduct\Mobile" → SpecWeave project ID: [mobile]
+  → Include child area paths? [Y/n]: y
+  → Keywords for auto-classification (optional): ios, android, xamarin
+
+Area path "MyProduct\DevOps" → SpecWeave project ID: [devops]
+  → Include child area paths? [Y/n]: y
+  → Keywords for auto-classification (optional): infrastructure, ci, cd, terraform
+```
+
+**Project ID validation:**
+- Must be lowercase, alphanumeric with hyphens
+- Must not collide with existing project IDs
+- If collision detected, suggest prefixed version: `myproduct-fe` instead of `fe`
+
+### Step 5: Create Directory Structure
+
+Create 2-level directory structure:
+
+```
+.specweave/docs/internal/specs/
+└── ADO-myproduct/              ← Level 1: ADO project
+    ├── fe/                     ← Level 2: SpecWeave project
+    │   └── .gitkeep
+    ├── be/
+    │   └── .gitkeep
+    ├── mobile/
+    │   └── .gitkeep
+    └── devops/
+        └── .gitkeep
+```
+
+### Step 6: Update config.json
+
+Add area path mapping to config:
+
+```json
+{
+  "sync": {
+    "profiles": {
+      "ado-default": {
+        "provider": "ado",
+        "config": {
+          "organization": "myorg",
+          "areaPathMapping": {
+            "project": "MyProduct",
+            "mappings": [
+              {
+                "areaPath": "MyProduct\\Frontend",
+                "specweaveProject": "fe",
+                "includeChildren": true,
+                "keywords": ["frontend", "ui", "angular", "css"]
+              },
+              {
+                "areaPath": "MyProduct\\Backend",
+                "specweaveProject": "be",
+                "includeChildren": true,
+                "keywords": ["api", "server", "database", "c#"]
+              },
+              {
+                "areaPath": "MyProduct\\Mobile",
+                "specweaveProject": "mobile",
+                "includeChildren": true,
+                "keywords": ["ios", "android", "xamarin"]
+              },
+              {
+                "areaPath": "MyProduct\\DevOps",
+                "specweaveProject": "devops",
+                "includeChildren": true,
+                "keywords": ["infrastructure", "ci", "cd", "terraform"]
+              }
+            ]
+          }
+        }
+      }
+    }
+  },
+  "multiProject": {
+    "enabled": true,
+    "activeProject": "fe",
+    "projects": {
+      "fe": {
+        "name": "Frontend",
+        "externalTools": {
+          "ado": {
+            "areaPath": "MyProduct\\Frontend",
+            "project": "MyProduct"
+          }
+        }
+      },
+      "be": {
+        "name": "Backend",
+        "externalTools": {
+          "ado": {
+            "areaPath": "MyProduct\\Backend",
+            "project": "MyProduct"
+          }
+        }
+      },
+      "mobile": {
+        "name": "Mobile",
+        "externalTools": {
+          "ado": {
+            "areaPath": "MyProduct\\Mobile",
+            "project": "MyProduct"
+          }
+        }
+      },
+      "devops": {
+        "name": "DevOps",
+        "externalTools": {
+          "ado": {
+            "areaPath": "MyProduct\\DevOps",
+            "project": "MyProduct"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Step 7: Display Summary
+
+```
+✅ Azure DevOps Area Paths Import Complete!
+
+🔷 ADO Project: MyProduct
+📁 Created: .specweave/docs/internal/specs/ADO-myproduct/
+
+Area paths imported:
+  ✓ MyProduct\Frontend → fe (includes children)
+    Keywords: frontend, ui, angular, css
+  ✓ MyProduct\Backend → be (includes children)
+    Keywords: api, server, database, c#
+  ✓ MyProduct\Mobile → mobile (includes children)
+    Keywords: ios, android, xamarin
+  ✓ MyProduct\DevOps → devops (includes children)
+    Keywords: infrastructure, ci, cd, terraform
+
+💡 Next steps:
+  1. Use /specweave:switch-project fe to switch active project
+  2. Create increment: /specweave:increment "feature name"
+  3. User stories will auto-sync to the correct area path based on keywords
+
+📖 Documentation: .specweave/docs/internal/architecture/adr/0143-jira-ado-multi-level-project-mapping.md
+```
+
+## Examples
+
+### Example 1: Interactive Import
+```
+User: /specweave-ado:import-areas
+
+You:
+🔷 Azure DevOps Area Path Import
+
+Enter the ADO project name: MyProduct
+Fetching area paths...
+
+Found 4 area paths:
+  ☑ MyProduct\Frontend
+  ☑ MyProduct\Backend
+  ☑ MyProduct\Mobile
+  ☐ MyProduct (root) [deselected]
+
+Mapping to SpecWeave projects:
+  MyProduct\Frontend → fe
+  MyProduct\Backend → be
+  MyProduct\Mobile → mobile
+
+✅ Import complete! 3 area paths mapped.
+```
+
+### Example 2: Dry Run
+```
+User: /specweave-ado:import-areas --project MyProduct --dry-run
+
+You:
+🔷 Azure DevOps Area Path Import (DRY RUN)
+
+Would import from project: MyProduct
+
+Would create:
+  .specweave/docs/internal/specs/ADO-myproduct/
+  .specweave/docs/internal/specs/ADO-myproduct/fe/
+  .specweave/docs/internal/specs/ADO-myproduct/be/
+  .specweave/docs/internal/specs/ADO-myproduct/mobile/
+
+Would update config.json with area path mapping.
+
+No changes made (dry run).
+```
+
+### Example 3: Already Configured
+```
+User: /specweave-ado:import-areas
+
+You:
+⚠️  Area path mapping already exists for project MyProduct
+
+Current mappings:
+  MyProduct\Frontend → fe
+  MyProduct\Backend → be
+
+Do you want to:
+  1. Add more area paths
+  2. Replace existing mapping
+  3. Cancel
+
+> 1
+
+Fetching additional area paths...
+  ☐ MyProduct\Frontend (already mapped)
+  ☐ MyProduct\Backend (already mapped)
+  ☑ MyProduct\Mobile (new)
+  ☑ MyProduct\DevOps (new)
+
+Added:
+  MyProduct\Mobile → mobile
+  MyProduct\DevOps → devops
+
+✅ Updated! Now 4 area paths mapped.
+```
+
+## Error Handling
+
+**Missing credentials:**
+```
+❌ Azure DevOps credentials not found
+
+Please add to .env:
+  AZURE_DEVOPS_PAT=your_personal_access_token
+  AZURE_DEVOPS_ORG=your_organization
+  AZURE_DEVOPS_PROJECT=your_project
+
+Or run: specweave init . (to configure Azure DevOps)
+```
+
+**Project not found:**
+```
+❌ ADO project "INVALID" not found in organization "myorg"
+
+Available projects you have access to:
+  - MyProduct (My Product Development)
+  - Infrastructure (DevOps & Infrastructure)
+  - Legacy (Legacy Systems)
+
+Tip: Use /specweave-ado:import-areas --project MyProduct
+```
+
+**No area paths found:**
+```
+⚠️  No child area paths found in project MyProduct
+
+The project only has the root area path. This means:
+  1. Teams aren't using area paths for organization
+  2. You can create area paths in ADO Project Settings
+
+Suggestions:
+  - Use single-project mode (no area path mapping)
+  - Create area paths in ADO: Project Settings → Work → Areas
+  - Run this command again after creating area paths
+```
+
+## Related Commands
+
+- `/specweave-ado:import-projects` - Import multiple ADO projects
+- `/specweave-ado:sync` - Sync increments with ADO
+- `/specweave:switch-project` - Switch active SpecWeave project
+- `/specweave:init-multiproject` - Initialize multi-project mode

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

@@ -134,6 +134,7 @@ class AdoSpecSync {
     const featureTitle = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
     const featureDescription = this.generateFeatureDescription(spec);
     const tags = [`spec:${spec.metadata.id}`, `priority:${spec.metadata.priority}`].join("; ");
+    const workItemType = this.mapTypeToAdo(spec.metadata.type, "Feature");
     const payload = [
       {
         op: "add",
@@ -148,12 +149,18 @@ class AdoSpecSync {
       {
         op: "add",
         path: "/fields/System.WorkItemType",
-        value: "Feature"
+        value: workItemType
       },
       {
         op: "add",
         path: "/fields/System.Tags",
         value: tags
+      },
+      {
+        // Set native ADO Priority field (P0→1, P1→2, P2→3, P3→4)
+        op: "add",
+        path: "/fields/Microsoft.VSTS.Common.Priority",
+        value: this.mapPriorityToAdo(spec.metadata.priority)
       }
     ];
     const response = await this.client.post("/wit/workitems/$Feature?api-version=7.0", payload);
@@ -224,7 +231,8 @@ class AdoSpecSync {
           title: storyTitle,
           description: storyDescription,
           parentId: featureId,
-          tags: [`user-story`, `spec:${spec.metadata.id}`, `priority:${us.priority}`].join("; ")
+          tags: [`user-story`, `spec:${spec.metadata.id}`, `priority:${us.priority}`].join("; "),
+          priority: us.priority
         });
         created.push(us.id);
         console.log(`   \u2705 Created ${us.id} \u2192 User Story #${newStory.id}`);
@@ -362,6 +370,7 @@ ${acList}
    * Create ADO User Story
    */
   async createStory(story) {
+    const workItemType = this.mapTypeToAdo(story.type, "User Story");
     const payload = [
       {
         op: "add",
@@ -376,13 +385,19 @@ ${acList}
       {
         op: "add",
         path: "/fields/System.WorkItemType",
-        value: "User Story"
+        value: workItemType
       },
       {
         op: "add",
         path: "/fields/System.Tags",
         value: story.tags
       },
+      {
+        // Set native ADO Priority field
+        op: "add",
+        path: "/fields/Microsoft.VSTS.Common.Priority",
+        value: this.mapPriorityToAdo(story.priority)
+      },
       {
         op: "add",
         path: "/relations/-",
@@ -431,6 +446,47 @@ ${acList}
     }
     await this.client.patch(`/wit/workitems/${storyId}?api-version=7.0`, payload);
   }
+  /**
+   * Map SpecWeave priority to ADO priority value
+   *
+   * ADO Priority field uses 1-4 scale:
+   * - 1 = Highest (P0)
+   * - 2 = High (P1)
+   * - 3 = Medium (P2)
+   * - 4 = Low (P3)
+   */
+  mapPriorityToAdo(priority) {
+    if (!priority) return 3;
+    const map = {
+      P0: 1,
+      P1: 2,
+      P2: 3,
+      P3: 4,
+      p0: 1,
+      p1: 2,
+      p2: 3,
+      p3: 4
+    };
+    return map[priority] || 3;
+  }
+  /**
+   * Map SpecWeave type to ADO work item type
+   *
+   * Supports: Feature, User Story, Bug, Task
+   */
+  mapTypeToAdo(type, defaultType = "Feature") {
+    if (!type) return defaultType;
+    const normalizedType = type.toLowerCase();
+    const map = {
+      bug: "Bug",
+      feature: "Feature",
+      epic: "Feature",
+      story: "User Story",
+      task: "Task",
+      enhancement: "Feature"
+    };
+    return map[normalizedType] || defaultType;
+  }
 }
 export {
   AdoSpecSync

package/plugins/specweave-ado/lib/ado-spec-sync.ts

@@ -223,6 +223,9 @@ export class AdoSpecSync {
     const featureDescription = this.generateFeatureDescription(spec);
     const tags = [`spec:${spec.metadata.id}`, `priority:${spec.metadata.priority}`].join('; ');
 
+    // Determine work item type (supports Bug for bug-type specs)
+    const workItemType = this.mapTypeToAdo(spec.metadata.type, 'Feature');
+
     const payload = [
       {
         op: 'add',
@@ -237,12 +240,18 @@ export class AdoSpecSync {
       {
         op: 'add',
         path: '/fields/System.WorkItemType',
-        value: 'Feature'
+        value: workItemType
       },
       {
         op: 'add',
         path: '/fields/System.Tags',
         value: tags
+      },
+      {
+        // Set native ADO Priority field (P0→1, P1→2, P2→3, P3→4)
+        op: 'add',
+        path: '/fields/Microsoft.VSTS.Common.Priority',
+        value: this.mapPriorityToAdo(spec.metadata.priority)
       }
     ];
 
@@ -335,7 +344,8 @@ export class AdoSpecSync {
           title: storyTitle,
           description: storyDescription,
           parentId: featureId,
-          tags: [`user-story`, `spec:${spec.metadata.id}`, `priority:${us.priority}`].join('; ')
+          tags: [`user-story`, `spec:${spec.metadata.id}`, `priority:${us.priority}`].join('; '),
+          priority: us.priority
         });
 
         created.push(us.id);
@@ -510,7 +520,12 @@ ${acList}
     description: string;
     parentId: number;
     tags: string;
+    priority?: string;
+    type?: string;
   }): Promise<AdoUserStory> {
+    // Determine work item type (supports Bug for bug-type stories)
+    const workItemType = this.mapTypeToAdo(story.type, 'User Story');
+
     const payload = [
       {
         op: 'add',
@@ -525,13 +540,19 @@ ${acList}
       {
         op: 'add',
         path: '/fields/System.WorkItemType',
-        value: 'User Story'
+        value: workItemType
       },
       {
         op: 'add',
         path: '/fields/System.Tags',
         value: story.tags
       },
+      {
+        // Set native ADO Priority field
+        op: 'add',
+        path: '/fields/Microsoft.VSTS.Common.Priority',
+        value: this.mapPriorityToAdo(story.priority)
+      },
       {
         op: 'add',
         path: '/relations/-',
@@ -590,4 +611,52 @@ ${acList}
 
     await this.client.patch(`/wit/workitems/${storyId}?api-version=7.0`, payload);
   }
+
+  /**
+   * Map SpecWeave priority to ADO priority value
+   *
+   * ADO Priority field uses 1-4 scale:
+   * - 1 = Highest (P0)
+   * - 2 = High (P1)
+   * - 3 = Medium (P2)
+   * - 4 = Low (P3)
+   */
+  private mapPriorityToAdo(priority?: string): number {
+    if (!priority) return 3; // Default to Medium
+
+    const map: Record<string, number> = {
+      P0: 1,
+      P1: 2,
+      P2: 3,
+      P3: 4,
+      p0: 1,
+      p1: 2,
+      p2: 3,
+      p3: 4
+    };
+
+    return map[priority] || 3;
+  }
+
+  /**
+   * Map SpecWeave type to ADO work item type
+   *
+   * Supports: Feature, User Story, Bug, Task
+   */
+  private mapTypeToAdo(type?: string, defaultType: string = 'Feature'): string {
+    if (!type) return defaultType;
+
+    const normalizedType = type.toLowerCase();
+
+    const map: Record<string, string> = {
+      bug: 'Bug',
+      feature: 'Feature',
+      epic: 'Feature',
+      story: 'User Story',
+      task: 'Task',
+      enhancement: 'Feature'
+    };
+
+    return map[normalizedType] || defaultType;
+  }
 }

package/plugins/specweave-ado/lib/ado-status-sync.js

@@ -31,12 +31,13 @@ class AdoStatusSync {
     };
   }
   /**
-   * Update ADO work item state
+   * Update ADO work item state and tags
    *
-   * Uses JSON Patch format to update System.State field.
+   * Uses JSON Patch format to update System.State and System.Tags fields.
+   * Tags are appended to existing tags, not replaced.
    *
    * @param workItemId - ADO work item ID (e.g., 123)
-   * @param status - Desired status
+   * @param status - Desired status with state and optional tags
    */
   async updateStatus(workItemId, status) {
     const patch = [
@@ -46,11 +47,42 @@ class AdoStatusSync {
         value: status.state
       }
     ];
+    if (status.tags && status.tags.length > 0) {
+      const currentTags = await this.getCurrentTags(workItemId);
+      const statusTagPatterns = ["Planning", "In Progress", "Paused", "Completed", "Abandoned", "On Hold"];
+      const preservedTags = currentTags.filter(
+        (tag) => !statusTagPatterns.some((pattern) => tag.toLowerCase() === pattern.toLowerCase())
+      );
+      const allTags = [.../* @__PURE__ */ new Set([...preservedTags, ...status.tags])];
+      patch.push({
+        op: "add",
+        path: "/fields/System.Tags",
+        value: allTags.join("; ")
+      });
+    }
     await this.client.patch(
       `/wit/workitems/${workItemId}?api-version=7.0`,
       patch
     );
   }
+  /**
+   * Get current tags from ADO work item
+   *
+   * @param workItemId - ADO work item ID
+   * @returns Array of current tags
+   */
+  async getCurrentTags(workItemId) {
+    try {
+      const response = await this.client.get(
+        `/wit/workitems/${workItemId}?api-version=7.0&$select=System.Tags`
+      );
+      const tagsString = response.data.fields?.["System.Tags"] || "";
+      if (!tagsString) return [];
+      return tagsString.split(";").map((tag) => tag.trim()).filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
   /**
    * Post comment about status change to ADO work item
    *