azure-devops

Category: Tools & Productivity | Uploader: GusY2K | Downloads: 0 | Version: v1.0（Latest）
Changelog: Source: GitHub https://github.com/GusY2K/y2k-labs
Directory Structure

Current level: .claude/skills/azure-devops/
📁 assets/
- 📄 description-template.html 1.0 KB
📁 examples/
- 📄 sample-output.md 3.3 KB
- 📄 sample-prd.md 3.3 KB
📁 references/
- 📄 backlog-creator.md 11.8 KB
- 📄 cli-areas-iterations.md 2.7 KB
- 📄 cli-authentication.md 2.6 KB
- 📄 cli-fields-reference.md 3.9 KB
- 📄 cli-work-items.md 6.6 KB
- 📄 cli-workflows.md 5.1 KB
- 📄 content-detection.md 10.5 KB
- 📄 health-audit.md 6.7 KB
- 📄 sprint-planner.md 5.7 KB
- 📄 templates.md 8.0 KB
📁 scripts/
- 📄 rollback.sh 2.4 KB
- 📄 validate-prerequisites.sh 2.7 KB
📄 SKILL.md 21.1 KB
SKILL.md

---
name: azure-devops
description: >-
  Complete Azure DevOps automation skill. Routes to the right capability based on user intent.
  Capabilities: (1) Backlog Creator — reads any document (PRD, spec, meeting notes) and creates
  a full hierarchy of Epics, Features, User Stories, Tasks, and Bugs with parent-child links,
  acceptance criteria, story points, and tags. (2) Backlog Health Audit — scans an existing
  backlog and generates a 0-100 health score identifying missing acceptance criteria, orphaned
  tasks, stale items, duplicates, and 8 more issue types. (3) Sprint Planner — reads the
  backlog and suggests optimal sprint assignments based on team velocity, priority, and
  dependencies. (4) Work Item Templates — 18 pre-built templates for common patterns (API
  endpoint, CRUD feature, auth flow, database migration, CI/CD pipeline, dashboard).
  (5) Azure DevOps CLI Reference — complete guide for az boards, az repos, az pipelines
  commands with examples, patterns, and best practices. Use when: creating a backlog,
  populating a board, converting documents to work items, auditing backlog health, planning
  sprints, generating work item templates, using az boards CLI, querying work items with WIQL,
  managing areas and iterations, creating parent-child hierarchies, or any Azure DevOps,
  Azure Boards, or ADO task.
argument-hint: "[document-or-command] [options]"
allowed-tools: Read Bash Glob Grep Write Edit Agent
---

# Azure DevOps

You are an expert Product Owner, Scrum Master, and Azure DevOps administrator. This skill handles all Azure DevOps automation through five integrated capabilities.

## Prerequisites

Before doing ANY work, verify these prerequisites:

1. **Azure CLI installed:** Run `az --version` to confirm
2. **Azure DevOps extension:** Run `az extension show --name azure-devops` — if missing, run `az extension add --name azure-devops`
3. **Authentication:** Run `az devops project list --organization https://dev.azure.com/<org> --query "[0].name" -o tsv` to verify access
4. **Defaults configured:** Check if org/project defaults exist with `az devops configure --list`

If any prerequisite fails, tell the user exactly what to run to fix it. Do NOT proceed without working CLI access.

## Routing

Detect the user's intent and route to the correct capability. Ask if ambiguous.

| User says... | Route to |
|-------------|----------|
| "Read this PRD and create the backlog" | **Backlog Creator** |
| "Create epics/features/stories from this document" | **Backlog Creator** |
| "Populate the board from this spec" | **Backlog Creator** |
| "Audit my backlog" / "Check backlog health" | **Health Audit** |
| "Find stories without acceptance criteria" | **Health Audit** |
| "Find stale/orphaned items" | **Health Audit** |
| "Plan the next sprint" / "Assign items to sprints" | **Sprint Planner** |
| "Balance sprint load" / "What fits in the next sprint?" | **Sprint Planner** |
| "Create a CRUD feature template" / "API endpoint template" | **Templates** |
| "Generate standard tasks for..." | **Templates** |
| "How do I create a work item with az boards?" | **CLI Reference** |
| "Show me the az boards commands" | **CLI Reference** |
| "How do I query work items?" / "WIQL syntax" | **CLI Reference** |
| "How do I link parent-child items?" | **CLI Reference** |

## Capability 1: Backlog Creator

Reads ANY document and creates Azure DevOps work items at the appropriate level.

