ado

What this skill does

# ado - Azure DevOps CLI

Use `az devops` (plus `az boards`, `az repos`, `az pipelines`) from PowerShell. Assumes `az login` and org/project defaults.

## Configuration
If `ado\config.json` is missing, ask:
1. What is your ADO organization URL? (e.g., `https://dev.azure.com/myorg`)
2. What is your project name?
3. What area path should Epics use?
4. What area path should Features/Stories/Tasks/Bugs use?
5. What iteration path should work items use?

Save to `ado\config.json` (gitignored). Config shape:
```json
{
  "organization": "https://dev.azure.com/ORG",
  "project": "PROJECT",
  "areaPaths": {
    "epic": "Project\\Team",
    "feature": "Project\\Team\\SubTeam",
    "story": "Project\\Team\\SubTeam",
    "task": "Project\\Team\\SubTeam",
    "bug": "Project\\Team\\SubTeam"
  },
  "iterationPath": "Project\\Iteration",
  "storyPointScale": [1, 1, 2, 3, 5, 8, 13, 21, 34, 55]
}
```

Load config:
```powershell
$config = Get-Content ".\ado\config.json" | ConvertFrom-Json
```

## Prerequisites
Verify auth and defaults:
```powershell
az account show --query "{name:name, user:user.name}" -o table
az devops configure --list
```

If defaults are missing:
```powershell
az devops configure --defaults organization=$config.organization project=$config.project
```

## Rules
- Always use PowerShell for scripting and JSON; do not pipe to python/node.
- Use `--query` JMESPath on `az` commands to filter JSON before PowerShell when possible.
- For any multi-step operation, read the matching section below first; never guess `az` flags or parameters.

## State Transitions
### User Story lifecycle
`New -> Ready to Review -> Ready to Code -> Active -> Closed`

| State | Meaning |
|-------|---------|
| New | Just created, not triaged |
| Ready to Review | Discuss in planning |
| Ready to Code | Planned and estimated |
| Active | In progress |
| Closed | Done |
| Removed | Deleted/cancelled |

### Feature and Epic lifecycle
`New -> Active -> Closed`

### Transition commands
```powershell
az boards work-item update --id ID --state "Ready to Review"
az boards work-item update --id ID --state "Ready to Code"
az boards work-item update --id ID --state Active
az boards work-item update --id ID --state Closed
```

## Quick Reference
Essential commands. For multi-step workflows, read the matching section in "Section Router" first.
```powershell
# Show a work item
az boards work-item show --id ID --output table

# Show with relations (children, parent, related)
az boards work-item show --id ID --expand relations --output json

# Get child IDs from a parent (e.g., features under an epic)
$json = az boards work-item show --id PARENT_ID --expand relations --output json | ConvertFrom-Json
$childIds = $json.relations | Where-Object { $_.attributes.name -eq 'Child' } | ForEach-Object { $_.url -replace '.*/', '' }

# Show multiple work items (loop - there is no --ids flag)
$childIds | ForEach-Object { az boards work-item show --id $_ --output json } | ForEach-Object { $_ | ConvertFrom-Json } | Select-Object id, @{N='Type';E={$_.fields.'System.WorkItemType'}}, @{N='Title';E={$_.fields.'System.Title'}}, @{N='State';E={$_.fields.'System.State'}} | Format-Table

# Query work items with WIQL
az boards query --wiql "SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.WorkItemType] = 'User Story' AND [System.State] = 'Active'" --output table

# Create a work item
az boards work-item create --type "User Story" --title "Title" --area $config.areaPaths.story --iteration $config.iterationPath

# Link child to parent (no --parent flag exists)
az boards work-item relation add --id CHILD_ID --relation-type parent --target-id PARENT_ID

# Update state
az boards work-item update --id ID --state Active

# Create a PR linked to work item
az repos pr create --title "feat: description" --work-items ID --auto-complete true --delete-source-branch true

# List active PRs
az repos pr list --status active --output table

# List pipeline runs
az pipelines runs list --top 5 --output table
```

