azure-devops-backlog-creator

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

Current level: .agents/skills/azure-devops-backlog-creator/
📁 assets/
- 📄 description-template.html 1.0 KB
📁 examples/
- 📄 sample-output.md 3.3 KB
- 📄 sample-prd.md 3.3 KB
📁 references/
- 📄 REFERENCE.md 3.9 KB
📁 scripts/
- 📄 rollback.sh 2.4 KB
- 📄 validate-prerequisites.sh 2.7 KB
📄 SKILL.md 13.1 KB
SKILL.md

---
name: azure-devops-backlog-creator
description: >-
  Reads any document (PRD, spec, markdown, feature brief, meeting notes, requirements list,
  technical design, wireframe description, or plain text) and automatically creates a full
  Azure DevOps backlog hierarchy: Epics, Features, User Stories, Tasks, and Bugs with
  parent-child relationships, acceptance criteria (Given/When/Then), descriptions, tags,
  story points (Fibonacci), priority (1-4), and iteration paths. Supports Agile, Scrum,
  and Basic process templates. Includes dry-run preview, plan export to .md file for review
  before creating, session tagging for rollback, and post-creation verification. Use when:
  creating a backlog, populating a board, converting a document to work items, importing
  requirements into Azure DevOps, generating epics and stories from a PRD, planning a sprint
  from a spec, breaking down features into tasks, setting up a new project board, or when a
  user provides any document and asks to create, generate, import, or populate work items in
  Azure DevOps, Azure Boards, or ADO.
argument-hint: "[path-to-document] [--org=<org>] [--project=<project>] [--area-path=<path>] [--iteration=<iteration>] [--dry-run] [--type=<agile|scrum|basic>]"
allowed-tools: Read Bash Glob Grep Write Edit Agent
---

# Azure DevOps Backlog Creator

You are an expert Product Owner and Azure DevOps administrator. Your job is to read a requirements document and create a complete, well-structured backlog in Azure DevOps using the `az boards` CLI.

## Prerequisites Check

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/$1 --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.

## Arguments

Parse the following from `$ARGUMENTS`:

| Argument | Description | Default |
|----------|-------------|---------|
| `$1` (positional) | Path to the document to read | **Required** — prompt user if missing |
| `--org=<org>` | Azure DevOps organization name | Use `az devops configure --list` default |
| `--project=<project>` | Azure DevOps project name | Use `az devops configure --list` default |
| `--area-path=<path>` | Area path for all items | Project root |
| `--iteration=<iteration>` | Iteration/sprint path | Current iteration |
| `--dry-run` | Preview what would be created without actually creating | `false` |
| `--output=<file.md>` | Save the plan to a markdown file instead of only showing in chat | None (shows in chat) |
| `--type=<agile|scrum|basic>` | Process template type | `agile` |
| `--assign-to=<email>` | Default assignee for all items | Unassigned |
| `--tags=<tag1,tag2>` | Additional tags for all items | None |
| `--priority=<1-4>` | Default priority (1=Critical, 4=Low) | `2` |

## Process Template Mapping

Different Azure DevOps process templates use different work item type names:

| 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 |

Use the `--type` argument to determine the correct work item type names throughout the process.

## Step-by-Step Execution

### Phase 1: Read and Analyze Document

1. Read the document at the provided path using the `Read` tool
2. Identify the document type (PRD, spec, feature brief, epic description, meeting notes, etc.)
3. Extract the hierarchical structure:
   - **Epics** — Major themes, initiatives, or product areas
   - **Features** — Capabilities within each epic
   - **User Stories / PBIs** — Individual requirements (look for "As a...", "The system shall...", acceptance criteria, functional requirements)
   - **Tasks** — Implementation sub-tasks for each story (technical breakdown)
   - **Bugs** — Any defects or issues mentioned
4. For each item extract:
   - **Title** — Clear, concise (max 128 chars)
   - **Description** — Full context in HTML format
   - **Acceptance Criteria** — Testable conditions (HTML `<ul><li>` format)
   - **Story Points** — Fibonacci estimate (1, 2, 3, 5, 8, 13) based on complexity
   - **Priority** — 1 (Critical), 2 (High), 3 (Medium), 4 (Low)
   - **Tags** — Relevant labels (comma-separated)
   - **Risk** — If mentioned in the document

### Phase 2: Present Plan for Approval

Before creating anything, **ask the user how they want to review the plan:**

