specweave 0.16.5 → 0.17.0

package/plugins/specweave-ado/skills/ado-multi-project/SKILL.md

@@ -0,0 +1,541 @@
+---
+name: ado-multi-project
+description: Expert at organizing specs and splitting tasks across multiple Azure DevOps projects. Handles project-per-team, area-path-based, and team-based architectures. Intelligently maps increments and specs to correct projects based on content analysis. Activates for multi-project Azure DevOps setups, task splitting, spec organization, team allocation, cross-project coordination.
+allowed-tools: Read, Write, Edit, Glob
+---
+
+# Azure DevOps Multi-Project Skill
+
+**Purpose**: Organize specs and increments across multiple Azure DevOps projects with intelligent mapping and folder organization.
+
+## What This Skill Does
+
+This skill handles complex multi-project Azure DevOps organizations by:
+
+1. **Analyzing increment content** to determine which project it belongs to
+2. **Creating project-specific folder structures** in `.specweave/docs/internal/specs/`
+3. **Mapping user stories to correct projects** based on keywords and context
+4. **Splitting tasks across projects** when increments span multiple teams
+5. **Maintaining bidirectional sync** between local specs and Azure DevOps work items
+
+## Supported Architectures
+
+### 1. Project-per-team (Recommended for Microservices)
+
+```
+Organization: mycompany
+├── AuthService (Project)
+├── UserService (Project)
+├── PaymentService (Project)
+└── NotificationService (Project)
+
+Local Structure:
+.specweave/docs/internal/specs/
+├── AuthService/
+├── UserService/
+├── PaymentService/
+└── NotificationService/
+```
+
+### 2. Area-path-based (Monolithic Applications)
+
+```
+Organization: enterprise
+└── ERP (Project)
+    ├── Finance (Area Path)
+    ├── HR (Area Path)
+    ├── Inventory (Area Path)
+    └── Sales (Area Path)
+
+Local Structure:
+.specweave/docs/internal/specs/ERP/
+├── Finance/
+├── HR/
+├── Inventory/
+└── Sales/
+```
+
+### 3. Team-based (Small Organizations)
+
+```
+Organization: startup
+└── Platform (Project)
+    ├── Alpha Team
+    ├── Beta Team
+    └── Gamma Team
+
+Local Structure:
+.specweave/docs/internal/specs/Platform/
+├── AlphaTeam/
+├── BetaTeam/
+└── GammaTeam/
+```
+
+## Intelligent Project Detection
+
+The skill analyzes increment content to determine the correct project:
+
+### Detection Patterns
+
+```typescript
+const projectPatterns = {
+  'AuthService': {
+    keywords: ['authentication', 'login', 'oauth', 'jwt', 'session', 'password'],
+    filePatterns: ['auth/', 'login/', 'security/'],
+    confidence: 0.0
+  },
+  'UserService': {
+    keywords: ['user', 'profile', 'account', 'registration', 'preferences'],
+    filePatterns: ['users/', 'profiles/', 'accounts/'],
+    confidence: 0.0
+  },
+  'PaymentService': {
+    keywords: ['payment', 'stripe', 'billing', 'invoice', 'subscription'],
+    filePatterns: ['payment/', 'billing/', 'checkout/'],
+    confidence: 0.0
+  }
+};
+
+// Analyze spec content
+const spec = readSpec(incrementId);
+for (const [project, pattern] of Object.entries(projectPatterns)) {
+  pattern.confidence = calculateConfidence(spec, pattern);
+}
+
+// Select project with highest confidence
+const selectedProject = Object.entries(projectPatterns)
+  .sort((a, b) => b[1].confidence - a[1].confidence)[0][0];
+```
+
+### Confidence Calculation
+
+- **Keyword match**: +0.2 per keyword found
+- **File pattern match**: +0.3 per pattern
+- **Explicit mention**: +1.0 if project name in spec
+- **Team mention**: +0.5 if team name matches
+
+**Threshold**: Confidence > 0.7 = auto-assign, otherwise prompt user
+
+## Usage Examples
+
+### Example 1: Single-Project Increment
+
+**Scenario**: Authentication feature for AuthService
+
+**Spec Analysis**:
+```
+Title: "Add OAuth 2.0 authentication"
+Keywords found: authentication, oauth, jwt
+File patterns: src/auth/oauth-provider.ts
+Confidence: AuthService = 0.9 ✅
+```
+
+**Action**:
+```bash
+# Auto-creates folder structure
+.specweave/docs/internal/specs/AuthService/
+└── spec-001-oauth-authentication.md
+
+# Maps to Azure DevOps
+Project: AuthService
+Work Item: Epic "OAuth 2.0 Authentication"
+```
+
+### Example 2: Multi-Project Increment
+
+**Scenario**: Checkout flow spanning multiple services
+
+**Spec Analysis**:
+```
+Title: "Implement checkout flow with payment processing"
+Keywords found: user, cart, payment, stripe, notification
+Confidence:
+  - UserService = 0.6
+  - PaymentService = 0.8 ✅
+  - NotificationService = 0.5
+```
+
+**Action**:
+```bash
+# Creates multi-project structure
+.specweave/docs/internal/specs/
+├── PaymentService/
+│   └── spec-002-checkout-payment.md (primary)
+├── UserService/
+│   └── spec-002-checkout-user.md (linked)
+└── NotificationService/
+    └── spec-002-checkout-notifications.md (linked)
+
+# Creates linked work items in Azure DevOps
+PaymentService: Epic "Checkout Payment Processing" (primary)
+UserService: Feature "User Cart Management" (links to primary)
+NotificationService: Feature "Order Notifications" (links to primary)
+```
+
+### Example 3: Area Path Organization
+
+**Scenario**: ERP system with module-based organization
+
+**Configuration**:
+```bash
+AZURE_DEVOPS_STRATEGY=area-path-based
+AZURE_DEVOPS_PROJECT=ERP
+AZURE_DEVOPS_AREA_PATHS=Finance,HR,Inventory
+```
+
+**Spec Analysis**:
+```
+Title: "Add payroll calculation engine"
+Keywords found: payroll, salary, tax, employee
+Area match: HR (confidence = 0.85)
+```
+
+**Action**:
+```bash
+# Creates area-based structure
+.specweave/docs/internal/specs/ERP/HR/
+└── spec-003-payroll-engine.md
+
+# Maps to Azure DevOps
+Project: ERP
+Area Path: ERP\HR
+Work Item: Epic "Payroll Calculation Engine"
+```
+
+## Task Splitting Across Projects
+
+When an increment spans multiple projects, tasks are intelligently split:
+
+### Input: Unified tasks.md
+```markdown
+# Tasks for Checkout Flow
+
+- T-001: Create shopping cart API (UserService)
+- T-002: Implement Stripe integration (PaymentService)
+- T-003: Add order confirmation email (NotificationService)
+- T-004: Update user order history (UserService)
+- T-005: Process payment webhook (PaymentService)
+```
+
+### Output: Project-specific work items
+
+**UserService** (2 tasks):
+- Task: Create shopping cart API
+- Task: Update user order history
+
+**PaymentService** (2 tasks):
+- Task: Implement Stripe integration
+- Task: Process payment webhook
+
+**NotificationService** (1 task):
+- Task: Add order confirmation email
+
+## Folder Structure Creation
+
+The skill automatically creates and maintains folder structure:
+
+### On Increment Creation
+
+```typescript
+async function createProjectFolders(increment: Increment) {
+  const projects = detectProjects(increment);
+
+  for (const project of projects) {
+    const specPath = `.specweave/docs/internal/specs/${project}/`;
+    await ensureDir(specPath);
+
+    // Create project-specific spec
+    const spec = extractProjectSpec(increment, project);
+    await writeSpec(`${specPath}/spec-${increment.number}-${increment.name}.md`, spec);
+
+    // Create README if first spec in project
+    if (isFirstSpec(project)) {
+      await createProjectReadme(project);
+    }
+  }
+}
+```
+
+### Project README Template
+
+```markdown
+# {Project} Specifications
+
+## Overview
+This folder contains specifications for the {Project} project.
+
+## Architecture
+{Brief description of project architecture}
+
+## Team
+- Team Lead: {name}
+- Developers: {list}
+
+## Specifications
+- [spec-001-feature.md](spec-001-feature.md) - {description}
+
+## External Links
+- Azure DevOps: https://dev.azure.com/{org}/{project}
+- Repository: {git-url}
+```
+
+## Sync Commands
+
+### Sync Increment to Projects
+
+```bash
+/specweave-ado:sync-increment 0014
+
+# Detects projects from spec
+# Creates work items in each project
+# Links work items together
+```
+
+### Sync Spec to Project
+
+```bash
+/specweave-ado:sync-spec AuthService/spec-001
+
+# Syncs single spec to specific project
+# Updates existing work item or creates new
+```
+
+### Sync All Specs
+
+```bash
+/specweave-ado:sync-all
+
+# Syncs all specs across all projects
+# Maintains relationships
+# Updates bidirectionally
+```
+
+## Project Mapping Configuration
+
+### Manual Mapping (config.json)
+
+```json
+{
+  "ado": {
+    "projectMappings": {
+      "auth-.*": "AuthService",
+      "user-.*": "UserService",
+      "payment-.*": "PaymentService",
+      "notification-.*": "NotificationService"
+    },
+    "defaultProject": "Platform",
+    "crossProjectLinking": true
+  }
+}
+```
+
+### Auto-Detection Rules
+
+```typescript
+const autoDetectionRules = [
+  {
+    pattern: /auth|login|oauth|security/i,
+    project: "AuthService"
+  },
+  {
+    pattern: /user|profile|account/i,
+    project: "UserService"
+  },
+  {
+    pattern: /payment|billing|stripe/i,
+    project: "PaymentService"
+  }
+];
+```
+
+## Cross-Project Coordination
+
+### Dependency Management
+
+When increments span projects, dependencies are tracked:
+
+```yaml
+# .specweave/increments/0014-checkout-flow/metadata.yml
+projects:
+  primary: PaymentService
+  dependencies:
+    - UserService: [T-001, T-004]
+    - NotificationService: [T-003]
+
+ado_mappings:
+  PaymentService:
+    epic: 12345
+    work_items: [12346, 12347]
+  UserService:
+    feature: 12348
+    work_items: [12349, 12350]
+  NotificationService:
+    feature: 12351
+    work_items: [12352]
+```
+
+### Cross-Project Queries
+
+```typescript
+// Find all work items for an increment across projects
+async function getIncrementWorkItems(incrementId: string) {
+  const metadata = await readMetadata(incrementId);
+  const workItems = [];
+
+  for (const [project, mapping] of Object.entries(metadata.ado_mappings)) {
+    const items = await adoClient.getWorkItems(project, mapping.work_items);
+    workItems.push(...items);
+  }
+
+  return workItems;
+}
+```
+
+## Best Practices
+
+### 1. Consistent Naming
+
+Use consistent naming across projects:
+```
+spec-001-oauth-authentication.md    # Good
+spec-001-auth.md                    # Too vague
+SPEC_001_OAuth.md                   # Inconsistent format
+```
+
+### 2. Clear Project Boundaries
+
+Define clear boundaries between projects:
+```yaml
+AuthService:
+  owns: [authentication, authorization, sessions]
+  not: [user profiles, user preferences]
+
+UserService:
+  owns: [profiles, preferences, user data]
+  not: [authentication, passwords]
+```
+
+### 3. Link Related Specs
+
+Link specs that span projects:
+```markdown
+# spec-002-checkout-payment.md
+
+Related Specs:
+- [User Cart](../UserService/spec-002-checkout-user.md)
+- [Notifications](../NotificationService/spec-002-checkout-notifications.md)
+```
+
+### 4. Use Project Prefixes
+
+Prefix increment names with primary project:
+```bash
+/specweave:increment "payment-stripe-integration"
+/specweave:increment "auth-oauth-provider"
+/specweave:increment "user-profile-redesign"
+```
+
+## Error Handling
+
+### Project Not Found
+
+```
+❌ Project "AuthService" not found in Azure DevOps
+
+Options:
+1. Create project "AuthService"
+2. Map to existing project
+3. Skip this project
+
+Your choice [1]:
+```
+
+### Ambiguous Project Detection
+
+```
+⚠️ Cannot determine project for increment 0014
+
+Multiple projects detected:
+- UserService (confidence: 0.6)
+- PaymentService (confidence: 0.6)
+
+Please select primary project:
+1. UserService
+2. PaymentService
+3. Both (multi-project)
+
+Your choice [3]:
+```
+
+### Sync Conflicts
+
+```
+⚠️ Sync conflict detected
+
+Local: spec-001 updated 2 hours ago
+Azure DevOps: Work item updated 1 hour ago
+
+Options:
+1. Use local version
+2. Use Azure DevOps version
+3. Merge changes
+4. View diff
+
+Your choice [3]:
+```
+
+## Integration with CI/CD
+
+### Auto-sync on Commit
+
+```yaml
+# .github/workflows/specweave-sync.yml
+on:
+  push:
+    paths:
+      - '.specweave/docs/internal/specs/**'
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: npx specweave ado-sync-all
+        env:
+          AZURE_DEVOPS_PAT: ${{ secrets.ADO_PAT }}
+```
+
+### Project-specific Pipelines
+
+```yaml
+# azure-pipelines.yml
+trigger:
+  paths:
+    include:
+      - .specweave/docs/internal/specs/$(System.TeamProject)/**
+
+variables:
+  - name: project
+    value: $(System.TeamProject)
+
+steps:
+  - script: npx specweave ado-sync-project $(project)
+```
+
+## Summary
+
+This skill enables sophisticated multi-project Azure DevOps organizations by:
+
+1. ✅ **Intelligent project detection** from spec content
+2. ✅ **Automatic folder organization** by project/area/team
+3. ✅ **Task splitting** across multiple projects
+4. ✅ **Cross-project linking** and dependency tracking
+5. ✅ **Bidirectional sync** with Azure DevOps work items
+
+**Result**: Seamless multi-project coordination with zero manual overhead!
+
+---
+
+**Skill Version**: 1.0.0
+**Introduced**: SpecWeave v0.17.0
+**Last Updated**: 2025-11-11