## Section Router
| User intent | Section | Read before |
|-------------|---------|-------------|
| Pick up work items, create branches, make PRs, monitor builds | Dev Flow | Any PR or branch workflow |
| Create features/stories, hierarchy, area paths, estimation | Planning Flow | Creating or linking work items |
| WIP, aging, throughput, cycle time, Kanban health | Backlog Management | Any backlog query or metric |
| Pipeline status, failed builds, logs, triggers | Pipeline Debugging | Any pipeline operation |
| WIQL field names, operators, macros, quoting | WIQL Reference | Writing any WIQL query |
| CLI command patterns, bulk ops, REST API, output formatting | Command Cookbook | Bulk operations or REST API calls |
| Board columns, WIP limits, Kanban column queries | Board Columns API | Any board column query |

## Troubleshooting
| Problem | Fix |
|---------|-----|
| `az account show` fails | Re-run `az login` - token expired |
| Empty query results | Check area path spelling; for `FROM WorkItemLinks` use REST API instead |
| `charmap` encoding error | Use `az devops invoke` not `az rest`; set `$env:PYTHONIOENCODING = "utf-8"` |
| Defaults not set | Run `az devops configure --defaults organization=$config.organization project=$config.project` |
| Permission denied on work items | Verify area path permissions in ADO project settings |
| WIQL syntax error | Check quoting; see WIQL Reference |

## Additional Tips
- Use `--output table` for readable output, `--output json` for parsing
- Use `--query` with JMESPath to filter JSON: `--query "[].{Id:id, Title:fields.\"System.Title\"}"`
- WIQL supports `@Me`, `@Today`, `@Today - N` macros
- Link PRs to work items with `AB#ID` in commits or PR descriptions
- Use `az devops wiki` for wiki operations
- Use `az boards iteration` and `az boards area` to manage team structure

## Dev Flow - Work Item -> Branch -> PR -> Merge
Use for picking up work items, creating branches, making PRs, or monitoring PR pipelines.

### 1. Pick up a work item
```powershell
# Find items ready to work on
az boards query --wiql "SELECT [System.Id], [System.Title], [System.State] `
  FROM WorkItems `
  WHERE [System.AssignedTo] = @Me `
  AND [System.State] = 'Ready to Code' `
  ORDER BY [Microsoft.VSTS.Common.Priority]" --output table

# Activate the item
az boards work-item update --id ID --state Active
```

### 2. Create a branch
```powershell
git checkout -b feature/ID-short-description
```

### 3. Create a PR linked to work item
```powershell
az repos pr create `
  --title "feat: description" `
  --description "Resolves AB#ID" `
  --work-items ID `
  --auto-complete true `
  --delete-source-branch true
```

The `--work-items` flag links the PR. Use `AB#ID` in description for extra linking.

### 4. Monitor pipeline on PR
```powershell
# List runs for the PR branch
az pipelines runs list --branch feature/ID-short-description --top 1 --output table

# Check run details
az pipelines runs show --id RUN_ID --output table
```

### 5. Complete PR
```powershell
az repos pr update --id PR_ID --status completed
```

Work item state transitions automatically if board rules are configured.

### Assign to self
```powershell
$me = az account show --query "user.name" -o tsv
az boards work-item update --id ID --assigned-to $me
```

## Planning Flow - Features, Stories, Hierarchy and Estimation
Assumes `$config` loaded from `.\ado\config.json`.

### Path conventions
| Work Item Type | Area Path (config key) | Iteration Path (config key) |
|---------------|------------------------|-----------------------------|
| Epic | `areaPaths.epic` | `iterationPath` |
| Feature | `areaPaths.feature` | `iterationPath` |
| User Story | `areaPaths.story` | `iterationPath` |
| Task | `areaPaths.task` | `iterationPath` |
| Bug | `areaPaths.bug` | `iterationPath` |

### Descriptions and acceptance criteria
| Work Item Type | Description Field | Acceptance Criteria |
|---------------|-------------------|-----