azaion/gps-denied-onboard
1
0
Fork 0
mirror of https://github.com/azaion/gps-denied-onboard.git synced 2026-04-23 01:46:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

add iterative development commands

Browse Source
This commit is contained in:
Oleksandr Bezdieniezhnykh
2025-12-05 15:49:34 +02:00
parent 281cddbe69
commit d371e68a79
3 changed files with 450 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/commands/4.development/4.10_generate_spec.md
+192
View File
@@ -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.
.cursor/commands/4.development/create-pbi.md
+185
View File
@@ -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"]
```
.cursor/commands/4.development/save-plan.md
+73
View File
@@ -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