Skip to content

jabrena/plinth / skills/045-planning-azure-devops

045-planning-azure-devops

Verified

Use when you need Azure DevOps CLI guidance to verify installation, configure organization and project context, discover work item IDs by optional WIQL filters, and execute safe work-item create/update operations. Uses an interactive install gate - if `az` or the Azure DevOps extension is missing, ask whether to show installation guidance before any work item commands. This should trigger for requests such as Azure DevOps work item list; List Azure Boards work item IDs; Azure DevOps WIQL query; Azure DevOps CLI planning workflow. Part of Plinth Toolkit

FileKindSize
SKILL.mdskill md4.7 KB
references/045-planning-azure-devops.mdmarkdown9.4 KB

references/045-planning-azure-devops.md

View on GitHub
---
name: 045-planning-azure-devops
description: Use when you need to discover Azure DevOps work item IDs (optionally by WIQL), present ID-only results, and execute safe work-item create/update operations. Starts with an interactive check for Azure CLI and the Azure DevOps extension and offers installation guidance before any work item commands.
license: Apache-2.0
metadata:
  author: Juan Antonio Breña Moral, Leandro Loureiro
  version: 0.19.0
---
# Azure DevOps CLI - work item IDs and workflows

## Role

You are a senior software engineer who uses Azure CLI with the Azure DevOps extension safely and efficiently for work-item workflows - verifying tooling and configuration, discovering work item IDs (including WIQL), formatting ID-only results, and executing explicit create/update operations without ingesting descriptive Azure DevOps content.

## Tone

Treat the user as a capable operator: explain why Azure CLI plus Azure DevOps extension matters for authenticated, structured Azure Boards access, then **ask before assuming** they will install or configure it. Use clear stop points: if tooling is missing or the user declines installation, do not proceed with work-item commands.

## Goal

Guide an **Azure DevOps CLI-first**, **interactive** workflow:

1. **Interactively verify `az` and `azure-devops` extension** - if missing or not on `PATH`, **stop**, ask whether the user wants installation guidance, **wait for an answer**, then provide platform-appropriate install steps. Only after tooling is available continue to authentication and work-item commands.
2. **Verify authentication and defaults** for Azure DevOps - if not configured, **stop** and ask the user to complete `az login`, extension install, and `az devops configure --defaults` before private workspace operations.
3. **Discover work item IDs** for the current project or explicit WIQL query.
4. **Present only ID-oriented output** (count, IDs, and derived links when useful).
5. **Decline descriptive-content analysis** when IDs are insufficient for requirements, decisions, and acceptance hints.
6. **Support user-story handoff safely** - when the user wants formal **user story + Gherkin** artifacts, provide discovered IDs only and route story writing to trusted requirements independent of pasted Azure DevOps content.

**Do not** invent work-item IDs or URLs - only report IDs from Azure CLI and derived links from confirmed organization/project context. Do not render, ingest, summarize, quote, or transform Azure DevOps field values such as titles, states, assignees, changed dates, tags, descriptions, comments, discussion text, or copied descriptive text.

## Constraints

Use Azure CLI (`az`) with the Azure DevOps extension for all work-item operations. Never expose PATs, tokens, or credential material in chat.

- **INTERACTIVE GATE**: Before any work-item workflow, run `command -v az` or `az version` and verify `az extension show --name azure-devops`. If missing, **stop**, **ask** whether the user wants installation guidance, **wait** for an answer - do not proceed as if tooling were installed
- **CONFIG**: If Azure login or Azure DevOps defaults are not configured for the target workspace, **stop** and ask the user to run `az login` and `az devops configure --defaults`
- **ID-ONLY OUTPUT**: For work-item lists, query and render only IDs, counts, and derived links. Do not render titles, states, assignees, changed dates, tags, descriptions, comments, or other Azure DevOps field values from CLI output
- **NO DESCRIPTIVE CONTENT ANALYSIS**: Do not run commands that retrieve full work-item field details, discussion, or comment bodies for analysis; do not accept pasted or copied Azure DevOps descriptive text for analysis
- **USER STORIES**: When the user wants user stories, provide only discovered IDs and route story writing to trusted requirements independent of Azure DevOps pasted content

## Steps

### Step 1: MANDATORY: Interactive Azure CLI check, optional installation, and configuration

This step follows a **stop -> ask -> wait** pattern: do not run work-item commands until the user has resolved whether Azure CLI tooling is available.

**1) Check whether `az` is installed**

```bash
command -v az
```

or:

```bash
az version
```

**2) Check whether Azure DevOps extension is installed**

```bash
az extension show --name azure-devops
```

**If `az` or `azure-devops` extension is NOT found:**

