title: "Create PBI from Spec (Azure DevOps via NGA MCP) — v6"
category: "development"
tags:
  - azure-devops
  - automation
  - specifications
  - pbis
  - mcp
version: "1.11"
description: "Create/update a Product Backlog Item in Azure DevOps via NGA MCP and optionally move/rename the original spec file. Maps Description vs Acceptance Criteria vs Technical Details into the correct ADO fields with detection & flags. Links PBI to parent Feature using Hierarchy-Reverse relation."
project: "Audit Platform"  # default ADO project (override with --project if needed)
---

# /create-pbi — Generate Azure DevOps PBI from Spec (via NGA MCP)

Create or update a **Product Backlog Item (PBI)** in **Azure DevOps** from a behavioral spec produced by `/generate-spec`.  
Optionally, when `--rename` is provided, **move/rename the original spec file** into a normalized path using the Feature and PBI context.

> ⚠️ Requires **NGA MCP** in Agent mode with ADO access and your PAT configured.  
> Uses the default project: **NextGenAudit-Platform** (no project listing).

---

## 🔧 Inputs

- **Spec path** (required): path to the source spec file. Example: `docs/specs/spec-export-e2e.md`
- **Feature** (required on create): ADO **Feature** work item ID to parent under (e.g., `987654`).
- **Optional flags:**
  - `--project "<ADO Project Name>"` (defaults to frontmatter `project`, here: "Audit Platform")
  - `--area "<Area Path>"`
  - `--iteration "<Iteration Path>"`
  - `--assign "<user@corp.com>"`
  - `--tags "t1,t2"`
  - `--update <PBI-ID>` (update existing PBI instead of creating a new one)
  - `--rename` (move/rename the original spec file to the pattern below)
  - `--pattern "{dir}/{featureId}-{featureSlug}/{id}-{slug}.md"` (override move pattern)
  - `--ac-field "Microsoft.VSTS.Common.AcceptanceCriteria"` (override Acceptance Criteria field name)
  - `--tech-field "Custom.TechnicalDetails"` (override Technical Details custom field name)

**Examples**
```
/create-pbi docs/specs/spec-export-e2e.md 987654 --area "Apps\JADx" --iteration "FY25\Q4" --rename
/create-pbi docs/specs/spec-export-e2e.md --update 123456 --assign "j.doe@company.com" --ac-field "Microsoft.VSTS.Common.AcceptanceCriteria" --tech-field "Custom.TechnicalDetails" --rename
```

---

## 🎯 Objective

1) Parse the spec to extract **Title**, **Description**, **Acceptance Criteria**, **Technical Details**.  
2) **Create or update** a PBI in **Azure DevOps** via **NGA MCP**, parented under **Feature** (unless `--update`).  
3) If `--rename` is used, move/rename the original spec file into a normalized folder path using Feature and PBI context.

---

## 🧩 Parsing Rules

### 🏷️ Title
Use the first header (`#` or `##`) at the top of the spec.

### 📝 Description (Markdown ONLY — no AC/Tech here)
Build from:
- **Purpose & Outcomes → Intent** (bullets)
- **Purpose & Outcomes → Success Signals** (bullets)
- (Optional) one-paragraph summary from **Behavior Change → New Behavior**

> **Do not include** Acceptance Criteria or Technical Details in Description if those fields exist in ADO.

### ✅ Acceptance Criteria (Gherkin HTML)
From **"5) Acceptance Criteria (Gherkin)"**, extract the **full Gherkin scenarios** including:
- The `Feature:` line
- Each complete `Scenario:` block with all `Given`, `When`, `Then`, `And` steps
- Convert the entire Gherkin text to **HTML format** preserving structure (use `<pre>` and `<code>` tags or properly formatted HTML)
- Do NOT create a simple checklist; keep the full Gherkin syntax as it is essential for test traceability.

### ⚙️ Technical Details
Bullets composed of:
- **Inputs → Key constraints**
- **Scope → Included/Excluded** (condensed)
- **Interfaces & Contracts** (names only — UI actions, endpoint names, event names)

---

## 🤖 Tool Usage — NGA MCP (Azure DevOps)

**Always use the configured project** (frontmatter `project`) unless `--project` overrides it.  
**Do not** call `projects.list`; resolve the project by name.

### Required capabilities
- `nga-mcp.azdo.workitems.create`
- `nga-mcp.azdo.workitems.update`
- `nga-mcp.azdo.workitems.get`
- `nga-mcp.azdo.workitems.fields` (to detect available fields on the PBI type)

### Field mapping (strict separation)
1. Detect available fields for **Product Backlog Item** via `nga-mcp.azdo.workitems.fields`. Cache once per session.
2. Determine target field names:
   - **Acceptance Criteria** target = `--ac-field` value if provided; else use `Microsoft.VSTS.Common.AcceptanceCriteria` **if present**; else `None`.
   - **Technical Details** target = `--tech-field` value if provided; else use a detected custom field containing "Technical" in its name; else `None`.
3. Build payloads:
   - **System.WorkItemType**: `Product Backlog Item`
   - **System.Title**: `<Title>`
   - **System.Description**: **HTML** converted from **Description** only.  
     - If AC target is `None`, append a `## Acceptance Criteria` section with full Gherkin (HTML formatted) to Description.  
     - If Tech target is `None`, append a `## Technical Details` section (HTML) to Description.
   - **<AC target>** (when set): full Gherkin scenarios converted to HTML (preserve `Feature:`, `Scenario:`, `Given/When/Then/And` structure).
   - **<Tech target>** (when set): bullets converted to HTML.
   - **System.AssignedTo**, **System.Tags**: from flags if provided.

> This ensures that AC/Tech **do not get duplicated** into Description when dedicated fields are present.

### Parent Link Setup (on creation only, when Feature ID is provided)

After creating the PBI, add a parent-child relation to link the PBI under the Feature using a JSON Patch operation:

```json
{
  "op": "add",
  "path": "/relations/-",
  "value": {
    "rel": "System.LinkTypes.Hierarchy-Reverse",
    "url": "https://dev.azure.com/pwc-us-prism/_apis/wit/workItems/{featureId}"
  }
}
```

**CRITICAL**: 
- Do NOT modify the Feature (parent) - only update the child PBI
- Do NOT use `System.Parent` field
- Do NOT use 'replace' operation on relations
- If creation-time relations aren't supported by NGA MCP, issue a follow-up PATCH on the newly created PBI with the same add operation

---

## 📝 Output Behavior — **Rename (Move original spec)**

- `{dir}` = directory of the original spec (e.g., `docs/specs`).  
- `{slug}` = kebab-case slug from the spec Title (e.g., `export-to-excel-e2e`).  
- `{id}` = PBI ID from ADO response (or `--update` value).  
- `{featureId}` = Feature work item ID provided as the second argument.  
- `{featureSlug}` = kebab-case slug from the Feature title when resolvable; otherwise derived from the spec title or left as `{featureId}` only.
- When `--rename` is provided, the command will **move (not copy)** the original spec file to:
  - **Default pattern:** `{dir}/{featureId}-{featureSlug}/{id}-{slug}.md`
- You may override with `--pattern` using placeholders `{dir}`, `{id}`, `{slug}`, `{featureId}`, `{featureSlug}`. The resolved path must remain under `{dir}`.
- The move is atomic when supported by the OS; the original file is removed after a successful move. Parent directories are created if missing.

---

## 🔂 Steps (Agent)

1. Parse **Title**, **Description**, **AC**, **Tech** per **Parsing Rules**.
   - For AC: Extract the COMPLETE Gherkin syntax from the "5) Acceptance Criteria (Gherkin)" section (including Feature line, all Scenario blocks, and all Given/When/Then/And steps).
2. Resolve project = frontmatter `project` or `--project`. (Do not list projects.)
3. Detect field availability via `workitems.fields`.
4. **Create** or **Update** the PBI with the field mapping above.
   - If creating a new PBI with a Feature ID provided, attempt to add the parent relation using the JSON Patch operation specified in "Parent Link Setup" section.
   - If creation-time relations aren't supported by the NGA MCP create function, immediately after creation perform a follow-up PATCH on the newly created PBI to add the relation with the same JSON Patch operation.
   - Do NOT modify the Feature (parent) work item.
5. If `--rename`: compose the destination path and move the original spec file to that location (create parent directories as needed).

---

## 🛡️ Guardrails

- No source code edits; only one work item and (optional) one file move.
- The destination must be within `{dir}`; abort if the resolved path escapes `{dir}`.
- If ADO creation/update fails, do not move the file.
- If AC/Tech fields are absent, append to Description; otherwise, keep Description clean.
- **CRITICAL**: Extract the FULL Gherkin scenarios with all steps (Given/When/Then/And) - do NOT create simple checklist items. The Gherkin syntax is required for proper test traceability in Azure DevOps.

---

## ✅ Rename example (resulting path)

```markdown
docs/specs/987654-export-to-excel/{id}-export-to-excel-e2e.md
```

---

## 🚀 Prompt

```
/create-pbi <spec-path> <feature-id> [--project "<name>"] [--area "<path>"] [--iteration "<path>"] [--assign "<user>"] [--tags "t1,t2"] [--update <pbi-id>] [--rename] [--pattern "{dir}/{featureId}-{featureSlug}/{id}-{slug}.md"] [--ac-field "Microsoft.VSTS.Common.AcceptanceCriteria"] [--tech-field "Custom.TechnicalDetails"]
```