/ado-sync

description: "[DEPRECATED] Help and guidance for Azure DevOps synchronization with SpecWeave increments. Use when asking how to set up ADO sync, configure credentials, or troubleshoot integration issues. For actual syncing, use sw-ado:push or sw-ado:pull command."
version: 1.0.0
user-invokable: false
deprecated: true

> ⚠️ DEPRECATED: Use `sw-ado:push` / `sw-ado:pull` instead. This skill will be removed in v1.3.0.

Migration

This skill has been deprecated as part of the Opus 4.7 framework alignment (increment 0669).

• **Use instead**: `sw-ado:push` (content SpecWeave→ADO) and `sw-ado:pull` (status ADO→SpecWeave)
• **Removal**: Scheduled for v1.3.0 (2 minor releases after v1.1.0)
• **Why**: Consolidated sync logic moved to the `sw-ado:*` command family.

For the migration policy, see `.specweave/docs/internal/specs/skill-deprecation-policy.md`.

---

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**: 1. Go to https://dev.azure.com/{organization}/_usersSettings/tokens 2. Click "New Token" 3. Name: "SpecWeave Sync" 4. Scopes: Work Items (Read & Write), Comments (Read & Write) 5. Copy token → Set environment variable

**Set Token**:

export AZURE_DEVOPS_PAT="your-token-here"

3. ADO Configuration

Add to `.specweave/config.json`:

{
  "sync": {
    "enabled": true,
    "preset": "bidirectional",
    "activeProfile": "default",
    "profiles": {
      "default": {
        "provider": "ado",
        "config": {
          "organization": "myorg",
          "project": "MyProject",
          "workItemType": "Epic",
          "areaPath": "MyProject\\Team A",
          "syncOnTaskComplete": true
        }
      }
    }
  }
}

**Credentials** (in `.env`, gitignored):

AZURE_DEVOPS_PAT=your-token-here
# Or org-specific: AZURE_DEVOPS_PAT_MYORG=your-token

---

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**: 1. User marks task complete: `[x] T-005: Add payment tests` 2. Hook detects ADO sync enabled 3. Calculate new completion % 4. Update ADO work item comment:

   ## Progress Update
   
   **Increment**: 0005-payment-integration
   **Status**: 60% complete (6/10 tasks)
   
   ### Recently Completed
   - [x] 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**: 1. User runs `sw:done 0005` 2. Validate all tasks complete 3. Close ADO work item automatically 4. 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**:

• Spe