spec-kit/templates/commands/adosync.md

description, scripts

description	scripts
Sync selected user stories or tasks to Azure DevOps	sh ps scripts/bash/create-ado-workitems.sh scripts/powershell/create-ado-workitems.ps1

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Prerequisites

CRITICAL: Before executing this command, verify:

1. Azure CLI is installed (az --version)
2. Azure DevOps extension is installed (az extension list | grep azure-devops)
3. User has authenticated with Azure CLI (az account show)

If Azure CLI is not installed, show error and installation link: https://aka.ms/installazurecliwindows If DevOps extension is missing, auto-install it: az extension add --name azure-devops If not authenticated, prompt: az login --use-device-code

Outline

CRITICAL WORKFLOW - Follow these steps IN ORDER:

This command syncs user stories from spec.md OR tasks from tasks.md to Azure DevOps as work items using Azure CLI with OAuth authentication (no PAT tokens required).

Two modes:

1. User Story Mode (default): Syncs user stories from spec.md as User Story work items
2. Task Mode (with -FromTasks flag): Syncs tasks from tasks.md as Task work items linked to parent User Stories

Step 1: Collect Azure DevOps Configuration (ASK USER IN CHAT FIRST)

DO THIS BEFORE ANYTHING ELSE: Ask the user for these configuration details in the chat:

1. Check for saved configuration first:

   • Look for ~/.speckit/ado-config.json (Windows: C:\Users\<username>\.speckit\ado-config.json)
   • If file exists, read and display the saved values

2. If configuration exists, ask user:

   I found your saved Azure DevOps configuration:
   - Organization: <saved-org>
   - Project: <saved-project>
   - Area Path: <saved-area-path>
   
   Would you like to use these settings? (yes/no)
   

