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