---
name: 'ADO Work Item Planning'
description: 'Reference specification for Azure DevOps work item planning files, templates, field definitions, and search protocols'
applyTo: '**/.copilot-tracking/workitems/**'
---

# Azure DevOps Work Items Planning File Instructions

## Purpose and Scope

This file is a reference specification that defines templates, field conventions, and search protocols for work item planning files. Workflow files consume this specification by including a cross-reference at the top of their content.

Cross-reference pattern for consuming files:

```markdown
Follow all instructions from #file:./ado-wit-planning.instructions.md while executing this workflow.
```

Inline reference pattern when citing specific sections:

```markdown
per templates in #file:./ado-wit-planning.instructions.md
using the matrix from #file:./ado-wit-planning.instructions.md
```

## MCP ADO Tools

Work item operations reference these MCP ADO tools:

Discovery and retrieval:

* `mcp_ado_search_workitem`: Search work items by text, project, type, or state. Key params: `searchText` (required), `project`, `workItemType`, `state`, `top`, `skip`.
* `mcp_ado_wit_get_work_item`: Retrieve a single work item. Key params: `id` (required), `project` (required), `expand`, `fields`.
* `mcp_ado_wit_get_work_items_batch_by_ids`: Retrieve multiple work items. Key params: `ids` (required), `project` (required), `fields`.
* `mcp_ado_wit_my_work_items`: Retrieve work items assigned to or modified by the current user. Key params: `project` (required), `type` (enum: `assignedtome` | `myactivity`), `includeCompleted` (boolean, default: `false`), `top` (number, default: 50).
* `mcp_ado_wit_get_work_items_for_iteration`: Retrieve work items for a specific sprint. Key params: `project` (required), `iterationId` (required), `team`.
* `mcp_ado_wit_list_backlog_work_items`: List backlog work items not assigned to an iteration. Key params: `project` (required), `team`, `backlogId`.
* `mcp_ado_wit_list_backlogs`: List available backlogs for a project. Key params: `project` (required), `team`.
* `mcp_ado_wit_get_query_results_by_id`: Execute a saved ADO query by ID or path. Key params: `id` (required), `project`, `team`, `responseType` (enum: `full` | `ids`, default: `full`), `top` (number, default: 50).

Iteration:

* `mcp_ado_work_list_team_iterations`: List team iterations and sprints. Key params: `project` (required), `team`, `timeframe`.

Creation and updates:

* `mcp_ado_wit_create_work_item`: Create a new work item. Key params: `project` (required), `workItemType` (required), `fields` (required array of name/value pairs).
* `mcp_ado_wit_add_child_work_items`: Add child items to a parent. Key params: `parentId` (required), `project` (required), `workItemType` (required), `items` (required array).
* `mcp_ado_wit_update_work_item`: Update a single work item. Key params: `id` (required), `updates` (required array with path/value).
* `mcp_ado_wit_update_work_items_batch`: Batch update multiple items. Key params: `updates` (required array with id/path/value).

Relationships and linking:

* `mcp_ado_wit_work_items_link`: Link work items together. Key params: `project` (required), `updates` (required array with id/linkToId/type).
* `mcp_ado_wit_link_work_item_to_pull_request`: Link to a PR. Key params: `workItemId`, `projectId` (GUID), `repositoryId` (GUID), `pullRequestId`.
* `mcp_ado_wit_add_artifact_link`: Add artifact links (branch, commit, build). Key params: `workItemId` (required), `project` (required), `linkType`.

History and comments:

* `mcp_ado_wit_list_work_item_comments`: List comments on a work item. Key params: `workItemId` (required), `project` (required).
* `mcp_ado_wit_list_work_item_revisions`: Get revision history. Key params: `workItemId` (required), `project` (required), `top`.
* `mcp_ado_wit_add_work_item_comment`: Add a comment. Key params: `workItemId` (required), `project` (required), `comment` (required).

Identity:

* `mcp_ado_core_get_identity_ids`: Resolve identity GUIDs from email or name. Key params: `searchFilter` (required, email or name string).

## Planning File Definitions & Directory Conventions

Root planning workspace structure:

```plain
.copilot-tracking/
  workitems/
    <planning-type>/
      <artifact-normalized-name>/
        artifact-analysis.md                    # Human-readable table + recommendations
        work-items.md                           # Human/Machine-readable plan (source of truth)
        handoff.md                              # Handoff for workitem execution
        planning-log.md                         # Structured operational & state log (routinely updated sections)
```

Valid `<planning-type>` values:

* `discovery`: Work item discovery from artifacts, PRDs, or user requests
* `pr`: Pull request work item linking and validation
* `sprint`: Sprint planning and work item organization
* `backlog`: Backlog refinement and prioritization

Normalization rules for `<artifact-normalized-name>`:

* Use lower-case, hyphenated base filename without extension (for example, `docs/Customer Onboarding PRD.md` becomes `docs--customer-onboarding-prd`).
* Replace spaces and punctuation with hyphens.
* Choose the primary artifact when multiple artifacts and documents are provided.

## Planning File Requirements

Planning markdown files start with:

```markdown
<!-- markdownlint-disable-file -->
<!-- markdown-table-prettify-ignore-start -->
```

Planning markdown files end with (before the final newline):

```markdown
<!-- markdown-table-prettify-ignore-end -->
```

## artifact-analysis.md

Create artifact-analysis.md when beginning work item discovery from PRDs, user requests, or codebase artifacts. This file captures the human-readable analysis of planned work items before finalizing in work-items.md.

Populate sections by extracting requirements from referenced artifacts, searching ADO for related items, and incorporating user feedback. Update the file iteratively as discovery progresses.

### Template

````markdown
# [Planning Type] Work Item Analysis - [Summarized Title]
* **Artifact(s)**: [e.g., relative/path/to/artifact-a.md, relative/path/to/artifact-b.md]
  * [(Optional) Inline Artifacts (e.g., User provided the following: [markdown block follows])]
* **Project**: [Project Name]
* **Area Path**: [(Optional) Area Path]
* **Iteration Path**: [(Optional) Iteration Path]

## Planned Work Items

### WI[Reference Number (e.g., 001)] - [one of, Create|Update|No Change] - [Summarized Work Item Title]
* **Working Title**: [Single line value (e.g., As a <persona>, I want <capability> so that <outcome>)]
* **Working Type**: [Supported Work Item Type]
* **Key Search Terms**: [Keyword groups (e.g., "primary term", "secondary term", "tertiary")]
* **Working Description**:
  ```markdown
  [Evolving description content constructed from artifacts and discovery]
  ```
* **Working Acceptance Criteria**:
  ```markdown
  * [Acceptance criterion 1 from artifacts and discovery]
  * [Acceptance criterion 2 from artifacts and discovery]
  ```
* **Found Work Item Field Values**:
  * [Work Item Field (e.g., System.Priority)]: [Value (e.g., 2, 3)]
* **Suggested Work Item Field Values**:
  * [Work Item Field (e.g., System.Priority)]: [Value (e.g., 2, 3)]

#### WI[Reference Number (e.g., 001)] - Related & Discovered Information
* [(Optional) zero or more Functional and Non-Functional Requirements blocks (e.g., Related Functional Requirements from relative/path/to/artifact-a.md)]
  * [(Optional) one or more Functional Requirement line items (e.g., FR-001: details of requirement)]
* [one or more Key Details blocks (e.g., Related Key Details from relative/path/to/artifact-b.md)]
  * [one or more Key Details line items (e.g., `Section 2.3` references dependency on data ingestion workflow)]
* [(Optional) zero or more Related Codebase blocks (e.g., Related Codebase Items Mentioned from User)]
  * [(Optional) one or more Related Codebase line items (e.g., src/components/example.ts: needs to be updated with related functionality, WidgetClass: needs IRepository)]

## Notes
* [(Optional) Notes worth mentioning (e.g., PRD specifically included two Epics (WI001, WI002))]
````

## work-items.md

work-items.md is the source of truth for planned work item operations. Capture the `System.State` field for every referenced work item, highlighting `Resolved` items. When a `Resolved` User Story satisfies the requirement without updates, keep the action as `No Change` and add a `Related` link from any new stories back to that item.

### Template