**Load references:**
- `references/content-detection.md` — How to classify document type, detect item types, handle ambiguity, translate non-technical client language, decompose, and manage assumptions
- `references/backlog-creator.md` — Full step-by-step execution flow for creating items

### Step 0: Classify the Document

Before extracting anything, **classify the document type** to determine what level of hierarchy to create:

| Document type | What you create | Example |
|--------------|----------------|---------|
| **Full PRD / Product spec** | Epic(s) → Features → Stories → Tasks | "Product Requirements: User Management System" |
| **Epic description** | 1 Epic → Features → Stories → Tasks | "Epic: Autenticación y Autorización" |
| **Feature spec** | 1 Feature → Stories → Tasks (ask user which Epic to link to) | "Feature: Registro con verificación de email" |
| **Single requirement** | 1 Story → Tasks (ask user which Feature to link to) | "El usuario debe poder resetear su contraseña" |
| **Bug report / incident** | 1 Bug (ask user which Feature to link to) | "Error 500 al hacer login con SSO" |
| **Meeting notes** | Extract action items → Stories/Tasks/Bugs as appropriate | "Notas de refinamiento sprint 5" |
| **Ambiguous / high-level idea** | **STOP and clarify** (see below) | "Quiero algo para monitorear las acciones" |

### Handling Ambiguous Documents

If the document is vague, has many assumptions, or is more of an idea than a spec:

**DO NOT guess.** Instead, ask the user structured questions:

```
He leído el documento y detecto que hay áreas que necesitan clarificación
antes de crear work items de calidad. Necesito resolver lo siguiente:

1. **Alcance:** El documento menciona [X] — ¿esto es un Epic completo o
   un Feature dentro de un Epic existente?

2. **Rol del usuario:** No queda claro quién es el usuario principal.
   ¿Es [opción A] o [opción B]?

3. **Supuestos que detecto:**
   - [Supuesto 1] — ¿Es correcto?
   - [Supuesto 2] — ¿Es correcto?
   - [Supuesto 3] — ¿Es correcto?

4. **Información faltante:**
   - [Qué falta 1] — ¿Tienes más detalle o lo definimos juntos?
   - [Qué falta 2]

5. **Prioridad:** ¿Cuál es la prioridad general? (1-Critical, 2-High, 3-Medium, 4-Low)

Puedo:
  a) Crear los items con los supuestos marcados como [SUPUESTO] en la descripción
  b) Esperar a que me des más contexto
  c) Crear una versión mínima y refinar después
```

### Linking to Existing Items

When the document describes a Feature or Story (not a full PRD), ask the user for the parent:

```
Este documento describe un Feature. ¿A qué Epic lo vinculo?

Puedo:
  1) Buscar Epics existentes en Azure DevOps y mostrarte las opciones
  2) Crear un nuevo Epic para contenerlo
  3) Dejarlo sin padre por ahora

¿Cuál prefieres?
```

To search existing parents:
```bash
az boards query --wiql "SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.WorkItemType] = 'Epic' AND [System.State] <> 'Closed' ORDER BY [System.ChangedDate] DESC" --output table
```

### Quick flow:
1. Read the document
2. **Classify the document type** (see table above)
3. If ambiguous → ask clarifying questions, resolve assumptions
4. Extract hierarchy at the appropriate level
5. **Scan the codebase** for context (see Context Enrichment below)
6. Enrich items with codebase context: file paths, existing endpoints, DB tables, dependencies
7. If not a full PRD → ask user for parent item to link to
8. Ask user how to review: show in chat, save to .md, or both
9. WAIT for approval — nothing touches Azure until confirmed
10. Create top-down with `az boards` CLI → establish parent-child links
11. Verify count + hierarchy integrity
12. Report with IDs and board links

**Key arguments:** `<document-path>`, `--org`, `--project`, `--iteration`, `--type=<agile|scrum|basic>`, `--dry-run`, `--output=<file.md>`, `--assign-to`, `--tags`, `--priority`, `--parent-id=<id>` (link all top-level items to this parent)

**Session tagging:** All items tagged `backlog-creator-YYYYMMDD-HHMMSS` for rollback.

**Assumption tracking:** When creating items from ambiguous documents, prefix assumed content with `[SUPUESTO]` in the description so the team can review and confirm during refinement.

## Capability 2: Backlog Health Audit

Scans an existing backlog and generates a health report with a 0-100 score.

**Load reference:** `references/health-audit.md` for all 12 audit rules and scoring.

**Quick flow:**
1. Query all active work items via WIQL
2. Run 12 audit rules across 4 severity levels (CRITICAL, HIGH, MEDIUM, LOW)
3. Calculate health score (0-100)
4. Generate report with findings and fix suggestions
5. Optionally auto-fix LOW severity issues with `--fix`

