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.5Action:
# 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,InventorySpec 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 togetherSync Spec to Project
/sw-ado:sync-spec AuthService/spec-001
# Syncs single spec to specific project
# Updates existing work item or creates newSync All Specs
/sw-ado:sync-all
# Syncs all specs across all projects
# Maintains relationships
# Updates bidirectionallyProject 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 format2. 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:
- ✅ 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