gps-denied-onboard/.cursor/commands/4.development/create-pbi.md

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.
   • (when set): full Gherkin scenarios converted to HTML (preserve Feature:, Scenario:, Given/When/Then/And structure).
   • (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:

{
  "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)

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"]