````markdown
# Work Items
* **Project**: [`projects` field for mcp ado tool]
* **Area Path**: [(Optional) `areaPath` field for mcp ado tool]
* **Iteration Path**: [(Optional) `iterationPath` field for mcp ado tool]
* **Repository**: [(Optional) `repository` field for mcp ado tool]

## WI[Reference Number (e.g, 002)] - [Action (one of, Create|Update|No Change)] - [Summarized Title (e.g., Update Component Functionality A)]
[1-5 Sentence Explanation of Change (e.g., Adding user story for functionality A called out in Section 2.3 of the referenced document)]

[(Optional) WI[Reference Number] - Similarity: [System.Id=Category (e.g., ADO-1024=Similar, ADO-901=Match, ADO-1071=Distinct)]]

* WI[Reference Number] - [Work Item Type Fields for single-line values (e.g., System.Id, System.WorkItemType, System.Title, System.Tags)]: [Single Line Value (e.g., As a user, I want functionality A in Component)]

### WI[Reference Number] - [Work Item Type Fields for multi-line values (e.g., System.Description, Microsoft.VSTS.Common.AcceptanceCriteria)]
```[Format (e.g., markdown, html, json)]
[Multi Line Value]
```

### WI[Reference Number] - Relationships
* WI[Reference Number] - [is-a Link Type (e.g., Child, Predecessor, Successor, Related)] - [Relation ID (either, WI[Related Reference Number], System.Id: [Work Item ID from mcp ado tool])]: [Single Line Reason (e.g., New user story for feature around component)]
````

### Example

````markdown
# Work Items
* **Project**: Project Name
* **Area Path**: Project Name\\Area\\Path
* **Repository**: project-repo

## WI002 - Update - Update Component Functionality A
Updating existing user story for functionality A from Section 2.3.

WI002 - Similarity: ADO-901=Match, ADO-1071=Similar (titles align on functionality A; ADO-1071 has broader scope)

* WI002 - System.Id: 1071
* WI002 - System.State: Active
* WI002 - System.WorkItemType: User Story
* WI002 - System.Title: As a user, I want functionality A with functionality B

### WI002 - System.Description
```markdown
## User Goal
As a user, I want to update component with functionality A and B.

## Requirements
* Functionality A becomes possible
* Functionality B becomes possible
```

### WI002 - Relationships
* WI002 - Child - WI001: Functionality A needed for Feature WI001
````

## planning-log.md

planning-log.md is a living document with sections that are routinely added, updated, extended, and removed in-place.

