Skip to content

Commit d6fb77d

Browse files
chaosdinosaurWilliamBerryiii
chaosdinosaur
and
WilliamBerryiii
authored
feat(instructions): add ADO backlog sprint planning and capacity tracking (#788)
# Pull Request ## Description Add sprint planning and capacity tracking instructions for the ADO Backlog Manager agent. This introduces `ado-backlog-sprint.instructions.md` with iteration coverage analysis, capacity tracking, gap detection, and work item assignment workflows. Includes an `ado-sprint-plan.prompt.md` prompt for sprint planning entry points. Part of the ADO Backlog Manager feature set (3 of 5 PRs). ## Related Issue(s) Closes #778 ## Type of Change Select all that apply: **Code & Documentation:** * [ ] Bug fix (non-breaking change fixing an issue) * [x] New feature (non-breaking change adding functionality) * [ ] Breaking change (fix or feature causing existing functionality to change) * [ ] Documentation update **Infrastructure & Configuration:** * [ ] GitHub Actions workflow * [ ] Linting configuration (markdown, PowerShell, etc.) * [ ] Security configuration * [ ] DevContainer configuration * [ ] Dependency update **AI Artifacts:** * [ ] Reviewed contribution with `prompt-builder` agent and addressed all feedback * [x] Copilot instructions (`.github/instructions/*.instructions.md`) * [x] Copilot prompt (`.github/prompts/*.prompt.md`) * [ ] Copilot agent (`.github/agents/*.agent.md`) * [ ] Copilot skill (`.github/skills/*/SKILL.md`) **Other:** * [ ] Script/automation (`.ps1`, `.sh`, `.py`) * [ ] Other (please describe): ## Sample Prompts (for AI Artifact Contributions) **User Request:** > Plan the next sprint for our ADO project — analyze iteration coverage, check team capacity, and identify gaps. **Execution Flow:** 1. Sprint planning prompt triggers with project context 2. Instruction file guides iteration discovery via MCP ADO tools 3. Coverage analysis identifies unassigned work items and capacity gaps 4. Gap detection surfaces missing assignments and overallocated team members 5. Sprint plan output written to `.copilot-tracking/workitems/sprint/` **Output Artifacts:** Sprint planning files in `.copilot-tracking/workitems/sprint/` containing iteration coverage analysis, capacity breakdown, and recommended work item assignments. **Success Indicators:** - Sprint coverage report identifies all iterations in scope - Capacity analysis accounts for team member availability - Gap detection surfaces unassigned high-priority items - Recommendations align with team capacity constraints ## Testing - Verified `npm run plugin:generate` succeeds with new collection entries - Confirmed frontmatter structure follows existing ADO instruction patterns - Validated collection YAML entries reference correct paths and kinds ## Checklist ### Required Checks * [x] Documentation is updated (if applicable) * [x] Files follow existing naming conventions * [x] Changes are backwards compatible (if applicable) * [ ] Tests added for new functionality (if applicable) ### AI Artifact Contributions * [ ] Used `/prompt-analyze` to review contribution * [ ] Addressed all feedback from `prompt-builder` review * [x] Verified contribution follows common standards and type-specific requirements ### Required Automated Checks The following validation commands must pass before merging: * [x] Markdown linting: `npm run lint:md` * [x] Spell checking: `npm run spell-check` * [x] Frontmatter validation: `npm run lint:frontmatter` * [x] Skill structure validation: `npm run validate:skills` * [x] Link validation: `npm run lint:md-links` * [x] PowerShell analysis: `npm run lint:ps` * [x] Plugin freshness: `npm run plugin:generate` ## Security Considerations * [x] This PR does not contain any sensitive or NDA information * [x] Any new dependencies have been reviewed for security issues * [x] Security-related scripts follow the principle of least privilege ## Additional Notes - Depends on Foundation PR (#776) and Triage PR (#787) for shared instruction infrastructure - Sprint instruction references `ado-wit-planning.instructions.md` for planning file schemas - Collection entries added to both `ado` and `hve-core-all` collections --------- Co-authored-by: Bill Berry <wberry@microsoft.com>
1 parent cde0190 commit d6fb77d

File tree

10 files changed

+306
-0
lines changed

10 files changed

+306
-0
lines changed

‎.github/instructions/ado/ado-backlog-sprint.instructions.md‎

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
---
2+
description: "Sprint planning workflow for Azure DevOps iterations with coverage analysis, capacity tracking, and gap detection - Brought to you by microsoft/hve-core"
3+
applyTo: '**/.copilot-tracking/workitems/sprint/**'
4+
---
5+
6+
# ADO Sprint Planning
7+
8+
Plan Azure DevOps iterations by analyzing work item coverage, capacity, dependencies, and gaps. Follow all instructions from #file:./ado-wit-planning.instructions.md while executing this workflow.
9+
10+
## Required Phases
11+
12+
### Phase 1: Discover and Retrieve
13+
14+
Gather iteration metadata and work items for the target sprint.
15+
16+
#### Step 1: Discover Iterations
17+
18+
Call `mcp_ado_work_list_team_iterations` to enumerate available iterations. Identify the current iteration (date range containing today), the next iteration, and any future iterations within the planning horizon.
19+
20+
Record iteration details in planning-log.md:
21+
22+
* Iteration name and path
23+
* Start date and end date
24+
* Whether the iteration is current, next, or future
25+
26+
When a specific iteration is provided as input, use that iteration. Otherwise, default to the current iteration.
27+
28+
#### Step 2: Retrieve Sprint Work Items
29+
30+
Call `mcp_ado_wit_get_work_items_for_iteration` with the target iteration ID to retrieve all work items assigned to the sprint.
31+
32+
Hydrate results via `mcp_ado_wit_get_work_items_batch_by_ids` to retrieve full field details including `System.State`, `System.AreaPath`, `System.WorkItemType`, `Microsoft.VSTS.Common.Priority`, `Microsoft.VSTS.Scheduling.StoryPoints`, `Microsoft.VSTS.Scheduling.OriginalEstimate`, `Microsoft.VSTS.Scheduling.RemainingWork`, and `Microsoft.VSTS.Scheduling.CompletedWork`.
33+
34+
#### Step 3: Retrieve Backlog Items
35+
36+
Call `mcp_ado_wit_list_backlog_work_items` to retrieve unplanned backlog items not assigned to any iteration. These candidates feed backlog grooming recommendations in Phase 2.
37+
38+
### Phase 2: Analyze
39+
40+
Evaluate the sprint across four dimensions: coverage, capacity, gaps, and dependencies.
41+
42+
#### Step 1: Triage Prerequisite Check
43+
44+
Count work items in the `New` state. When more than 50% of sprint items are in `New` state, recommend running triage via `ado-backlog-triage.instructions.md` before continuing sprint planning. Log the recommendation in planning-log.md and inform the user.
45+
46+
Sprint planning can continue alongside a triage recommendation, but the plan should note that classifications may shift after triage completes.
47+
48+
#### Step 2: Coverage Analysis
49+
50+
Build an Area Path coverage matrix showing which areas are represented in the sprint and which are missing.
51+
52+
| Area Path | Items | Story Points | Status |
53+
|------------------|-------|--------------|-------------|
54+
| {{area_path}} | {{n}} | {{points}} | Covered |
55+
| {{missing_area}} | 0 | 0 | Not Covered |
56+
57+
Identify Area Paths with active work items in the backlog but no representation in the sprint. Flag these as coverage gaps.
58+
59+
Build a hierarchy coverage matrix showing decomposition completeness at each work item type level:
60+
61+
| Level | Total | With Children | Orphaned | Completeness |
62+
|---------|-------|---------------|----------|--------------|
63+
| Epic | {{n}} | {{n}} | {{n}} | {{pct}}% |
64+
| Feature | {{n}} | {{n}} | {{n}} | {{pct}}% |
65+
| Story | {{n}} | {{n}} | {{n}} | {{pct}}% |
66+
| Task | {{n}} | {{n}} | {{n}} | {{pct}}% |
67+
68+
Identify orphaned stories (no parent Feature), features without parent Epics, and stories lacking Task decomposition. ADO's 4-level hierarchy enables coverage analysis that flat issue trackers cannot provide.
69+
70+
#### Step 3: Capacity Analysis
71+
72+
Sum planned effort using `Microsoft.VSTS.Scheduling.StoryPoints` for User Stories or `Microsoft.VSTS.Scheduling.OriginalEstimate` for Tasks and Bugs.
73+
74+
When team capacity is provided as input, compare planned effort against capacity:
75+
76+
| Metric | Value |
77+
|----------------|------------------|
78+
| Planned Effort | {{total_points}} |
79+
| Team Capacity | {{capacity}} |
80+
| Utilization | {{percentage}}% |
81+
| Remaining | {{remaining}} |
82+
83+
Include burndown metrics when `CompletedWork` data is available:
84+
85+
| Metric | Value |
86+
|----------------|-----------------------------------------|
87+
| Original Est. | Sum of `OriginalEstimate` across items |
88+
| Completed Work | Sum of `CompletedWork` across items |
89+
| Remaining Work | Sum of `RemainingWork` across items |
90+
| Burndown Ratio | `CompletedWork / OriginalEstimate` as % |
91+
92+
When capacity is not provided, report planned effort totals and recommend that the user supply capacity data for utilization calculations.
93+
94+
Break down effort by team member when `System.AssignedTo` data is available.
95+
96+
#### Step 4: Gap Analysis
97+
98+
Cross-reference requirements documents, PRDs, or other planning artifacts against the iteration backlog when documents are provided. Identify requirements with no matching work items in the sprint.
99+
100+
When no documents are provided, skip this step and note that gap analysis requires reference documents.
101+
102+
#### Step 5: Dependency Detection
103+
104+
Examine work item links for parent-child relationships and predecessor/successor dependencies:
105+
106+
* Identify items with predecessors outside the current sprint (external blockers).
107+
* Identify items with successors in the current sprint (internal chains).
108+
* Flag items with unresolved parent links or missing child items.
109+
110+
Record dependency chains in planning-log.md.
111+
112+
### Phase 3: Plan
113+
114+
Produce sprint plan and grooming recommendations.
115+
116+
#### Step 1: Backlog Grooming Recommendations
117+
118+
From the unplanned backlog retrieved in Phase 1, identify items that could be pulled into the sprint. Evaluate candidates by:
119+
120+
* Priority: higher-priority items first
121+
* Capacity: remaining capacity after planned items
122+
* Dependencies: items whose predecessors are complete or in the current sprint
123+
* Coverage: items that fill identified Area Path gaps
124+
125+
Rank candidates and present the top recommendations.
126+
127+
#### Step 2: Generate Sprint Plan
128+
129+
Create sprint-plan.md in `.copilot-tracking/workitems/sprint/{{iteration-kebab}}/` using the template in the Output section.
130+
131+
#### Step 3: Present for Review
132+
133+
Present the sprint plan to the user, highlighting:
134+
135+
* Capacity utilization and over/under-commitment
136+
* Coverage gaps by Area Path
137+
* External dependencies and blockers
138+
* Backlog grooming candidates ranked by fit
139+
140+
## Output
141+
142+
The sprint planning workflow produces output files in `.copilot-tracking/workitems/sprint/{{iteration-kebab}}/`.
143+
144+
### sprint-plan.md Template
145+
146+
Planning markdown files must start and end with the directives defined in the planning specification.
147+
148+
```markdown
149+
<!-- markdownlint-disable-file -->
150+
<!-- markdown-table-prettify-ignore-start -->
151+
# Sprint Plan - {{iteration_name}}
152+
153+
* **Project**: {{project}}
154+
* **Iteration**: {{iteration_path}}
155+
* **Dates**: {{start_date}} to {{end_date}}
156+
* **Team Capacity**: {{capacity}} (if provided)
157+
* **Date Generated**: {{YYYY-MM-DD}}
158+
159+
## Summary
160+
161+
| Metric | Value |
162+
| ------------------- | ------------------ |
163+
| Total Items | {{item_count}} |
164+
| Story Points | {{total_points}} |
165+
| Capacity | {{capacity}} |
166+
| Utilization | {{utilization}}% |
167+
| Items in New State | {{new_count}} |
168+
| External Blockers | {{blocker_count}} |
169+
| Burndown Ratio | {{burndown_pct}}% |
170+
171+
## Work Items by Priority
172+
173+
### Priority 1 - Critical
174+
175+
| ID | Title | Type | State | Story Points | Assigned To | Area Path |
176+
| -- | ----- | ---- | ----- | ------------ | ----------- | --------- |
177+
| {{id}} | {{title}} | {{type}} | {{state}} | {{points}} | {{assignee}} | {{area}} |
178+
179+
### Priority 2
180+
181+
| ID | Title | Type | State | Story Points | Assigned To | Area Path |
182+
| -- | ----- | ---- | ----- | ------------ | ----------- | --------- |
183+
| {{id}} | {{title}} | {{type}} | {{state}} | {{points}} | {{assignee}} | {{area}} |
184+
185+
### Priority 3-4
186+
187+
| ID | Title | Type | State | Story Points | Assigned To | Area Path |
188+
| -- | ----- | ---- | ----- | ------------ | ----------- | --------- |
189+
| {{id}} | {{title}} | {{type}} | {{state}} | {{points}} | {{assignee}} | {{area}} |
190+
191+
## Coverage Matrix
192+
193+
### Area Path Coverage
194+
195+
| Area Path | Items | Story Points | Status |
196+
| --------- | ----- | ------------ | ------ |
197+
| {{area_path}} | {{count}} | {{points}} | {{status}} |
198+
199+
### Hierarchy Coverage
200+
201+
| Level | Total | With Children | Orphaned | Completeness |
202+
| ----- | ----- | ------------- | -------- | ------------ |
203+
| Epic | {{n}} | {{n}} | {{n}} | {{pct}}% |
204+
| Feature | {{n}} | {{n}} | {{n}} | {{pct}}% |
205+
| Story | {{n}} | {{n}} | {{n}} | {{pct}}% |
206+
| Task | {{n}} | {{n}} | {{n}} | {{pct}}% |
207+
208+
## Dependencies
209+
210+
### External Blockers
211+
212+
| Sprint Item | Blocked By | External Iteration | Status |
213+
| ----------- | ---------- | ------------------ | ------ |
214+
| {{id}} | {{blocker_id}} | {{iteration}} | {{status}} |
215+
216+
### Internal Chains
217+
218+
| Predecessor | Successor | Relationship |
219+
| ----------- | --------- | ------------ |
220+
| {{pred_id}} | {{succ_id}} | {{link_type}} |
221+
222+
## Gap Analysis
223+
224+
{{gap_analysis_results or "No reference documents provided for gap analysis."}}
225+
226+
## Backlog Grooming Candidates
227+
228+
| ID | Title | Priority | Story Points | Rationale |
229+
| -- | ----- | -------- | ------------ | --------- |
230+
| {{id}} | {{title}} | {{priority}} | {{points}} | {{rationale}} |
231+
232+
## Recommended Actions
233+
234+
* {{action_item}}
235+
<!-- markdown-table-prettify-ignore-end -->
236+
```
237+
238+
### planning-log.md
239+
240+
Use the planning-log.md template from the planning specification. Set the planning type to `Sprint` and track each analysis step through discovery, analysis, and planning.
241+
242+
## Success Criteria
243+
244+
Sprint planning is complete when:
245+
246+
* The target iteration has been identified and its work items retrieved.
247+
* Coverage, capacity, dependency, and (optionally) gap analyses have been performed.
248+
* A sprint-plan.md exists with all analysis sections populated.
249+
* Backlog grooming candidates have been identified and ranked when capacity permits.
250+
* The user has reviewed the plan and any recommended actions.
251+
* planning-log.md reflects the final state of all analysis steps.
252+
253+
---
254+
255+
Brought to you by microsoft/hve-core

‎.github/prompts/ado/ado-sprint-plan.prompt.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
description: "Plan an Azure DevOps sprint by analyzing iteration coverage, capacity, dependencies, and backlog gaps"
3+
agent: ADO Backlog Manager
4+
argument-hint: "project=... iteration=... [documents=...] [capacity=...] [autonomy={full|partial|manual}]"
5+
---
6+
7+
# Plan ADO Sprint
8+
9+
Analyze an Azure DevOps iteration, assess work item coverage against Area Paths and optional planning documents, and produce a prioritized sprint plan with gap analysis and dependency awareness.
10+
11+
Follow all instructions from #file:../../instructions/ado/ado-backlog-sprint.instructions.md for sprint planning workflows, coverage analysis, and capacity tracking.
12+
Follow all instructions from #file:../../instructions/ado/ado-wit-planning.instructions.md for shared conventions, planning file templates, and field definitions.
13+
14+
## Inputs
15+
16+
* `${input:project}`: (Required) Azure DevOps project name.
17+
* `${input:iteration}`: (Required) Target iteration name or path for the sprint.
18+
* `${input:documents}`: (Optional) File paths or URLs of source documents (PRDs, RFCs) for cross-referencing against iteration work items.
19+
* `${input:sprintGoal}`: (Optional) Sprint goal or theme description to focus prioritization.
20+
* `${input:capacity}`: (Optional) Team capacity or story point limit for the sprint.
21+
* `${input:contentFormat:Markdown}`: (Optional) Content format for rich-text fields in planning files. Use `Markdown` for Azure DevOps Services (dev.azure.com) or `Html` for Azure DevOps Server (on-premises). Defaults to Markdown.
22+
23+
## Requirements
24+
25+
* Resolve `${input:iteration}` and verify it exists before fetching work items.
26+
* When `${input:documents}` is provided, cross-reference extracted requirements against iteration work items and identify coverage gaps.
27+
* When `${input:capacity}` is provided, include only top-ranked items up to the capacity limit.
28+
* Prioritize `${input:sprintGoal}`-aligned items when a sprint goal is provided.
29+
* Write planning artifacts to `.copilot-tracking/workitems/sprint/{{iteration-kebab}}/`.
30+
* When the iteration contains no work items, suggest running discovery via *ado-discover-work-items.prompt.md*.
31+
* When excessive unclassified items are found, recommend triage via *ado-triage-work-items.prompt.md* before sprint planning.
32+
33+
---
34+
35+
Proceed with planning the sprint for the specified iteration following the sprint planning workflow instructions.

‎collections/ado.collection.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ items:
2222
kind: prompt
2323
- path: .github/prompts/ado/ado-update-wit-items.prompt.md
2424
kind: prompt
25+
- path: .github/prompts/ado/ado-sprint-plan.prompt.md
26+
kind: prompt
2527
- path: .github/prompts/ado/ado-triage-work-items.prompt.md
2628
kind: prompt
2729
# Instructions
@@ -35,6 +37,8 @@ items:
3537
kind: instruction
3638
- path: .github/instructions/ado/ado-wit-planning.instructions.md
3739
kind: instruction
40+
- path: .github/instructions/ado/ado-backlog-sprint.instructions.md
41+
kind: instruction
3842
- path: .github/instructions/ado/ado-backlog-triage.instructions.md
3943
kind: instruction
4044
- path: .github/instructions/ado/ado-interaction-templates.instructions.md

‎collections/hve-core-all.collection.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,8 @@ items:
8888
kind: prompt
8989
- path: .github/prompts/ado/ado-process-my-work-items-for-task-planning.prompt.md
9090
kind: prompt
91+
- path: .github/prompts/ado/ado-sprint-plan.prompt.md
92+
kind: prompt
9193
- path: .github/prompts/ado/ado-triage-work-items.prompt.md
9294
kind: prompt
9395
- path: .github/prompts/ado/ado-update-wit-items.prompt.md
@@ -177,6 +179,8 @@ items:
177179
kind: prompt
178180
- path: .github/prompts/security-planning/risk-register.prompt.md
179181
kind: prompt
182+
- path: .github/instructions/ado/ado-backlog-sprint.instructions.md
183+
kind: instruction
180184
- path: .github/instructions/ado/ado-backlog-triage.instructions.md
181185
kind: instruction
182186
- path: .github/instructions/ado/ado-create-pull-request.instructions.md

‎plugins/ado/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ copilot plugin install ado@hve-core
2424
| ado-get-my-work-items | Retrieve user's current Azure DevOps work items and organize them into planning file definitions |
2525
| ado-process-my-work-items-for-task-planning | Process retrieved work items for task planning and generate task-planning-logs.md handoff file |
2626
| ado-update-wit-items | Prompt to update work items based on planning files |
27+
| ado-sprint-plan | Plan an Azure DevOps sprint by analyzing iteration coverage, capacity, dependencies, and backlog gaps |
2728
| ado-triage-work-items | Triage untriaged Azure DevOps work items with field classification, iteration assignment, and duplicate detection |
2829

2930
## Instructions
@@ -35,6 +36,7 @@ copilot plugin install ado@hve-core
3536
| ado-update-wit-items | Work item creation and update protocol using MCP ADO tools with handoff tracking |
3637
| ado-wit-discovery | Protocol for discovering Azure DevOps work items via user assignment or artifact analysis with planning file output |
3738
| ado-wit-planning | Reference specification for Azure DevOps work item planning files, templates, field definitions, and search protocols |
39+
| ado-backlog-sprint | Sprint planning workflow for Azure DevOps iterations with coverage analysis, capacity tracking, and gap detection - Brought to you by microsoft/hve-core |
3840
| ado-backlog-triage | Triage workflow for Azure DevOps work items with field classification, iteration assignment, and duplicate detection - Brought to you by microsoft/hve-core |
3941
| ado-interaction-templates | Work item description and comment templates for consistent Azure DevOps content formatting - Brought to you by microsoft/hve-core |
4042
| hve-core-location | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. |

‎plugins/ado/commands/ado-sprint-plan.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../.github/prompts/ado/ado-sprint-plan.prompt.md

‎plugins/ado/instructions/ado-backlog-sprint.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../.github/instructions/ado/ado-backlog-sprint.instructions.md

0 commit comments

Comments
 (0)