--- description: Sync selected user stories or tasks to Azure DevOps scripts: sh: scripts/bash/create-ado-workitems.sh ps: scripts/powershell/create-ado-workitems.ps1 --- ## User Input ```text $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: 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\\.speckit\ado-config.json`) - If file exists, read and display the saved values 2. **If configuration exists**, ask user: ```text I found your saved Azure DevOps configuration: - Organization: - Project: - 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: ```text What is your Azure DevOps Organization name? (e.g., "MSFTDEVICES" from https://dev.azure.com/MSFTDEVICES) ``` **Wait for response, then ask:** ```text What is your Azure DevOps Project name? (e.g., "Devices") ``` **Wait for response, then ask:** ```text 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: ```markdown ### User Story - (Priority: P<N>) ``` 3. **Display found stories in chat** like this: ```text 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: ```markdown - [ ] T001 [P] [US1] Task description ``` 3. **Display found tasks grouped by User Story** in chat: ```text 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**: ```text 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**: ```text 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**: ```text 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: ```powershell .\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: ```javascript { 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**: ```text 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**: ```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**: ```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: ```text 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: ```markdown ## ✅ 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: ```markdown ### ⚠️ 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`: ```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 ```text ❌ 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 ```text ❌ 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 ```text ❌ 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 ```bash # 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 ```