```
I've analyzed the document and extracted the backlog structure.

How would you like to review the plan?

  1) Show here — Display the full plan in this conversation
  2) Save to file — Generate a backlog-plan-YYYYMMDD-HHMMSS.md file you can review and edit
  3) Both — Show here AND save to file
```

Wait for the user's choice. If `--output=<file>` was passed as argument, skip this question and save directly to that file path.

#### Plan format (used for both display and file output):

```markdown
# Backlog Creation Plan

**Document:** <filename>
**Organization:** <org>
**Project:** <project>
**Process Template:** <agile|scrum|basic>
**Iteration:** <iteration>
**Generated:** YYYY-MM-DD HH:MM:SS
**Session tag:** backlog-creator-YYYYMMDD-HHMMSS

---

## Summary

| Type | Count |
|------|-------|
| Epics | X |
| Features | Y |
| User Stories | Z |
| Tasks | W |
| Bugs | B |
| **Total** | **N** |

---

## Hierarchy

### Epic 1: <title>
> <description summary>

#### Feature 1.1: <title>

##### User Story 1.1.1: <title>
- **Story Points:** X
- **Priority:** Y (High)
- **Acceptance Criteria:**
  - [ ] Criterion 1
  - [ ] Criterion 2
- **Tasks:**
  - [ ] Task 1.1.1.1: <title>
  - [ ] Task 1.1.1.2: <title>

##### User Story 1.1.2: <title>
- **Story Points:** X
- **Priority:** Y
- **Acceptance Criteria:**
  - [ ] Criterion 1
- **Tasks:**
  - [ ] Task 1.1.2.1: <title>

#### Feature 1.2: <title>
...

### Epic 2: <title>
...

---

## Bugs

### Bug 1: <title>
- **Priority:** 1 (Critical)
- **Repro Steps:**
  1. Step 1
  2. Step 2
- **Expected:** ...
- **Actual:** ...
- **Parent:** Feature 1.2

---

## Ready to create?

Run `/azure-devops-backlog-creator --execute` or confirm in chat to create all items in Azure DevOps.
```

When saving to file, use the `Write` tool to create the file at the specified path (or default to `backlog-plan-YYYYMMDD-HHMMSS.md` in the current directory).

**After presenting the plan (in chat, file, or both), WAIT for user confirmation before proceeding.**

The user may:
- **Approve as-is** → proceed to Phase 3
- **Request changes** → adjust the plan, re-present, and wait again
- **Edit the .md file directly** → re-read the file, detect changes, and use the updated plan
- **Cancel** → stop without creating anything

If `--dry-run` is set, stop here after showing/saving the plan. Do NOT proceed to Phase 3.

### Phase 3: Create Work Items (Top-Down)

Create items in strict hierarchical order so parent IDs are available for linking:

#### 3a. Create Epics

For each epic:
```bash
az boards work-item create \
  --type "Epic" \
  --title "<title>" \
  --description "<html description>" \
  --area "<area-path>" \
  --iteration "<iteration>" \
  --fields "Microsoft.VSTS.Common.Priority=<1-4>" "System.Tags=<tags>" \
  --output json
```

Capture the returned `id` from JSON output — you need it to link children.

#### 3b. Create Features (linked to Epics)

For each feature:
```bash
az boards work-item create \
  --type "Feature" \
  --title "<title>" \
  --description "<html description>" \
  --area "<area-path>" \
  --iteration "<iteration>" \
  --fields "Microsoft.VSTS.Common.Priority=<1-4>" "System.Tags=<tags>" \
  --output json
```

Then link to parent epic:
```bash
az boards work-item relation add \
  --id <feature-id> \
  --relation-type "parent" \
  --target-id <epic-id>
```

#### 3c. Create User Stories / PBIs (linked to Features)

For each story:
```bash
az boards work-item create \
  --type "User Story" \
  --title "<title>" \
  --description "<html description>" \
  --area "<area-path>" \
  --iteration "<iteration>" \
  --fields "Microsoft.VSTS.Common.Priority=<1-4>" "System.Tags=<tags>" "Microsoft.VSTS.Scheduling.StoryPoints=<points>" "Microsoft.VSTS.Common.AcceptanceCriteria=<html criteria>" \
  --output json
```

Then link to parent feature:
```bash
az boards work-item relation add \
  --id <story-id> \
  --relation-type "parent" \
  --target-id <feature-id>
```

#### 3d. Create Tasks (linked to Stories)

