mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-04-22 11:36:37 +00:00
add iterative development commands
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -0,0 +1,185 @@
|
||||
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"]
|
||||
```
|
||||
Reference in New Issue
Block a user