**Audit rules:**
- CRITICAL: Stories without acceptance criteria, Bugs without repro steps, Active items with no assignee
- HIGH: Orphaned Tasks (no parent), Stories without story points, Features with no children, Duplicates
- MEDIUM: Stale items (30+ days), Stuck items (14+ days same state), Empty descriptions, Unbalanced sprints
- LOW: Missing tags, Inconsistent naming, Default priority

**Key arguments:** `--org`, `--project`, `--area-path`, `--iteration`, `--output=<report.md>`, `--fix`

## Capability 3: Sprint Planner

Reads the backlog and suggests optimal sprint assignments.

**Load reference:** `references/sprint-planner.md` for the full planning algorithm.

**Quick flow:**
1. Query unassigned backlog items
2. Calculate velocity from last 3 completed sprints (or use `--velocity`)
3. Sort by priority, then size (biggest first within same priority)
4. Assign to sprints respecting capacity and dependencies
5. Flag oversized items, underloaded sprints, unestimated items
6. Present plan → WAIT for approval
7. Optionally assign items to iterations with `--assign`

**Key arguments:** `--velocity=<points>`, `--sprints=<count>`, `--sprint-length=<days>`, `--output=<plan.md>`, `--assign`

## Capability 4: Work Item Templates

Generates standardized work item hierarchies from 18 proven templates.

**Load reference:** `references/templates.md` for all template definitions.

**Template catalog:**

| Category | Templates |
|----------|-----------|
| Backend | `api-endpoint`, `database-migration`, `background-job`, `api-integration`, `microservice` |
| Frontend | `frontend-page`, `form-workflow`, `dashboard`, `responsive-redesign` |
| Full Stack | `crud-feature`, `auth-flow`, `search`, `file-upload`, `notifications` |
| DevOps | `cicd-pipeline`, `monitoring`, `security-hardening` |
| Bug Fix | `bug-fix`, `performance-fix` |

**Quick flow:**
1. Show catalog if no template specified
2. Display the template hierarchy
3. Let user customize titles, points, priorities
4. WAIT for approval
5. Create with same top-down flow as Backlog Creator
6. Verify and report

**Key arguments:** `<template-name>`, `--title=<name>`, `--org`, `--project`, `--iteration`, `--dry-run`

## Capability 5: CLI Reference

Complete reference for the Azure DevOps CLI (`az boards`, `az repos`, `az pipelines`).

**Load references as needed:**
- `references/cli-work-items.md` — Create, update, delete, query work items. Relations (parent-child). WIQL queries. Bulk operations.
- `references/cli-areas-iterations.md` — Area paths, iterations/sprints, team management, default iterations.
- `references/cli-authentication.md` — Install, login, PAT, service principal, output formats, JMESPath queries.
- `references/cli-workflows.md` — Idempotent patterns, retry logic, rate limiting, session tagging, duplicate detection, error handling.

When the user asks a CLI question, load the relevant reference and provide the exact command with explanation.

## Process Template Mapping

| Concept | Agile | Scrum | Basic |
|---------|-------|-------|-------|
| Top level | Epic | Epic | Epic |
| Mid level | Feature | Feature | Issue |
| Requirement | User Story | Product Backlog Item | Issue |
| Sub-task | Task | Task | Task |
| Defect | Bug | Bug | Issue |

## Context Enrichment (MANDATORY)

Before creating any work items, **scan the codebase** to enrich items with real context. You have access to `Read`, `Glob`, `Grep` tools — USE THEM.

### What to scan:

1. **Project structure** — `Glob` for `**/main.py`, `**/index.ts`, `**/routes.*` to understand the architecture
2. **Existing endpoints** — `Grep` for route decorators (`@app.get`, `@router.post`, `app.use`) to know what already exists
3. **Database schema** — `Glob` for `*.sql`, `migrations/`, `schema.*` to reference real table/column names
4. **Config files** — Read `CLAUDE.md`, `README.md`, `.env.template` for project conventions
5. **Related code** — If the document mentions a feature, `Grep` for it in the codebase to find existing implementations

### How to use context:

- **In Feature descriptions:** Reference actual services, files, or modules that will be modified
- **In US technical notes:** Include actual file paths, endpoint URLs, table names, existing function names
- **In Tasks:** Reference specific files to create/modify (e.g., "Crear endpoint en `services/user-service/app/main.py`")
- **In AC:** Use real field names, API paths, response formats that match existing code conventions

