Azure DevOps Sync Skill

Purpose: Seamlessly sync SpecWeave increments with Azure DevOps work items for unified project tracking.

Default Behavior: Bidirectional (two-way) sync - Changes in either system are automatically synchronized

⚠️ IMPORTANT: This skill provides HELP and GUIDANCE about Azure DevOps sync. For actual syncing, users should use the /sw-ado:sync command directly. This skill should NOT auto-activate when the command is being invoked.

Capabilities:

• Bidirectional sync: SpecWeave ↔ ADO (default)

• Create ADO work items from increments

• Sync task progress → ADO comments

• Update increment status ← ADO state changes

• Pull ADO comments and field updates → SpecWeave

• Close work items when increments complete

• Support for Epics, Features, User Stories

When This Skill Activates

✅ Do activate when:

• User asks: "How do I set up Azure DevOps sync?"

• User asks: "What ADO credentials do I need?"

• User asks: "How does ADO integration work?"

• User needs help configuring Azure DevOps integration

❌ Do NOT activate when:

• User invokes /sw-ado:sync command (command handles it)

• Command is already running (avoid duplicate invocation)

• Task completion hook is syncing (automatic process)

• "Close ADO work item when done"

Prerequisites

1. ADO Plugin Installed

Check if installed

/plugin list --installed | grep sw-ado

Install if needed

/plugin install sw-ado@specweave

2. Azure DevOps Personal Access Token (PAT)

Create PAT:

• Go to https://dev.azure.com/{organization}/_usersSettings/tokens

• Click "New Token"

• Name: "SpecWeave Sync"

• Scopes: Work Items (Read & Write), Comments (Read & Write)

• Copy token → Set environment variable

Set Token:

export AZURE_DEVOPS_PAT="your-token-here"

3. ADO Configuration

Add to .specweave/config.json :

{ "externalPM": { "tool": "ado", "enabled": true, "config": { "organization": "myorg", "project": "MyProject", "workItemType": "Epic", "areaPath": "MyProject\Team A", "syncOnTaskComplete": true } } }

Commands Available

/sw-ado:create-workitem <increment-id>

Purpose: Create ADO work item from increment

Example:

/sw-ado:create-workitem 0005

Result:

• Creates Epic/Feature/User Story in ADO

• Links work item to increment (metadata)

• Adds initial comment with spec summary

• Sets tags: specweave , increment-0005

/sw-ado:sync <increment-id>

Purpose: Sync increment progress with ADO work item

Example:

/sw-ado:sync 0005

Result:

• Calculates task completion (%)

• Updates work item description

• Adds comment with progress update

• Updates state (New → Active → Resolved)

/sw-ado:close-workitem <increment-id>

Purpose: Close ADO work item when increment complete

Example:

/sw-ado:close-workitem 0005

Result:

• Updates work item state → Closed

• Adds completion comment with summary

• Marks work item as resolved

/sw-ado:status <increment-id>

Purpose: Check ADO sync status for increment

Example:

/sw-ado:status 0005

Result:

ADO Sync Status

Increment: 0005-payment-integration Work Item: #12345 URL: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345 State: Active Completion: 60% (6/10 tasks) Last Synced: 2025-11-04 10:30:00 Sync Enabled: ✅

Automatic Sync

When Task Completes

Trigger: Post-task-completion hook fires

Flow:

• User marks task complete: [x] T-005: Add payment tests

• Hook detects ADO sync enabled

• Calculate new completion %

• Update ADO work item comment:

Progress Update

Increment: 0005-payment-integration Status: 60% complete (6/10 tasks)

Recently Completed

• T-005: Add payment tests

Remaining

• T-007: Add refund functionality
• T-008: Implement subscriptions
• T-009: Add analytics
• T-010: Security audit

🤖 Auto-updated by SpecWeave

When Increment Completes

Trigger: /sw:done command

Flow:

• User runs /sw:done 0005

• Validate all tasks complete

• Close ADO work item automatically

• Add completion comment with summary

Work Item Types

Epic (Recommended)

Use When: Large feature spanning multiple sprints

Mapping:

• SpecWeave increment → ADO Epic

• Tasks → Epic description (checklist)

• Progress → Epic comments

Feature

Use When: Medium-sized feature within a sprint

Mapping:

• SpecWeave increment → ADO Feature

• Tasks → Feature description (checklist)

• Progress → Feature comments

User Story

Use When: Small, single-sprint work

Mapping:

• SpecWeave increment → ADO User Story

• Tasks → User Story description (checklist)

• Progress → User Story comments

Bidirectional Sync (Optional)

Enable: Set bidirectional: true in config

Flow: ADO → SpecWeave

• User updates work item state in ADO (Active → Resolved)

• SpecWeave detects change (polling or webhook)

• Updates increment status locally

• Notifies user: "Work item #12345 resolved → Increment 0005 marked complete"

Note: Bidirectional sync requires webhook or polling setup

Configuration Options

.specweave/config.json :

{ "externalPM": { "tool": "ado", "enabled": true, "config": { "organization": "myorg", "project": "MyProject", "personalAccessToken": "${AZURE_DEVOPS_PAT}", "workItemType": "Epic", "areaPath": "MyProject\Team A", "iterationPath": "MyProject\Sprint 1", "syncOnTaskComplete": true, "syncOnIncrementComplete": true, "createWorkItemsAutomatically": true, "bidirectional": false, "tags": ["specweave", "increment"], "customFields": { "incrementId": "Custom.IncrementId" } } } }

Troubleshooting

Error: "Personal Access Token invalid"

Solution:

• Verify token is set: echo $AZURE_DEVOPS_PAT

• Check token scopes: Work Items (Read & Write)

• Ensure token not expired

• Regenerate token if needed

Error: "Work item not found"

Solution:

• Check work item ID is correct

• Verify you have access to the project

• Ensure work item not deleted

Error: "Organization or project not found"

Solution:

• Verify organization name: https://dev.azure.com/{organization}

• Check project name (case-sensitive)

• Ensure you have access to the project

API Rate Limits

Azure DevOps:

• Rate limit: 200 requests per minute per PAT

• Burst limit: 5000 requests per hour

• Recommendation: Enable rate limiting in config

Config:

{ "externalPM": { "config": { "rateLimiting": { "enabled": true, "maxRequestsPerMinute": 150 } } } }

Security Best Practices

DO:

• ✅ Store PAT in environment variable (AZURE_DEVOPS_PAT )

• ✅ Use .env file (gitignored)

• ✅ Set minimum required scopes

• ✅ Rotate PAT every 90 days

DON'T:

• ❌ Commit PAT to git

• ❌ Share PAT via Slack/email

• ❌ Use PAT with excessive permissions

• ❌ Log PAT to console/files

Related Commands

• /sw:inc

• Create increment (auto-creates ADO work item if enabled)

• /sw:do

• Execute tasks (auto-syncs progress to ADO)

• /sw:done

• Complete increment (auto-closes ADO work item)

• /sw:status

• Show increment status (includes ADO sync status)

Examples

Example 1: Create Increment with ADO Sync

User

"Create increment for payment integration"

SpecWeave (if ADO enabled)

1. PM agent generates spec.md
2. Auto-create ADO Epic #12345
3. Link Epic to increment metadata
4. Display: "Created increment 0005 → ADO Epic #12345"

Example 2: Manual Sync

User completed 3 tasks manually

Now sync to ADO

/sw-ado:sync 0005

Result: ADO Epic #12345 updated with 30% progress

Example 3: Check Sync Status

/sw-ado:status 0005

Output:

Work Item: #12345

URL: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345

State: Active

Completion: 60%

Last Synced: 5 minutes ago

Status: Ready to use Version: 0.1.0 Plugin: specweave-ado