Phase tracking applies when the consuming workflow file defines phases (see the workflow file's Required Phases section for phase definitions):

* Track all new, in-progress, and completed steps for each phase.
* Update the Status section with in-progress review of completed and proposed steps.
* Update Previous Phase when moving to any other phase (phases can repeat based on discovery needs).
* Update Current Phase and Previous Phase when transitioning phases.

### Template

````markdown
# [Planning Type] - Work Item Planning Log
* **Project**: [`projects` field for mcp ado tool]
* **Repository**: [(Optional) `repository` field for mcp ado tool]
* **Previous Phase**: [(Optional) (e.g., Phase-1, Phase-2, N/A, Just Started) (Only if instructions use phases)]
* **Current Phase**: [(e.g., Phase-1, Phase-2, N/A, Just Started) (Only if instructions use phases)]

## Status
[e.g., 1/20 docs reviewed, 0/10 codefiles reviewed, 2/5 ado wit searched]

**Summary**: [e.g., Searching for ADO Work Items based on keywords]

## Discovered Artifacts & Related Files
* AT[Reference Number (e.g., 001)] [relative/path/to/file (identified from referenced artifacts, discovered in artifacts, conversation, codebase)] - [one of, Not Started|In-Progress|Complete] - [Processing|Related|N/A]

## Discovered ADO Work Items
* ADO-[ADO Work Item ID (identified from mcp_ado_search_workitem, discovered in artifacts, conversation) (e.g., 1023)] - [one of, Not Started|In-Progress|Complete] - [Processing|Related|N/A]

## Work Items
### **WI[Reference Number]** - [WorkItemType (e.g., User Story)] - [one of, In-Progress|Complete]
* WI[Reference Number] - Work Item Section (see artifact-analysis.md)
* Working Search Keywords: [Working Keywords (e.g., "the keyword OR another keyword")]
* Related ADO Work Items - Similarity: [System.Id=Category (Rationale) (e.g., ADO-1023=Similar (overlapping scope), ADO-102=Match (same user goal))]
* Suggested Action: [one of, Create|Update|No Change]

[Collected & Discovered Information]

[Possible Work Item Field Values (Refer to Work Item Fields)]

## Doc Analysis - artifact-analysis.md
### [relative/path/to/referenced/doc.ext]
* WI[Reference Number] - Work Item Section (see artifact-analysis.md): [Summary of what was done (e.g., New section made)]
### [relative/path/to/another/referenced/doc.ext]
* WI[Reference Number] - Work Item Section (see artifact-analysis.md): [Summary of what was done (e.g., Section was updated)]

## ADO Work Items
### ADO-[ADO Work Item ID]
[All content from mcp_ado_wit_get_work_item]
````

### Field Value Example

````markdown
* Working **System.Title**: As a user, I want a title that can be updated
* Working **System.Description**:
  ```markdown
  As a user, I want to update component with functionality A.
  ```
````

## handoff.md

Handoff file requirements:

* Include a reference to each work item defined in work-items.md.
* Order entries with Create actions first, Update actions second, and No Change entries last. When operating in discovery-only mode, list the No Change entries while noting that no modifications are planned.
* Include a markdown checkbox next to each work item with a summary.
* Include project-relative paths to all planning files (handoff.md, work-items.md, planning-log.md).
* Update the Summary section whenever the Work Items section changes.

### Template

```markdown
# Work Item Handoff
* **Project**: [`projects` field for mcp ado tool]
* **Repository**: [(Optional) `repository` field for mcp ado tool]

## Planning Files:
  * .copilot-tracking/workitems/<planning-type>/<artifact-normalized-name>/handoff.md
  * .copilot-tracking/workitems/<planning-type>/<artifact-normalized-name>/work-items.md
  * .copilot-tracking/workitems/<planning-type>/<artifact-normalized-name>/planning-log.md

## Summary
* Total Items: 3
* Actions: create 1, update 1, no change 1
* Types: User Story 3

## Work Items - work-items.md
* [ ] (Create) [(Optional) **Needs Review**] WI[Reference Number (e.g., 003)] [Work Item Type (e.g., Epic)]
  * [(Optional) all WI[Reference Number] Relationships as individual line items]
  * [Summary (e.g., New user story for functionality C)]
* [ ] (Update) [(Optional) **Needs Review**] WI[Reference Number (e.g., 001)] [Work Item Type (e.g., User Story)] - System.Id [ADO Work Item ID, (e.g., 1071)]
  * [(Optional) all WI[Reference Number] Relationships as individual line items]
  * [Summary (e.g., Update existing user story for functionality A)]
* [ ] (No Change) WI[Reference Number (e.g., 005)] [Work Item Type (e.g., User Story)] - System.Id [ADO Work Item ID]
  * [(Optional) all WI[Reference Number] Relationships as individual line items]
  * [Summary (e.g., Existing story covers telemetry tasks requested; no updates required)]
```

## Work Item Fields

Track field usage explicitly so downstream automation can rely on consistent data. When discovering existing items, capture the current values for every field planned for modification and preserve any organization-specific custom fields that already exist on the work item.

Relative Work Item Type Fields:

* Core: "System.Id", "System.WorkItemType", "System.Title", "System.State", "System.Reason", "System.Parent", "System.AreaPath", "System.IterationPath", "System.TeamProject", "System.Description", "System.AssignedTo", "System.CreatedBy", "System.CreatedDate", "System.ChangedBy", "System.ChangedDate", "System.CommentCount"
* Board: "System.BoardColumn", "System.BoardColumnDone", "System.BoardLane"
* Classification / Tags: "System.Tags"
* Common Extensions: "Microsoft.VSTS.Common.AcceptanceCriteria", "Microsoft.VSTS.TCM.ReproSteps", "Microsoft.VSTS.Common.Priority", "Microsoft.VSTS.Common.StackRank", "Microsoft.VSTS.Common.ValueArea", "Microsoft.VSTS.Common.BusinessValue", "Microsoft.VSTS.Common.Risk", "Microsoft.VSTS.Common.TimeCriticality", "Microsoft.VSTS.Common.Severity"
* Estimation & Scheduling: "Microsoft.VSTS.Scheduling.StoryPoints", "Microsoft.VSTS.Scheduling.OriginalEstimate", "Microsoft.VSTS.Scheduling.RemainingWork", "Microsoft.VSTS.Scheduling.CompletedWork", "Microsoft.VSTS.Scheduling.Effort"

**Work Item Types and Available Fields:**
| Type       | Key Fields                                                                                                                                                                                                                                                             |
|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Epic       | System.Title, System.Description, System.AreaPath, System.IterationPath, Microsoft.VSTS.Common.BusinessValue, Microsoft.VSTS.Common.ValueArea, Microsoft.VSTS.Common.Priority, Microsoft.VSTS.Scheduling.Effort                                                        |
| Feature    | System.Title, System.Description, System.AreaPath, System.IterationPath, Microsoft.VSTS.Common.ValueArea, Microsoft.VSTS.Common.BusinessValue, Microsoft.VSTS.Common.Priority                                                                                          |
| User Story | System.Title, System.Description, Microsoft.VSTS.Common.AcceptanceCriteria, Microsoft.VSTS.Scheduling.StoryPoints, Microsoft.VSTS.Common.Priority, Microsoft.VSTS.Common.ValueArea                                                                                     |
| Bug        | System.Title, Microsoft.VSTS.TCM.ReproSteps, Microsoft.VSTS.Common.Severity, Microsoft.VSTS.Common.Priority, Microsoft.VSTS.Common.StackRank, Microsoft.VSTS.Common.ValueArea, Microsoft.VSTS.Scheduling.StoryPoints (optional), System.AreaPath, System.IterationPath |

Rules:

* Feature requires Epic parent.
* User Story requires Feature parent.
* Bug links are optional; add relationships when they provide helpful traceability, but do not create placeholder links just to satisfy this checklist.

## Search Keyword & Search Text Protocol

Goal: Deterministic, resumable discovery of existing work items.

### Step 1: Maintain Active Keyword Groups

Build an ordered list where each group contains 1-4 specific terms (multi-word phrases allowed) joined by OR.

### Step 2: Compose Search Text

Format the `searchText` parameter:

* Single group: `(term1 OR "multi word")`
* Multiple groups: `(group1) AND (group2)`

### Step 3: Execute Search and Process Results

Execute `mcp_ado_search_workitem` with a page size of 50.

Filter results to identify candidates for similarity assessment:

* Search highlights contain terms matching the planned item's core concepts
* Work item type is the same or one level above/below (for example, User Story results when planning a User Story, or Feature/Task results)
* Work item is not already linked to the planned item

Assess the candidates by relevance. For each candidate:

1. Fetch full work item using `mcp_ado_wit_get_work_item` and update planning-log.md.
2. Perform similarity assessment (see guidance below).
3. Assign action using the Similarity Categories table.
4. Record the assessment in planning-log.md under the Discovered Work Items section.

### Similarity Assessment

Analyze the relationship between the planned work item and each discovered item through aspect-by-aspect comparison:

1. **Title comparison**: Identify the core intent of each title. Determine whether they describe the same goal or outcome.
2. **Description comparison**: Examine whether they address the same problem or user need. Note any scope differences.
3. **Acceptance criteria comparison**: Evaluate whether completing one item would satisfy the requirements of the other.

When a field is absent from the discovered item:

* Missing acceptance criteria: Compare against scope and deliverables mentioned in the description. Capabilities and Epics typically lack acceptance criteria.
* Missing description: Use title and any linked child items to infer scope. Apply the Uncertain category when insufficient information remains.
* Different work item types: A User Story and Capability at different abstraction levels cannot be a Match. Evaluate whether the planned item should become a child of the discovered item.

Based on the analysis, classify the relationship using the Similarity Categories table.

### Similarity Categories

| Category  | Meaning                                              | Action                           |
|-----------|------------------------------------------------------|----------------------------------|
| Match     | Same work item; creating both would duplicate effort | Update existing item             |
| Similar   | Related enough that consolidation may be appropriate | Review with user before deciding |
| Distinct  | Different items with minimal overlap                 | Create new item                  |
| Uncertain | Insufficient information or conflicting signals      | Request user guidance            |

### Human Review Triggers

Request user guidance when:

* Either item lacks a title or description
* Discovered item lacks acceptance criteria and is a different work item type than the planned item
* Title suggests alignment but acceptance criteria diverge significantly
* Work item types differ by more than one abstraction level (for example, User Story compared to Epic)
* Domain-specific terminology requires expert interpretation
* The relationship is genuinely ambiguous after analysis

### Recording Similarity Assessments

Record each assessment in planning-log.md under a Discovered Work Items section with:

* ADO ID and title of the discovered item
* Category assigned (Match, Similar, Distinct, or Uncertain)
* Brief rationale explaining the classification
* Recommended action based on the category

Format: `ADO-{id}: {Category} - {rationale}`

Example:

```markdown
## Discovered Work Items

* ADO-1019: Similar - Edge inferencing framework overlaps with model validation goals; scope is broader (framework vs specific validation feature)
* ADO-1176: Similar - Cloud training capability addresses model lifecycle; planned item focuses on edge validation subset
* ADO-1179: Distinct - MLOps toolchain is infrastructure-level; planned item is user-facing validation feature
```

## State Persistence Protocol

Update planning-log.md as information is discovered to ensure continuity when context is summarized.

### Pre-Summarization Capture

Before summarization occurs, capture in planning-log.md:

* Full paths to all working files with a summary of each file's purpose
* Any uncaptured information that belongs in planning files
* Work item IDs already reviewed
* Work item IDs pending review
* Current phase and remaining steps
* Outstanding search criteria

### Post-Summarization Recovery

When context contains `<summary>` with only one tool call, recover state before continuing:

1. List the working folder with `list_dir` under `.copilot-tracking/workitems/<planning-type>/<artifact-normalized-name>/`.
2. Read planning-log.md to rebuild context.
3. Notify the user that context is being rebuilt and confirm the approach before proceeding.

Recovery notification format:

```markdown
## Resuming After Context Summarization

Context history was summarized. Rebuilding from planning files:

📋 **Analyzing**: [planning-log.md summary]

Next steps:
* [Planned actions]

Proceed with this approach?
```

## Three-Tier Autonomy Model

Autonomy mode determines which operations require user confirmation before execution. The ADO Backlog Manager defaults to Partial. Users override via the `autonomy` input parameter.

| Mode              | Create | Update | Link | State Change |
|-------------------|--------|--------|------|--------------|
| Full              | Auto   | Auto   | Auto | Auto         |
| Partial (default) | Gate   | Auto   | Auto | Gate         |
| Manual            | Gate   | Gate   | Gate | Gate         |

Gate means the agent presents its recommendation and waits for user confirmation before executing. Auto means the agent executes without prompting.

Autonomy applies to all MCP tool calls that create, modify, or delete ADO entities. Read-only queries (search, get, list) never require gating.

## Content Sanitization Guards

Apply these guards before any ADO API call that writes user-visible content (work item descriptions, comments, field updates).

### Local-Only Path Guard

Detect `.copilot-tracking/` paths in outbound content. When found:

1. Read the referenced file to extract relevant details.
2. Replace the path with an inline summary of the extracted details.
3. Never send `.copilot-tracking/` paths to ADO APIs.

### Planning Reference ID Guard

Detect planning reference IDs in outbound content. Patterns to match:

* `WI` followed by digits (e.g., `WI001`, `WI002`) — ADO planning IDs
* `WI-` followed by a prefix and digits (e.g., `WI-SEC-001`, `WI-RAI-001`, `WI-SSSC-001`) — namespaced planner IDs

When found:

1. If the reference maps to a known ADO work item ID, replace with the ADO ID (e.g., `#12345`).
2. If the reference has no known mapping, replace with a descriptive phrase.
3. If the reference is self-referential, remove it entirely.

### Template ID Guard

Detect template ID placeholders in outbound content. Patterns to match:

* `{{TEMP-N}}` — un-namespaced template IDs
* `{{SEC-TEMP-N}}`, `{{RAI-TEMP-N}}`, `{{SSSC-TEMP-N}}` — namespaced template IDs

When found:

1. If the template ID maps to a known ADO work item ID, replace with the ADO ID (e.g., `#12345`).
2. If the template ID has no known mapping, replace with a descriptive phrase.

Never send planning reference IDs or template ID placeholders to ADO APIs.

## Temporary ID Mapping

Handoff files use temporary ID placeholders for planned work items that do not yet exist. The execution stage maintains a mapping table as items are created, resolving references in subsequent operations.

### Placeholder Formats

The ADO Backlog Manager's own planning uses un-namespaced placeholders:

* `WI001`, `WI002`, `WI003`, incrementing sequentially.

Domain planners use namespaced planning reference IDs that follow the same lifecycle:

* `WI-SEC-{NNN}` — Security Planner (e.g., `WI-SEC-001`, `WI-SEC-002`)
* `WI-RAI-{NNN}` — RAI Planner (e.g., `WI-RAI-001`, `WI-RAI-002`)
* `WI-SSSC-{NNN}` — SSSC Planner (e.g., `WI-SSSC-001`, `WI-SSSC-002`)

Template ID placeholders use a corresponding format:

* `{{TEMP-N}}` — un-namespaced template IDs
* `{{SEC-TEMP-N}}`, `{{RAI-TEMP-N}}`, `{{SSSC-TEMP-N}}` — namespaced template IDs

### Resolution

During execution, resolve each placeholder to the actual ADO System.Id after creation:

```text
WI001 → ADO #12345 (created)
WI-SEC-001 → ADO #12346 (created)
WI-RAI-001 → ADO #12347 (created)
WI-SSSC-001 → ADO #12348 (created)
```

Resolution rules:

* Create parent work items before children so that parent IDs are available for linking.
* When a planning reference ID or template ID appears in a link or update operation, resolve it from the mapping table before calling MCP ADO tools.
* Record the mapping in handoff-logs.md as each work item is created.
* If a reference cannot be resolved (creation failed), skip dependent operations and log the failure.

## Content Format Detection

Azure DevOps supports two rendering formats for rich-text fields (`System.Description`, `Microsoft.VSTS.Common.AcceptanceCriteria`, `Microsoft.VSTS.TCM.ReproSteps`):

| Format   | ADO Version                                         | `format` Parameter Value |
|----------|-----------------------------------------------------|--------------------------|
| Markdown | Azure DevOps Services (dev.azure.com)               | `"Markdown"`             |
| HTML     | Azure DevOps Server (on-premises, visualstudio.com) | `"Html"`                 |

### Detection Protocol

1. When the user provides a `contentFormat` input, use it directly.
2. When the organization URL contains `dev.azure.com`, use Markdown.
3. When the organization URL contains a custom domain or `visualstudio.com`, use HTML.
4. When the format cannot be determined, default to Markdown and inform the user that HTML is available for Azure DevOps Server instances.

The detected format applies to all `format` parameters in MCP ADO tool calls for rich-text fields. Record the detected format in planning-log.md under the Status section.

### Format in Planning Files

The `work-items.md` template uses fenced code blocks with a format annotation. Set the annotation to match the detected format:

* Markdown: ` ```markdown `
* HTML: ` ```html `

Execution workflows read this annotation to determine the `format` parameter value for MCP ADO tool calls.

### Format Conversion

When the detected format is HTML, convert markdown template content to HTML before writing to ADO fields. The content structure remains identical; only the syntax changes.

| Markdown              | HTML Equivalent                           |
|-----------------------|-------------------------------------------|
| `## Heading`          | `<h2>Heading</h2>`                        |
| `* list item`         | `<ul><li>list item</li></ul>`             |
| `1. ordered item`     | `<ol><li>ordered item</li></ol>`          |
| `- [ ] checkbox item` | `<ul><li>&#9744; checkbox item</li></ul>` |
| `- [x] checked item`  | `<ul><li>&#9745; checked item</li></ul>`  |
| `**bold**`            | `<strong>bold</strong>`                   |
| `*italic*`            | `<em>italic</em>`                         |
| `text\n\ntext`        | `<p>text</p><p>text</p>`                  |
| `> blockquote`        | `<blockquote>blockquote</blockquote>`     |