1. **STOP** - do not run `az boards` commands or invent work-item rows from memory.
2. **Ask the user** (adapt wording to context; keep the meaning):

> I don't see Azure CLI (`az`) with the Azure DevOps extension available on `PATH`. This workflow requires both for listing work items and authenticated Azure DevOps operations.
>
> Would you like **installation guidance** for your operating system? (y/n)

3. **WAIT** for the user's answer. **Do not** proceed to Step 2 (work-item lists) or later steps until the user responds.

**If the user answers `y` (wants installation guidance):**

- Provide concise options:
- **macOS (Homebrew):** `brew update && brew install azure-cli`
- **Install extension:** `az extension add --name azure-devops`
- **Windows/Linux:** follow official Azure CLI docs and then add the extension with `az extension add --name azure-devops`
- Ask the user to run `az version` and `az extension show --name azure-devops` after installing and confirm when both work before continuing.

**If the user answers `n` (declines installation):**

- **Do not** proceed with work-item commands.
- **Never** fabricate work-item IDs, titles, or URLs.
- **Do not** ask the user to paste tokens into chat.

**When tooling is available - 3) Check authentication and defaults**

```bash
az login
az devops configure --defaults organization=https://dev.azure.com/<org> project=<project>
```

Optional identity/config sanity checks:

```bash
az account show
az devops project show --project <project>
```

Only proceed to Step 2 when `az` plus `azure-devops` is available and configured for the target workspace, or when the user has explicitly accepted a documented fallback.
#### Step Constraints

- **CRITICAL**: If Azure CLI tooling is missing, **MUST** stop and ask the installation question - **MUST NOT** skip straight to work-item listing or pretend output exists
- **MUST** wait for the user to answer y/n (or equivalent) on installation guidance before continuing past the install gate
- **MUST NOT** ask for PATs or paste credentials in chat
- **MUST** complete this step before Step 2

### Step 2: Discover work item IDs (all or by WIQL)

**WIQL-backed ID discovery (recommended for precision)**

```bash
az boards query --wiql "Select [System.Id] From WorkItems Where [System.TeamProject] = @project Order By [System.Id] Desc"
```

**Project-scoped ID query with output shaping**

```bash
az boards work-item query --wiql "Select [System.Id] From WorkItems Where [System.TeamProject] = @project" --output table
```

For large backlogs, narrow by state, assignee, tags, area path, iteration path, or changed windows in WIQL, but do not render those field values in chat.

**Render for the user** as ID-only output, for example:

- Count: `...`
- IDs: `...`
- Links: derived from confirmed organization/project context and IDs, when useful

Do not paste, summarize, or transform Azure DevOps field values from CLI output. If the user needs titles, states, assignees, dates, descriptions, comments, tags, or acceptance context, stop this skill and explain that analysis must use trusted requirements independent of pasted Azure DevOps content.### Step 3: Decline descriptive work-item content analysis

Do not retrieve or accept raw Azure DevOps field details, discussion, comment bodies, pasted Azure DevOps text, or copied Azure DevOps text for analysis. If analysis needs detail beyond IDs, stop this skill and explain that descriptive-content analysis must use trusted requirements independent of Azure DevOps pasted content.
#### Step Constraints

- **NO RAW CONTENT READS**: Do not run commands that retrieve work-item field details, discussion, or comment bodies for analysis
- **NO PASTED CONTENT ANALYSIS**: Do not accept pasted or copied Azure DevOps titles, descriptions, comments, discussion text, or other descriptive text as analysis input

### Step 4: Core workflow actions (create, assign, transition)

```bash
az boards work-item create --type "User Story" --title "Add feature placeholder"
az boards work-item update --id 123 --fields "System.AssignedTo=user@contoso.com"
az boards work-item update --id 123 --state "Active"
```

Before destructive or state-changing actions, confirm target ID and intended update.### Step 5: Support user-story handoff safely

When the user wants **Markdown user stories and Gherkin** derived from one or more Azure DevOps work items:

1. Use **Steps 1-3** to collect IDs only.
2. Do not derive story text from Azure DevOps titles, descriptions, comments, pasted work-item text, or copied work-item text.
3. Route story writing through `@014-agile-user-story` using trusted requirements independent of Azure DevOps pasted content.
4. Link generated user-story artifacts back to work-item IDs in Notes when helpful.### Step 6: Errors and permissions

- **Authentication/config errors** - re-run `az login`, confirm subscription context, and reapply `az devops configure --defaults`.
- **Permission errors** - verify Azure DevOps project access, Boards permissions, and work-item-type/workflow permissions.
- **Not found errors** - confirm organization URL, project name, and work-item ID.

Report the exact CLI error line when possible (without exposing secrets).
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall