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:

• Analyzing increment content to determine which project it belongs to

• Creating project-specific folder structures in .specweave/docs/internal/specs/

• Mapping user stories to correct projects based on keywords and context

• Splitting tasks across projects when increments span multiple teams

• 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 - {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
• Notifications

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:

• ✅ Intelligent project detection from spec content

• ✅ Automatic folder organization by project/area/team

• ✅ Task splitting across multiple projects

• ✅ Cross-project linking and dependency tracking

• ✅ 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