diff --git a/.cursor/commands/4.development/4.10_generate_spec.md b/.cursor/commands/4.development/4.10_generate_spec.md new file mode 100644 index 0000000..3a8f148 --- /dev/null +++ b/.cursor/commands/4.development/4.10_generate_spec.md @@ -0,0 +1,192 @@ +# Generate Feature Specification + +Create a focused behavioral specification that describes **what** the system should do, not **how** it should be built. + +## Objective + +Generate lean specifications with: +- Clear problem statement and desired outcomes +- Behavioral acceptance criteria in Gherkin format +- Essential non-functional requirements +- No implementation prescriptiveness + +## Process + +1. Read the building block or feature description +2. Analyze the codebase to understand context +3. Generate a behavioral specification using the structure below +4. **DO NOT** include implementation details, file structures, or technical architecture +5. Focus on behavior, user experience, and acceptance criteria + +## Specification Structure + +### Header +```markdown +# [Feature Name] + +**Status**: Draft | **Date**: [YYYY-MM-DD] | **Feature**: [Brief Feature Description] +``` + +### Problem +Clear, concise statement of the problem users are facing. + +### Outcome +Measurable or observable goals/benefits (use bullet points). + +### Scope + +#### Included +What's in scope for this feature (bullet points). + +#### Excluded +Explicitly what's **NOT** in scope (bullet points). + +### Acceptance Criteria + +Each acceptance criterion should be: +- Numbered sequentially (AC-1, AC-2, etc.) +- Include a brief title +- Written in Gherkin format (Given/When/Then) + +Example: +```markdown +**AC-1: Export Availability** +``` +Given the user is viewing the dashboard +When the dashboard loads +Then an "Export to Excel" button should be visible in the filter/actions area +``` + +### Non-Functional Requirements + +Only include essential non-functional requirements: +- Performance (if relevant) +- Compatibility (if relevant) +- Reliability (if relevant) + +Use sub-sections with bullet points. + +### Constraints + +High-level constraints that guide implementation: +- Architectural patterns (if critical) +- Technical limitations +- Integration requirements +- No breaking changes (if applicable) + +### Risks & Mitigation + +List key risks with mitigation strategies (if applicable). + +Each risk should have: +- *Risk*: Description +- *Mitigation*: Approach + +--- + +## Output Guidelines + +**DO:** +- Focus on behavior and user experience +- Use clear, simple language +- Keep acceptance criteria testable +- Include realistic scope boundaries +- Write from the user's perspective + +**DON'T:** +- Include implementation details (file paths, classes, methods) +- Prescribe technical solutions or libraries +- Add architectural diagrams or code examples +- Specify exact API endpoints or data structures +- Include step-by-step implementation instructions +- Add "how to build" guidance + +## Example + +```markdown +# Dashboard Export to Excel + +**Status**: Draft | **Date**: 2025-01-XX | **Feature**: Export Dashboard Data to Excel + +--- + +## Problem + +Users currently have no efficient way to export dashboard data for offline analysis, reporting, or sharing. Manual copy-paste is time-consuming, error-prone, and lacks context about active filters. + +## Outcome + +- Eliminate manual copy-paste workflows +- Enable accurate data sharing with proper context +- Measurable time savings (target: <30s vs. several minutes) +- Improved data consistency for offline analysis + +## Scope + +### Included +- Export filtered dashboard data to Excel +- Single-click export from dashboard view +- Respect all active filters (status, date range) + +### Excluded +- CSV or PDF export options +- Scheduled or automated exports +- Email export functionality + +--- + +## Acceptance Criteria + +**AC-1: Export Button Visibility** +``` +Given the user is viewing the dashboard +When the dashboard loads +Then an "Export to Excel" button should be visible in the actions area +``` + +**AC-2: Basic Export Functionality** +``` +Given the user is viewing the dashboard with data +When the user clicks the "Export to Excel" button +Then an Excel file should download to their default location +And the filename should include a timestamp +``` + +--- + +## Non-Functional Requirements + +**Performance** +- Export completes in <2 seconds for up to 1000 records +- Support up to 10,000 records per export + +**Compatibility** +- Excel files openable in Microsoft Excel, Google Sheets, and LibreOffice +- Standard Excel format (.xlsx) + +--- + +## Constraints + +- Must respect all currently active filters +- Must follow existing hexagonal architecture patterns +- No breaking changes to existing functionality + +--- + +## Risks & Mitigation + +**Risk 1: Excel File Compatibility** +- *Risk*: Generated files don't open correctly in all spreadsheet applications +- *Mitigation*: Use standard Excel format, test with multiple applications +``` + +--- + +## Implementation Notes + +- Use descriptive but concise titles +- Keep specifications focused and scoped appropriately +- Remember: This is a **behavioral spec**, not an implementation plan + +**CRITICAL**: Generate the spec file ONLY. Do NOT modify code, create files, or make any implementation changes at this stage. \ No newline at end of file diff --git a/.cursor/commands/4.development/create-pbi.md b/.cursor/commands/4.development/create-pbi.md new file mode 100644 index 0000000..a43f683 --- /dev/null +++ b/.cursor/commands/4.development/create-pbi.md @@ -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 ""` (defaults to frontmatter `project`, here: "Audit Platform") + - `--area ""` + - `--iteration ""` + - `--assign ""` + - `--tags "t1,t2"` + - `--update ` (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 `
` and `` 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**: ``
+   - **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"]
+```
diff --git a/.cursor/commands/4.development/save-plan.md b/.cursor/commands/4.development/save-plan.md
new file mode 100644
index 0000000..d3b04ed
--- /dev/null
+++ b/.cursor/commands/4.development/save-plan.md
@@ -0,0 +1,73 @@
+---
+title: "Save Plan — /save-plan"
+category: "planning"
+tags:
+  - planning
+  - documentation
+version: "1.0"
+description: "Save the current in-memory plan to disk mirroring the spec structure."
+---
+
+# /save-plan — Save Plan to Disk
+
+Save the current in-memory plan to disk (mirroring spec structure under `docs/plans/`).
+
+---
+
+## Syntax
+
+```bash
+/save-plan --spec @<original-spec-path>
+```
+
+- `--spec @<original-spec-path>` (required): Original spec path to mirror structure
+
+---
+
+## Behavior
+
+1) Read the current in-memory plan from Cursor's Plan mode.
+2) Determine output path by mirroring the spec's subpath:
+   - Spec: `docs/specs/<subpath>/<filename>.md`
+   - Plan: `docs/plans/<subpath>/<filename>.md`
+3) Ensure parent directories exist; write the plan atomically.
+4) Return saved plan path.
+
+---
+
+## Prerequisites
+
+- Cursor is in Plan mode with an active plan
+- Original spec exists at the provided path
+
+---
+
+## Usage
+
+After generating a plan in Plan mode:
+
+```bash
+/save-plan --spec @docs/specs/888568-language-content-service-implementation-execute/920755-export-to-excel-backend-frontend-and-filters.md
+```
+
+This writes plan to: `docs/plans/888568-language-content-service-implementation-execute/920755-export-to-excel-backend-frontend-and-filters.md`
+
+---
+
+## Example
+
+Command:
+```bash
+/save-plan --spec @docs/specs/924274-jadx-test/924326-dashboard-export-to-excel.md
+```
+
+Result:
+- Plan saved to `docs/plans/924274-jadx-test/924326-dashboard-export-to-excel.md`
+
+---
+
+## Notes
+
+- Only works when a plan exists in memory (Plan mode)
+- If plan file already exists, it's overwritten
+- Preserves the original plan structure and todos as-is