-
Notifications
You must be signed in to change notification settings - Fork 47
docs(agents): add GitHub Backlog Manager documentation and agent catalog #503
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
WilliamBerryiii
merged 7 commits into
main
from
docs/478-github-backlog-manager-documentation
Feb 13, 2026
+945
−1
Merged
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
9b8bba6
docs(agents): add GitHub Backlog Manager documentation and agent catalog
WilliamBerryiii e43bde2
docs(agents): correct tracking directory paths to match planning conv…
WilliamBerryiii b322526
Merge branch 'main' into docs/478-github-backlog-manager-documentation
WilliamBerryiii 9ee4ae3
style(agents): fix table column alignment in using-together lifecycle…
WilliamBerryiii f876f8f
Merge branch 'main' into docs/478-github-backlog-manager-documentation
WilliamBerryiii 0f9bca2
docs(docs): address PR review comments on backlog manager documentation
WilliamBerryiii d4d7dcf
Merge branch 'main' into docs/478-github-backlog-manager-documentation
WilliamBerryiii File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Some comments aren't visible on the classic Files Changed page.
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| --- | ||
| title: Agent Systems Catalog | ||
| description: Overview of all hve-core agent systems with workflow documentation and quick links | ||
| author: Microsoft | ||
| ms.date: 2026-02-12 | ||
| ms.topic: overview | ||
| keywords: | ||
| - github copilot | ||
| - agents | ||
| - agent catalog | ||
| estimated_reading_time: 5 | ||
| --- | ||
|
|
||
| hve-core organizes specialized agents into functional groups. Each group combines agents, prompts, and instruction files into cohesive workflows for specific engineering tasks. | ||
|
|
||
| | Group | Agents | Complexity | Documentation | | ||
| |---------------------------|----------|-------------|---------------------------------------------| | ||
| | RPI Orchestration | 5 | High | [RPI Documentation](../rpi/README.md) | | ||
| | GitHub Backlog Management | 1 active | Very High | [Backlog Manager](github-backlog/README.md) | | ||
| | ADO Integration | 1 | Medium-High | Planned | | ||
| | Document Builders | 4 | Medium-High | Planned | | ||
| | Data Pipeline | 4 | Medium | Planned | | ||
| | DevOps Quality | 2 | High | Planned | | ||
| | Meta/Engineering | 1 | High | Planned | | ||
| | Infrastructure | 1 | Very High | Planned | | ||
| | Utility | 1 | Low-Medium | Planned | | ||
|
|
||
| ## RPI Orchestration | ||
|
|
||
| The Research, Plan, Implement methodology separates complex tasks into specialized phases. Five agents (task-researcher, task-planner, task-implementor, task-reviewer, and the RPI orchestrator) coordinate through planning files to deliver structured engineering workflows. See the [RPI Documentation](../rpi/README.md) for the full guide. | ||
|
|
||
| ## GitHub Backlog Management | ||
|
|
||
| Automates issue discovery, triage, sprint planning, and execution across GitHub repositories. The backlog manager agent orchestrates five distinct workflows with three-tier autonomy control. See the [Backlog Manager Documentation](github-backlog/README.md) for workflow guides. | ||
|
|
||
| ## ADO Integration | ||
|
|
||
| Bridges Azure DevOps work items with local Copilot workflows. The ADO integration agent handles work item discovery, planning file creation, pull request generation, and build status monitoring. | ||
|
|
||
| ## Document Builders | ||
|
|
||
| Four specialized agents for creating structured documents. Includes builders for Architecture Decision Records, Business Requirements Documents, Product Requirements Documents, and security plans. | ||
|
|
||
| ## Data Pipeline | ||
|
|
||
| Processes and transforms data across formats and systems. Four agents handle data extraction, transformation, validation, and loading workflows. | ||
|
|
||
| ## DevOps Quality | ||
|
|
||
| Two agents focused on code quality and deployment reliability. Covers PR review automation and build pipeline analysis. | ||
WilliamBerryiii marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## Meta/Engineering | ||
|
|
||
| The prompt builder agent creates and validates prompt engineering artifacts. Supports interactive authoring with sandbox testing for prompts, instructions, agents, and skills. | ||
|
|
||
| ## Infrastructure | ||
|
|
||
| Manages cloud infrastructure provisioning and configuration. Handles Bicep and Terraform deployments with validation and drift detection. | ||
|
|
||
| ## Utility | ||
|
|
||
| General-purpose agents for common development tasks such as file organization, content transformation, and small automation helpers. | ||
|
|
||
| --- | ||
|
|
||
| <!-- markdownlint-disable MD036 --> | ||
| *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, | ||
| then carefully refined by our team of discerning human reviewers.* | ||
| <!-- markdownlint-enable MD036 --> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,112 @@ | ||
| --- | ||
| title: GitHub Backlog Manager | ||
| description: Automated issue discovery, triage, sprint planning, and execution for GitHub repositories | ||
| author: Microsoft | ||
| ms.date: 2026-02-12 | ||
| ms.topic: concept | ||
| keywords: | ||
| - github backlog manager | ||
| - issue management | ||
| - triage | ||
| - sprint planning | ||
| - github copilot | ||
| estimated_reading_time: 5 | ||
| --- | ||
|
|
||
| The GitHub Backlog Manager automates issue lifecycle management across GitHub repositories. It coordinates five specialized workflows (discovery, triage, sprint planning, execution, and quick add) through planning files and handoff artifacts, applying consistent labels, detecting duplicates, and organizing issues into milestones with configurable autonomy levels. | ||
|
|
||
| > Backlog management is a constraint-satisfaction problem. Each workflow handles a bounded scope, reducing errors by limiting the decisions any single step makes. | ||
|
|
||
| ## Why Use the Backlog Manager? | ||
|
|
||
| * 🏷️ Consistency: Every issue receives labels, priority, and milestone assignment following the same taxonomy, eliminating drift across contributors | ||
| * 🔍 Visibility: Discovery workflows surface issues from code changes, team assignments, and cross-repository searches, so nothing falls through gaps | ||
| * ⚡ Throughput: Automated triage and sprint planning handle repetitive decisions, freeing your team for engineering work | ||
WilliamBerryiii marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| > [!TIP] | ||
| > For the full rationale and quality comparison, see [Why the Backlog Manager Works](why-backlog-manager.md). | ||
|
|
||
| ## The Five Workflows | ||
|
|
||
| ### 🔍 Discovery | ||
|
|
||
| Discovery finds and categorizes issues from multiple sources. Three discovery paths cover different starting points: user-centric (assigned issues), artifact-driven (local code changes mapped to backlog items), and search-based (criteria-driven queries across repositories). Discovery produces issue analysis files that feed into triage. | ||
|
|
||
| See the [Discovery workflow guide](discovery.md) for paths, artifacts, and examples. | ||
|
|
||
| ### 🏷️ Triage | ||
|
|
||
| Triage assigns labels, assesses priority, and detects duplicates for discovered issues. It applies a 17-label taxonomy organized by type, area, priority, and lifecycle categories. Conventional commit patterns in issue titles inform label suggestions. A four-aspect similarity framework flags potential duplicates before they create noise. | ||
WilliamBerryiii marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| See the [Triage workflow guide](triage.md) for the label taxonomy and duplicate detection. | ||
|
|
||
| ### 📋 Sprint Planning | ||
|
|
||
| Sprint planning organizes triaged issues into milestones with capacity awareness. A six-step milestone discovery process matches issues to existing or new milestones. The workflow assesses issue volume against team capacity and recommends distribution across sprints. | ||
|
|
||
| See the [Sprint Planning workflow guide](sprint-planning.md) for milestone discovery and capacity planning. | ||
|
|
||
| ### ⚡ Execution | ||
|
|
||
| Execution consumes handoff files produced by earlier workflows and performs the planned operations. It creates, updates, and closes issues according to the plan, tracking each operation with checkbox-based progress and per-operation logging. Failed operations log errors without blocking the rest of the batch. | ||
|
|
||
| See the [Execution workflow guide](execution.md) for handoff consumption and operation logging. | ||
|
|
||
| ### ➕ Quick Add | ||
|
|
||
| Quick Add is a single-issue shortcut for creating one issue without running the full pipeline. Use it when you need to file an issue quickly and apply standard labels and milestone in a single step. | ||
|
|
||
| ## Autonomy Levels | ||
|
|
||
| The backlog manager operates at three autonomy tiers, controlling which operations proceed automatically and which pause for approval. | ||
|
|
||
| | Tier | Create | Labels/Milestone | Close | Comment | | ||
| |-------------------|--------|------------------|-------|---------| | ||
| | Full | Auto | Auto | Auto | Auto | | ||
| | Partial (default) | Gate | Auto | Gate | Auto | | ||
| | Manual | Gate | Gate | Gate | Gate | | ||
|
|
||
| Partial autonomy is the default, applying labels and milestones automatically while gating issue creation and closure for review. Adjust the tier based on repository maturity and team trust. | ||
|
|
||
| ## When to Use | ||
|
|
||
| | Use Backlog Manager When... | Use Manual Management When... | | ||
| |-------------------------------------------------|-------------------------------------------| | ||
| | Managing more than 20 open issues | Working with fewer than 10 issues | | ||
| | Multiple contributors need consistent triage | Single maintainer with full context | | ||
| | Sprint planning requires milestone organization | No milestone-based planning process | | ||
| | Cross-repository issue discovery is needed | All issues originate from a single source | | ||
| | Label consistency matters for reporting | Ad-hoc labeling suits the workflow | | ||
|
|
||
| ## Quick Start | ||
|
|
||
| 1. Configure your MCP servers following the [MCP Configuration guide](../../getting-started/mcp-configuration.md) | ||
| 2. Open a Copilot Chat session and type: `Discover open issues assigned to me` | ||
| 3. Review the discovery output, then type `/clear` and start a triage session | ||
| 4. Continue through sprint planning and execution as needed | ||
|
|
||
| > [!IMPORTANT] | ||
| > Clear context between workflows by typing `/clear`. Each workflow operates independently and mixing contexts produces unreliable results. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| The GitHub Backlog Manager requires MCP server configuration for GitHub API access. See [MCP Configuration](../../getting-started/mcp-configuration.md) for setup instructions. The GitHub MCP tools (listed in the agent specification) must be available in your VS Code context. | ||
|
|
||
| > [!NOTE] | ||
| > The GitHub Backlog Manager replaces the deprecated `github-issue-manager` agent. If you have prompts or workflows referencing `github-issue-manager`, update them to use `github-backlog-manager` instead. | ||
|
|
||
| ## Next Steps | ||
|
|
||
| * [Discovery](discovery.md) - Find and categorize issues from multiple sources | ||
| * [Triage](triage.md) - Assign labels, priorities, and detect duplicates | ||
| * [Sprint Planning](sprint-planning.md) - Organize issues into milestones | ||
| * [Execution](execution.md) - Execute planned operations from handoff files | ||
| * [Using Workflows Together](using-together.md) - End-to-end pipeline walkthrough | ||
| * [Why the Backlog Manager Works](why-backlog-manager.md) - Design rationale and quality comparison | ||
|
|
||
| --- | ||
|
|
||
| <!-- markdownlint-disable MD036 --> | ||
| *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, | ||
| then carefully refined by our team of discerning human reviewers.* | ||
| <!-- markdownlint-enable MD036 --> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,126 @@ | ||
| --- | ||
| title: Discovery Workflow | ||
| description: Discover and categorize GitHub issues through user-centric, artifact-driven, and search-based paths | ||
| author: Microsoft | ||
| ms.date: 2026-02-12 | ||
| ms.topic: tutorial | ||
| keywords: | ||
| - github backlog manager | ||
| - issue discovery | ||
| - github copilot | ||
| estimated_reading_time: 5 | ||
| --- | ||
|
|
||
| The Discovery workflow finds and categorizes GitHub issues from multiple sources, producing structured analysis files that feed into triage and planning. | ||
|
|
||
| ## When to Use | ||
|
|
||
| * 🆕 Starting a new sprint and need to survey open issues across repositories | ||
| * 👤 Reviewing issues assigned to you or your team before a planning session | ||
| * 🔀 Code changes on a feature branch that may relate to existing backlog items | ||
| * 🔍 Searching for issues matching specific criteria across multiple repositories | ||
|
|
||
| ## What It Does | ||
|
|
||
| 1. Identifies issues through one of three discovery paths (user-centric, artifact-driven, or search-based) | ||
| 2. Retrieves issue metadata including labels, assignees, milestones, and linked pull requests | ||
| 3. Categorizes issues by type, area, and current state | ||
| 4. Produces structured analysis files with issue summaries and recommendations | ||
| 5. Flags issues that may need triage attention (unlabeled, stale, or assigned incorrectly) | ||
|
|
||
| > [!NOTE] | ||
| > Discovery is deliberately separated from triage. Finding issues and deciding what to do with them are different cognitive tasks. Running them in a single pass increases the chance of misclassification. | ||
|
|
||
| ## The Three Discovery Paths | ||
|
|
||
| ### User-Centric Discovery | ||
|
|
||
| Finds issues assigned to a specific user or team. This path is ideal for sprint preparation, where you need to see your current backlog before planning new work. The workflow queries GitHub for issues by assignee, filters by state, and organizes results by repository and milestone. | ||
|
|
||
| ### Artifact-Driven Discovery | ||
|
|
||
| Analyzes local code changes (branches, commits, modified files) and maps them to existing backlog items. This path surfaces issues related to your current work, helping you avoid duplicate effort and identify issues your changes may resolve. The workflow reads git diff output and searches for matching issues by file path, keyword, and component area. | ||
|
|
||
| ### Search-Based Discovery | ||
|
|
||
| Queries across repositories using criteria you define: labels, keywords, date ranges, milestone association, or any combination. This path handles broad inventory tasks, such as finding all unlabeled issues, all issues older than 90 days, or all issues in a specific area across multiple repositories. | ||
|
|
||
| ## Output Artifacts | ||
|
|
||
| ```text | ||
| .copilot-tracking/github-issues/discovery/<scope-name>/ | ||
| ├── issue-analysis.md # Categorized issue inventory with metadata | ||
| ├── issues-plan.md # Recommended actions for discovered issues | ||
| └── planning-log.md # Discovery session log with search queries used | ||
| ``` | ||
|
|
||
| Discovery writes its output to the `.copilot-tracking/github-issues/discovery/` directory. The scope name reflects the discovery target (a username, repository, or search description). These files serve as input for the triage workflow. | ||
|
|
||
| ## How to Use | ||
|
|
||
| ### Option 1: Prompt Shortcut | ||
|
|
||
| Use the backlog manager prompts to start a discovery session: | ||
|
|
||
| ```text | ||
| Discover open issues assigned to me in microsoft/hve-core | ||
| ``` | ||
|
|
||
| ```text | ||
| Find issues related to my current branch changes | ||
| ``` | ||
|
|
||
| ```text | ||
| Search for unlabeled issues across all repositories in our organization | ||
| ``` | ||
|
|
||
| ### Option 2: Direct Agent | ||
|
|
||
| Start a conversation with the GitHub Backlog Manager agent and describe your discovery goal. The agent classifies your intent and dispatches the appropriate discovery path automatically. | ||
|
|
||
| ## Example Prompt | ||
|
|
||
| ```text | ||
| Discover open issues assigned to me in microsoft/hve-core that don't have | ||
| a milestone. Include any issues labeled "needs-triage" regardless of assignee. | ||
| ``` | ||
|
|
||
| ## Tips | ||
|
|
||
| ✅ Do: | ||
|
|
||
| * Scope discovery to a specific repository or user to keep results manageable | ||
| * Run discovery before triage to ensure you have a complete picture | ||
| * Use artifact-driven discovery when working on a feature branch to find related issues | ||
| * Review the planning log to understand what queries produced the results | ||
|
|
||
| ❌ Don't: | ||
|
|
||
| * Combine discovery with triage in a single session (clear context between workflows) | ||
| * Run discovery across an entire organization without filters (results become unwieldy) | ||
| * Skip reviewing the issue analysis before proceeding to triage | ||
| * Assume discovery catches everything on the first pass (iterate if needed) | ||
|
|
||
| ## Common Pitfalls | ||
|
|
||
| | Pitfall | Solution | | ||
| |------------------------------------------|-----------------------------------------------------------------------| | ||
| | Too many results to review | Narrow the scope with repository, label, or date filters | | ||
| | Missing issues from private repositories | Verify MCP token has access to the target repositories | | ||
| | Stale results from cached queries | Clear context and re-run discovery for fresh API results | | ||
| | Artifact-driven path finds no matches | Ensure your branch has committed changes (unstaged files are skipped) | | ||
|
|
||
| ## Next Steps | ||
|
|
||
| 1. Send your discovery output through the [Triage workflow](triage.md) to assign labels and priorities | ||
| 2. See [Using Workflows Together](using-together.md) for the full pipeline walkthrough | ||
|
|
||
| > [!TIP] | ||
| > Run `/clear` between discovery and triage. Each workflow reads its own planning files and mixing session context produces unreliable label suggestions. | ||
|
|
||
| --- | ||
|
|
||
| <!-- markdownlint-disable MD036 --> | ||
| *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, | ||
| then carefully refined by our team of discerning human reviewers.* | ||
| <!-- markdownlint-enable MD036 --> |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.