ado-backlog-manager

portability	ol-coupled
reuse	ol-platform-only
requires	["azure-devops-mcp","azure-devops"]
name	ado-backlog-manager
description	Publish an approved feature spec (tasks.md) to Azure DevOps Boards as a structured hierarchy of work items. Creates one Feature per feature spec (under the release Epic when present), User Stories that group tasks by requirement, and Tasks for each atomic task — each with a back-link to the spec wiki page, requirements traceability, skill-routing tag, and estimate. The Azure DevOps parallel of backlog-manager (JIRA) and linear-backlog-manager (Linear). Use when: the project tracker is ADO and a feature spec has been approved and needs to become a tracked backlog, or when a new requirement needs to be added to an existing ADO Feature. Phase 2 of the ol-sdd-workflow orchestrator when the project's tracker is ado. Requires Azure DevOps MCP — if the MCP is unavailable, fall back to `local-backlog-manager`.

Azure DevOps Backlog Manager

Role

You publish approved feature specs into Azure DevOps Boards. You do not decide what to build — that was settled by feature-spec-author in Phase 1. You translate the approved tasks.md into a hierarchy of ADO work items and maintain the ticket map that Phase 3 and 4 will use.

You are the Azure DevOps parallel of backlog-manager (JIRA) / linear-backlog-manager (Linear). The workflow routes here when tracker: ado. You are invoked by the ol-sdd-workflow orchestrator at Phase 2, or directly when backlog changes are needed.

Work-item-type mapping (ADO-native 4-level — see skills/task-executor/references/tracker-ado.md for the full adapter):

Workflow concept	ADO work item type
release	Epic (created by release-planner)
feature (the workflow "epic")	Feature
story	User Story
task	Task

Inputs

• documentation/specs/{feature}/tasks.md — approved (Phase 1 gate 1c passed)
• documentation/specs/{feature}/requirements.md — for story grouping
• documentation/specs/{feature}/design.md — for the Feature description
• Wiki URL for the spec page — for back-links
• ADO organisation + project (from documentation/workflow-config.md ado.*)
• Default assignee (optional)
• Optional: existing release Epic from documentation/releases/{release}/epic-map.md — if present, the Feature is parented under it rather than created free-standing

Feature handling: release Epic vs standalone

Before creating anything, determine the parent strategy:

1. Release Epic exists (from Phase 0.5 release-planner):

   • Read the Epic id from documentation/releases/{release}/epic-map.md
   • Fetch the existing Feature for this spec (release-planner creates an empty Feature per in-scope feature, parented to the release Epic). Use wit_get_work_item.
   • Update its System.Description with: full design overview, spec wiki URL, repo spec folder link — fleshing out the skeleton
   • Create User Stories and Tasks as children of this existing Feature
   • Do NOT create a new Feature or Epic

2. No release plan, or feature not in epic-map:

   • Create a new standalone Feature (optionally under a new Epic if the user wants a release container)
   • User Stories and Tasks become children of this Feature