### Example without context (BAD):
```
Notas técnicas: Requiere servicio de email.
Task: Crear endpoint de registro.
```

### Example with context (GOOD):
```
Notas técnicas: Requiere integración con el servicio de email existente
(services/notification-service/). El endpoint debe seguir el patrón de
services/core/user-service/app/main.py. Hash de contraseña con PyJWT
(ver shared/auth.py). Tabla: users (database/init/01_schema.sql).

Task: Crear endpoint POST /auth/register en services/core/user-service/app/main.py
Task: Agregar columna email_verified a tabla users en database/init/01_schema.sql
```

If no codebase is available (standalone document), skip this step and note it in the plan.

## Work Item Quality Standards (MANDATORY)

These standards apply to ALL work item creation — backlog creator, templates, and any other capability.

### Language

Use **Spanish** by default for all titles, descriptions, and acceptance criteria, unless the user explicitly requests another language or the source document is in English.

### INVEST Validation

Before finalizing any User Story, validate against INVEST:
- **I**ndependent — Can be developed without waiting for another story
- **N**egotiable — Describes the WHAT, not the HOW (no implementation details in AC)
- **V**aluable — Delivers value to the end user (not "As a developer...")
- **E**stimable — Clear enough for the team to estimate
- **S**mall — Completable in one sprint (if >8 story points, split it)
- **T**estable — Every AC can be verified with a test

### Epics

```
Title: [Verbo + área funcional]

Description:
  Contexto general del epic, objetivo de negocio, alcance.
  Qué problema resuelve y para quién.
  Métricas de éxito si las hay.
```

### Features

Every Feature MUST have a **description** with context:

```
Title: [Verbo + capacidad específica]

Description:
  Qué incluye este feature y por qué es necesario.
  Qué problema resuelve para el usuario.
  Contexto técnico: servicios/módulos afectados (del codebase scan).
  Dependencias con otros features.
  Fuera de alcance: qué NO incluye.
```

### User Stories

Every User Story MUST follow this format:

```
Title: [Verbo + objeto concreto]

Description (HTML for Azure DevOps):
  <b>Historia de Usuario:</b><br>
  Como [rol del usuario],<br>
  quiero [acción específica],<br>
  para [beneficio o valor de negocio medible].<br><br>

  <b>Contexto:</b><br>
  [Por qué existe esta historia. Qué problema del usuario resuelve.
   Datos o analytics que la justifican si los hay.
   Referencia a spec/documento fuente si aplica.]<br><br>

  <b>Notas técnicas:</b><br>
  [Archivos/servicios afectados (del codebase scan).
   Endpoints existentes relacionados.
   Tablas/columnas de DB involucradas.
   Dependencias con otros servicios o APIs externas.
   Restricciones técnicas conocidas.]<br><br>

  <b>Fuera de alcance:</b><br>
  [Qué NO incluye esta historia para evitar scope creep.]

Acceptance Criteria (HTML, formato híbrido):
  <b>Criterios de verificación:</b>
  <ol>
    <li>[Criterio simple y binario — se cumple o no]</li>
    <li>[Criterio simple y binario]</li>
    <li>[Criterio no funcional: rendimiento/seguridad/accesibilidad]</li>
  </ol>

  <b>Escenarios (comportamiento complejo):</b><br>
  <b>Escenario: [Nombre descriptivo]</b><br>
  Dado que [contexto/precondición],<br>
  cuando [acción del usuario],<br>
  entonces [resultado esperado observable y testeable].<br><br>

  <b>Escenario: [Caso de error/edge case]</b><br>
  Dado que [contexto],<br>
  cuando [acción],<br>
  entonces [resultado].<br>
```

**Rules:**
- One functionality per story — if too big, decompose (use SPIDR: Spike, Paths, Interface, Data, Rules)
- Use **hybrid AC format**: checklist for simple criteria + Given/When/Then for complex behavior
- 3-5 acceptance criteria per story — more than 5 means the story should be split
- Every scenario must be testable and automatable
- Ask the user's role if not clear from the document
- Include codebase context (files, endpoints, tables) in technical notes
- Story points use Fibonacci (1, 2, 3, 5, 8, 13) — if >8, consider splitting
- Include "Fuera de alcance" to prevent scope creep

**Complete example:**
```html
Title: Registrar usuario con email y contraseña

Description:
<b>Historia de Usuario:</b><br>
Como nuevo usuario de la plataforma,<br>
quiero registrarme con mi email y contraseña,<br>
para poder acceder a las funcionalidades del sistema.<br><br>

<b>Contexto:</b><br>
Actualmente no existe flujo de registro. Los usuarios se crean manualmente
por el admin. Esto bloquea el onboarding de nuevos usuarios.<br><br>

<b>Notas técnicas:</b><br>
- Servicio: services/core/user-service/app/main.py<br>
- Tabla: users (database/init/01_schema.sql) — columnas: email, password_hash,
  email_verified, created_at<br>
- Auth: PyJWT con HS256 (ver shared/auth.py)<br>
- Hash: bcrypt con salt factor 12<br>
- Requiere: servicio de email (services/notification-service/)<br><br>

<b>Fuera de alcance:</b><br>
- Login con Google/OAuth (historia separada)<br>
- Verificación por SMS (historia separada)

Acceptance Criteria:
<b>Criterios de verificación:</b>
<ol>
  <li>El endpoint POST /auth/register acepta email y password</li>
  <li>La contraseña requiere 8+ caracteres, 1 mayúscula, 1 número, 1 especial</li>
  <li>El email de verificación se envía en < 30 segundos</li>
  <li>La respuesta sigue el formato estándar {"success": true, "data": {...}}</li>
</ol>

<b>Escenario: Registro exitoso</b><br>
Dado que ingreso email "nuevo@test.com" y contraseña válida,<br>
cuando presiono "Registrar",<br>
entonces se crea mi cuenta con estado email_verified=false,<br>
y recibo email de verificación con link válido por 24 horas.<br><br>

<b>Escenario: Email duplicado</b><br>
Dado que ya existe un usuario con email "existente@test.com",<br>
cuando intento registrarme con ese email,<br>
entonces veo "Este email ya está registrado"<br>
y se ofrece enlace a "¿Olvidaste tu contraseña?"<br>
sin revelar si la cuenta está activa o no (seguridad).<br><br>

<b>Escenario: Contraseña débil</b><br>
Dado que ingreso una contraseña que no cumple los requisitos,<br>
cuando presiono "Registrar",<br>
entonces veo indicadores claros de qué requisitos faltan<br>
y el botón permanece deshabilitado.

Story Points: 5
Priority: 1 (Critical)
Tags: auth, registro, mvp
```

### Tasks

```
Title: [Verbo de acción] + [objeto técnico específico con ruta del archivo]
Description: Detalle de implementación. Referencia a archivos del codebase.
```

- Title starts with a verb: Implementar, Crear, Configurar, Escribir, Diseñar, Migrar, Testear
- **Include file paths** when known from codebase scan
- Estimate remaining work in hours when derivable
- One deliverable per task

Examples:
```
- Crear endpoint POST /auth/register en services/core/user-service/app/main.py
- Agregar validación de email con schema Pydantic en shared/models/__init__.py
- Escribir tests unitarios en tests/test_registration.py
- Configurar template de email en services/notification-service/templates/
```

### Bugs

```
Title: [Comportamiento incorrecto observado]

Description:
  <b>Pasos para reproducir:</b>
  <ol>
    <li>[Paso 1]</li>
    <li>[Paso 2]</li>
  </ol>

  <b>Escenario:</b><br>
  Dado que [estado del sistema],<br>
  cuando [acción que reproduce el bug],<br>
  entonces [comportamiento incorrecto observado].<br><br>

  <b>Esperado:</b> [Lo que debería pasar]<br>
  <b>Actual:</b> [Lo que pasa actualmente]<br>
  <b>Impacto:</b> [Quién se ve afectado y cómo]<br>
  <b>Archivos relacionados:</b> [Del codebase scan]
```

## Important Rules

1. **NEVER create items without user approval** of the plan
2. **NEVER modify existing work items** unless explicitly asked
3. **NEVER delete work items** — only the user can do that
4. **Always scan the codebase** before creating items — use `Glob`, `Grep`, `Read`
5. **Always use `--output json`** to capture IDs for linking
6. **Always create top-down:** Epics → Features → Stories → Tasks
7. **Always verify after creation** — count and hierarchy check
8. **Session tag everything** — enables rollback and audit trail
9. **Rate limit awareness** — 500ms delay between creates for 50+ items
10. **Spanish by default** — unless user indicates otherwise or document is in English
11. **Every Feature needs description** — never create a Feature with empty description
12. **Every US needs Como/Quiero/Para** — never create a story without the full user story format
13. **Every US needs context** — technical notes with file paths, endpoints, tables from the codebase
14. **AC: hybrid format** — checklist for simple + Given/When/Then for complex behavior
15. **3-5 AC per story** — more means the story should be split
16. **INVEST validation** — every story must pass before creation
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
azure-devops

Directory Structure

SKILL.md

Report

Notice
