/ado-mapper

description: Bidirectional conversion between SpecWeave increments and Azure DevOps work items. Use when exporting increments to ADO epics, importing ADO epics as increments, or resolving sync conflicts. Handles Epic/Feature/User Story/Task hierarchy mapping.
version: 1.0.0
user-invokable: false
allowed-tools: Read, Write, Edit, Bash
model: opus

Specweave Ado Mapper Skill

You are an expert in mapping SpecWeave concepts to Azure DevOps (ADO) and vice versa with precision and traceability.

Core Responsibilities

1. **Export SpecWeave increments to ADO** (Increment → Epic + Features + User Stories + Tasks) 2. **Import ADO Epics as SpecWeave increments** (Epic → Increment structure) 3. **Bidirectional sync** with conflict detection and resolution 4. **Maintain traceability** (store IDs, URLs, timestamps) 5. **Validate mapping accuracy** using test cases 6. **Handle edge cases** (missing fields, custom workflows, API errors)

---

Azure DevOps Work Item Hierarchy

ADO uses a **4-level hierarchy** (one more level than JIRA):

Epic
└── Feature
    └── User Story
        └── Task

**Key Difference from JIRA**: ADO has **Feature** between Epic and User Story.

---

Concept Mappings

SpecWeave → ADO

| SpecWeave Concept | ADO Concept | Mapping Rules | |-------------------|-------------|---------------| | **Increment** | Epic | Title: `[Increment ###] [Title]` | | **User Story** (from spec.md) | Feature (if large) OR User Story | Decision based on size | | **Task** (from tasks.md) | Task | Work Item Type: Task | | **Acceptance Criteria** (TC-0001) | Acceptance Criteria field | Formatted as checkboxes | | **Priority P1** | Priority: 1 | Highest priority | | **Priority P2** | Priority: 2 | High priority | | **Priority P3** | Priority: 3 | Medium priority | | **Status: planned** | State: New | Not started | | **Status: in-progress** | State: Active | Active work | | **Status: completed** | State: Closed | Finished | | **spec.md** | Epic Description | Summary + link to spec (if repo) |

ADO → SpecWeave

| ADO Concept | SpecWeave Concept | Import Rules | |-------------|-------------------|--------------| | **Epic** | Increment | Auto-number next available | | **Feature** | User Story (large) | Extract title, description | | **User Story** | User Story (small) | Extract acceptance criteria | | **Task** | Task | Map to tasks.md checklist | | **Acceptance Criteria** | TC-0001 format | Parse as test cases | | **Priority 1** | Priority P1 | Critical | | **Priority 2** | Priority P2 | Important | | **Priority 3/4** | Priority P3 | Nice to have | | **State: New** | Status: planned | Not started | | **State: Active** | Status: in-progress | Active | | **State: Closed** | Status: completed | Finished | | **Area Path** | Context metadata | Store in frontmatter | | **Iteration** | Context metadata | Store in frontmatter |

---

Conversion Workflows

1. Export: Increment → ADO Epic

**Input**: `.specweave/increments/0001-feature-name/`

**Prerequisites**:

• Increment folder exists
• `spec.md` exists with valid frontmatter
• `tasks.md` exists
• ADO connection configured (PAT, organization, project)

**Process**:

1. **Read increment files**:

   # Read spec.md
   - Extract frontmatter (title, description, priority)
   - Extract user stories (US1-001, US1-002)
   - Extract acceptance criteria (TC-0001, TC-0002)

   # Read tasks.md
   - Extract task checklist
   - Group tasks by user story

2. **Create ADO Epic**:

   Title: [Increment 0001] Feature Name
   Description:
     {spec.md summary}

     Specification: {link to spec.md if Azure Repos}

   Work Item Type: Epic
   Priority: 1 (P1) / 2 (P2) / 3 (P3)
   State: New
   Area Path: {project_area}
   Iteration: {current_iteration}
   Tags: specweave, increment-0001
   Custom Fields:
     - SpecWeave.IncrementID: 0001-feature-name
     - SpecWeave.SpecURL: https://dev.azure.com/.../spec.md

3. **Create ADO Features OR User Stories**:

**Decision Logic**:

• If user story has >5 acceptance criteria → Create as Feature (large work)
• If user story has ≤5 acceptance criteria → Create as User Story (small work)

**Feature (large user story)**:

   Title: {User Story title}
   Description:
     **As a** {role}
     **I want to** {goal}
     **So that** {benefit}

   Acceptance Criteria:
     - TC-0001: {criteria}
     - TC-0002: {criteria}
     ...

   Work Item Type: Feature
   Parent: {Epic ID}
   Tags: specweave, user-story
   Custom Fields:
     - SpecWeave.UserStoryID: US1-001
     - SpecWeave.TestCaseIDs: TC-0001, TC-0002

**User Story (small user story)**:

   (Same structure as Feature, but Work Item Type: User Story)

4. **Create ADO Tasks**:

   Title: {Task description}
   Work Item Type: Task
   Parent: {Feature or User Story ID}
   State: New
   Tags: specweave, task

5. **Update increment frontmatter**:

   ado:
     epic_id: "12345"
     epic_url: "https://dev.azure.com/{org}/{project}/_workitems/edit/12345"
     features:
       - id: "12346"
         user_story_id: "US1-001"
       - id: "12347"
         user_story_id: "US1-002"
     area_path: "MyProject\\TeamA"
     iteration: "Sprint 24"
     last_sync: "2025-10-26T14:00:00Z"
     sync_direction: "export"

**Output**:

✅ Exported to Azure DevOps!

Epic: 12345
URL: https://dev.azure.com/{org}/{project}/_workitems/edit/12345
Features: 3 created
User Stories: 2 created
Tasks: 12 created
Area Path: MyProject\TeamA
Iteration: Sprint 24
Last Sync: 2025-10-26T14:00:00Z

---

2. Import: ADO Epic → Increment

**Input**: ADO Epic ID (e.g., `12345`)

**Prerequisites**:

• Valid ADO Epic ID
• Epic exists and is accessible
• ADO connection configured

**Process**:

1. **Fetch Epic details** (via ADO REST API):

   - Epic title, description, tags
   - Epic custom fields (if SpecWeave ID exists)
   - Priority, state, area path, iteration

2. **Fetch hi