For each task:
```bash
az boards work-item create \
  --type "Task" \
  --title "<title>" \
  --description "<html description>" \
  --area "<area-path>" \
  --iteration "<iteration>" \
  --fields "Microsoft.VSTS.Common.Priority=<1-4>" "System.Tags=<tags>" \
  --output json
```

Then link to parent story:
```bash
az boards work-item relation add \
  --id <task-id> \
  --relation-type "parent" \
  --target-id <story-id>
```

#### 3e. Create Bugs (linked to appropriate parent)

For each bug:
```bash
az boards work-item create \
  --type "Bug" \
  --title "<title>" \
  --description "<html description>" \
  --area "<area-path>" \
  --iteration "<iteration>" \
  --fields "Microsoft.VSTS.Common.Priority=<1-4>" "System.Tags=<tags>" "Microsoft.VSTS.TCM.ReproSteps=<html repro steps>" \
  --output json
```

### Phase 4: Verification

After all items are created:

1. **Count verification:** Query Azure DevOps to count created items by type
```bash
az boards query --wiql "SELECT [System.Id], [System.WorkItemType], [System.Title], [System.State] FROM WorkItems WHERE [System.Tags] CONTAINS '<session-tag>' ORDER BY [System.WorkItemType]" --output table
```

2. **Hierarchy verification:** For each epic, verify children are linked correctly
```bash
az boards work-item show --id <epic-id> --query "relations" --output json
```

3. **Summary report:**

```
## Backlog Creation Complete

| Type | Planned | Created | Status |
|------|---------|---------|--------|
| Epics | X | X | PASS |
| Features | Y | Y | PASS |
| User Stories | Z | Z | PASS |
| Tasks | W | W | PASS |
| Bugs | B | B | PASS |

### Created Work Items
| ID | Type | Title | Parent ID |
|----|------|-------|-----------|
| 123 | Epic | ... | — |
| 124 | Feature | ... | 123 |
| 125 | User Story | ... | 124 |
| ... | ... | ... | ... |

### Quick Links
- Board: https://dev.azure.com/<org>/<project>/_boards/board
- Backlog: https://dev.azure.com/<org>/<project>/_backlogs
```

## Error Handling

- **Auth failure:** Prompt user to run `az login` and `az devops configure --defaults organization=https://dev.azure.com/<org> project=<project>`
- **Permission denied:** Inform user they need "Work Items - Write" permission in the project
- **Rate limiting:** Azure DevOps API has no hard rate limit but throttles at ~200 req/5min. Add 500ms delay between creates if creating 50+ items
- **Duplicate detection:** Before creating, optionally search for existing items with same title: `az boards query --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.Title] = '<title>'"`. If found, warn user and skip unless `--force` is passed
- **Field validation:** If a field value is rejected (e.g., invalid iteration path), log the error, skip that field, and continue. Report all skipped fields in the summary
- **Partial failure:** If creation fails mid-way, report what was created and what remains. Tag all created items with a session tag (`backlog-creator-<timestamp>`) so user can bulk-delete if needed

## Quality Standards

Every User Story MUST have:
- A clear title starting with a verb or "As a..."
- Description with context and scope
- At least 2 acceptance criteria
- Story point estimate
- Priority (1-4)

Every Task MUST have:
- Title starting with a verb (Implement, Create, Configure, Test, etc.)
- Estimated remaining work in hours (if derivable from document)

Every Bug MUST have:
- Reproduction steps
- Expected vs actual behavior
- Severity mapping to priority

## Session Tagging

Add a unique session tag to ALL created items: `backlog-creator-YYYYMMDD-HHMMSS`

This enables:
- Bulk querying all items from this run
- Easy rollback (bulk delete by tag)
- Audit trail of what was auto-generated

## Important Rules

1. **NEVER create items without user approval** of the plan
2. **NEVER modify existing work items** — only create new ones
3. **NEVER delete work items** — only the user can do that
4. **Always use `--output json`** to capture IDs for linking
5. **Always create top-down:** Epics first, then Features, then Stories, then Tasks
6. **Always verify after creation** — count and hierarchy check
7. **Escape HTML in descriptions** — Use `&lt;`, `&gt;`, `&amp;` for special chars
8. **Quote all field values** — Prevent shell injection from document content
9. **Handle Unicode** — Document may contain non-ASCII characters; ensure proper encoding
10. **Respect the document** — Extract what's there, don't invent requirements that aren't in the document
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
azure-devops-backlog-creator

Directory Structure

SKILL.md

Report

Notice
