anton-abyzov/plugins/specweave/skills/ado-multi-project

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

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:

# 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:

# 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:

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:

# 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

# 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

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

# {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

sw-ado:sync-increment 0014

# Detects projects from spec
# Creates work items in each project
# Links work items together

Sync Spec to Project

sw-ado:sync-spec AuthService/spec-001

# Syncs single spec to specific project
# Updates existing work item or creates new

Sync All Specs

sw-ado:sync-all

# Syncs all specs across all projects
# Maintains relationships
# Updates bidirectionally

Project Mapping Configuration

Manual Mapping (config.json)

{
  "ado": {
    "projectMappings": {
      "auth-.*": "AuthService",
      "user-.*": "UserService",
      "payment-.*": "PaymentService",
      "notification-.*": "NotificationService"
    },
    "defaultProject": "Platform",
    "crossProjectLinking": true
  }
}

Auto-Detection Rules

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:

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

// 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:

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:

# 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:

sw:increment "payment-stripe-integration"
sw:increment "auth-oauth-provider"
sw: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

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

# 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