specweave 0.17.0 → 0.17.2

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

@@ -0,0 +1,313 @@
+/**
+ * Azure DevOps Spec Content Sync
+ *
+ * Syncs spec CONTENT (title, description, user stories) to ADO Features.
+ * Does NOT sync STATUS - that's managed in ADO.
+ *
+ * Sync Direction:
+ * - Title/Description: SpecWeave → ADO (we update)
+ * - State (New/Active/Resolved/Closed): ADO → SpecWeave (we read)
+ */
+
+import { AdoClientV2 } from './ado-client-v2.js';
+import {
+  parseSpecContent,
+  detectContentChanges,
+  buildExternalDescription,
+  hasExternalLink,
+  updateSpecWithExternalLink,
+  SpecContent,
+  ContentSyncResult,
+} from '../../../src/core/spec-content-sync.js';
+import { SyncProfile } from '../../../src/core/types/sync-profile.js';
+import path from 'path';
+import fs from 'fs/promises';
+
+export interface AdoContentSyncOptions {
+  specPath: string;
+  client: AdoClientV2;
+  dryRun?: boolean;
+  verbose?: boolean;
+}
+
+/**
+ * Sync spec content to ADO feature
+ * Creates feature if it doesn't exist, updates if it does
+ */
+export async function syncSpecContentToAdo(
+  options: AdoContentSyncOptions
+): Promise<ContentSyncResult> {
+  const { specPath, client, dryRun = false, verbose = false } = options;
+
+  try {
+    // 1. Parse spec content
+    const spec = await parseSpecContent(specPath);
+    if (!spec) {
+      return {
+        success: false,
+        action: 'error',
+        error: 'Failed to parse spec content',
+      };
+    }
+
+    if (verbose) {
+      console.log(`📄 Parsed spec: ${spec.id}`);
+      console.log(`   Title: ${spec.title}`);
+      console.log(`   User Stories: ${spec.userStories.length}`);
+    }
+
+    // 2. Check if feature already exists
+    const existingWorkItemId = await hasExternalLink(specPath, 'ado');
+
+    if (existingWorkItemId) {
+      // UPDATE existing feature
+      return await updateAdoFeature(
+        client,
+        spec,
+        parseInt(existingWorkItemId),
+        options
+      );
+    } else {
+      // CREATE new feature
+      return await createAdoFeature(client, spec, options);
+    }
+  } catch (error: any) {
+    return {
+      success: false,
+      action: 'error',
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Create new ADO feature from spec
+ */
+async function createAdoFeature(
+  client: AdoClientV2,
+  spec: SpecContent,
+  options: AdoContentSyncOptions
+): Promise<ContentSyncResult> {
+  const { specPath, dryRun, verbose } = options;
+
+  try {
+    // Build feature title and description
+    const title = `[${spec.id.toUpperCase()}] ${spec.title}`;
+    const description = buildAdoDescription(spec);
+
+    if (verbose) {
+      console.log(`\n📝 Creating ADO feature:`);
+      console.log(`   Title: ${title}`);
+      console.log(`   Description length: ${description.length} chars`);
+    }
+
+    if (dryRun) {
+      console.log('\n🔍 Dry run - would create feature:');
+      console.log(`   Title: ${title}`);
+      console.log(`   Description:\n${description}`);
+
+      return {
+        success: true,
+        action: 'created',
+        externalId: 'DRY-RUN',
+        externalUrl: 'https://dev.azure.com/DRY-RUN',
+      };
+    }
+
+    // Create feature
+    const tags = ['specweave', 'spec', spec.metadata.priority || 'P2'];
+    const workItem = await client.createEpic({
+      title,
+      description,
+      tags,
+    });
+
+    if (verbose) {
+      console.log(`✅ Created feature #${workItem.id}`);
+      console.log(`   URL: ${workItem._links.html.href}`);
+    }
+
+    // Update spec with ADO link
+    await updateSpecWithExternalLink(
+      specPath,
+      'ado',
+      workItem.id.toString(),
+      workItem._links.html.href
+    );
+
+    return {
+      success: true,
+      action: 'created',
+      externalId: workItem.id.toString(),
+      externalUrl: workItem._links.html.href,
+    };
+  } catch (error: any) {
+    return {
+      success: false,
+      action: 'error',
+      error: `Failed to create ADO feature: ${error.message}`,
+    };
+  }
+}
+
+/**
+ * Update existing ADO feature with spec content
+ */
+async function updateAdoFeature(
+  client: AdoClientV2,
+  spec: SpecContent,
+  workItemId: number,
+  options: AdoContentSyncOptions
+): Promise<ContentSyncResult> {
+  const { specPath, dryRun, verbose } = options;
+
+  try {
+    // Get current work item
+    const workItem = await client.getWorkItem(workItemId);
+
+    if (verbose) {
+      console.log(`\n🔄 Checking for changes in feature #${workItemId}`);
+    }
+
+    // Detect changes
+    const changes = detectContentChanges(spec, {
+      title: workItem.fields['System.Title'].replace(/^\[SPEC-\d+\]\s*/, ''),
+      description: stripHtmlTags(workItem.fields['System.Description'] || ''),
+      userStoryCount: 0, // TODO: Parse from description
+    });
+
+    if (!changes.hasChanges) {
+      if (verbose) {
+        console.log('   ℹ️  No changes detected');
+      }
+
+      return {
+        success: true,
+        action: 'no-change',
+        externalId: workItemId.toString(),
+        externalUrl: workItem._links.html.href,
+      };
+    }
+
+    if (verbose) {
+      console.log('   📝 Changes detected:');
+      for (const change of changes.changes) {
+        console.log(`      - ${change}`);
+      }
+    }
+
+    // Build updated content
+    const newTitle = `[${spec.id.toUpperCase()}] ${spec.title}`;
+    const newDescription = buildAdoDescription(spec);
+
+    if (dryRun) {
+      console.log('\n🔍 Dry run - would update feature:');
+      console.log(`   Title: ${newTitle}`);
+      console.log(`   Description:\n${newDescription}`);
+
+      return {
+        success: true,
+        action: 'updated',
+        externalId: workItemId.toString(),
+        externalUrl: workItem._links.html.href,
+      };
+    }
+
+    // Update feature (ONLY title and description, NOT state!)
+    await client.updateWorkItem(workItemId, {
+      title: newTitle,
+      description: newDescription,
+    });
+
+    // Note: We do NOT update State (New → Active → Resolved → Closed)
+    // State transitions are managed in ADO by humans/workflows
+
+    if (verbose) {
+      console.log(`✅ Updated feature #${workItemId}`);
+    }
+
+    return {
+      success: true,
+      action: 'updated',
+      externalId: workItemId.toString(),
+      externalUrl: workItem._links.html.href,
+    };
+  } catch (error: any) {
+    return {
+      success: false,
+      action: 'error',
+      error: `Failed to update ADO feature: ${error.message}`,
+    };
+  }
+}
+
+/**
+ * Build ADO description from spec content
+ * ADO supports HTML in description
+ */
+function buildAdoDescription(spec: SpecContent): string {
+  let html = '';
+
+  // Add spec description
+  if (spec.description) {
+    html += `<p>${escapeHtml(spec.description)}</p>`;
+  }
+
+  // Add user stories
+  if (spec.userStories.length > 0) {
+    html += '<h2>User Stories</h2>';
+
+    for (const us of spec.userStories) {
+      html += `<h3>${us.id}: ${escapeHtml(us.title)}</h3>`;
+
+      if (us.acceptanceCriteria.length > 0) {
+        html += '<p><strong>Acceptance Criteria:</strong></p><ul>';
+        for (const ac of us.acceptanceCriteria) {
+          const checkbox = ac.completed ? '☑' : '☐';
+          html += `<li>${checkbox} ${ac.id}: ${escapeHtml(ac.description)}</li>`;
+        }
+        html += '</ul>';
+      }
+    }
+  }
+
+  // Add metadata
+  if (spec.metadata.priority) {
+    html += `<p><strong>Priority:</strong> ${spec.metadata.priority}</p>`;
+  }
+
+  return html;
+}
+
+/**
+ * Escape HTML special characters
+ */
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+/**
+ * Strip HTML tags from text
+ */
+function stripHtmlTags(html: string): string {
+  return html.replace(/<[^>]*>/g, '').trim();
+}
+
+/**
+ * Check if spec content sync is enabled
+ */
+export async function isContentSyncEnabled(projectRoot: string): Promise<boolean> {
+  try {
+    const configPath = path.join(projectRoot, '.specweave', 'config.json');
+    const config = JSON.parse(await fs.readFile(configPath, 'utf-8'));
+
+    return config.sync?.settings?.syncSpecContent !== false;
+  } catch {
+    return true; // Default: enabled
+  }
+}

package/plugins/specweave-ado/lib/conflict-resolver.ts

@@ -145,7 +145,7 @@ export class ConflictResolver {
    */
   public mapExternalStatus(tool: 'ado' | 'jira' | 'github', externalStatus: string): SpecStatus {
     const mapping = STATUS_MAPPING[tool];
-    return mapping[externalStatus] || 'unknown' as SpecStatus;
+    return (mapping as Record<string, SpecStatus>)[externalStatus] || 'unknown' as SpecStatus;
   }
 
   /**

package/plugins/specweave-ado/skills/ado-resource-validator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ado-resource-validator
-description: Validates Azure DevOps projects and resources exist, creates missing resources automatically. Smart enough to prompt user to select existing or create new projects. Supports multiple projects for project-per-team strategy, area paths for area-path-based strategy, and teams for team-based strategy. Activates for ado setup, ado validation, ado configuration, missing ado project, azure devops .env setup.
+description: Validates Azure DevOps projects and resources exist, creates missing resources automatically. Smart enough to prompt user to select existing or create new projects. Supports multiple projects for project-per-team strategy, area paths for area-path-based strategy, and teams for team-based strategy. NEW - Per-project configuration support - AZURE_DEVOPS_AREA_PATHS_{ProjectName} and AZURE_DEVOPS_TEAMS_{ProjectName} for hierarchical organization. Activates for ado setup, ado validation, ado configuration, missing ado project, azure devops .env setup, per-project area paths, per-project teams.
 allowed-tools: Read, Bash, Write, Edit
 ---
 
@@ -66,6 +66,32 @@ AZURE_DEVOPS_TEAMS=Alpha Team,Beta Team,Gamma Team
 → Validates MainProduct project exists
 → Creates teams if missing: Alpha Team, Beta Team, Gamma Team
 
+**NEW: Per-Project Configuration** (Advanced - Multiple Projects × Resources)
+```bash
+# Multiple projects with their own area paths and teams
+AZURE_DEVOPS_STRATEGY=project-per-team
+AZURE_DEVOPS_PROJECTS=Backend,Frontend,Mobile
+
+# Per-project area paths (hierarchical naming)
+AZURE_DEVOPS_AREA_PATHS_Backend=API,Database,Cache
+AZURE_DEVOPS_AREA_PATHS_Frontend=Web,Admin,Public
+AZURE_DEVOPS_AREA_PATHS_Mobile=iOS,Android,Shared
+
+# Per-project teams (optional)
+AZURE_DEVOPS_TEAMS_Backend=Alpha,Beta
+AZURE_DEVOPS_TEAMS_Frontend=Gamma
+```
+→ Validates 3 projects exist: Backend, Frontend, Mobile
+→ Creates area paths per project:
+  - Backend\API, Backend\Database, Backend\Cache
+  - Frontend\Web, Frontend\Admin, Frontend\Public
+  - Mobile\iOS, Mobile\Android, Mobile\Shared
+→ Creates teams per project:
+  - Backend: Alpha, Beta
+  - Frontend: Gamma
+
+**Naming Convention**: `{PROVIDER}_{RESOURCE_TYPE}_{PROJECT_NAME}`
+
 ## Validation Flow
 
 ### Step 1: Strategy Detection
@@ -326,28 +352,155 @@ Work items will be organized by area:
   • Analytics features → EnterpriseApp\Analytics
 ```
 
+## Implementation Details
+
+**Location**: `src/utils/external-resource-validator.ts`
+
+**Core Classes**:
+```typescript
+// Main validator class
+export class AzureDevOpsResourceValidator {
+  private pat: string;
+  private organization: string;
+  private envPath: string;
+
+  constructor(envPath: string = '.env') {
+    this.envPath = envPath;
+    const env = this.loadEnv();
+    this.pat = env.AZURE_DEVOPS_PAT || '';
+    this.organization = env.AZURE_DEVOPS_ORG || '';
+  }
+
+  // Main validation entry point
+  async validate(): Promise<AzureDevOpsValidationResult> {
+    const env = this.loadEnv();
+    const strategy = env.AZURE_DEVOPS_STRATEGY || 'project-per-team';
+
+    // Validate based on strategy
+    if (strategy === 'project-per-team') {
+      return this.validateMultipleProjects(projectNames);
+    } else if (strategy === 'area-path-based') {
+      return this.validateAreaPaths(projectName, areaPaths);
+    } else if (strategy === 'team-based') {
+      return this.validateTeams(projectName, teams);
+    }
+  }
+}
+
+// Public API function
+export async function validateAzureDevOpsResources(
+  envPath: string = '.env'
+): Promise<AzureDevOpsValidationResult> {
+  const validator = new AzureDevOpsResourceValidator(envPath);
+  return validator.validate();
+}
+```
+
+**Key Implementation Features**:
+
+1. **Async Project Creation** (ADO-specific):
+   ```typescript
+   // ADO creates projects asynchronously - need to poll for completion
+   async createProject(name: string): Promise<AzureDevOpsProject> {
+     const result = await this.callAzureDevOpsApi('projects?api-version=7.0', 'POST', body);
+
+     // Wait for project to be fully created (ADO async behavior)
+     await this.waitForProjectCreation(result.id);
+
+     return { id: result.id, name, description };
+   }
+
+   // Poll until project is in 'wellFormed' state
+   private async waitForProjectCreation(projectId: string): Promise<void> {
+     const maxAttempts = 30; // 30 seconds max wait
+     for (let i = 0; i < maxAttempts; i++) {
+       const project = await this.getProject(projectId);
+       if (project.state === 'wellFormed') {
+         return; // Project is ready!
+       }
+       await new Promise(resolve => setTimeout(resolve, 1000)); // Wait 1 second
+     }
+     throw new Error('Project creation timeout');
+   }
+   ```
+
+2. **Interactive Prompts** (when resources missing):
+   ```typescript
+   const { action } = await inquirer.prompt([
+     {
+       type: 'list',
+       name: 'action',
+       message: `Project "${projectName}" not found. What would you like to do?`,
+       choices: [
+         { name: 'Create new project', value: 'create' },
+         { name: 'Select existing project', value: 'select' },
+         { name: 'Skip this project', value: 'skip' },
+         { name: 'Cancel', value: 'cancel' }
+       ]
+     }
+   ]);
+   ```
+
+3. **Automatic .env Updates**:
+   ```typescript
+   // After creating projects, update .env
+   updateEnv(key: string, value: string): void {
+     const envContent = fs.readFileSync(this.envPath, 'utf-8');
+     const updated = envContent.replace(
+       new RegExp(`^${key}=.*$`, 'm'),
+       `${key}=${value}`
+     );
+     fs.writeFileSync(this.envPath, updated);
+   }
+   ```
+
 ## CLI Command
 
-**Manual validation**:
+**Automatic validation** (during setup):
 ```bash
-# From TypeScript
-npx tsx src/utils/external-resource-validator.ts --provider=ado
+# Runs automatically during specweave init
+npx specweave init
 
-# Or via skill activation
+# Also runs automatically before sync
+/specweave-ado:sync 0014
+```
+
+**Manual validation**:
+```bash
+# Via skill activation
 "Can you validate my Azure DevOps configuration?"
+
+# Via TypeScript directly
+npx tsx -e "import { validateAzureDevOpsResources } from './dist/utils/external-resource-validator.js'; await validateAzureDevOpsResources();"
+
+# Via CLI (future command - planned)
+specweave validate-ado
 ```
 
 **Validation output**:
 ```typescript
+interface AzureDevOpsValidationResult {
+  valid: boolean;
+  strategy: 'project-per-team' | 'area-path-based' | 'team-based';
+  projects: Array<{
+    name: string;
+    id: string;
+    exists: boolean;
+  }>;
+  created: string[];      // Names of newly created resources
+  envUpdated: boolean;    // Whether .env was modified
+}
+
+// Example output:
 {
   valid: true,
   strategy: 'project-per-team',
   projects: [
     { name: 'WebApp', id: 'proj-001', exists: true },
-    { name: 'MobileApp', id: 'proj-002', exists: true },
-    { name: 'Platform', id: 'proj-003', exists: true }
+    { name: 'MobileApp', id: 'proj-002', exists: true, created: true },
+    { name: 'Platform', id: 'proj-003', exists: true, created: true }
   ],
-  created: [],
+  created: ['MobileApp', 'Platform'],
   envUpdated: false
 }
 ```
@@ -700,20 +853,54 @@ Based on strategy, the skill creates appropriate folder structure:
     └── spec-001-feature-c.md
 ```
 
+## Key Differences from JIRA
+
+**Azure DevOps vs JIRA Resource Creation**:
+
+| Aspect | Azure DevOps | JIRA |
+|--------|-------------|------|
+| **Project Creation** | Asynchronous (polling required) | Synchronous (immediate) |
+| **Creation Time** | 5-30 seconds | <1 second |
+| **Status Tracking** | Poll `state` field ('wellFormed') | No polling needed |
+| **API Complexity** | Higher (async handling) | Lower (sync operations) |
+| **Board Creation** | Auto-created with project | Requires separate API call |
+| **Process Templates** | Required (Agile, Scrum, CMMI) | Not applicable |
+
+**Why Async Matters**:
+
+When you create an ADO project, the API returns immediately with `state: 'new'`, but the project isn't usable yet. The validator polls every 1 second (max 30 attempts) until `state: 'wellFormed'`:
+
+```typescript
+// Create project (returns immediately)
+const project = await createProject('MobileApp'); // state: 'new'
+
+// Poll until ready
+await waitForProjectCreation(project.id); // Polls until state: 'wellFormed'
+
+// Now safe to use!
+console.log('✅ Project ready for work items');
+```
+
+**Impact on UX**:
+- JIRA: "✅ Project created" (instant)
+- ADO: "📦 Creating project... ⏳ Waiting for Azure DevOps to complete setup... ✅ Project ready!" (5-30s)
+
 ## Summary
 
 This skill ensures your Azure DevOps configuration is **always valid** by:
 
 1. ✅ **Validating projects** - Check if projects exist, prompt to select or create
 2. ✅ **Supporting multiple strategies** - Project-per-team, area-path-based, team-based
-3. ✅ **Auto-creating resources** - Projects, area paths, teams
+3. ✅ **Auto-creating resources** - Projects, area paths, teams (with async handling)
 4. ✅ **Organizing specs** - Create folder structure based on projects
 5. ✅ **Clear error messages** - Actionable guidance for all failures
+6. ✅ **Handles ADO async behavior** - Polls for project creation completion
 
-**Result**: Zero manual Azure DevOps setup - system handles everything!
+**Result**: Zero manual Azure DevOps setup - system handles everything, including ADO's async project creation!
 
 ---
 
-**Skill Version**: 1.0.0
+**Skill Version**: 1.1.0
 **Introduced**: SpecWeave v0.17.0
-**Last Updated**: 2025-11-11
+**Last Updated**: 2025-11-11
+**Key Changes v1.1.0**: Added implementation details, async project creation handling, JIRA comparison

package/plugins/specweave-github/.claude-plugin/plugin.json

@@ -15,5 +15,6 @@
     "integration",
     "sync",
     "specweave"
-  ]
+  ],
+  "hooks": "hooks/hooks.json"
 }