feat(prompts): add ADO discovery and work item prompts with agent routing (#790)

# Pull Request

## Description

Add discovery and single-work-item creation prompts, add autonomy hooks
to existing instruction files, and wire 5 existing ADO prompts through
the ADO Backlog Manager agent via `agent:` frontmatter.

Part of the ADO Backlog Manager feature set (4 of 5 PRs).

## Related Issue(s)

Closes #779

## 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:**
> Discover unplanned work items in our ADO project based on recent code
changes.

**Execution Flow:**
1. Discovery prompt triggers with project context and discovery path
(user-centric, artifact-driven, or search-based)
2. Instruction file guides work item discovery via MCP ADO tools
3. Planning files written to `.copilot-tracking/workitems/discovery/`
4. Agent routing connects to ADO Backlog Manager for orchestration

**Output Artifacts:**
Discovery planning files in `.copilot-tracking/workitems/discovery/`
containing discovered work items with field recommendations and
similarity analysis.

**Success Indicators:**
- Discovery prompt routes through ADO Backlog Manager agent
- Existing prompts gain `agent:` frontmatter for Backlog Manager routing
- contentFormat input available on prompts that generate ADO content

## Testing

- Verified `npm run plugin:generate` succeeds with new collection
entries
- Confirmed frontmatter structure follows existing ADO prompt patterns
- Validated existing prompt modifications preserve backward
compatibility

## 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) for shared autonomy model and format
detection infrastructure
- 5 existing prompts modified only to add `agent: ADO Backlog Manager`
frontmatter and contentFormat inputs — no behavioral changes
- Collection entries added to both `ado` and `hve-core-all` collections

Co-authored-by: Bill Berry <wberry@microsoft.com>

Author: chaosdinosaur

.github/instructions/ado/ado-wit-discovery.instructions.md

@@ -5,6 +5,8 @@ applyTo: '**/.copilot-tracking/workitems/discovery/**'
 
 # Azure DevOps Work Item Discovery
 
+When invoked via the ADO Backlog Manager, honor the active autonomy mode from the [Three-Tier Autonomy Model](./ado-wit-planning.instructions.md#three-tier-autonomy-model) for operations that create or modify planning files.
+
 Discover Azure DevOps work items through two paths: user-centric queries ("show me my work items") or artifact-driven analysis (documents, branches, commits). Follow #file:ado-wit-planning.instructions.md for templates, field definitions, and search protocols.
 
 ## Scope

.github/prompts/ado/ado-add-work-item.prompt.md

@@ -0,0 +1,93 @@
+---
+description: "Create a single Azure DevOps work item with conversational field collection and parent validation"
+agent: ADO Backlog Manager
+argument-hint: "project=... [type={Epic|Feature|UserStory|Bug|Task}] [title=...]"
+---
+
+# Add ADO Work Item
+
+Create a single work item through conversational field collection, validate parent hierarchy, and log the result. Use interaction templates from #file:../../instructions/ado/ado-interaction-templates.instructions.md for description formatting.
+
+Follow all instructions from #file:../../instructions/ado/ado-wit-planning.instructions.md for field definitions and shared conventions.
+Follow all instructions from #file:../../instructions/ado/ado-interaction-templates.instructions.md for work item description and comment templates.
+
+## Inputs
+
+* `${input:project}`: (Required) Azure DevOps project name.
+* `${input:type}`: (Optional) Work item type: Epic, Feature, User Story, Bug, Task. When not provided, present options during field collection.
+* `${input:title}`: (Optional) Work item title. When not provided, prompt during field collection.
+* `${input:parentId}`: (Optional) Parent work item ID for hierarchy linking.
+* `${input:areaPath}`: (Optional) Area Path for the new work item.
+* `${input:iterationPath}`: (Optional) Iteration Path for the new work item.
+* `${input:contentFormat:Markdown}`: (Optional) Content format for rich-text fields. Use `Markdown` for Azure DevOps Services (dev.azure.com) or `Html` for Azure DevOps Server (on-premises). Defaults to Markdown.
+
+## Required Steps
+
+The workflow proceeds through five steps: resolve project context, select work item type, collect fields conversationally, validate parent hierarchy, then create the work item and log the result.
+
+### Step 1: Resolve Project Context
+
+Establish the target project and verify access before proceeding.
+
+1. Call `mcp_ado_core_get_identity_ids` to establish authenticated user context.
+2. Verify `${input:project}` is accessible. When inaccessible, report the error and prompt for correction.
+3. When `${input:areaPath}` or `${input:iterationPath}` is not provided, retrieve available paths via `mcp_ado_work_list_team_iterations` or similar retrieval calls for context.
+
+### Step 2: Select Work Item Type
+
+Determine the work item type for creation.
+
+1. When `${input:type}` matches a valid type (Epic, Feature, User Story, Bug, Task), use it directly.
+2. When `${input:type}` is not provided, present the available types and ask the user to select one.
+3. Record the selected type for field collection in the next step.
+
+### Step 3: Collect Fields
+
+Gather field values through conversation using the interaction template for the selected work item type.
+
+1. When `${input:title}` is not provided, prompt the user for a title.
+2. Collect the description using the appropriate interaction template format for the selected type. Select the Markdown or HTML template variant from #file:../../instructions/ado/ado-interaction-templates.instructions.md based on `${input:contentFormat}`.
+3. For optional fields not provided through inputs (Priority, Severity for bugs, Tags, Assigned To), ask the user whether they want to supply values.
+4. Merge provided inputs with conversationally collected values.
+
+### Step 4: Validate Parent Hierarchy
+
+Verify parent-child relationships are valid before creation.
+
+1. When `${input:parentId}` is provided, fetch the parent work item via `mcp_ado_wit_get_work_item` and verify the hierarchy is valid:
+   * Features require an Epic parent.
+   * User Stories require a Feature parent.
+   * Tasks and Bugs can be children of User Stories or Features.
+2. When the hierarchy is invalid, warn the user and suggest corrections or alternative parent items.
+3. When `${input:parentId}` is not provided and the selected type is Feature, User Story, Task, or Bug, ask the user if they want to link to a parent item.
+
+### Step 5: Create and Log
+
+Submit the work item to Azure DevOps and record the result.
+
+1. When `${input:parentId}` is provided and valid, call `mcp_ado_wit_add_child_work_items` to create the item as a child of the parent.
+2. When no parent is specified, call `mcp_ado_wit_create_work_item` with the collected fields (title, description, type, Area Path, Iteration Path, Priority, Tags, and any additional fields). Set the `format` parameter to `${input:contentFormat}` for Description, Acceptance Criteria, and Repro Steps fields.
+3. On success, extract the work item ID and URL from the response and confirm creation with the user.
+4. Create or append to a tracking artifact in `.copilot-tracking/workitems/execution/{{YYYY-MM-DD}}/` with the work item ID, URL, type, title, applied fields, and parent relationship.
+5. On failure, report the error and suggest corrections or a retry.
+
+## Success Criteria
+
+* Project context is resolved and access is verified before field collection.
+* The work item type is selected before collecting type-specific fields.
+* Required fields are validated before creation.
+* Parent hierarchy is validated when a parent ID is provided.
+* The work item is created with correct metadata and interaction template formatting matching `${input:contentFormat}`.
+* A tracking artifact exists in `.copilot-tracking/workitems/execution/{{YYYY-MM-DD}}/`.
+
+## Error Handling
+
+* Project inaccessible: display the error and prompt for correction.
+* Invalid parent hierarchy: warn the user and suggest valid parent options.
+* Required field missing after prompting: re-prompt until a value is provided.
+* Creation failure: display the error message and suggest corrections.
+* Parent work item not found: inform the user and offer to proceed without linking.
+
+---
+
+Proceed with creating the Azure DevOps work item following the Required Steps.

.github/prompts/ado/ado-create-pull-request.prompt.md

@@ -1,5 +1,6 @@
 ---
 description: "Generate pull request description, discover related work items, identify reviewers, and create Azure DevOps pull request with all linkages."
+agent: ADO Backlog Manager
 ---
 
 # Create Azure DevOps Pull Request with Work Item & Reviewer Discovery

.github/prompts/ado/ado-discover-work-items.prompt.md

@@ -0,0 +1,35 @@
+---
+description: "Discover Azure DevOps work items through user-centric queries, artifact-driven analysis, or search-based exploration"
+agent: ADO Backlog Manager
+argument-hint: "project=... [documents=...] [searchTerms=...]"
+---
+
+# Discover ADO Work Items
+
+Classify the discovery path based on user intent, execute the appropriate discovery workflow, assess similarity against existing work items, and produce planning files. Three discovery paths are supported: user-centric queries (Path A), artifact-driven analysis from documents (Path B), and search-based exploration (Path C).
+
+Follow all instructions from #file:../../instructions/ado/ado-wit-discovery.instructions.md while executing this workflow.
+Follow all instructions from #file:../../instructions/ado/ado-wit-planning.instructions.md for shared conventions, planning file templates, and field definitions.
+
+## Inputs
+
+* `${input:project}`: (Required) Azure DevOps project name.
+* `${input:documents}`: (Optional) Document paths for artifact-driven analysis. Triggers Path B when provided.
+* `${input:searchTerms}`: (Optional) Keywords for search-based discovery. Triggers Path C when provided without documents.
+* `${input:areaPath}`: (Optional) Area Path filter to scope discovery.
+* `${input:iterationPath}`: (Optional) Iteration Path filter to scope discovery.
+* `${input:autonomy:partial}`: (Optional, defaults to partial) Autonomy tier controlling confirmation gates during handoff review. Values: `full`, `partial`, `manual`.
+* `${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.
+
+## Requirements
+
+* Classify the discovery path before executing any searches or document parsing.
+* Scope all searches to `${input:project}` and apply `${input:areaPath}` and `${input:iterationPath}` filters when provided.
+* Path B produces planning artifacts in `.copilot-tracking/workitems/discovery/{{scope-name}}/` including *artifact-analysis.md*, *work-items.md*, and *handoff.md*. Use `${input:contentFormat}` for fenced code block annotations in *work-items.md* multi-line field values. When input contains formal PRD or requirements documents, the orchestrator routes to `AzDO PRD to WIT` instead of this path.
+* Paths A and C produce a *planning-log.md* and a conversational summary without creating a handoff.
+* Discovery does not execute work item operations. The handoff is presented for review before any execution occurs.
+* When neither documents nor search terms are provided and user intent is unclear, ask for clarification before proceeding.
+
+---
+
+Proceed with discovering Azure DevOps work items following the discovery workflow instructions.

.github/prompts/ado/ado-get-build-info.prompt.md

@@ -1,5 +1,6 @@
 ---
 description: "Retrieve Azure DevOps build information for a Pull Request or specific Build Number."
+agent: ADO Backlog Manager
 ---
 
 # ADO Build Info & Log Extraction (Targeted or Latest PR Build)

.github/prompts/ado/ado-get-my-work-items.prompt.md

@@ -1,5 +1,6 @@
 ---
 description: "Retrieve user's current Azure DevOps work items and organize them into planning file definitions"
+agent: ADO Backlog Manager
 ---
 
 # Get My Work Items and Create Planning Files
@@ -8,19 +9,6 @@ Follow all instructions from #file:../../instructions/ado/ado-wit-planning.instr
 
 You WILL retrieve all work items assigned to the current user (`@Me`) within the specified Azure DevOps project using Azure DevOps tools, then organize them into the standardized planning file structure. This creates a foundation for future work item planning and execution.
 
-## General User Conversation Guidance
-
-Keep the user up-to-date while processing work items.
-
-Follow these guidelines whenever interacting with the user through conversation:
-
-* Utilize markdown styling whenever interacting with the user.
-* Provide double newlines for each paragraph or new section.
-* Use bolding for title words and italics for emphasis.
-* For all unordered lists use markdown `*` instead of only using newlines.
-* Use emojis to help get your point across.
-* Avoid giving the user an overwhelming amount of information.
-
 ## Inputs
 
 * ${input:project}: (Required) Azure DevOps project name or ID
@@ -29,6 +17,7 @@ Follow these guidelines whenever interacting with the user through conversation:
 * ${input:types:Bug, Task, User Story}: Comma-separated Work Item Types to fetch (case-insensitive). Default: Bug, Task, User Story.
 * ${input:states:Active, New, Resolved}: (Optional) Comma-separated workflow states to include. Default: Active, New, Resolved.
 * ${input:planningType:current-work}: Planning type for organizing retrieved work items. Default: current-work.
+* `${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.
 
 ## 1. Required Protocol
 

.github/prompts/ado/ado-process-my-work-items-for-task-planning.prompt.md

@@ -1,5 +1,6 @@
 ---
 description: "Process retrieved work items for task planning and generate task-planning-logs.md handoff file"
+agent: ADO Backlog Manager
 ---
 
 # Process My Work Items for Task Planning
@@ -8,19 +9,6 @@ Follow all instructions from #file:../../instructions/ado/ado-wit-planning.instr
 
 You WILL process work items from the planning file structure created by `ado-get-my-work-items.prompt.md` and generate a comprehensive task planning handoff file. This creates enriched work item documentation ready for task research and detailed implementation planning.
 
-## General User Conversation Guidance
-
-Keep the user up-to-date while processing work items.
-
-Follow these guidelines whenever interacting with the user through conversation:
-
-* Utilize markdown styling whenever interacting with the user.
-* Provide double newlines for each paragraph or new section.
-* Use bolding for title words and italics for emphasis.
-* For all unordered lists use markdown `*` instead of only using newlines.
-* Use emojis to help get your point across.
-* Avoid giving the user an overwhelming amount of information.
-
 ## Inputs
 
 * ${input:planningDir:`.copilot-tracking/workitems/current-work/my-assigned-work-items/`}: (Required) Path to planning directory containing work-items.md

.github/prompts/ado/ado-update-wit-items.prompt.md

@@ -1,5 +1,6 @@
 ---
 description: "Prompt to update work items based on planning files"
+agent: ADO Backlog Manager
 ---
 
 # Update Work Items
@@ -12,6 +13,7 @@ Follow all instructions from #file:../../instructions/ado/ado-update-wit-items.i
 * ${input:project}: (Optional) Override ADO work item project name
 * ${input:areaPath}: (Optional) Override area path
 * ${input:iterationPath}: (Optional) Override iteration path
+* `${input:contentFormat:Markdown}`: (Optional) Content format for rich-text fields. Use `Markdown` for Azure DevOps Services (dev.azure.com) or `Html` for Azure DevOps Server (on-premises). Defaults to Markdown.
 * ${input:dryRun:false}: Preview operations without making mcp ado tool calls
 
 ---

collections/ado.collection.yml

@@ -22,6 +22,10 @@ items:
     kind: prompt
   - path: .github/prompts/ado/ado-update-wit-items.prompt.md
     kind: prompt
+  - path: .github/prompts/ado/ado-add-work-item.prompt.md
+    kind: prompt
+  - path: .github/prompts/ado/ado-discover-work-items.prompt.md
+    kind: prompt
   - path: .github/prompts/ado/ado-sprint-plan.prompt.md
     kind: prompt
   - path: .github/prompts/ado/ado-triage-work-items.prompt.md

collections/hve-core-all.collection.yml

@@ -80,8 +80,12 @@ items:
   kind: agent
 - path: .github/agents/security-planning/security-plan-creator.agent.md
   kind: agent
+- path: .github/prompts/ado/ado-add-work-item.prompt.md
+  kind: prompt
 - path: .github/prompts/ado/ado-create-pull-request.prompt.md
   kind: prompt
+- path: .github/prompts/ado/ado-discover-work-items.prompt.md
+  kind: prompt
 - path: .github/prompts/ado/ado-get-build-info.prompt.md
   kind: prompt
 - path: .github/prompts/ado/ado-get-my-work-items.prompt.md