--- name: create-ado-work-items description: Creates Azure DevOps work items for Power Platform / Dataverse Model-Driven App projects. Use when creating ADO work items, building a backlog, scaffolding a project, or converting requirements into Epics, Features, and User Stories/PBIs. Part of the /project-standup pipeline (Phase 3). argument-hint: "[project-name] [optional: scaffold-only | from-build-spec PATH]" --- When creating Azure DevOps work items for a Power Platform / Dataverse Model-Driven App project, follow these standards exactly. ## Pipeline Integration When invoked as **Phase 3** of the `/project-standup` pipeline: **Input:** `build-specification.json` from Phase 2 (`/architect-app`) — NOT raw extracted requirements. The build specification contains validated, architecture-reviewed definitions for every table, column, form, view, security role, and flow. Work items are created from this spec, ensuring they reflect architecture decisions (OOB entity filtering, global option set consolidation, validated field types, etc.). **Output:** `ado-work-items.json` — mapping file for Phase 4 (`/build-dataverse-app`). ### Source Reference Footers When `build-specification.json` includes `source_references`, EVERY PBI description gets a source footer: ```html
Source: Requirements.docx (snippets 12-15) | Original Document ``` Look up each story's `source_refs` in the `source_references` map to get `source_doc`, `source_url`, and `snippet_range`. ### ADO Work Items Mapping File After ALL work items are created, write `ado-work-items.json`: ```json { "project": "ADO MCP Demo", "created_at": "ISO timestamp", "process_template": "Scrum", "story_type": "Product Backlog Item", "items": [ { "id": 1234, "type": "Epic", "title": "Core Data Model", "state": "New", "parent_id": null, "category": "Tables", "is_scaffold": false }, { "id": 1235, "type": "Feature", "title": "Application & Payment Tables", "state": "New", "parent_id": 1234, "category": "Tables" }, { "id": 1236, "type": "Product Backlog Item", "title": "Create Application table", "state": "New", "parent_id": 1235, "category": "Tables", "source_refs": ["batch-001:REQ-003"] } ] } ``` This file is the **critical handoff artifact** to Phase 4. Without it, the Dataverse builder cannot trace operations back to ADO stories or update them as work completes. ## Pre-Flight Before creating ADO work items: - Authenticate to the target ADO environment (read `.ado-auth.json` or run `ado_authenticate`) - Confirm the target ADO project and area path with the user - If working from a build specification, verify the spec file exists and read it - Check existing work items in the project to avoid creating duplicates: `wit_query_work_items` with a title search ## Guardrails - **Always create parent items before children.** Epics first, then Features (linked to Epic), then PBIs/Stories (linked to Feature), then Tasks (linked to Story). Capture the returned work item ID at each level for linking. - **Never create work items without a parent link** (except top-level Epics). Orphaned work items are hard to find and manage. - **Include source references** when creating from extracted requirements. Every PBI should have a source footer linking back to the original document. - **Batch creation is preferred** for 4+ items — use `wit_batch_create_work_items` for efficiency. --- ## Step 1: Detect Process Template Before creating any work items, determine the target project's process template: - **Scrum:** Epic > Feature > **Product Backlog Item** - **Agile:** Epic > Feature > **User Story** Use `wit_get_work_item_type` or check existing work items to determine which type to use. Use the correct story-level type for ALL story-level items. ## Step 2: Always Create Standard Scaffold Every Power Platform project gets these 5 Epics with their Features. Create them first using `wit_create_work_item` and link with `wit_link_work_items` (linkType: "child"). ### Epic 1: Infrastructure Setup Features: General App Setup, SharePoint Environments, Solution Management, Power Platform Environments, Power Pages Environments (if applicable), Deployment ### Epic 2: Security Features: Business Units, Security Roles, Field Security Profiles, SharePoint Document Management Security, Document Management Records Retention Policy ### Epic 3: Documentation Requests & Action Items Features: Client Documentation Requests, Client Action Items ### Epic 4: Standard Supporting Document Templates Features: Templates (Sitemap Layout, Field-level Matrix, Security Role Matrix, User Story States, Data Migration Mapping) ### Epic 5: Enhancements & Support Placeholder Epic — created empty for post-go-live items. ## Step 3: Work Item Formatting ### Epic Description (HTML) ``` Objective: [Main goal and business value]
Scope: [What is included and what is not]
Context: [Background information]
Dependencies: [Any dependencies or considerations] ``` ### Feature Description (HTML) ``` Objective: [What this feature delivers]
Scope: [Boundaries of this feature]
Context: [How it fits in the broader Epic] ``` ### Story/PBI Description (HTML) Title pattern: `[Action] [object] [context]` (e.g., "Create Contact table", "Configure Manager security role") ``` AS A [role/persona]
I WANT [what the user needs]
SO THAT [business benefit]

Implementation Details:
``` ### Story/PBI Acceptance Criteria (HTML) ``` GIVEN [precondition or context]
WHEN [specific action]
THEN [expected result]

GIVEN [another scenario]
WHEN [another action]
THEN [another result] ``` Include 2-4 GIVEN/WHEN/THEN scenarios per story. ## Step 4: Dynamic Work Items from Build Specification When creating work items from a `build-specification.json` (Phase 3 of `/project-standup`), generate PBIs directly from the architecture-reviewed spec: ### From `custom_tables` array: - One "Create [table] table" PBI per table → use **Create New Table** template - One "Create system views for [table]" PBI per table → use **Create System Views** template - One "Add custom fields to [table]" PBI per OOB entity with custom columns ### From `forms` array: - One PBI per form definition → include tab/section/field layout from spec - Subgrid PBIs from form subgrid definitions → use **Add Subgrid to Form** template - Quick view PBIs from form quick_view definitions → use **Add Quick View Form** template ### From `security_roles` array: - One "Create [role] security role" PBI per role → use **Create Security Role** template - One "Secure [table] records" PBI per table that has role-specific privileges ### From `flows` array: - One PBI per flow → use **Notification/Power Automate Flow** template ### From `global_option_sets` array: - One PBI per global option set creation (group under Infrastructure) For the full template details of each pattern, read [pbi-templates.md](pbi-templates.md). **Available patterns:** Create New Table, Create System Views, Add Subgrid to Form, Add Quick View Form, Hide/Show Field/Section/Tab, Calculated Field, Notification/Power Automate Flow, Secure Table Records, Configure Search, Dashboard, Business Process Flow, Create Security Role ### When NOT using build-specification.json If creating work items from raw requirements/documentation (standalone usage), match to PBI template patterns and fill in `[brackets]` from the actual requirements. ## Rules 1. Always create scaffold Epics for every project 2. Match requirements to PBI templates when pattern matches — use template format with project details 3. Create custom PBIs for non-matching requirements — still use AS A/I WANT/SO THAT + GIVEN/WHEN/THEN 4. One PBI per discrete deliverable — don't combine multiple tables or roles 5. Group PBIs into Features by functional area 6. Group Features into Epics by business capability 7. Preserve verbatim details from spec/requirements — exact field names, schema names, table names, option values 8. Security PBIs always go under the Security Epic 9. Cross-reference documents (field matrices, security matrices, sitemap layouts) in descriptions 10. When `source_references` are available, append source footer to every PBI description ## Validation After creating work items: - Query the created Epics to verify parent-child hierarchy is correct: `wit_get_work_item` with `$expand=relations` - Verify total counts match expectations (Epics, Features, Stories/PBIs, Tasks) - Report: items created per type, any linking errors, ADO project and area path used