Skip to content

feat(agents): add GitHub backlog management pipeline #447

@WilliamBerryiii

Description

@WilliamBerryiii

Summary

Introduces a complete TPM-focused GitHub backlog management pipeline — 5 instructions, 4 prompts, and 1 orchestrator agent — mirroring the ADO tooling pipeline architecture with GitHub-native MCP tools. Replaces and deprecates the single-purpose github-issue-manager agent with a comprehensive four-stage workflow covering triage, discovery, sprint planning, and batch execution.

Branch: feat/github-backlog-management-tooling
Commit: 3fe2c00
Scope: 19 files changed, 2,621 insertions, 477 deletions

Motivation

The existing github-issue-manager.agent.md provided only conversational filing, navigation, and search for individual GitHub issues. TPMs managing GitHub backlogs needed the same rigor available for ADO work items: batch triage, duplicate detection, milestone-based sprint planning, hierarchy-aware execution, and three-tier autonomy controls. The ADO pipeline (planning → discovery → update → PR) proved the architectural blueprint; this work adapts that blueprint to GitHub's issue model.

Architecture

Instructions-first pipeline (parallel to the ADO tooling suite):

github-backlog-planning.instructions.md (P0 — reference specification)
    ├── github-backlog-triage.instructions.md (consumes planning spec)
    ├── github-backlog-discovery.instructions.md (consumes planning spec)
    └── github-backlog-update.instructions.md (consumes planning spec)

github-backlog-manager.agent.md (orchestrator)
    ├── github-triage-issues.prompt.md → triage instructions
    ├── github-discover-issues.prompt.md → discovery instructions
    ├── github-execute-backlog.prompt.md → update instructions
    └── github-sprint-plan.prompt.md → planning spec + milestone APIs

Key design decisions:

  • Reference specification as foundationgithub-backlog-planning.instructions.md (758 lines) defines planning file templates, field conventions, MCP tool catalog, search protocols, similarity assessment matrix, state persistence, and the three-tier autonomy model. All workflow instructions cross-reference this file rather than duplicating conventions.
  • Intent-based routing — The orchestrator agent classifies incoming requests into one of five workflow types (triage, discovery, sprint, execution, single-issue) and dispatches to the appropriate prompt via handoff configuration.
  • Three-tier autonomy — Full (no gates), Partial (key gates only), Manual (all gates). Workflows default to Partial; users override per session.
  • Similarity assessment — A 5-dimension matrix (title, body, labels, milestone, assignee) with weighted scoring prevents duplicate issue creation during batch operations.
  • Hierarchy-aware execution — Batch operations process parent issues before children to maintain referential integrity with GitHub's sub-issues API.

Changes

New Artifacts (10 files)

Instructions (5)

File Lines Purpose
github-backlog-planning.instructions.md 758 Reference specification: planning file templates, MCP tool catalog, search protocols, similarity assessment, state persistence, three-tier autonomy model
github-backlog-triage.instructions.md 302 Triage pipeline: batch label suggestion, milestone assignment, priority assessment, duplicate detection with planning file output
github-backlog-discovery.instructions.md 234 Discovery workflows: artifact-driven, user-centric, and search-based issue discovery with planning file generation
github-backlog-update.instructions.md 226 Execution pipeline: consumes planning handoffs, executes batch issue operations with hierarchy-aware ordering
community-interaction.instructions.md 335 Community interaction voice/tone guidelines referenced by backlog workflows for issue/PR comments

Prompts (4)

File Lines Purpose
github-triage-issues.prompt.md 84 Entry point for triage workflow — scopes to repo, runs label/milestone/duplicate analysis
github-discover-issues.prompt.md 128 Entry point for discovery — three modes (artifact-driven, user-centric, search-based)
github-execute-backlog.prompt.md 78 Entry point for batch execution — consumes planning handoffs, applies changes
github-sprint-plan.prompt.md 109 Sprint planning — milestone management, velocity analysis, capacity allocation

Agent (1)

File Lines Purpose
github-backlog-manager.agent.md 174 Orchestrator with intent classification, five workflow dispatch paths, handoff configuration to all four prompts

Modified Files (9)

File Change Detail
github-add-issue.prompt.md Bug fix + refactor Fixed mcp_github_create_issuemcp_github_issue_write (tool doesn't exist); rewrote from 304→86 lines; now delegates to github-backlog-planning.instructions.md for templates; maturity changed to experimental
github-issue-manager.agent.md Deprecated Content replaced with deprecation notice pointing to github-backlog-manager.agent.md; maturity set to deprecated
CUSTOM-AGENTS.md Updated Agent table: github-issue-managergithub-backlog-manager with updated description and workflow notes
hve-core-installer.agent.md Updated Agent count 14+ → 20+; agent listing updated to include github-backlog-manager; formatting fixes
writing-style.instructions.md Extended Added "Community" row to formality/pronoun tables; cross-reference to community-interaction.instructions.md
docs/getting-started/install.md Reference update github-issue-managergithub-backlog-manager
docs/getting-started/mcp-configuration.md Reference update Agent MCP Dependencies table updated with new agent name and description
extension/README.md Reference update Agent listing updated to github-backlog-manager
extension/package.json Regenerated Manifest updated: 21 agents, 26 prompts, 23 instructions

Validation

All validators passed on the committed artifacts:

Validator Result
npm run format:tables Clean
npm run lint:frontmatter 127 files, 0 errors
npm run lint:md 0 errors (fixed MD013 in agent file during validation)
npm run spell-check 91 files, 0 issues
npm run lint:md-links All links passed
npm run extension:prepare 21 agents, 26 prompts, 23 instructions

Review Checklist

Artifact Quality

  • Planning specification covers MCP tool catalog, planning file templates, similarity assessment
  • Triage instructions produce planning files with label/milestone recommendations
  • Discovery instructions support all three modes (artifact, user, search)
  • Update instructions consume planning handoffs with hierarchy-aware ordering
  • Community interaction instructions define voice/tone for issue comments
  • All four prompts correctly reference their backing instructions
  • Orchestrator agent routes all five intent types to correct workflows
  • Bug fix resolves non-existent mcp_github_create_issue tool reference

Integration

  • Deprecated github-issue-manager agent has clear migration notice
  • All cross-repo references updated (CUSTOM-AGENTS, installer, docs, extension)
  • Extension manifest registers all new artifacts
  • Writing-style instructions include community interaction cross-reference

Maturity

  • All new artifacts ship at experimental
  • Deprecated agent marked with deprecated maturity
  • Progression to preview after multi-repo testing and TPM feedback

Research

  • .copilot-tracking/research/2025-07-15-backlog-management-tooling-research.md (851 lines)
  • .copilot-tracking/details/2026-02-05-github-backlog-tooling-details.md
  • .copilot-tracking/plans/2026-02-05-github-backlog-tooling-plan.instructions.md

Metadata

Metadata

Labels

agentsCustom chat agents (.agent.md)featureNew feature triggering minor version bump

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions