diff --git a/docs/README.md b/docs/README.md index 49ca0afe..81c7cc7c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,7 +6,7 @@ ms.date: 2026-01-22 ms.topic: overview --- -HVE Core is an enterprise-ready prompt engineering framework for GitHub Copilot. It provides 18 specialized agents, 18 reusable prompts, 17+ instruction sets, and a validation pipeline with JSON schema enforcement. The framework separates AI concerns into distinct artifact types with clear boundaries, preventing runaway behavior through constraint-based design. +HVE Core is an enterprise-ready prompt engineering framework for GitHub Copilot. It provides specialized agents, reusable prompts, instruction sets, and a validation pipeline with JSON schema enforcement. The framework separates AI concerns into distinct artifact types with clear boundaries, preventing runaway behavior through constraint-based design. ## Audience @@ -29,6 +29,18 @@ The Getting Started guide walks through installation, configuration, and running **[Getting Started Guide โ†’](getting-started/README.md)** +## Agent Systems + +**Time to complete**: 10-15 minutes + +hve-core provides specialized agents organized into functional groups. Each group combines agents, prompts, and instruction files into cohesive workflows for specific engineering tasks. + +* [RPI Orchestration](rpi/README.md) separates complex tasks into research, planning, implementation, and review phases +* [GitHub Backlog Manager](agents/github-backlog/README.md) automates issue discovery, triage, sprint planning, and execution across GitHub repositories +* Additional systems documented in the [Agent Catalog](agents/README.md) + +**[Browse the Agent Catalog โ†’](agents/README.md)** + ## RPI Methodology **Time to complete**: 20-40 minutes diff --git a/docs/agents/README.md b/docs/agents/README.md new file mode 100644 index 00000000..1edf0f02 --- /dev/null +++ b/docs/agents/README.md @@ -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. + +## 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. + +--- + + +*๐Ÿค– Crafted with precision by โœจCopilot following brilliant human instruction, +then carefully refined by our team of discerning human reviewers.* + diff --git a/docs/agents/github-backlog/README.md b/docs/agents/github-backlog/README.md new file mode 100644 index 00000000..61b90873 --- /dev/null +++ b/docs/agents/github-backlog/README.md @@ -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 + +> [!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. + +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 + +--- + + +*๐Ÿค– Crafted with precision by โœจCopilot following brilliant human instruction, +then carefully refined by our team of discerning human reviewers.* + diff --git a/docs/agents/github-backlog/discovery.md b/docs/agents/github-backlog/discovery.md new file mode 100644 index 00000000..09902b91 --- /dev/null +++ b/docs/agents/github-backlog/discovery.md @@ -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// +โ”œโ”€โ”€ 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. + +--- + + +*๐Ÿค– Crafted with precision by โœจCopilot following brilliant human instruction, +then carefully refined by our team of discerning human reviewers.* + diff --git a/docs/agents/github-backlog/execution.md b/docs/agents/github-backlog/execution.md new file mode 100644 index 00000000..8f59d747 --- /dev/null +++ b/docs/agents/github-backlog/execution.md @@ -0,0 +1,131 @@ +--- +title: Execution Workflow +description: Apply triage and planning recommendations to GitHub issues through structured handoff consumption +author: Microsoft +ms.date: 2026-02-12 +ms.topic: tutorial +keywords: + - github backlog manager + - issue execution + - handoff + - github copilot +estimated_reading_time: 5 +--- + +The Execution workflow consumes handoff files from triage and sprint planning, applying approved changes to GitHub issues. It tracks progress through checkbox-based handoff logs and produces operation reports for audit and recovery. + +## When to Use + +* โœ… Triage or sprint planning handoff files are ready for application +* ๐Ÿท๏ธ Applying label changes, milestone assignments, or issue closures in bulk +* ๐Ÿ”— Linking duplicate issues and closing the redundant copies +* ๐Ÿ“ Updating issue metadata across multiple issues in a single session + +## What It Does + +1. Reads handoff files from triage or sprint planning workflows +2. Validates each recommended operation against current issue state +3. Applies approved changes (labels, milestones, closures, comments) via GitHub MCP tools +4. Marks each handoff checkbox as complete after successful application +5. Produces an operation log documenting what changed and what was skipped + +> [!NOTE] +> Execution only processes checked items in the handoff file. Uncheck any recommendation you want to skip before starting the execution workflow. + +## Handoff Consumption + +The execution workflow uses checkbox-based progress tracking in handoff files: + +```markdown +## Pending Operations + +- [x] #42 - Add label: bug (applied) +- [x] #42 - Assign milestone: v2.1 (applied) +- [ ] #57 - Close as duplicate of #42 (skipped - unchecked) +- [x] #63 - Add label: documentation (applied) +``` + +Each line represents one atomic operation. The workflow processes checked items sequentially, validating current issue state before each change. If an issue has been modified since triage (new labels added, milestone changed, issue closed), the workflow flags the conflict and skips that operation rather than overwriting recent changes. + +## Operation Logging + +Every execution session produces a structured log: + +* Operations attempted with timestamps +* Success and failure counts with error details +* Issues skipped due to state conflicts +* API rate limit status at session end + +This log supports recovery when execution is interrupted. Re-running execution on the same handoff file picks up where it left off because completed items are already checked. + +## Output Artifacts + +```text +.copilot-tracking/github-issues/// +โ””โ”€โ”€ handoff-logs.md # Per-operation processing status (created next to consumed handoff) +``` + +The consumed handoff file is updated in place as operations complete, marking checkboxes for processed items. The handoff log records per-operation results with processing status, supporting recovery when execution is interrupted. + +## How to Use + +### Option 1: Prompt Shortcut + +```text +Execute the triage handoff for microsoft/hve-core +``` + +```text +Apply sprint planning assignments from my latest planning session +``` + +### Option 2: Direct Agent + +Attach or reference the handoff file when starting an execution conversation. The agent reads the pending operations and begins processing checked items. + +## Example Prompt + +```text +Execute the triage handoff at .copilot-tracking/github-issues/triage/2026-02-10/triage-plan.md. +Skip any operations on issues that have been updated in the last 24 hours. +``` + +## Tips + +โœ… Do: + +* Review handoff files before execution and uncheck operations you want to skip +* Run execution in a clean session (use `/clear` after triage or planning) +* Check the operation log after execution to verify all changes applied correctly +* Re-run execution if interrupted; completed checkboxes prevent duplicate operations + +โŒ Don't: + +* Execute handoffs without reviewing the recommendations first +* Modify the checkbox format in handoff files (the workflow depends on the `- [ ]` / `- [x]` syntax) +* Run execution while other team members are actively editing the same issues +* Combine triage and planning handoffs in a single execution session + +## Common Pitfalls + +| Pitfall | Solution | +|--------------------------------------|--------------------------------------------------------------------------| +| Autonomy level mismatches | Set the expected autonomy level before execution (full, partial, manual) | +| Stale handoff data | Re-run discovery and triage if the handoff is more than a few days old | +| Partial execution after interruption | Re-run execution on the same handoff; completed items are skipped | +| Rate limiting during bulk operations | The workflow pauses automatically and resumes; check the operation log | + +## Next Steps + +1. Review the execution log for any skipped operations or conflicts +2. See [Using Workflows Together](using-together.md) for iterating through the full pipeline after execution + +> [!TIP] +> For large handoffs with many operations, consider executing in batches by checking only a subset of items at a time. This makes review easier and reduces the blast radius of any unexpected changes. + +--- + + +*๐Ÿค– Crafted with precision by โœจCopilot following brilliant human instruction, +then carefully refined by our team of discerning human reviewers.* + diff --git a/docs/agents/github-backlog/sprint-planning.md b/docs/agents/github-backlog/sprint-planning.md new file mode 100644 index 00000000..7c52a7e1 --- /dev/null +++ b/docs/agents/github-backlog/sprint-planning.md @@ -0,0 +1,121 @@ +--- +title: Sprint Planning Workflow +description: Organize triaged issues into milestones with priority sequencing and capacity awareness +author: Microsoft +ms.date: 2026-02-12 +ms.topic: tutorial +keywords: + - github backlog manager + - sprint planning + - milestones + - github copilot +estimated_reading_time: 5 +--- + +The Sprint Planning workflow organizes triaged issues into milestones, sequences work by priority, and produces execution-ready handoff files that map issues to their target sprint. + +## When to Use + +* ๐Ÿ“… Starting a new sprint or release cycle and need to assign issues to milestones +* ๐ŸŽฏ Issues have been triaged but lack milestone assignments +* ๐Ÿ”„ Rebalancing work across milestones after scope changes or team adjustments +* ๐Ÿ“‹ Creating milestone structure for a new project or repository + +## What It Does + +1. Reads triage output to understand issue classification and priority levels +2. Discovers existing milestones or recommends new ones based on issue patterns +3. Maps issues to milestones considering priority, dependencies, and grouping +4. Sequences work within each milestone based on priority assessment and blocking relationships +5. Produces a sprint plan with milestone assignments and a handoff file for execution + +> [!NOTE] +> Sprint planning does not create milestones automatically. It recommends milestone assignments in a handoff file that the execution workflow applies after your review. + +## Milestone Discovery + +The workflow follows a structured approach to milestone management: + +1. Queries the repository for existing open milestones with due dates +2. Maps triaged issues to milestones by area label and priority +3. Identifies issues that fit no current milestone and recommends creating new ones +4. Checks milestone capacity using issue count and priority distribution +5. Flags milestones that appear overloaded relative to their due date +6. Produces a milestone map showing current and recommended assignments + +This process ensures sprint plans build on existing repository structure rather than creating parallel tracking systems. + +## Output Artifacts + +```text +.copilot-tracking/github-issues/sprint// +โ”œโ”€โ”€ sprint-analysis.md # Milestone mapping and capacity review +โ”œโ”€โ”€ sprint-plan.md # Recommended assignments and sequencing +โ””โ”€โ”€ handoff.md # Execution-ready handoff with checkboxes +``` + +The sprint plan includes reasoning for each milestone assignment, making it possible to adjust recommendations before execution applies them. + +## How to Use + +### Option 1: Prompt Shortcut + +```text +Plan the next sprint for microsoft/hve-core using my latest triage results +``` + +```text +Assign milestones to all triaged issues without milestone assignments +``` + +### Option 2: Direct Agent + +Start a conversation with the GitHub Backlog Manager agent and reference your triage output. The agent reads the triage analysis and handoff files, then builds a sprint plan based on current milestone structure. + +## Example Prompt + +```text +Plan sprint assignments for microsoft/hve-core. Use the v2.1 milestone for +high-priority bugs and the v2.2 milestone for enhancements. Create a new +"documentation-refresh" milestone for any docs-area issues without a milestone. +``` + +## Tips + +โœ… Do: + +* Run triage before sprint planning so issues have consistent labels and priorities +* Review milestone capacity recommendations before approving assignments +* Use the sequencing output to identify blocking chains within a milestone +* Adjust milestone assignments in the handoff file before passing to execution + +โŒ Don't: + +* Plan sprints without triaged issues (issues that lack triage metadata produce unreliable plans) +* Ignore capacity warnings for milestones approaching their due date +* Create milestones through sprint planning when they should be created through repository settings +* Assume the workflow sees private milestones (verify MCP token permissions) + +## Common Pitfalls + +| Pitfall | Solution | +|----------------------------------------|-------------------------------------------------------------------------| +| Issues assigned to closed milestones | The workflow flags these for reassignment; review before execution | +| Milestone names don't match repository | Verify milestone names in the handoff match existing milestones exactly | +| Priority conflicts within a milestone | Review the sequencing recommendations and adjust priority labels first | +| Too many issues for a single milestone | Split across milestones or re-prioritize lower-priority items out | + +## Next Steps + +1. Review the sprint plan and handoff file for accuracy +2. Proceed to the [Execution workflow](execution.md) to apply milestone assignments + +> [!TIP] +> For teams with fixed sprint cadences, create milestones in advance through repository settings. Sprint planning works best when it maps to existing milestones rather than recommending new ones. + +--- + + +*๐Ÿค– Crafted with precision by โœจCopilot following brilliant human instruction, +then carefully refined by our team of discerning human reviewers.* + diff --git a/docs/agents/github-backlog/triage.md b/docs/agents/github-backlog/triage.md new file mode 100644 index 00000000..e792544b --- /dev/null +++ b/docs/agents/github-backlog/triage.md @@ -0,0 +1,132 @@ +--- +title: Triage Workflow +description: Classify, label, and detect duplicate GitHub issues using structured triage analysis +author: Microsoft +ms.date: 2026-02-12 +ms.topic: tutorial +keywords: + - github backlog manager + - issue triage + - labels + - duplicate detection + - github copilot +estimated_reading_time: 5 +--- + +The Triage workflow classifies issues discovered in the previous phase, recommending labels, detecting duplicates, and producing handoff files for sprint planning or direct execution. + +## When to Use + +* ๐Ÿท๏ธ Issues need labels assigned or updated after a discovery pass +* ๐Ÿ” Suspected duplicates require confirmation before closing +* ๐Ÿ“Š Preparing issue metadata for milestone assignment in sprint planning +* ๐Ÿงน Cleaning up a backlog with inconsistent or missing labels + +## What It Does + +1. Reads issue analysis files produced by the discovery workflow +2. Evaluates each issue against a 17-label taxonomy organized by category +3. Compares issues across four similarity dimensions to detect duplicates +4. Generates confidence scores for label suggestions and duplicate matches +5. Produces triage recommendations with reasoning for each classification + +> [!NOTE] +> Triage recommendations are proposals, not automatic changes. The execution workflow applies labels and closes duplicates only after you review and approve the handoff file. + +## Label Taxonomy + +The triage workflow uses a structured label taxonomy organized into four categories: + +| Category | Labels | Purpose | +|-----------|-----------------------------------------------------------------|------------------------------------| +| Type | bug, feature, enhancement, documentation, maintenance, security | Classifies the nature of work | +| Lifecycle | needs-triage, duplicate, wontfix, breaking-change | Controls issue disposition | +| Scope | agents, prompts, instructions, infrastructure | Maps to repository components | +| Community | good-first-issue, help-wanted, question | Contributor engagement and support | + +Each issue receives one label per category where applicable. The triage workflow explains its reasoning for each suggested label, allowing you to adjust before execution. + +## Duplicate Detection + +Duplicate detection compares issues across four dimensions: + +* Title similarity using normalized keyword matching +* Description overlap through content comparison +* Label set intersection to identify functionally equivalent issues +* Assignee and milestone alignment to catch split work items + +When confidence exceeds the threshold, the workflow links the duplicate pair in its recommendation file and suggests which issue to keep based on age, completeness, and discussion activity. + +## Output Artifacts + +```text +.copilot-tracking/github-issues/triage// +โ”œโ”€โ”€ planning-log.md # Progress tracking and analysis results +โ””โ”€โ”€ triage-plan.md # Label suggestions, duplicate findings, and recommended operations +``` + +The triage plan includes reasoning for each classification, making it possible to adjust recommendations before execution applies them. + +## How to Use + +### Option 1: Prompt Shortcut + +```text +Triage the issues discovered in my latest discovery session +``` + +```text +Check for duplicates in microsoft/hve-core issues labeled "needs-triage" +``` + +### Option 2: Direct Agent + +Attach or reference the discovery output files when starting a triage conversation. The agent reads the issue analysis and begins classification automatically. + +## Example Prompt + +```text +Triage all issues from my latest discovery pass for microsoft/hve-core. +Apply the standard label taxonomy and flag any potential duplicates with +confidence scores above 70%. +``` + +## Tips + +โœ… Do: + +* Run discovery first to build a complete issue inventory before you triage +* Review duplicate pairs before approving closure recommendations +* Adjust label suggestions in the handoff file before passing to execution +* Use the confidence scores to prioritize which recommendations to review first + +โŒ Don't: + +* Triage issues you haven't discovered (the workflow needs analysis files as input) +* Auto-approve all triage recommendations without reviewing confidence scores +* Modify the handoff file format (execution depends on the checkbox structure) +* Run triage and execution in the same session without clearing context + +## Common Pitfalls + +| Pitfall | Solution | +|---------------------------------------|-----------------------------------------------------------------------------| +| Low confidence on label suggestions | Provide more context in the issue description or add manual labels | +| False-positive duplicate matches | Review the four similarity dimensions and adjust the confidence threshold | +| Missing labels from taxonomy | Verify the label exists in the repository before expecting triage to use it | +| Triage conflicts with existing labels | The workflow flags conflicts rather than overwriting existing labels | + +## Next Steps + +1. Review and adjust the triage handoff file before proceeding +2. Move to [Sprint Planning](sprint-planning.md) to assign milestones, or skip directly to [Execution](execution.md) for label-only changes + +> [!TIP] +> For repositories with custom label schemes, update the taxonomy reference before running triage. The workflow applies whatever taxonomy is configured, so mismatches produce irrelevant suggestions. + +--- + + +*๐Ÿค– Crafted with precision by โœจCopilot following brilliant human instruction, +then carefully refined by our team of discerning human reviewers.* + diff --git a/docs/agents/github-backlog/using-together.md b/docs/agents/github-backlog/using-together.md new file mode 100644 index 00000000..2f004821 --- /dev/null +++ b/docs/agents/github-backlog/using-together.md @@ -0,0 +1,159 @@ +--- +title: Using Workflows Together +description: Connect discovery, triage, sprint planning, and execution into a complete backlog management pipeline +author: Microsoft +ms.date: 2026-02-12 +ms.topic: tutorial +keywords: + - github backlog manager + - workflow pipeline + - github copilot + - backlog management +estimated_reading_time: 8 +--- + +Each backlog manager workflow handles one phase of issue management. Connecting them creates a pipeline that takes issues from discovery through execution, with structured handoffs ensuring nothing falls through the cracks. + +## The Pipeline + +```text +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Discovery โ”‚ โ”€โ”€โ†’โ”‚ Triage โ”‚ โ”€โ”€โ†’โ”‚ Sprint Planning โ”‚ โ”€โ”€โ†’โ”‚ Execution โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ†‘ โ”‚ + โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ Iterate โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +The pipeline is linear but not rigid. Skip sprint planning when you only need to apply labels. Return to discovery after execution when new issues surface. Each workflow reads its predecessor's output files, so the pipeline works as long as the handoff artifacts exist. + +## Clear Context Between Workflows + +Each workflow operates within its own session context. Mixing workflows in a single session produces unreliable results because the agent carries forward assumptions from the previous workflow. + +Between each workflow: + +1. Type `/clear` to reset the conversation context +2. Attach or reference the output files from the previous workflow +3. Start the next workflow with a fresh prompt + +This is the single most important practice for reliable pipeline execution. The `/clear` step takes seconds and prevents hours of debugging misapplied labels or incorrect milestone assignments. + +> [!IMPORTANT] +> The `/clear` step between workflows is not optional. Each workflow loads specific instruction files and planning artifacts. Stale context from a previous workflow interferes with the current workflow's classification logic. + +All GitHub-facing comments (issue replies, label rationale, duplicate explanations) follow the voice and tone rules defined in `community-interaction.instructions.md`. This instruction file loads automatically when the backlog manager agents operate, so you do not need to configure it separately. + +## End-to-End Walkthrough + +This walkthrough covers a realistic pipeline run for a repository with accumulated issues that have not been reviewed. + +### Step 1: Discover Issues + +Start with a scoped discovery pass: + +```text +Discover all open issues in microsoft/hve-core that are unassigned +and don't have a milestone. Include issues labeled "needs-triage". +``` + +Discovery produces analysis files in `.copilot-tracking/github-issues/discovery/hve-core/`. Review the issue analysis to confirm the scope is correct before proceeding. + +### Step 2: Clear and Triage + +```text +/clear +``` + +Then start triage: + +```text +Triage the issues from my latest discovery session for microsoft/hve-core. +Flag duplicates with confidence scores and suggest labels using the +standard taxonomy. +``` + +Review the triage plan at `.copilot-tracking/github-issues/triage//triage-plan.md`. Adjust any label suggestions or duplicate flags before continuing. + +### Step 3: Clear and Plan + +```text +/clear +``` + +Then plan the sprint: + +```text +Plan sprint assignments for microsoft/hve-core using the triage results. +Assign high-priority bugs to the v2.1 milestone and enhancements to v2.2. +``` + +Review the sprint plan and handoff file. Adjust milestone assignments for any issues where the automatic mapping doesn't fit. + +### Step 4: Clear and Execute + +```text +/clear +``` + +Then execute: + +```text +Execute the sprint planning handoff for microsoft/hve-core. Apply all +checked operations in the handoff file. +``` + +Check the execution log for any skipped operations or state conflicts. + +### Step 5: Iterate + +Review the execution results. If new issues were discovered during the process, or if some operations were skipped due to conflicts, return to discovery or triage for another pass. + +## Planning File Lifecycle + +Planning files move through three states during the pipeline: + +| State | Location | Created By | Consumed By | +|---------------|-------------------------------------------|-----------------|-------------| +| Analysis | `discovery//issue-analysis.md` | Discovery | Triage | +| Triage Plan | `triage//triage-plan.md` | Triage | Execution | +| Sprint Plan | `sprint//handoff.md` | Sprint Planning | Execution | +| Execution Log | `//handoff-logs.md` | Execution | User review | + +Files are created once and updated in place. The execution workflow marks checkboxes in handoff files as it processes each operation, providing a built-in audit trail. + +## Iteration Model + +Most backlogs require multiple passes through the pipeline. The iteration model supports this with three patterns: + +* Full cycle: Run all four workflows when starting a new sprint or onboarding a new repository +* Triage-execute: Skip sprint planning when applying label corrections or closing duplicates +* Discovery-only: Run discovery periodically to monitor for new issues without immediate action + +Each pass produces independent output files scoped by date and target, so previous results are preserved for comparison. + +## Artifact Summary + +| Workflow | Input | Output | Key File | +|-----------------|------------------|---------------------------------------|---------------------| +| Discovery | Repository scope | Issue inventory and recommendations | `issue-analysis.md` | +| Triage | Discovery output | Label suggestions and duplicate flags | `triage-plan.md` | +| Sprint Planning | Triage output | Milestone assignments and sequencing | `handoff.md` | +| Execution | Handoff files | Applied changes and operation log | `handoff-logs.md` | + +## Quick Reference + +| Task | Workflow | Prompt Example | +|-----------------------------|--------------------|--------------------------------------------------| +| Survey open issues | Discovery | "Discover open issues assigned to me" | +| Assign labels to new issues | Triage | "Triage issues from my latest discovery" | +| Find and close duplicates | Triage + Execution | "Check for duplicates and close confirmed ones" | +| Plan the next sprint | Sprint Planning | "Plan sprint assignments for the v2.1 milestone" | +| Apply all recommendations | Execution | "Execute the triage handoff" | +| Full backlog review | All four workflows | Run each in sequence with `/clear` between them | + +--- + + +*๐Ÿค– Crafted with precision by โœจCopilot following brilliant human instruction, +then carefully refined by our team of discerning human reviewers.* + diff --git a/docs/agents/github-backlog/why-backlog-manager.md b/docs/agents/github-backlog/why-backlog-manager.md new file mode 100644 index 00000000..03d226e8 --- /dev/null +++ b/docs/agents/github-backlog/why-backlog-manager.md @@ -0,0 +1,79 @@ +--- +title: Why the Backlog Manager Works +description: Design principles and cognitive foundations behind the GitHub Backlog Manager workflow separation +author: Microsoft +ms.date: 2026-02-12 +ms.topic: concept +keywords: + - github backlog manager + - workflow design + - github copilot + - backlog management +estimated_reading_time: 6 +--- + +Backlog management looks simple from the outside: read issues, assign labels, close duplicates. In practice, teams struggle with it because the work combines several cognitively different tasks into one undifferentiated session. The GitHub Backlog Manager addresses this by separating those tasks into focused workflows, each designed for one type of thinking. + +## The Core Insight + +Discovering issues, classifying them, planning their execution, and applying changes require different mental models. Discovery is exploratory and divergent. Triage is analytical and convergent. Sprint planning is strategic and forward-looking. Execution is mechanical and precise. + +Combining these in a single pass forces constant context-switching between exploration, analysis, strategy, and action. The result is inconsistent labels, missed duplicates, and milestones that don't reflect actual priorities. + +The backlog manager solves this by giving each cognitive mode its own workflow, its own session, and its own output artifacts. You focus on one type of thinking at a time, and structured handoff files carry context forward without requiring you to hold it all in memory. + +## How Each Workflow Helps + +Discovery narrows the aperture. Instead of staring at a full issue list, you define what you're looking for (your assignments, issues related to a branch, issues matching specific criteria) and get back a structured inventory. The analysis file captures what was found and why, so triage starts with organized input rather than raw data. + +Triage applies consistent classification. Working from discovery output rather than live issue lists means every issue gets evaluated against the same taxonomy in the same pass. Duplicate detection works better when issues are compared in batches rather than individually, because patterns only emerge when you see the full set. + +Sprint planning builds on classified data. With labels and duplicates resolved, milestone assignment becomes a mapping exercise rather than a judgment call. The workflow can reason about capacity and priority because triage has already done the classification work. + +Execution applies changes mechanically. By the time you reach execution, every change has been reviewed and approved in a handoff file. The workflow processes checkboxes, not decisions. This separation means bulk changes are safe because the decision-making happened in earlier phases with full context. + +## Quality Comparison + +| Aspect | Manual Process | Managed Pipeline | +|----------------------|---------------------------------------------|-------------------------------------------------| +| Label consistency | Varies by who triages and when | Same taxonomy applied in every pass | +| Duplicate detection | Relies on memory and search skills | Systematic comparison across four dimensions | +| Milestone assignment | Often deferred or forgotten | Structured recommendations with capacity checks | +| Audit trail | Issue history only | Planning files, handoff logs, execution logs | +| Recovery from errors | Undo individual changes manually | Re-run execution; completed items are tracked | +| Time per issue | Decreases with fatigue during long sessions | Consistent because each workflow is short | + +## Learning Curve + +The backlog manager is designed for progressive adoption: + +1. Start with discovery alone to survey your backlog without changing anything +2. Add triage when you want consistent labeling across issues +3. Introduce sprint planning when milestones and priorities become important +4. Use execution when you're comfortable with the handoff review process + +Each workflow is useful independently. You don't need to adopt the full pipeline to get value from individual workflows. + +> [!TIP] +> Most teams start with discovery and triage, adding sprint planning and execution as confidence grows. There is no requirement to use all four workflows together. + +## Choosing Your Approach + +The backlog manager supports three autonomy levels. Choose based on your comfort with automated changes and the sensitivity of your repository: + +| Level | Discovery | Triage | Sprint Planning | Execution | +|---------|-----------|-----------|-----------------|-----------| +| Full | Automatic | Automatic | Automatic | Automatic | +| Partial | Automatic | Review | Automatic | Review | +| Manual | Automatic | Review | Review | Review | + +Full autonomy suits repositories where the cost of a mislabeled issue is low and velocity matters most. Manual control fits repositories where every change needs human approval. Partial autonomy balances speed with oversight by requiring review at the points where judgment matters most: classification and change application. + +The right level depends on your repository, not on the tool. Start with manual control and increase autonomy as you verify the workflow produces reliable results for your specific backlog. + +--- + + +*๐Ÿค– Crafted with precision by โœจCopilot following brilliant human instruction, +then carefully refined by our team of discerning human reviewers.* + diff --git a/docs/architecture/ai-artifacts.md b/docs/architecture/ai-artifacts.md index cb083f0b..663a0654 100644 --- a/docs/architecture/ai-artifacts.md +++ b/docs/architecture/ai-artifacts.md @@ -361,6 +361,7 @@ The extension provides these contribution points: ## Related Documentation +* [Agent Systems Catalog](../agents/README.md) - Overview of all agent systems with workflow documentation * [AI Artifacts Common Standards](../contributing/ai-artifacts-common.md) - Quality requirements for all artifacts * [Contributing Prompts](../contributing/prompts.md) - Prompt file specifications * [Contributing Agents](../contributing/custom-agents.md) - Agent file specifications diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 80a0f415..6f0fd34b 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -110,6 +110,7 @@ Copy the scripts you need to your project's `scripts/` directory and adjust path - Try [Your First Workflow](first-workflow.md) for a quick start - Learn the [RPI Workflow](../rpi/README.md) for complex tasks +- Browse the [Agent Catalog](../agents/README.md) for all agent system documentation - Explore [Agents](../../.github/CUSTOM-AGENTS.md) for available agents - Review [Instructions](../../.github/instructions/README.md) for coding guidelines - Check the [README](../../README.md) for feature overview diff --git a/docs/rpi/README.md b/docs/rpi/README.md index e7823817..5e3c3073 100644 --- a/docs/rpi/README.md +++ b/docs/rpi/README.md @@ -119,6 +119,7 @@ Research findings are preserved in files, not chat history. Clean context lets e * [Task Reviewer Guide](task-reviewer.md) - Validate implementations * [Using Them Together](using-together.md) - Complete workflow example * [Agents Reference](../../.github/CUSTOM-AGENTS.md) - All available agents +* [Agent Systems Catalog](../agents/README.md) - Browse all agent families beyond RPI ---