The decision is made from documentation/releases/*/epic-map.md lookups. Ask the user to confirm which Epic/Feature (if multiple releases are active).

Outputs

Output	Where
ADO Feature (one)	work item AB#NNN (type Feature)
ADO User Stories (several)	AB#NNN, children of the Feature
ADO Tasks (many)	AB#NNN, children of the User Stories
Ticket map	documentation/specs/{feature}/ticket-map.md

Work-item Structure

Feature (the workflow epic)

• Title: {Feature Name} — {one-line description}
• Description: Overview + link to the spec wiki page + link to repo spec folder
• Tags: feature:{feature-name}; ol-sdd
• Estimate (Microsoft.VSTS.Scheduling.OriginalEstimate): sum of child User Story estimates (hours)
• Parent: the release Epic (Hierarchy link) when present

User Story (one per requirement group)

• Title: Requirement user story ("As a {role}, I want {feature}, so that {benefit}")
• Description: Acceptance criteria from requirements.md (EARS format preserved)
• Parent: the Feature (Hierarchy link)
• Tags: feature:{feature-name}; req:{requirement-number}
• Estimate (Microsoft.VSTS.Scheduling.OriginalEstimate): sum of child Task estimates (hours)

Task (one per atomic task in tasks.md)

• Title: Task title from tasks.md (e.g., "Add licence columns to LegalEntities model")
• Description:
  • Task purpose
  • Exact files to create/modify
  • _Leverage: references
  • _Requirements: back-link
  • Spec section link (wiki URL + anchor)
  • Implementation hints (from design.md if relevant)
• Parent: the User Story covering the referenced requirement (Hierarchy link)
• Tags: feature:{feature-name}; skill:{skill-name}; exec:{engine}; req:{requirement-number} (skill from the _Skill: annotation; engine codex/claude — see Execution-engine assignment)
• Estimate (Microsoft.VSTS.Scheduling.OriginalEstimate): from tasks.md _Estimate: field (hours)
• State: New
• Assignee (System.AssignedTo): default assignee if configured

Execution-engine assignment

Each Task is tagged upfront with the engine that will implement it, so Phase 4's executor never decides at runtime. The engine is one of:

• exec:claude — implemented by the routed Claude-native engineer skill (skill:{name}), with the full clean-code-reviewer loop.
• exec:codex — implemented by delegated Codex via the Codex MCP.

Default rule: classify each task simple/complex using task-executor's complexity-triage signals (estimate ≥ 5 pts / > 4h · more than 3 files · introduces/changes a public API, schema, or migration · domain is auth/payments/data-identity(BIE)/security · touches async/locking/transactions/ordering · requires new test files), then complex → exec:claude, simple → exec:codex. All derivable from tasks.md at backlog time. Set it as a default the user reviews — show it per task in the Step 3 preview and the ticket map, and let the user override any task's engine before publishing. The exec:{engine} tag is the single source of truth sprint-planner carries into the kickoff and sprint-executor reads.

Workflow

Step 1 — Validate Inputs

• Confirm tasks.md exists and is marked approved
• Confirm the three spec files all exist
• Confirm ADO org + project are available (from documentation/workflow-config.md or user input)
• Confirm the feature does not already have a Feature work item (avoid duplicate publication — wit_query_by_wiql for a Feature tagged feature:{name}). If one exists, ask: update existing or abort?

Step 2 — Parse tasks.md

Extract:

• Top-level groupings (headings) → candidate User Stories
• Individual tasks (- [ ] N.) with their metadata fields (_Requirements:, _Leverage:, _Skill:, _Estimate:)
• Requirements references — group tasks by requirement to form User Stories

Step 3 — Preview Before Publishing

Produce a preview of what will be created:

Feature: {feature-name} — {description}   (under Epic AB#{release})
├── User Story: As a {role}...  (sum: 6h)
│   ├── Task: Add columns to model          [skill:python-data-engineer, exec:codex,  2h]
│   ├── Task: Write Alembic migration        [skill:python-data-engineer, exec:claude, 2h]
│   └── Task: Add unit tests                 [skill:clean-code-tests,     exec:codex,  2h]
├── User Story: As a {role}...  (sum: 8h)
│   └── ...
Total: {N} work items, estimated {H}h   ·   engines: {n} claude / {m} codex

Ask the user to approve before any work items are created — and to override any task's exec: engine if they disagree with the default classification.

Step 4 — Create Work Items

Use Azure DevOps MCP tools (see the adapter) in this order:

1. Feature:
   • If a release Feature skeleton exists: wit_update_work_item to flesh out its description, add tags, link the wiki
   • Otherwise: wit_create_work_item(project, 'Feature', {...}); parent it to the release Epic with wit_work_items_link (Hierarchy-Forward) if one exists
2. wit_create_work_item(project, 'User Story', {...}) for each story, then wit_work_items_link to parent it to the Feature
3. wit_create_work_item(project, 'Task', {...}) for each task, then wit_work_items_link to parent it to its User Story
4. wit_add_work_item_comment on each Task with the spec-section back-link (wiki URL + anchor + local file path)
5. Add explicit Predecessor/Successor links (System.LinkTypes.Dependency) for any cross-task ordering named in tasks.md

Create in small batches and surface any API errors immediately — don't continue on failure.

If operating on a release Feature, also update documentation/releases/{release}/epic-map.md: change the Spec Status column for this feature from "specced" to "in backlog".

Step 5 — Write Ticket Map

Create documentation/specs/{feature}/ticket-map.md:

# Ticket Map — {feature-name}

Feature: [AB#100](https://dev.azure.com/{org}/{project}/_workitems/edit/100)

| Task (from tasks.md) | ADO ID | Type | Skill | Engine | Estimate | State |
|----------------------|--------|------|-------|--------|----------|-------|
| 1. Add columns to model | [AB#102](url) | Task | python-data-engineer | codex | 2h | New |
| 2. Write Alembic migration | [AB#103](url) | Task | python-data-engineer | claude | 2h | New |
...

Commit this file to the repo — it's the canonical mapping Phase 3/4 use.

Step 6 — Update the Spec Wiki Page

Append a "Work Items" section to the spec wiki page (via the docs adapter, appendSection) with a table matching the ticket map, so reviewers can trace from spec to work items.

Step 7 — Return

Return to caller with:

• Feature id
• Count of User Stories and Tasks created
• Total estimated hours
• Ticket map file path
• ADO board URL

Updates and Amendments

When a spec changes after work items are published:

• New task added: create a new Task under the appropriate User Story; append to ticket map
• Task removed: set the work item State to "Removed" with a reason comment; mark as removed in ticket map
• Task scope changed: wit_update_work_item the Task description; update ticket map
• Estimate changed: wit_update_work_item the estimate field

Never delete work items — the audit trail matters (set State to "Removed" instead).

What This Skill Does NOT Do

• Does not author specs (Phase 1 / feature-spec-author)
• Does not plan sprints (Phase 3 / sprint-planner)
• Does not execute tasks (Phase 4 / sprint-executor)
• Does not log implementation details (Phase 5 / impl-logger)

References

• skills/task-executor/references/tracker-ado.md — the ADO tracker adapter (read this first for the WIT mapping + tool names).
• skills/backlog-manager/SKILL.md · skills/linear-backlog-manager/SKILL.md — the JIRA / Linear parallels.
• skills/feature-spec-author/references/docs-adapter.md — the docs adapter (Step 6, docs: ado-wiki).
• prompts/coding/templates/jira-epic-template.md · jira-story-template.md · jira-subtask-template.md — content templates (fields map onto ADO work-item fields).
• Azure DevOps MCP: wit_create_work_item, wit_update_work_item, wit_work_items_link, wit_add_work_item_comment, wit_query_by_wiql.

---

Feedback

If the user corrects this skill's output due to a misinterpretation or missing rule in the skill itself (not a one-off preference), invoke skill-feedback to capture structured feedback and optionally post a GitHub issue.

If skill-feedback is not installed, ask the user: "This looks like a skill defect. Would you like to install the skill-feedback skill to report it?" If the user declines, continue without feedback capture.