Skip to content
14 changes: 13 additions & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
69 changes: 69 additions & 0 deletions docs/agents/README.md
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.

## 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 -->
112 changes: 112 additions & 0 deletions docs/agents/github-backlog/README.md
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

> [!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

---

<!-- 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 -->
126 changes: 126 additions & 0 deletions docs/agents/github-backlog/discovery.md
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 -->
Loading
Loading