ado-multi-project
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.
When & Why to Use This Skill
This Claude skill streamlines complex Azure DevOps workflows by intelligently organizing specifications and splitting tasks across multiple projects. It automates project mapping through content analysis, maintains structured local documentation, and ensures bidirectional synchronization with work items, making it essential for teams managing microservices or multi-team architectures.
Use Cases
- Microservices Coordination: Automatically detecting and routing feature specs to the correct service-specific Azure DevOps projects (e.g., AuthService, PaymentService) based on technical keywords and file patterns.
- Cross-Project Task Splitting: Breaking down a unified requirement into project-specific work items and distributing them across different team backlogs while maintaining dependencies.
- Area Path Organization: Automatically mapping user stories to specific functional Area Paths within monolithic Azure DevOps projects using intelligent context detection.
- Bidirectional Documentation Sync: Maintaining a structured local repository of markdown specifications that stays perfectly in sync with Azure DevOps Epics, Features, and Tasks.
- Multi-Team Architecture Management: Handling diverse organizational structures including project-per-team, area-path-based, and team-based architectures with zero manual overhead.
| 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:
- 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](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:
- ✅ 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