version: "1.0.0" name: push-to-ado description: Uploads a drafted User Story or Technical Story to Azure DevOps as a work item, populating Title, Description, Acceptance Criteria, Story Points, Priority, and Tags, and optionally linking a parent feature. Also supports creating a full Epic → Feature → Story hierarchy from a structured backlog, and updating existing work items in bulk. Use when the user says "push to ADO", "create in ADO", "upload to ADO", "add to ADO", "update ADO items", or similar after stories have been drafted in conversation.

Push to ADO

Three scripts are available. Choose based on what the user provides:

Single story — upload.ps1

Extracts structured fields from the story already in context and calls upload.ps1 to create the ADO work item. Do not re-derive the API logic — all implementation lives in the script.

Step 1 — Extract fields from the story in context

Parse the story markdown (output of /technical-story or /user-story) and collect:

Work item type is always User Story — hardcoded in the script.

Step 2 — Call the script

pwsh ~/.claude/skills/push-to-ado/scripts/upload.ps1 `
  -Title "..." `
  -Description "..." `
  -AcceptanceCriteria "..." `
  -StoryPoints 3 `
  -Priority "High" `
  -ParentId 2881288

Omit -ParentId if no parent was provided.

Pass -Org and -Project only if the user explicitly provides them; otherwise the script reads from $env:ADO_ORG / $env:ADO_PROJECT.

Step 3 — Report result

After the script completes, show the user the returned work item URL. If the script errors, surface the error message and do not retry silently.

Full hierarchy — upload-hierarchy.ps1

Use when the user provides a structured backlog with multiple Epics, Features, and Stories to create in one pass.

The script defines a New-WorkItem helper function that accepts any ADO work item type (Epic, Feature, User Story) and handles auth, parent linking, and field mapping. Technical stories are created as User Story type with the tag Technical.

How to use it

1. Open scripts/upload-hierarchy.ps1 and replace the placeholder comment with New-WorkItem calls for the user's backlog, following the call pattern documented below.
2. Run it:

ADO_ORG=myorg ADO_PROJECT=myproject pwsh ~/.claude/skills/push-to-ado/scripts/upload-hierarchy.ps1

New-WorkItem parameters

Parent linking pattern

Capture the returned ID from each Epic/Feature call and pass it as -ParentId to its children:

$epicId    = New-WorkItem -Type "Epic"    -Title "My Epic" ...
$featureId = New-WorkItem -Type "Feature" -Title "My Feature" -ParentId $epicId ...
             New-WorkItem -Type "User Story" -Title "My Story" -ParentId $featureId ...

Bulk update existing items — update-work-items.ps1

Use when stories already exist in ADO (created via upload-hierarchy.ps1 or manually) and need their Title, Description, Acceptance Criteria, Story Points, or Priority replaced with improved content — for example, after re-drafting stories through /user-story or /technical-story.

How to use it

1. Open scripts/update-work-items.ps1 and replace the placeholder comment with one Update-WorkItem call per item, providing the known ADO work item ID for each.
2. Run it:

ADO_ORG=myorg ADO_PROJECT=myproject pwsh ~/.claude/skills/push-to-ado/scripts/update-work-items.ps1

Update-WorkItem parameters

Typical workflow

1. Draft improved stories using /user-story or /technical-story
2. Note the ADO ID of each item to update
3. Populate update-work-items.ps1 with one Update-WorkItem call per item
4. Run the script — all fields are patched in a single PATCH request per item