3. If no configuration OR user says no, ask these questions ONE BY ONE in chat:

   What is your Azure DevOps Organization name?
   (e.g., "MSFTDEVICES" from https://dev.azure.com/MSFTDEVICES)
   

   Wait for response, then ask:

   What is your Azure DevOps Project name?
   (e.g., "Devices")
   

   Wait for response, then ask:

   What is your Area Path?
   (e.g., "Devices\SW\ASPX\CE\Portals and Services")
   

4. Store the responses as variables for later use

Step 2: Locate and Parse Spec File

If User Story Mode (default):

1. Find the current feature directory (look for nearest spec.md in workspace)

2. Read spec.md and extract all user stories using pattern:

   ### User Story <N> - <Title> (Priority: P<N>)
   

3. Display found stories in chat like this:

   Found 5 user stories in spec.md:
   
   [1] User Story 1 - User Authentication (P1)
   [2] User Story 2 - Profile Management (P1)
   [3] User Story 3 - Password Reset (P2)
   [4] User Story 4 - Session Management (P2)
   [5] User Story 5 - Account Deletion (P3)
   

If Task Mode (with -FromTasks argument):

1. Find the current feature directory (look for nearest tasks.md in workspace)

2. Read tasks.md and extract all tasks using pattern:

   - [ ] T001 [P] [US1] Task description
   

3. Display found tasks grouped by User Story in chat:

   Found 25 tasks in tasks.md:
   
   User Story 1 (8 tasks):
     [1] T001 - Setup authentication service
     [2] T002 - Create login endpoint
     [3] T003 - Implement password validation
     ...
   
   User Story 2 (12 tasks):
     [8] T010 - Design user profile schema
     [9] T011 - Create profile API
     ...
   
   No parent (5 unlinked tasks):
     [20] T050 - Update documentation
     ...
   

Step 3: Ask User Which Items to Sync

CRITICAL: You MUST ask the user which items to sync. DO NOT skip this step!

If User Story Mode:

Ask user in chat:

Which user stories would you like to sync to Azure DevOps?

Options:
  • all - Sync all user stories
  • 1,2,3 - Sync specific stories (comma-separated)
  • 1-5 - Sync a range of stories

Your selection:

Wait for user response, then parse selection:

• "all" → select all stories
• "1,3,5" → select stories 1, 3, and 5
• "1-5" → select stories 1 through 5
• Empty/invalid → prompt again

If Task Mode (-FromTasks):

Ask user in chat:

Which tasks would you like to sync to Azure DevOps?

You can select by:
  • all - Sync all tasks
  • us1 - All tasks for User Story 1
  • us1,us2 - All tasks for multiple User Stories
  • 1,2,3 - Specific task numbers (comma-separated)
  • 1-10 - Range of task numbers

Your selection:

Wait for user response, then parse selection:

• "all" → select all tasks
• "us1" → select all tasks linked to User Story 1
• "us1,us3" → select all tasks linked to User Story 1 and 3
• "1,3,5" → select tasks 1, 3, and 5
• "1-10" → select tasks 1 through 10
• Empty/invalid → prompt again

Step 4: Show Confirmation

After getting selection, show what will be created:

You selected X tasks to sync:

User Story 1 (3 tasks):
  - T001 - Setup authentication service
  - T002 - Create login endpoint
  - T003 - Implement password validation

User Story 2 (2 tasks):
  - T005 - Design user profile schema
  - T006 - Create profile API

Is this correct? (yes/no)

Step 5a: Execute Script with Collected Parameters

Now run the PowerShell script with all the parameters collected from chat:

.\scripts\powershell\create-ado-workitems-oauth.ps1 `
  -SpecFile "<path-to-spec.md>" `
  -Organization "$orgName" `
  -Project "$projectName" `
  -AreaPath "$areaPath" `
  -Stories "<selection>" `
  -NoConfirm

Note: Use -NoConfirm flag since we already confirmed with the user in chat.

The script will:

1. ✅ Check Azure CLI installation
2. ✅ Verify/install Azure DevOps extension
3. ✅ Authenticate via az login (OAuth) if needed
4. ✅ Create work items using az boards work-item create
5. ✅ Return work item IDs and URLs
6. ✅ Save mapping to .speckit/azure-devops-mapping.json
7. ✅ Update configuration file ~/.speckit/ado-config.json

Step 6a: Display Results

Show the script output which includes:

• Real-time progress for each story
• Created work item IDs and URLs
• Summary table
• Links to Azure DevOps boards

Step 5b: Prepare Work Items

For each selected user story, prepare work item data:

{
  type: "User Story",
  title: `User Story ${storyNumber} - ${storyTitle}`,
  fields: {
    "System.Description": `${description}\n\n**Why this priority**: ${whyPriority}\n\n**Independent Test**: ${independentTest}`,
    "Microsoft.VSTS.Common.AcceptanceCriteria": formatAcceptanceCriteria(scenarios),
    "Microsoft.VSTS.Common.Priority": convertPriority(priority), // P1→1, P2→2, P3→3
    "System.Tags": `spec-kit; ${featureName}; user-story`,
    "System.AreaPath": areaPath || `${project}`,
    "System.IterationPath": `${project}` // Can be enhanced to detect current sprint
  }
}

Acceptance Criteria Formatting:

Scenario 1:
Given: <given>
When: <when>
Then: <then>

Scenario 2:
Given: <given>
When: <when>
Then: <then>

Step 5c: Execute Script with Collected Parameters

Now run the PowerShell/Bash script with all the parameters collected from chat:

PowerShell:

.\scripts\powershell\create-ado-workitems-oauth.ps1 `
  -SpecFile "<path-to-spec.md or tasks.md>" `
  -Organization "$orgName" `
  -Project "$projectName" `
  -AreaPath "$areaPath" `
  -Stories "<selection>" `
  -FromTasks  # Only if syncing tasks

Bash:

./scripts/bash/create-ado-workitems-oauth.sh \
  --spec-file "<path-to-spec.md or tasks.md>" \
  --organization "$orgName" \
  --project "$projectName" \
  --area-path "$areaPath" \
  --stories "<selection>" \
  --from-tasks  # Only if syncing tasks

The script will:

1. ✅ Check Azure CLI installation
2. ✅ Verify/install Azure DevOps extension
3. ✅ Authenticate via az login (OAuth) if needed
4. ✅ Create work items using az boards work-item create
5. ✅ Return work item IDs and URLs
6. ✅ Save mapping to .speckit/azure-devops-mapping.json
7. ✅ Update configuration file ~/.speckit/ado-config.json

Step 6b: Display Results

Show the script output which includes:

• Real-time progress for each story/task
• Created work item IDs and URLs
• Summary table
• Links to Azure DevOps boards

1. Error handling:

   • Authentication failed → Show re-authentication instructions
   • Permission denied → Explain required Azure DevOps permissions (Contributor or higher)
   • Extension not found → Guide user to install ms-daw-tca.ado-productivity-copilot
   • Network error → Show error and suggest retry
   • Invalid field → Show error and continue with remaining stories

2. Real-time feedback: Display status as each work item is created:

   Creating User Story 1 of 3...
   ✓ Created User Story 1: Display Success Notifications (#12345)
   
   Creating User Story 2 of 3...
   ✓ Created User Story 2: Edit Notifications (#12346)
   
   Creating User Story 3 of 3...
   ✗ Failed User Story 3: Delete Notifications (Permission denied)
   

Step 6c: Display Results

Show summary table:

## ✅ Azure DevOps Sync Complete

**Organization**: MSFTDEVICES  
**Project**: Devices  
**Feature**: photo-album-management  
**Synced**: 3 of 4 user stories

### Created Work Items

| Story | Title | Priority | Work Item | Status |
|-------|-------|----------|-----------|--------|
| 1 | Create Photo Albums | P1 | [#12345](https://dev.azure.com/MSFTDEVICES/Devices/_workitems/edit/12345) | ✅ Created |
| 2 | Add Photos to Albums | P1 | [#12346](https://dev.azure.com/MSFTDEVICES/Devices/_workitems/edit/12346) | ✅ Created |
| 3 | Delete Albums | P2 | [#12347](https://dev.azure.com/MSFTDEVICES/Devices/_workitems/edit/12347) | ✅ Created |

### View in Azure DevOps

- **Boards**: [https://dev.azure.com/MSFTDEVICES/Devices/_boards](https://dev.azure.com/MSFTDEVICES/Devices/_boards)
- **Work Items**: [https://dev.azure.com/MSFTDEVICES/Devices/_workitems](https://dev.azure.com/MSFTDEVICES/Devices/_workitems)
- **Backlog**: [https://dev.azure.com/MSFTDEVICES/Devices/_backlogs/backlog](https://dev.azure.com/MSFTDEVICES/Devices/_backlogs/backlog)

### Tracking

Saved mapping to: `.speckit/azure-devops-mapping.json`

### Next Steps

Now that your user stories are in Azure DevOps, continue with implementation planning:

1. **Create technical plan**: `/speckit.plan` - Generate implementation plan with research and design artifacts
2. **Generate tasks**: `/speckit.tasks` - Break down the plan into actionable tasks
3. **Sync tasks to Azure DevOps**: `/speckit.adosync -FromTasks` - Create Task work items linked to User Stories

Or you can:
- Review work items in Azure DevOps: [View Boards](https://dev.azure.com/{organization}/{project}/_boards)
- Assign work items to team members
- Add to current sprint/iteration

If any failures occurred, also show:

### ⚠️ Errors

| Story | Title | Error |
|-------|-------|-------|
| 4 | Share Albums | Authentication failed - please re-authenticate with Azure DevOps |

Step 7: Save Mapping

Save work item mapping to .speckit/azure-devops-mapping.json:

{
  "feature": "photo-album-management",
  "organization": "MSFTDEVICES",
  "project": "Devices",
  "syncDate": "2026-02-27T10:30:00Z",
  "workItems": [
    {
      "storyNumber": 1,
      "storyTitle": "Create Photo Albums",
      "workItemId": 12345,
      "workItemUrl": "https://dev.azure.com/MSFTDEVICES/Devices/_workitems/edit/12345",
      "priority": "P1",
      "status": "created"
    }
  ]
}

This mapping file allows:

• Tracking which stories have been synced
• Preventing duplicate syncs
• Updating existing work items (future enhancement)

Error Handling

Authentication Required

❌ Azure CLI Not Authenticated

You need to authenticate with Azure CLI to create work items.

To authenticate:
1. Run: az login --use-device-code
2. Follow the prompts in your browser
3. Return to the terminal and run this command again

The script will automatically prompt for authentication if needed.

No Spec File Found

❌ No Spec File Found

This command requires a spec.md file in your feature directory.

To create a spec file, use:
  /specify <your feature description>

Example:
  /specify Add photo album management with create, edit, and delete capabilities

Invalid Story Selection

❌ Invalid Story Selection

Valid formats:
  • all - Select all user stories
  • 1,2,3 - Comma-separated story numbers
  • 1-5 - Range of story numbers

Your input: "abc"

Please try again with a valid selection.

Key Rules

• Check Azure CLI installed, auto-install DevOps extension if missing
• Use OAuth (az login) - no PAT tokens
• Save org/project/area to ~/.speckit/ado-config.json for reuse
• Title format: User Stories = "User Story {#} - {title}", Tasks = "T{#} - {desc}"
• Priority mapping: P1→1, P2→2, P3→3, P4→4
• Auto-link tasks to parent user stories via [US#] references
• Continue on failure, report all errors at end
• Save mapping to .speckit/azure-devops-mapping.json

Example Usage

# Sync user stories from spec.md
# Agent will prompt for org/project/area interactively
/speckit.adosync

# Sync tasks from tasks.md
/speckit.adosync -FromTasks

# The agent will:
# 1. Ask for Azure DevOps configuration (org, project, area)
# 2. Display found user stories or tasks
# 3. Ask which ones to sync
# 4. Create work items via Azure CLI
# 5. Display results with work item IDs and URLs