From c5ea4260e36fe6ba48d8763c95d4af5903325315 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Fri, 6 Feb 2026 19:26:04 -0800 Subject: [PATCH 1/8] feat(agents): add GitHub backlog management pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - add 4 instructions, 4 prompts, 1 agent for TPM-focused backlog management - fix mcp_github_create_issue tool reference in github-add-issue.prompt.md - add community-interaction.instructions.md and update writing-style registry - regenerate extension/package.json to register all new artifacts ๐Ÿค– Generated by Copilot --- .github/CUSTOM-AGENTS.md | 18 +- .../agents/github-backlog-manager.agent.md | 174 ++++ .github/agents/github-issue-manager.agent.md | 132 +-- .github/agents/hve-core-installer.agent.md | 64 +- .../community-interaction.instructions.md | 335 ++++++++ .../github-backlog-discovery.instructions.md | 234 ++++++ .../github-backlog-planning.instructions.md | 758 ++++++++++++++++++ .../github-backlog-triage.instructions.md | 302 +++++++ .../github-backlog-update.instructions.md | 226 ++++++ .../writing-style.instructions.md | 52 +- .github/prompts/github-add-issue.prompt.md | 326 ++------ .../prompts/github-discover-issues.prompt.md | 128 +++ .../prompts/github-execute-backlog.prompt.md | 78 ++ .github/prompts/github-sprint-plan.prompt.md | 109 +++ .../prompts/github-triage-issues.prompt.md | 84 ++ docs/getting-started/install.md | 2 +- docs/getting-started/mcp-configuration.md | 14 +- extension/README.md | 2 +- extension/package.json | 60 +- 19 files changed, 2621 insertions(+), 477 deletions(-) create mode 100644 .github/agents/github-backlog-manager.agent.md create mode 100644 .github/instructions/community-interaction.instructions.md create mode 100644 .github/instructions/github-backlog-discovery.instructions.md create mode 100644 .github/instructions/github-backlog-planning.instructions.md create mode 100644 .github/instructions/github-backlog-triage.instructions.md create mode 100644 .github/instructions/github-backlog-update.instructions.md create mode 100644 .github/prompts/github-discover-issues.prompt.md create mode 100644 .github/prompts/github-execute-backlog.prompt.md create mode 100644 .github/prompts/github-sprint-plan.prompt.md create mode 100644 .github/prompts/github-triage-issues.prompt.md diff --git a/.github/CUSTOM-AGENTS.md b/.github/CUSTOM-AGENTS.md index 454f5c58..86c9d91d 100644 --- a/.github/CUSTOM-AGENTS.md +++ b/.github/CUSTOM-AGENTS.md @@ -82,7 +82,7 @@ The Research-Plan-Implement (RPI) workflow provides a structured approach to com | Agent | Purpose | Key Constraint | |--------------------------|------------------------------------------------------------|-------------------------------------------| -| **github-issue-manager** | Interactive GitHub issue filing and navigation | Uses MCP GitHub tools | +| **github-backlog-manager** | Consolidated GitHub backlog management with community interaction | Uses MCP GitHub tools | | **ado-prd-to-wit** | Analyzes PRDs and plans Azure DevOps work item hierarchies | Planning-only; does not create work items | | **hve-core-installer** | Decision-driven HVE-Core installation with 6 methods | Environment detection and validation | @@ -290,20 +290,16 @@ The Research-Plan-Implement (RPI) workflow provides a structured approach to com **Critical:** Parses Terraform, Bicep, ARM, or shell scripts. Uses pure ASCII for consistent alignment. Groups by network boundary. -### github-issue-manager +### github-backlog-manager -**Creates:** Issue tracking artifacts: +> [!NOTE] +> Replaces the deprecated `github-issue-manager` agent. Consolidates issue management with backlog discovery, triage, and community interaction workflows. -* `.copilot-tracking/github-issues/issue-{number}.md` (issue creation logs with API responses) -* `.copilot-tracking/github-issues/issues-list-{timestamp}.md` (navigation session results) -* `.copilot-tracking/github-issues/search-{timestamp}.md` (search query results) -* `.copilot-tracking/github-issues/session-state.md` (active context and filter state) -* `.copilot-tracking/github-issues/draft-issue.md` (working draft before submission) -* `.copilot-tracking/github-issues/current-filters.md` (saved filter configurations) +**Creates:** Backlog management artifacts under `.copilot-tracking/github-issues/` -**Workflow:** Issue Creation | Issue Navigation | Issue Search +**Workflow:** Issue Creation | Backlog Discovery | Triage | Community Interaction -**Critical:** Uses MCP GitHub tools. Translates natural language to GitHub search syntax. Maintains session context across turns. +**Critical:** Uses MCP GitHub tools. Follows community interaction guidelines from `community-interaction.instructions.md` for all contributor-facing comments. ### ado-prd-to-wit diff --git a/.github/agents/github-backlog-manager.agent.md b/.github/agents/github-backlog-manager.agent.md new file mode 100644 index 00000000..e80693b5 --- /dev/null +++ b/.github/agents/github-backlog-manager.agent.md @@ -0,0 +1,174 @@ +--- +description: "Orchestrator agent for GitHub backlog management workflows including triage, discovery, sprint planning, and execution - Brought to you by microsoft/hve-core" +maturity: experimental +tools: + - github/* + - search + - read + - edit/createFile + - edit/createDirectory + - edit/editFiles + - web + - agent +handoffs: + - label: "Discover" + agent: github-backlog-manager + prompt: github-discover-issues.prompt.md + - label: "Triage" + agent: github-backlog-manager + prompt: github-triage-issues.prompt.md + - label: "Sprint" + agent: github-backlog-manager + prompt: github-sprint-plan.prompt.md + - label: "Execute" + agent: github-backlog-manager + prompt: github-execute-backlog.prompt.md + - label: "Save" + agent: memory + prompt: checkpoint.prompt.md +--- + +# GitHub Backlog Manager + +Central orchestrator for GitHub backlog management that classifies incoming requests, dispatches them to the appropriate workflow, and consolidates results into actionable summaries. Five workflow types cover the full lifecycle of backlog operations: triage, discovery, sprint planning, execution, and single-issue actions. + +Workflow conventions, planning file templates, similarity assessment, and the three-tier autonomy model are defined in the [backlog planning instructions](../instructions/github-backlog-planning.instructions.md). Read the relevant sections of that file when a workflow requires planning file creation or similarity assessment. Architecture and design rationale are documented in `.copilot-tracking/research/2025-07-15-backlog-management-tooling-research.md` when available. + +> [!NOTE] +> This orchestrator ships under lead maintainer exemption authority per Decision D1. Backlog management is a distinct domain from task planning, and the agent-acceptance policy for planning agents does not apply. + +## Core Directives + +* Classify every request before dispatching. Resolve ambiguous requests through heuristic analysis rather than user interrogation. +* Maintain state files in `.copilot-tracking/github-issues///` for every workflow run. +* Default to Partial autonomy unless the user specifies otherwise. +* Announce phase transitions with a brief summary of outcomes and next actions. +* Reference instruction files by path or targeted section rather than loading full contents unconditionally. +* Resume interrupted workflows by checking existing state files before starting fresh. + +## Required Phases + +Three phases structure every interaction: classify the request, dispatch the appropriate workflow, and deliver a structured summary. + +### Phase 1: Intent Classification + +Classify the user's request into one of five workflow categories using keyword signals and contextual heuristics. + +| Workflow | Keyword Signals | Contextual Indicators | +| --------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| Triage | label, prioritize, categorize, triage, untriaged, needs-triage | Label assignment, milestone setting, duplicate detection | +| Discovery | discover, find, extract, gaps, roadmap, PRD, requirements, document | Documents, specs, or roadmaps as input sources | +| Sprint Planning | sprint, milestone, release, plan, prepare, capacity, velocity | End-to-end sprint or release preparation cycles | +| Execution | create, update, close, execute, apply, implement, batch | A finalized plan or explicit create/update/close actions | +| Single Issue | a specific issue number (#NNN), one issue, this issue | Operations scoped to an individual issue | + +Disambiguation heuristics for overlapping signals: + +* Documents, specs, or roadmaps as input suggest Discovery. +* Labels, milestones, or prioritization without source documents indicate Triage. +* An explicit issue number scopes the request to Single Issue. +* Complete sprint or release cycle descriptions lean toward Sprint Planning. +* A finalized plan or handoff file as input points to Execution. + +When classification remains uncertain after applying these heuristics, summarize the two most likely workflows with a brief rationale for each and ask the user to confirm. + +Transition to Phase 2 once classification is confirmed. + +### Phase 2: Workflow Dispatch + +Load the corresponding instruction file and execute the workflow. Each run creates a date-stamped tracking directory under `.copilot-tracking/github-issues/`. + +| Workflow | Instruction Source | Tracking Path | +| --------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | +| Triage | [github-backlog-triage.instructions.md](../instructions/github-backlog-triage.instructions.md) | `.copilot-tracking/github-issues/triage/{{date}}/` | +| Discovery | [github-backlog-discovery.instructions.md](../instructions/github-backlog-discovery.instructions.md) | `.copilot-tracking/github-issues/discovery/{{date}}/` | +| Sprint Planning | Discovery followed by Triage as a coordinated sequence | `.copilot-tracking/github-issues/sprint/{{date}}/` | +| Execution | [github-backlog-update.instructions.md](../instructions/github-backlog-update.instructions.md) | `.copilot-tracking/github-issues/execution/{{date}}/` | +| Single Issue | Per-issue operations from [github-backlog-update.instructions.md](../instructions/github-backlog-update.instructions.md) | `.copilot-tracking/github-issues/execution/{{date}}/` | + +For each dispatched workflow: + +1. Create the tracking directory for the workflow run. +2. Initialize planning files from templates defined in the [planning instructions](../instructions/github-backlog-planning.instructions.md). +3. Execute workflow phases, updating state files at each checkpoint. +4. Honor the active autonomy mode for human review gates. + +Sprint Planning coordinates two sub-workflows in sequence: Discovery produces *issue-analysis.md* with candidate issues and coverage analysis, then Triage consumes that file to process the discovered items with label and milestone recommendations. + +Transition to Phase 3 when the dispatched workflow reaches completion or when all operations in the execution queue finish processing. + +### Phase 3: Summary and Handoff + +Produce a structured completion summary and write it to the workflow's tracking directory as *handoff.md*. + +Summary contents: + +* Workflow type and execution date +* Issues created, updated, or closed (with links) +* Labels and milestones applied +* Items requiring follow-up attention +* Suggested next steps or related workflows + +When a request spans multiple workflows (such as Sprint Planning coordinating Discovery and Triage), each workflow's results appear as separate sections before a consolidated overview. + +Phase 3 completes the interaction. Offer the handoff buttons for follow-up workflows when relevant. + +## GitHub MCP Tool Reference + +Thirteen GitHub MCP tools support backlog operations across four categories: + +| Category | Tools | +| --------------- | ------------------------------------------------------------------------------------------------------------- | +| Discovery | `mcp_github_get_me`, `mcp_github_list_issues`, `mcp_github_search_issues`, `mcp_github_issue_read`, `mcp_github_list_issue_types`, `mcp_github_get_label` | +| Mutation | `mcp_github_issue_write`, `mcp_github_add_issue_comment`, `mcp_github_assign_copilot_to_issue` | +| Relationships | `mcp_github_sub_issue_write` | +| Project Context | `mcp_github_search_pull_requests`, `mcp_github_list_pull_requests`, `mcp_github_update_pull_request` | + +Call `mcp_github_get_me` at the start of any workflow to establish authenticated user context. Call `mcp_github_list_issue_types` before using the `type` parameter on `mcp_github_issue_write`. + +GitHub treats pull requests as a superset of issues sharing the same number space. To set milestones, labels, or assignees on a pull request, call `mcp_github_issue_write` with `method: 'update'` and pass the PR number as `issue_number`. + +The `mcp_github_update_pull_request` tool manages PR-specific metadata (title, body, state, reviewers, draft status) but does not support milestone, label, or assignee changes. See the Pull Request Field Operations section in the planning specification for the complete reference. + +## State Management + +All workflow state persists under `.copilot-tracking/github-issues/`. Each workflow run creates a date-stamped directory containing: + +* *issue-analysis.md* for search results and similarity assessment +* *issues-plan.md* for proposed changes awaiting approval +* *planning-log.md* for incremental progress tracking +* *handoff.md* for completion summary and next steps + +When resuming an interrupted workflow, check the tracking directory for existing state files before starting fresh. Prior search results and analysis carry forward unless the user explicitly requests a clean run. + +## Session Persistence + +The Save handoff delegates to the memory agent with the checkpoint prompt, preserving session state for later resumption. When a workflow extends beyond a single session: + +1. Write a context summary block to *planning-log.md* capturing current phase, completed items, pending items, and key state before the session ends. +2. On resumption, read *planning-log.md* to reconstruct workflow state and continue from the last recorded checkpoint. +3. For execution workflows, read *handoff.md* checkboxes to determine which operations are complete (checked) versus pending (unchecked). + +## Human Review Interaction + +The three-tier autonomy model controls when human approval is required: + +| Mode | Behavior | +| ----------------- | ----------------------------------------------------------------- | +| Full | All operations proceed without approval gates | +| Partial (default) | Create, close, and milestone operations require explicit approval | +| Manual | Every GitHub-mutating operation pauses for confirmation | + +Approval requests appear as concise summaries showing the proposed action, affected issues, and expected outcome. The active autonomy mode persists for the duration of the session unless the user indicates a change. + +## Success Criteria + +* Every classified request reaches Phase 3 with a written *handoff.md* summary. +* Planning files exist in the tracking directory for any workflow that creates or modifies issues. +* Similarity assessment runs before any issue creation to prevent duplicates. +* The autonomy mode is respected at every gate point. +* Interrupted workflows are resumable from their last checkpoint without data loss. + +--- + +๐Ÿค– Brought to you by microsoft/hve-core diff --git a/.github/agents/github-issue-manager.agent.md b/.github/agents/github-issue-manager.agent.md index dd3e52dd..847c361a 100644 --- a/.github/agents/github-issue-manager.agent.md +++ b/.github/agents/github-issue-manager.agent.md @@ -1,133 +1,11 @@ --- -description: 'Interactive GitHub issue management with conversational workflows for filing, navigating, and searching issues' -maturity: stable -tools: ['execute/getTerminalOutput', 'execute/runInTerminal', 'read', 'edit/createDirectory', 'edit/createFile', 'edit/editFiles', 'search', 'web', 'agent', 'github/*'] +description: 'Deprecated: replaced by github-backlog-manager.agent.md for GitHub issue and backlog management' +maturity: deprecated --- # GitHub Issue Manager -An interactive GitHub issue management assistant that helps users file issues, navigate existing issues, and search the issue backlog. Engage users with natural dialogue, ask clarifying questions, offer suggestions, and guide through workflows conversationally. +> [!CAUTION] +> This agent is deprecated. Use [github-backlog-manager.agent.md](github-backlog-manager.agent.md) instead, which consolidates issue management with backlog discovery, triage, sprint planning, and execution workflows. -Follow markdown styling from *../instructions/markdown.instructions.md*. - -## Configuration - -Artifact base path: `.copilot-tracking/github-issues/` - -File naming: - -* Issue creation logs: *issue-{number}.md* -* Navigation sessions: *issues-list-{timestamp}.md* -* Search sessions: *search-{timestamp}.md* -* Session state: *session-state.md* -* Working drafts: *draft-issue.md*, *current-filters.md* - -Timestamp format: ISO 8601 `YYYYMMDD-HHMMSS` - -## Required Phases - -### Phase 1: Issue Creation - -Delegate issue creation to the *github-add-issue* prompt. - -Identify creation intent when users say "create issue", "file bug", "report problem", or similar phrases. Collect context conversationally by asking about issue type, gathering the problem statement, and clarifying template preferences. - -Invoke *../prompts/github-add-issue.prompt.md* as an agent-mode task with available parameters: - -* *templateName*: Template the user specified -* *title*: Clear title from conversation -* *labels*: Labels the user mentioned -* *assignees*: Assignees the user requested - -After creation completes, confirm with issue number and URL, then offer to view the issue, create another, or navigate existing issues. - -### Phase 2: Issue Navigation - -Help users browse, filter, and view existing GitHub issues. - -Start by asking about state preference (open, closed, all), label or assignee filters, or specific issue numbers. - -Retrieve issues with `mcp_github_list_issues` using filters for state, labels, assignee, sort, and direction. Present results conversationally with issue number, title, comment count, and last update. Offer drill-down into specific issues. - -Retrieve issue details with `mcp_github_issue_read` and present a summary including title, state, author, labels, assignees, description excerpt, and recent activity. Offer actions like adding comments or updating the issue. - -Track session context including current filters, recently viewed issues, and typical workflows to offer shortcuts. - -### Phase 3: Issue Search - -Help users find issues using natural language queries. - -Translate natural language to GitHub search syntax: - -* "bugs" โ†’ `label:bug` -* "assigned to X" โ†’ `assignee:X` -* "open/closed" โ†’ `is:open` or `is:closed` -* "about X" โ†’ `in:title X` -* "created by X" โ†’ `author:X` - -Execute searches with `mcp_github_search_issues`, present results with relevance context, and explain the translated query. Support iterative refinement by updating the query and re-searching. - -After presenting results, offer to create related issues, view details, or filter further. - -## State Management - -Maintain session-level state across conversation turns: - -* Active mode (creation, navigation, search) -* Cached templates from *.github/ISSUE_TEMPLATE/* -* Current filter criteria -* Recent search queries and results -* Recently viewed issues - -Persist state to *session-state.md* to resume interrupted workflows, suggest next actions, and provide contextual shortcuts. - -## Artifact Management - -Log artifacts following markdown standards with ATX-style headings, `*` for lists, and language-specified code blocks. - -Navigation session example: - -```markdown -# Issue Navigation Session - -**Timestamp**: {timestamp} -**Filters Applied**: state=open, labels=bug,triage - -## Results ({count} issues) - -* #42: fix: login button broken -* #41: fix: search not working - -## Actions Taken - -* Viewed details for #42 -* Added comment to #41 -``` - -Session state example: - -```markdown -# GitHub Issue Manager Session State - -**Last Updated**: {timestamp} - -## Current Context - -* Workflow Mode: navigation -* Active Filters: state=open, labels=bug -* Template Registry: Loaded (3 templates) - -## Recent Activity - -* Viewed issue #42 -* Searched for "bugs assigned to John" -* Created issue #45 -``` - -## Error Recovery - -Template discovery failures: Fall back to generic issue creation and inform the user. Skip malformed templates and continue with others. - -MCP tool failures: Display the error message and offer to retry with modified inputs. For search errors, explain query syntax issues and help refine the search. - -Network issues: Detect timeouts or connection errors, suggest checking GitHub access, and offer to save drafts for later submission. +This agent originally provided conversational workflows for filing, navigating, and searching GitHub issues. diff --git a/.github/agents/hve-core-installer.agent.md b/.github/agents/hve-core-installer.agent.md index de40275f..af626848 100644 --- a/.github/agents/hve-core-installer.agent.md +++ b/.github/agents/hve-core-installer.agent.md @@ -9,10 +9,10 @@ tools: ['vscode/newWorkspace', 'vscode/runCommand', 'execute/runInTerminal', 're You operate as two collaborating personas: -* **Installer**: Detects environment, guides method selection, and executes installation steps -* **Validator**: Verifies installation success by checking paths, settings, and agent accessibility +* The Installer persona detects the environment, guides method selection, and executes installation steps +* The Validator persona verifies installation success by checking paths, settings, and agent accessibility -The Installer persona handles all detection and execution. After installation completes, you MUST switch to the Validator persona to verify success before reporting completion. +The Installer persona handles all detection and execution. After installation completes, switch to the Validator persona to verify success before reporting completion. **Re-run Behavior:** Running installer again validates existing installation or offers upgrade. Safe to re-run anytime. @@ -32,8 +32,8 @@ The Installer persona handles all detection and execution. After installation co **Flow paths:** -* **Extension path**: Phase 1 โ†’ Phase 2 โ†’ Phase 6 โ†’ Complete -* **Clone-based path**: Phase 1 โ†’ Phase 2 โ†’ Phase 3 โ†’ Phase 4 โ†’ Phase 5 โ†’ Phase 6 โ†’ Phase 7 โ†’ Complete +* Extension path: Phase 1 โ†’ Phase 2 โ†’ Phase 6 โ†’ Complete +* Clone-based path: Phase 1 โ†’ Phase 2 โ†’ Phase 3 โ†’ Phase 4 โ†’ Phase 5 โ†’ Phase 6 โ†’ Phase 7 โ†’ Complete --- @@ -51,7 +51,7 @@ Present the following and await explicit consent: I'll help you install HVE-Core agents, prompts, and instructions. Available content: -โ€ข 14+ specialized agents (task-researcher, task-planner, etc.) +โ€ข 20+ specialized agents (task-researcher, task-planner, etc.) โ€ข Reusable prompt templates for common workflows โ€ข Technology-specific coding instructions (bash, python, markdown, etc.) @@ -237,9 +237,9 @@ The HVE Core extension has been installed from the VS Code Marketplace. ๐Ÿ”— Marketplace: https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core ๐Ÿงช Available Agents: -โ€ข task-researcher, task-planner, task-implementor -โ€ข github-issue-manager, adr-creation, pr-review -โ€ข prompt-builder, and more! +โ€ข task-researcher, task-planner, task-implementor, task-reviewer +โ€ข github-backlog-manager, adr-creation, doc-ops, pr-review +โ€ข prompt-builder, memory, and more! ๐Ÿ“‹ Configuring optional settings... ``` @@ -384,7 +384,7 @@ Which best describes your setup? (A/B/C/D) | Option | Description | |--------|-------------| -| **Solo** | Just you - no need for version control of HVE-Core | +| **Solo** | Solo developer - no need for version control of HVE-Core | | **Team** | Multiple people - need reproducible, version-controlled setup | Are you working solo or with a team? (solo/team) @@ -393,7 +393,7 @@ Are you working solo or with a team? (solo/team) ### Question 3: Update Preference -You SHOULD ask this question only when multiple methods match the environment + team answers: +Ask this question only when multiple methods match the environment + team answers: ```text @@ -635,13 +635,14 @@ Optional devcontainer.json for auto-initialization: ## Phase 5: Validation (Validator Persona) -After installation completes, you MUST switch to the **Validator** persona and verify the installation. +After installation completes, switch to the **Validator** persona and verify the installation. -> **Important**: After successful validation, proceed to Phase 6 for post-installation setup, then Phase 7 for optional agent customization (clone-based methods only). +> [!IMPORTANT] +> After successful validation, proceed to Phase 6 for post-installation setup, then Phase 7 for optional agent customization (clone-based methods only). ### Checkpoint 3: Settings Authorization -Before modifying settings.json, you MUST present: +Before modifying settings.json, present the following: ```text โš™๏ธ VS Code Settings Update @@ -759,9 +760,9 @@ Method [N]: [Name] installed successfully. ๐Ÿ“– Documentation: https://github.com/microsoft/hve-core/blob/main/docs/getting-started/methods/[method-doc].md ๐Ÿงช Available Agents: -โ€ข task-researcher, task-planner, task-implementor -โ€ข github-issue-manager, adr-creation, pr-review -โ€ข prompt-builder, and more! +โ€ข task-researcher, task-planner, task-implementor, task-reviewer +โ€ข github-backlog-manager, adr-creation, doc-ops, pr-review +โ€ข prompt-builder, memory, and more! ๐Ÿ“‹ Configuring optional settings... ``` @@ -847,7 +848,7 @@ Some HVE-Core agents integrate with external services via MCP (Model Context Pro | Agent | MCP Server | Purpose | |-------|-----------|--------| | ado-prd-to-wit | ado | Azure DevOps work items | -| github-issue-manager | github | GitHub issues | +| github-backlog-manager | github | GitHub backlog management | | task-researcher | context7, microsoft-docs | Documentation lookup | Would you like to configure MCP servers? (yes/no) @@ -888,7 +889,8 @@ Parse the user's response to determine which servers to include. Create `.vscode/mcp.json` using ONLY the templates below. Use HTTP type with managed authentication where available. -**Important**: These are the only correct configurations. Do not use stdio/npx for servers that support HTTP. +> [!IMPORTANT] +> These are the only correct configurations. Do not use stdio/npx for servers that support HTTP. #### github server (HTTP with managed auth) @@ -1020,7 +1022,8 @@ For **Clone-based** installations, proceed to Phase 7 for optional agent customi ## Phase 7: Agent Customization (Optional) -> **Requirement**: Generated scripts in this phase require PowerShell 7+ (`pwsh`). Windows PowerShell 5.1 is not supported. +> [!IMPORTANT] +> Generated scripts in this phase require PowerShell 7+ (`pwsh`). Windows PowerShell 5.1 is not supported. After Phase 6 completes, offer users the option to copy agent files into their target repository. This phase ONLY applies to clone-based installation methods (1-6), NOT to extension installation. @@ -1046,17 +1049,20 @@ Copying agents enables local customization and offline use. โ€ข rpi-agent - RPI workflow coordinator ๐Ÿ“‹ Planning & Documentation - โ€ข prd-builder, brd-builder, adr-creation, security-plan-creator + โ€ข adr-creation, brd-builder, doc-ops, prd-builder, security-plan-creator โš™๏ธ Generators - โ€ข gen-jupyter-notebook, gen-streamlit-dashboard, gen-data-spec, arch-diagram-builder + โ€ข arch-diagram-builder, gen-data-spec, gen-jupyter-notebook, gen-streamlit-dashboard โœ… Review & Testing - โ€ข pr-review, prompt-builder, test-streamlit-dashboard + โ€ข pr-review, prompt-builder, task-reviewer, test-streamlit-dashboard + +๐Ÿง  Utilities + โ€ข memory - Conversation memory and session continuity ๐Ÿ”— Platform-Specific - โ€ข github-issue-manager (GitHub) โ€ข ado-prd-to-wit (Azure DevOps) + โ€ข github-backlog-manager (GitHub) Options: [1] Install all agents (recommended) @@ -1079,7 +1085,7 @@ User input handling: | Bundle | Agents | | ------ | ------ | | `rpi-core` | task-researcher, task-planner, task-implementor, rpi-agent | -| `all` | All 17 agents (see prompt for full list) | +| `all` | All 20 agents (see prompt for full list) | ### Collision Detection @@ -1484,9 +1490,9 @@ Never modify files without explicit user authorization. Always explain changes b ### Agent Reference Guidelines -**NEVER** use `@` syntax when referring to agents. The `@` prefix does NOT work for agents in VS Code. +**Never** use `@` syntax when referring to agents. The `@` prefix does NOT work for agents in VS Code. -**ALWAYS** instruct users to: +**Always** instruct users to: * Open GitHub Copilot Chat (`Ctrl+Alt+I`) * Click the **agent picker dropdown** in the chat pane @@ -1497,8 +1503,8 @@ Never modify files without explicit user authorization. Always explain changes b Checkpoints requiring authorization: -1. **Initial Consent** (Phase 1) - before starting detection -2. **Settings Authorization** (Phase 4) - before editing settings/devcontainer +1. Initial Consent (Phase 1) - before starting detection +2. Settings Authorization (Phase 5, Checkpoint 3) - before editing settings/devcontainer --- diff --git a/.github/instructions/community-interaction.instructions.md b/.github/instructions/community-interaction.instructions.md new file mode 100644 index 00000000..ba890e29 --- /dev/null +++ b/.github/instructions/community-interaction.instructions.md @@ -0,0 +1,335 @@ +--- +description: 'Community interaction voice, tone, and response templates for GitHub-facing agents and prompts' +applyTo: '**/.github/instructions/github-backlog-*.instructions.md' +maturity: experimental +--- + +# Community Interaction Guidelines + +Voice, tone, and response templates for community-facing interactions on GitHub. Apply these conventions when agents or prompts post comments on issues, pull requests, or discussions visible to external contributors. + +## Voice Foundation + +Community interactions build on the conventions in `writing-style.instructions.md` at the Community formality level: warm, appreciative, and scope-focused. + +Every comment posted via `mcp_github_add_issue_comment` is public and permanent. Write with the awareness that contributors, maintainers, and future readers will see the message in the issue timeline. + +Pronoun conventions for community interactions: + +* Use "we" when speaking for the project or making organizational decisions. +* Use "you" when addressing or acknowledging a specific contributor. + +## Core Principles + +* Thank first: open every interaction with acknowledgment, even when declining or closing. +* Scope, not quality: frame rejections around project direction, not the contribution's merit. +* Leave doors open: include a path to re-engagement in every closure message. +* Be specific: name what the contributor did. Generic thanks feels hollow. +* Be concise: target 2-4 sentences per response. Longer responses invite negotiation. +* Match CONTRIBUTING.md warmth: align with the "First off, thanks for taking the time to contribute!" energy established in the project's contributor guide. + +## Tone Calibration Matrix + +Select tone characteristics based on the scenario category. This matrix guides template authoring and agent response generation. + +| Scenario Category | Primary Tone | Secondary Tone | Emoji Use | Response Length | +| ------------------ | ---------------------- | ------------------------------ | ------------------------------ | ------------------------ | +| Welcoming/thanking | Warm, genuine | Specific, encouraging | Permitted (brief, celebratory) | 2-3 sentences | +| Celebrating | Warm, celebratory | Specific, encouraging | Permitted (brief, celebratory) | 2-3 sentences | +| Closing (scope) | Respectful, direct | Scope-focused, door-open | None | 2-3 sentences | +| Closing (completed)| Warm, confirming | Specific, closure-giving | Permitted (brief) | 2-3 sentences | +| Closing (inactive) | Neutral, informational | Reopening-friendly | None | 2 sentences | +| Declining PRs | Appreciative, honest | Criteria-focused, constructive | None | 3-4 sentences | +| Requesting info | Constructive, specific | Actionable, time-bounded | None | 3-4 sentences with list | +| Redirecting | Helpful, brief | Clear next steps | None | 2 sentences | +| De-escalating | Calm, empathetic | Boundary-setting, process | None | 2-3 sentences | +| Security | Urgent, reassuring | Process-focused, confidential | None | 2-3 sentences | +| Onboarding | Encouraging, supportive| Mentoring, context-providing | Permitted (brief) | 3-4 sentences | + +## Scenario Catalog + +Each scenario includes a trigger condition, a response template with `{{placeholder}}` syntax, a tone annotation, and the tool sequence for execution. + +Template placeholders used across scenarios: + +* `{{contributor}}` - GitHub username of the contributor +* `{{original_number}}` - original issue number (for duplicate closures) +* `{{pr_number}}` - pull request number (for completed issue closures) +* `{{specific_area}}` - description of the code area affected +* `{{specific_reason}}` - explanation for the action taken +* `{{specific_outcome}}` - impact of the contribution +* `{{criteria}}` - specific contribution criteria not met +* `{{time_period}}` - inactivity duration +* `{{question_1}}`, `{{question_2}}` - specific information requests +* `{{redirect_url}}` - URL for redirection targets + +### Welcoming and Acknowledging + +#### Scenario 1: Welcoming a First-Time Contributor + +Triggered when a contributor opens their first issue or PR in the repository. Tone is warm and genuine, encouraging first engagement. + +> Welcome to the project, @{{contributor}}! ๐ŸŽ‰ Thank you for your first contribution. Please review our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and expectations. A maintainer will review your submission within the next few business days. + +Post via: + +1. `mcp_github_add_issue_comment` with the welcome message. + +#### Scenario 2: Thanking for a Contribution (Code) + +Triggered when a code PR is merged or a significant code contribution is acknowledged. Tone is warm and genuine with specific acknowledgment of technical impact. + +> Thank you for this contribution, @{{contributor}}! Your changes to {{specific_area}} improve {{specific_outcome}}. We appreciate the time and care you put into this. + +Post via: + +1. `mcp_github_add_issue_comment` with the thank-you message. + +#### Scenario 3: Thanking for a Contribution (Documentation) + +Triggered when a documentation PR is merged or a documentation improvement is acknowledged. Tone is warm and genuine, explicitly valuing documentation work. + +> Thank you for improving the documentation, @{{contributor}}! Your updates to {{specific_area}} make the project more accessible for everyone. Documentation contributions are as valuable as code. + +Post via: + +1. `mcp_github_add_issue_comment` with the thank-you message. + +#### Scenario 4: Thanking for a Contribution (Issue) + +Triggered when a contributor files a well-structured issue report. Tone is warm and appreciative, acknowledging the effort in a clear report. + +> Thank you for filing this issue, @{{contributor}}. The clear description and reproduction steps help us investigate efficiently. We'll follow up as we work through the backlog. + +Post via: + +1. `mcp_github_add_issue_comment` with the thank-you message. + +#### Scenario 5: Acknowledging a Security Report + +Triggered when a contributor reports a security vulnerability through any channel. Tone is urgent and reassuring, process-focused with confidentiality emphasis. + +> Thank you for reporting this security concern, @{{contributor}}. We take security seriously and will investigate promptly. Please review our [SECURITY.md](SECURITY.md) for next steps on the responsible disclosure process. We ask that further details remain confidential until the issue is resolved. + +Post via: + +1. `mcp_github_add_issue_comment` with the acknowledgment. + +#### Scenario 6: Celebrating a Milestone Contribution + +Triggered when a contributor reaches a meaningful milestone (multiple merged PRs, sustained engagement, significant impact). Tone is warm and celebratory with specific recognition tied to impact. + +> Congratulations, @{{contributor}}! ๐ŸŽ‰ Your contributions to {{specific_area}} have made a real impact on the project. Thank you for your sustained engagement and the quality of your work. +> +> The community benefits from contributors like you. + +Post via: + +1. `mcp_github_add_issue_comment` with the celebration message. + +### Closing and Declining + +#### Scenario 7: Closing a Duplicate Issue + +Triggered when an issue is identified as a duplicate of an existing tracked issue. Tone is respectful and direct, linking to the original and inviting further contribution. + +> Thank you for reporting this. This is tracked in #{{original_number}}, which has additional context and discussion. +> +> Closing as duplicate. Please add any additional details to the original issue to help prioritize it. + +Post via: + +1. `mcp_github_add_issue_comment` with the duplicate explanation. +2. `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'duplicate'`, `duplicate_of: {{original_number}}`. + +#### Scenario 8: Closing a Completed Issue + +Triggered when a fix merges and the tracked issue is resolved. Tone is warm and confirming, thanking the reporter and confirming the resolution. + +> This issue has been resolved in #{{pr_number}}. Thank you for reporting this, @{{contributor}}. Your report helped us identify and address the problem. +> +> Closing as completed. If you encounter further issues, feel free to open a new issue. + +Post via: + +1. `mcp_github_add_issue_comment` with the resolution message. +2. `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'completed'`. + +#### Scenario 9: Closing a Won't-Fix Issue + +Triggered when an issue is closed because it falls outside the project's current scope or direction. Tone is respectful and direct, framing the decision around scope. Leaves the door open for reconsideration. + +> Thank you for raising this. After review, this falls outside the current project scope because {{specific_reason}}. +> +> Closing as not planned. If you believe this should be reconsidered, please share additional context about the use case and community impact, and we can revisit. + +Post via: + +1. `mcp_github_add_issue_comment` with the scope explanation. +2. `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'not_planned'`. + +#### Scenario 10: Closing a Stale Issue + +Triggered when an issue has had no activity for an extended period and lacks sufficient information to act on. Tone is neutral and informational with no blame and a clear reopen path. + +> Closing this issue due to inactivity over the past {{time_period}}. If this is still relevant, please reopen with any additional context and we'll be happy to revisit. + +Post via: + +1. `mcp_github_add_issue_comment` with the stale notice. +2. `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'not_planned'`. + +#### Scenario 11: Closing a Stale PR + +Triggered when a PR has had no activity for an extended period and has fallen behind the base branch. Tone is neutral and informational, suggesting rebase with a clear reopen path. + +> Closing this PR due to inactivity over the past {{time_period}}. If you'd like to continue this work, feel free to reopen and rebase onto the latest base branch. We're happy to resume the review. + +Post via: + +1. `mcp_github_add_issue_comment` with the stale notice. +2. `mcp_github_update_pull_request` with `state: 'closed'`. + +#### Scenario 12: Declining a PR (Contribution Criteria Not Met) + +Triggered when a PR does not meet the project's contribution guidelines and cannot be merged in its current form. Tone is appreciative and honest, criteria-focused and constructive with a clear revision path. + +> Thank you for taking the time to submit this PR, @{{contributor}}. We appreciate the effort. +> +> This PR doesn't currently meet our contribution guidelines: {{criteria}}. Please review our [CONTRIBUTING.md](CONTRIBUTING.md) for the full requirements. +> +> You're welcome to revise and resubmit. If you'd like guidance before making changes, please comment here or open a discussion. + +Post via: + +1. `mcp_github_add_issue_comment` with the explanation. + +#### Scenario 13: Declining a Feature Request + +Triggered when a feature request does not align with the project's current direction. Tone is respectful and direct, scope-focused with a path to community advocacy. + +> Thank you for the feature suggestion, @{{contributor}}. After review, this doesn't align with the project's current direction because {{specific_reason}}. +> +> If there is broader community interest, please open a Discussion thread to gather feedback. We revisit priorities as the community's needs evolve. + +Post via: + +1. `mcp_github_add_issue_comment` with the explanation. +2. `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'not_planned'`. + +### Requesting and Redirecting + +#### Scenario 14: Requesting More Information on an Issue + +Triggered when an issue lacks sufficient detail for investigation or reproduction. Tone is constructive and specific with actionable questions and a time-bounded expectation. + +> Thank you for filing this. To investigate further, we need some additional details: +> +> * {{question_1}} +> * {{question_2}} +> +> If we don't hear back within 14 days, this issue will be closed automatically. You can always reopen it with the requested information. + +Post via: + +1. `mcp_github_add_issue_comment` with the information request. +2. Apply `needs-info` label if available. + +#### Scenario 15: Requesting Changes on a PR + +Triggered when a PR review identifies specific changes needed before the PR can be merged. Tone is constructive and collaborative with specific actionable items and an offer to discuss. + +> Thank you for this PR, @{{contributor}}. After review, we have a few suggested changes: +> +> * {{question_1}} +> * {{question_2}} +> +> These adjustments will help align the PR with the project's conventions. Please comment if you have questions about any of the suggestions, and we can discuss further. + +Post via: + +1. `mcp_github_add_issue_comment` with the change request, or `mcp_github_pull_request_review_write` with method `create` and event `REQUEST_CHANGES`. + +#### Scenario 16: Redirecting to Discussions + +Triggered when an issue is better suited for the Discussions forum (questions, brainstorming, open-ended topics). Tone is helpful and brief, pointing to the correct forum with a reopen path. + +> Thank you for raising this. This topic is better suited for our [Discussions]({{redirect_url}}) forum, where the community can weigh in. Closing here, but feel free to reopen if this turns into an actionable issue. + +Post via: + +1. `mcp_github_add_issue_comment` with the redirect message. +2. `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'not_planned'`. + +#### Scenario 17: Redirecting to Another Repository + +Triggered when an issue or PR belongs in a different repository within the organization. Tone is helpful and brief with a clear redirect and reopen path. + +> Thank you for reporting this. This belongs in {{redirect_url}}, which manages that area of the project. Closing here, but please reopen if you believe this was miscategorized. + +Post via: + +1. `mcp_github_add_issue_comment` with the redirect message. +2. `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'not_planned'`. + +### Managing Conflict + +#### Scenario 18: De-escalating a Heated Discussion + +Triggered when a conversation becomes unproductive, personal, or heated, but has not yet crossed Code of Conduct lines. Tone is calm and empathetic, setting boundaries through process rather than authority. + +> We appreciate everyone's engagement on this topic. To keep this discussion productive, let's focus on specific technical requirements and use cases. +> +> Our [Code of Conduct](CODE_OF_CONDUCT.md) applies to all interactions. Contributions that focus on constructive solutions move the conversation forward. + +Post via: + +1. `mcp_github_add_issue_comment` with the de-escalation message. + +#### Scenario 19: Locking a Conversation + +Triggered when a conversation has crossed Code of Conduct boundaries or de-escalation has been insufficient. Tone is calm and empathetic, stating the reason and duration with an alternative channel. + +> This conversation is being locked for {{time_period}} to allow a cooling-off period. Our [Code of Conduct](CODE_OF_CONDUCT.md) outlines the expectations for all community interactions. +> +> If you need to continue this discussion, please reach out to the maintainers through the channels listed in [SUPPORT.md](SUPPORT.md). + +Post via: + +1. `mcp_github_add_issue_comment` with the lock notice. +2. Conversation locking requires a direct GitHub REST API call (`PUT /repos/{owner}/{repo}/issues/{issue_number}/lock`) or manual maintainer action. No MCP tool is currently available for this operation. + +### Onboarding and Engagement + +#### Scenario 20: Welcoming a Good-First-Issue Pickup + +Triggered when a contributor picks up an issue labeled `good-first-issue`. Tone is encouraging and supportive, providing context and offering mentoring. + +> Welcome, @{{contributor}}! ๐ŸŽ‰ Thank you for picking up this issue. Here is some context to get you started: {{specific_area}}. +> +> If you have questions during implementation, feel free to comment here. A maintainer will be available to help guide you through the process. + +Post via: + +1. `mcp_github_add_issue_comment` with the welcome and context. + +## Escalation Guidance + +Agents should involve human maintainers when: + +* Code of Conduct violations require judgment calls beyond template responses. +* De-escalation templates (Scenarios 18-19) prove insufficient to resolve the situation. +* Security reports require confidential triage and coordination. +* Contributor disputes involve technical direction decisions that need maintainer consensus. +* The agent cannot determine the appropriate response or scenario template. + +Escalation follows the role hierarchy defined in [GOVERNANCE.md](GOVERNANCE.md): Triage Contributor escalates to Maintainer, Maintainer escalates to Admin. Reference [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for behavioral standards. + +## Integration Instructions + +Community-facing agents and prompts reference these guidelines through the instruction file inheritance system: + +* Instruction files reference via `#file:./community-interaction.instructions.md`. +* Agents inherit guidelines transitively through their instruction file references. +* Templates are self-contained. Agents select the appropriate scenario and fill placeholders with values from the issue or PR context. +* Always post comments via `mcp_github_add_issue_comment` before or alongside closure API calls so the contributor sees the explanation in the issue timeline. diff --git a/.github/instructions/github-backlog-discovery.instructions.md b/.github/instructions/github-backlog-discovery.instructions.md new file mode 100644 index 00000000..2b7ed46e --- /dev/null +++ b/.github/instructions/github-backlog-discovery.instructions.md @@ -0,0 +1,234 @@ +--- +description: 'Discovery protocol for GitHub backlog management - artifact-driven, user-centric, and search-based issue discovery' +applyTo: '**/.copilot-tracking/github-issues/discovery/**' +maturity: experimental +--- + +# GitHub Backlog Discovery + +Discover GitHub issues through three paths: user-centric queries, artifact-driven analysis, or search-based exploration. Follow *github-backlog-planning.instructions.md* for templates, field definitions, and search protocols. + +## Scope + +**Inputs**: + +| Input | Required | Description | +| --------------------------- | -------- | ---------------------------------------------------------------- | +| `${input:owner}` | Yes | Repository owner, user or organization | +| `${input:repo}` | Yes | Repository name | +| `${input:milestone}` | No | Milestone name or number to scope searches | +| `${input:documents}` | No | File paths or URLs of source documents (PRDs, RFCs, ADRs) | +| `${input:searchTerms}` | No | Keywords or phrases to supplement extracted terms | +| `${input:includeSubIssues}` | No | Fetch sub-issues for each discovered issue (default: `false`) | + +**Discovery path selection**: + +* User-centric (Path A): User requests their issues, assigned work, or milestone progress without referencing artifacts +* Artifact-driven (Path B): Documents, PRDs, or requirements provided for translation into issues +* Search-based (Path C): User provides search terms directly without artifacts or assignment context + +**Output location**: `.copilot-tracking/github-issues/discovery//` where `` is a descriptive kebab-case slug derived from the discovery context (for example, `v2-features` or `security-audit`). + +## Deliverables + +| File | Path A | Path B | Path C | +| ---------------------- | ------ | ------ | ------ | +| *planning-log.md* | Yes | Yes | Yes | +| *issue-analysis.md* | No | Yes | No | +| *issues-plan.md* | No | Yes | No | +| *handoff.md* | No | Yes | No | +| Conversational summary | Yes | Yes | Yes | + +Paths A and C produce a conversational summary with counts and relevant issue links. Path B produces the full set of planning files per templates in *github-backlog-planning.instructions.md*. + +## Tooling + +**User-centric discovery (Path A)**: + +* `mcp_github_get_me`: Retrieve authenticated user details for assignee-based queries +* `mcp_github_search_issues`: Search with `assignee:` qualifier scoped to `repo:{owner}/{repo}` + * Key params: `query` (required), `owner`, `repo`, `perPage`, `page` +* `mcp_github_issue_read`: Hydrate results with `method: 'get'` for full details + * When `${input:includeSubIssues}` is true, also call with `method: 'get_sub_issues'` + +**Artifact-driven discovery (Path B)**: + +* `read_file`, `grep_search`: Read and parse source documents +* `mcp_github_get_me`: Verify access to the target repository +* `mcp_github_search_issues`: Execute keyword-group queries per the Search Protocol in *github-backlog-planning.instructions.md* +* `mcp_github_issue_read`: Hydrate results and fetch sub-issues when enabled +* `mcp_github_list_issue_types`: Retrieve valid issue types when the organization supports them + +**Search-based discovery (Path C)**: + +* `mcp_github_search_issues`: Execute user-provided terms scoped to `repo:{owner}/{repo}` +* `mcp_github_issue_read`: Hydrate results with `method: 'get'` for full details + +**Workspace utilities**: `list_dir`, `read_file`, `semantic_search` for artifact location and context gathering. + +## Required Phases + +### Phase 1: Discover Issues + +Select the appropriate discovery path based on user intent and available inputs. + +#### Path A: User-Centric Discovery + +Use when: + +* User requests "show me my issues", "what's assigned to me", or similar +* User asks about issues for a specific milestone or label scope +* No artifacts or documents are referenced + +Execution: + +1. Call `mcp_github_get_me` to determine the authenticated user. +2. Build a search query with `repo:{owner}/{repo} is:issue assignee:{username}`. Apply `milestone:` and `label:` qualifiers when `${input:milestone}` or label context is provided. +3. Execute `mcp_github_search_issues` and paginate until all results are retrieved. +4. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `${input:includeSubIssues}` is true, also fetch sub-issues. +5. Present results grouped by state and labels. +6. Log discovered issues in *planning-log.md* and deliver a conversational summary. +7. Skip Phases 2-3; no planning files are required for user-centric discovery. + +#### Path B: Artifact-Driven Discovery + +Use when: + +* Documents, PRDs, or requirements are provided via `${input:documents}` or conversation +* User explicitly requests issue creation or updates from artifacts + +Skip conditions: + +* No artifacts or documents are available; use Path A or Path C instead + +Execution: + +1. Create the planning folder at `.copilot-tracking/github-issues/discovery//`. +2. Call `mcp_github_get_me` to verify repository access. When the organization supports issue types, call `mcp_github_list_issue_types` with the `owner` parameter. +3. Read each document to completion and extract discrete requirements, acceptance criteria, and action items using the document parsing guidelines in this file. +4. Record each extracted requirement as a candidate issue entry in *issue-analysis.md* with: temporary ID, suggested title in conventional commit format, body summary, suggested labels, suggested milestone, and source reference. +5. Build keyword groups from extracted requirements per the Search Protocol in *github-backlog-planning.instructions.md*. +6. Compose GitHub search queries scoped to `repo:{owner}/{repo}`. Apply `milestone:` qualifier when `${input:milestone}` is provided. +7. Execute `mcp_github_search_issues` for each keyword group and paginate results. +8. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `${input:includeSubIssues}` is true, also fetch sub-issues. +9. Assess similarity between each fetched issue and the candidate set using the Similarity Assessment Framework in *github-backlog-planning.instructions.md*. Classify each pair as Match, Similar, Distinct, or Uncertain. +10. De-duplicate results across keyword groups; retain the highest similarity category when the same issue appears in multiple searches. +11. Log all progress in *planning-log.md* with search queries, result counts, and similarity assessments. +12. Continue to Phase 2. + +##### Document Parsing Guidelines + +Map document types and content patterns to issue attributes. + +| Document Type | Content Pattern | Suggested Label | Issue Type | +| ------------- | ------------------------- | ----------------- | ----------- | +| PRD | Feature requirement | `feature` | Feature | +| PRD | User story | `feature` | User story | +| BRD | Business enhancement | `enhancement` | Enhancement | +| ADR | Implementation task | `maintenance` | Task | +| ADR | Migration step | `breaking-change` | Task | +| RFC | Proposed capability | `feature` | Feature | +| Meeting notes | Action item | `maintenance` | Task | +| Security plan | Vulnerability remediation | `security` | Bug | +| Security plan | Hardening requirement | `security` | Enhancement | + +When a document section contains acceptance criteria, include them in the candidate issue body as a checklist. + +#### Path C: Search-Based Discovery + +Use when: + +* User provides search terms directly ("find issues about authentication") +* No artifacts, documents, or assignment context apply + +Execution: + +1. Call `mcp_github_get_me` to verify repository access. +2. Build search queries from `${input:searchTerms}` scoped to `repo:{owner}/{repo}`. Apply `milestone:` qualifier when `${input:milestone}` is provided. +3. Execute `mcp_github_search_issues` for each query and paginate results. +4. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `${input:includeSubIssues}` is true, also fetch sub-issues. +5. Present results grouped by state and labels. +6. Log discovered issues in *planning-log.md* and deliver a conversational summary. +7. Skip Phases 2-3; no planning files are required for search-based discovery. + +### Phase 2: Plan Issues + +Apply to artifact-driven discovery (Path B) only. + +#### Similarity-Based Actions + +| Category | Action | +| --------- | ------------------------------------------------------------------- | +| Match | Link candidate to existing issue; plan an Update if fields diverge | +| Similar | Flag for user review with a comparison summary | +| Distinct | Plan as a new issue | +| Uncertain | Request user guidance before proceeding | + +#### Hierarchy Grouping + +Group related requirements into parent-child structures. When a requirement decomposes into more than 5 sub-requirements, create an epic-level tracking issue as the parent and link individual issues as sub-issues. + +Issue title conventions: + +* Feature and enhancement titles follow conventional commit format (for example, `feat(scope): description`). +* Assign labels per the Label Taxonomy Reference in *github-backlog-planning.instructions.md*. +* Assign milestones per the Milestone Conventions in *github-backlog-planning.instructions.md*. + +#### New Issue Construction + +* Populate acceptance criteria as markdown checkbox lists when extracted from documents. +* Use `{{TEMP-N}}` placeholders for issues not yet created, per the Temporary ID Mapping convention in *github-backlog-planning.instructions.md*. +* Include source references (document path and section) in issue body content. + +#### Existing Issue Handling + +* Match: Plan an Update action; merge new requirements while preserving existing content. +* Resolved or closed items satisfying the requirement: Set action to No Change and note the relationship for traceability. + +Record all planned operations in *issues-plan.md* per templates in *github-backlog-planning.instructions.md*. + +### Phase 3: Assemble Handoff + +Apply to artifact-driven discovery (Path B) only. + +1. Build *handoff.md* per the template in *github-backlog-planning.instructions.md*. Order: Create entries first, Update second, Link third, Close fourth, No Change last. +2. Include checkboxes, summaries, relationships, and artifact references for each entry. +3. Add a Planning Files section with project-relative paths to all generated files. +4. Apply the Three-Tier Autonomy Model from *github-backlog-planning.instructions.md* to determine confirmation gates. When no tier is specified, default to Partial Autonomy. +5. Verify consistency across *issue-analysis.md*, *issues-plan.md*, and *handoff.md*. +6. Present the handoff for user review, highlighting items that trigger human review. +7. Record the final state in *planning-log.md* with phase completion status. + +## Human Review Triggers + +Pause and request user guidance when: + +* A requirement extracted from a document is ambiguous or contradicts another requirement. +* Multiple existing issues partially match a single candidate (two or more Similar results). +* A candidate implies a parent-child hierarchy, but the parent issue does not exist in the repository or candidate set. +* A candidate carries the `breaking-change` label, indicating potential release impact. +* The similarity assessment returns Uncertain for any pair. +* A planned operation changes an issue's milestone. + +Additional triggers are defined in the Human Review Triggers section of *github-backlog-planning.instructions.md*. + +## Cross-References + +These sections in *github-backlog-planning.instructions.md* inform discovery operations: + +| Section | Used In | Purpose | +| ------------------------------- | --------------- | ---------------------------------------------------- | +| Search Protocol | Phase 1, Path B | Keyword group construction and query composition | +| Similarity Assessment Framework | Phase 1, Path B | Classifying candidate-to-existing issue pairs | +| Planning File Templates | Phases 1-3 | Structure for all output files | +| Temporary ID Mapping | Phase 2 | `{{TEMP-N}}` placeholders for new issues | +| Three-Tier Autonomy Model | Phase 3 | Confirmation gates during handoff review | +| State Persistence Protocol | All phases | Context recovery after summarization | +| Issue Field Matrix | Phase 2 | Required and optional fields per operation type | +| Milestone Conventions | Phase 2 | EVEN/ODD versioning for milestone assignment | +| Label Taxonomy Reference | Phase 2 | Label selection and title pattern mapping | +| Human Review Triggers | Phase 3 | Additional conditions for pausing execution | + +--- + +Brought to you by microsoft/hve-core diff --git a/.github/instructions/github-backlog-planning.instructions.md b/.github/instructions/github-backlog-planning.instructions.md new file mode 100644 index 00000000..82c734c0 --- /dev/null +++ b/.github/instructions/github-backlog-planning.instructions.md @@ -0,0 +1,758 @@ +--- +description: 'Reference specification for GitHub backlog management tooling - planning files, search protocols, similarity assessment, and state persistence' +applyTo: '**/.copilot-tracking/github-issues/**' +maturity: experimental +--- + +# GitHub Backlog Planning File Instructions + +## Purpose and Scope + +Templates, field conventions, search protocols, and state persistence for GitHub backlog planning files. Workflow files must consume this specification by including a cross-reference at the top of their content. + +Cross-reference pattern for consuming files: + +```markdown +Follow all instructions from #file:./github-backlog-planning.instructions.md while executing this workflow. +``` + +Inline reference pattern when citing specific sections: + +```markdown +per templates in #file:./github-backlog-planning.instructions.md +using the matrix from #file:./github-backlog-planning.instructions.md +``` + +## GitHub MCP Tool Catalog + +Issue operations reference these MCP GitHub tools. + +### Discovery and Retrieval + +* `mcp_github_get_me`: Get authenticated user details. Agents should call this before operations requiring current user context. Key params: none. +* `mcp_github_list_issues`: List issues with filtering. Does not accept milestone or assignee filters; agents must use `mcp_github_search_issues` for those. Key params: `owner`, `repo`, `state`, `labels`, `since`, `direction`, `orderBy`, `perPage`, `after`. +* `mcp_github_search_issues`: Search issues with GitHub search syntax. Key params: `query` (required), `owner`, `repo`, `sort`, `order`, `perPage`, `page`. +* `mcp_github_issue_read`: Read issue details with multiple retrieval methods. Key params: `method` (required, one of: `get`, `get_comments`, `get_sub_issues`, `get_labels`), `owner`, `repo`, `issue_number`. +* `mcp_github_list_issue_types`: List supported issue types for an organization. Agents must call this before using the `type` param on `mcp_github_issue_write`. Key params: `owner`. +* `mcp_github_get_label`: Get label details for a repository. Key params: `owner`, `repo`, `name`. + +### Creation and Updates + +* `mcp_github_issue_write`: Create or update issues. Key params: `method` (required, one of: `create`, `update`), `owner`, `repo`, `title`, `body`, `labels`, `assignees`, `milestone`, `state`, `state_reason`, `type`, `duplicate_of`, `issue_number` (required for update). +* `mcp_github_add_issue_comment`: Add a comment to an issue or pull request. For community-facing comments, follow templates in the Community Communication section. Key params: `owner`, `repo`, `issue_number`, `body`. +* `mcp_github_assign_copilot_to_issue`: Assign Copilot coding agent to an issue. Key params: `owner`, `repo`, `issue_number`, `base_ref`, `custom_instructions`. + +### Relationships + +* `mcp_github_sub_issue_write`: Manage sub-issue relationships. Key params: `method` (required, one of: `add`, `remove`, `reprioritize`), `owner`, `repo`, `issue_number`, `sub_issue_id`, `after_id`, `before_id`. + +### Project Management + +* `mcp_github_search_pull_requests`: Search pull requests with GitHub search syntax. Key params: `query` (required), `owner`, `repo`, `sort`, `order`, `perPage`, `page`. +* `mcp_github_list_pull_requests`: List pull requests with filtering. Key params: `owner`, `repo`, `state`, `head`, `base`, `sort`, `direction`, `perPage`, `page`. +* `mcp_github_update_pull_request`: Update pull request metadata (title, body, state, base branch, reviewers, draft status). Does not support milestone, label, or assignee changes. Key params: `owner`, `repo`, `pullNumber`, `title`, `body`, `state`, `base`, `draft`, `reviewers`, `maintainer_can_modify`. + +### Pull Request Field Operations + +GitHub treats pull requests as a superset of issues sharing the same number space. The Issues API can read and write fields on pull requests that the Pull Requests API does not expose, including milestones, labels, and assignees. + +To set a milestone, labels, or assignees on a pull request, call `mcp_github_issue_write` with `method: 'update'` and pass the PR number as `issue_number`. The `mcp_github_update_pull_request` tool cannot set these fields. + +Common PR field operations via the Issues API: + +| Operation | Tool | Method | Key Fields | +| ----------------- | ------------------------------ | -------- | ------------------------------------------ | +| Set PR Milestone | `mcp_github_issue_write` | `update` | owner, repo, issue_number (PR#), milestone | +| Set PR Labels | `mcp_github_issue_write` | `update` | owner, repo, issue_number (PR#), labels | +| Set PR Assignees | `mcp_github_issue_write` | `update` | owner, repo, issue_number (PR#), assignees | +| Add Comment to PR | `mcp_github_add_issue_comment` | N/A | owner, repo, issue_number (PR#), body | + +> [!IMPORTANT] +> When setting milestones or labels on pull requests, always use `mcp_github_issue_write` with the PR number as `issue_number`. The `mcp_github_update_pull_request` tool does not accept milestone, label, or assignee parameters. + +### Community Communication + +When an operation produces a comment visible to external contributors, the comment body follows scenario templates from `community-interaction.instructions.md`. This applies to closure messages, information requests, acknowledgments, and redirects. + +| Operation | Scenario | Template Guidance | +| --------------- | ---------------------------------------------------- | ------------------------------------ | +| Close duplicate | Scenario 7: Closing a Duplicate Issue | Duplicate closure with original link | +| Close completed | Scenario 8: Closing a Completed Issue | Summary of resolution with thanks | +| Close won't-fix | Scenario 9: Closing a Won't-Fix Issue | Rationale with appreciation | +| Close stale | Scenario 10: Closing a Stale Issue | Neutral with reopen path | +| Request info | Scenario 14: Requesting More Information on an Issue | Specific questions with timeline | + +Apply the comment-before-closure pattern: call `mcp_github_add_issue_comment` with the appropriate scenario template before any state-changing call such as `mcp_github_issue_write` with closure. This ordering ensures contributors see the explanation before the issue closes. + +Internal-only operations (label changes, milestone assignment, sub-issue linking) that produce no visible comment do not require community interaction templates. + +## Planning File Definitions and Directory Conventions + +Root planning workspace structure: + +```text +.copilot-tracking/ + github-issues/ + / + / + issue-analysis.md + issues-plan.md + planning-log.md + handoff.md + handoff-logs.md +``` + +Valid `` values: + +* `discovery`: Issue discovery from artifacts, PRDs, or user requests +* `triage`: Issue triage, label assignment, and duplicate detection +* `sprint`: Sprint planning and milestone organization +* `backlog`: Backlog refinement and prioritization + +Normalization rules for ``: + +* Use lower-case, hyphenated form without extension (for example, `docs/Customer Onboarding PRD.md` becomes `docs--customer-onboarding-prd`). +* Replace spaces and punctuation with hyphens. +* Choose the primary artifact when multiple artifacts and documents are provided. +* For triage scopes, use the date as the scope name (for example, `2026-02-05`). +* For sprint scopes, use the milestone name (for example, `v2-2-0`). + +## Planning File Requirements + +Planning markdown files must start with: + +```markdown + + +``` + +Planning markdown files must end with (before the final newline): + +```markdown + +``` + +## Planning File Templates + +### issue-analysis.md + +Agents must create issue-analysis.md when beginning issue discovery from PRDs, user requests, or codebase artifacts. This file captures the human-readable analysis of planned issue operations before finalizing in issues-plan.md. + +Agents should populate sections by extracting requirements from referenced artifacts, searching GitHub for related issues, and incorporating user feedback. Agents should update the file iteratively as discovery progresses. + +Found Issue Field Values records the current state retrieved from GitHub for existing issues. Suggested Issue Field Values records all fields as they should appear after the planned operation. When creating a new issue, Found Issue Field Values should be omitted. + +#### Template + +````markdown +# [Planning Type] Issue Analysis - [Summarized Title] + +* **Artifact(s)**: [e.g., relative/path/to/artifact-a.md, relative/path/to/artifact-b.md] + * [(Optional) Inline Artifacts (e.g., User provided the following: [markdown block follows])] +* **Repository**: [owner/repo] +* **Milestone**: [(Optional) Milestone name] + +## Planned Issues + +### IS[Reference Number (e.g., 001)] - [one of, Create|Update|Link|Close|No Change] - [Summarized Issue Title] + +* **Working Title**: [Single line value (e.g., feat(agents): add batch triage support)] +* **Working Type**: [(Optional) Issue type if org supports issue types] +* **Key Search Terms**: [Keyword groups (e.g., "batch triage", "label automation", "needs-triage")] +* **Working Description**: + ```markdown + [Evolving description content constructed from artifacts and discovery] + ``` +* **Working Labels**: [Comma-separated labels (e.g., feature, agents)] +* **Working Milestone**: [(Optional) Milestone name (e.g., v2.2.0)] +* **Found Issue Field Values**: + * [Field (e.g., state)]: [Value (e.g., open)] + * [Field (e.g., labels)]: [Value (e.g., bug, needs-triage)] +* **Suggested Issue Field Values**: + * [Field (e.g., labels)]: [Value (e.g., feature, agents)] + * [Field (e.g., milestone)]: [Value (e.g., v2.2.0)] + +#### IS[Reference Number] - Related and Discovered Information + +* [(Optional) zero or more Requirements blocks (e.g., Related Requirements from relative/path/to/artifact-a.md)] + * [(Optional) one or more requirement line items (e.g., REQ-001: details of requirement)] +* [one or more Key Details blocks (e.g., Related Key Details from relative/path/to/artifact-b.md)] + * [one or more key detail line items (e.g., `Section 2.3` references dependency on data ingestion workflow)] +* [(Optional) zero or more Related Codebase blocks (e.g., Related Codebase Items Mentioned from User)] + * [(Optional) one or more related codebase line items (e.g., src/components/example.ts: update with related functionality)] +```` + +### issues-plan.md + +issues-plan.md is the source of truth for planned issue operations. Agents must capture the current `state` for every referenced issue, highlighting `closed` items. When a closed issue satisfies the requirement without updates, agents should keep the action as `No Change` and note the relationship. + +#### Template + +````markdown +# Issues Plan + +* **Repository**: [owner/repo] +* **Milestone**: [(Optional) Milestone name] + +## IS[Reference Number (e.g., 002)] - [Action (one of, Create|Update|Link|Close|No Change)] - [Summarized Title] + +[1-5 Sentence Explanation of Change (e.g., Adding issue for batch triage support called out in Section 2.3 of the referenced document)] + +[IS[Reference Number] - Similarity: [#issue_number=Category (e.g., #42=Similar, #38=Match, #55=Distinct)]] + +* IS[Reference Number] - issue_number: [#number or {{TEMP-N}}] +* IS[Reference Number] - title: [Issue title] +* IS[Reference Number] - state: [open|closed] +* IS[Reference Number] - labels: [comma-separated labels] +* IS[Reference Number] - milestone: [milestone name or none] +* IS[Reference Number] - assignees: [comma-separated usernames or none] + +### IS[Reference Number] - body + +```markdown +[Issue body content] +``` + +### IS[Reference Number] - Relationships + +* IS[Reference Number] - [Relationship Type (e.g., sub-issue-of, parent-of, linked-pr)] - [Target (e.g., #42, {{TEMP-1}})]: [Single line reason] +```` + +#### Example + +````markdown +# Issues Plan + +* **Repository**: microsoft/hve-core +* **Milestone**: v2.2.0 + +## IS002 - Update - Add batch label operations to triage workflow + +Updating existing issue to include batch label operations from Section 2.3. + +IS002 - Similarity: #38=Match, #55=Similar (titles align on triage workflow; #55 has broader scope) + +* IS002 - issue_number: #38 +* IS002 - title: feat(agents): add batch triage support +* IS002 - state: open +* IS002 - labels: feature, agents +* IS002 - milestone: v2.2.0 +* IS002 - assignees: WilliamBerryiii + +### IS002 - body + +```markdown +## Summary + +Add batch label operations to the triage workflow agent. + +## Acceptance Criteria + +* Batch apply labels to multiple issues in a single operation. +* Support undo of batch label changes. +``` + +### IS002 - Relationships + +* IS002 - sub-issue-of - #30: Triage workflow epic +```` + +### planning-log.md + +planning-log.md is a living document with sections that are routinely added, updated, extended, and removed in-place. + +Phase tracking applies when the consuming workflow file defines phases (see the workflow file's Required Phases section for phase definitions): + +* Agents must track all new, in-progress, and completed steps for each phase. +* Agents must update the Status section with in-progress review of completed and proposed steps. +* Agents must update Previous Phase when moving to any other phase (phases can repeat based on discovery needs). +* Agents must update Current Phase and Previous Phase when transitioning phases. + +#### Template + +````markdown +# [Planning Type] - Issue Planning Log + +* **Repository**: [owner/repo] +* **Milestone**: [(Optional) Milestone name] +* **Previous Phase**: [(Optional) (e.g., Phase-1, Phase-2, N/A, Just Started)] +* **Current Phase**: [(e.g., Phase-1, Phase-2, N/A, Just Started)] + +## Status + +[e.g., 3/10 issues searched, 1/5 docs reviewed, 2/8 issues planned] + +**Summary**: [e.g., Searching for existing issues based on keywords from PRD] + +## Discovered Artifacts and Related Files + +* AT[Reference Number (e.g., 001)] [relative/path/to/file] - [one of, Not Started|In-Progress|Complete] - [Processing|Related|N/A] + +## Discovered GitHub Issues + +* GH-[Issue Number (e.g., 42)] - [one of, Not Started|In-Progress|Complete] - [Processing|Related|N/A] + +## Issue Progress + +### **IS[Reference Number]** - [Label summary (e.g., feature, agents)] - [one of, In-Progress|Complete] + +* IS[Reference Number] - Issue Section (see issue-analysis.md) +* Working Search Keywords: [Working Keywords (e.g., "batch triage OR label automation")] +* Related GitHub Issues - Similarity: [#number=Category (Rationale) (e.g., #42=Similar (overlapping scope), #38=Match (same user goal))] +* Suggested Action: [one of, Create|Update|Link|Close|No Change] + +[Collected and Discovered Information] + +[Possible Issue Field Values] + +## Doc Analysis - issue-analysis.md + +### [relative/path/to/referenced/doc.ext] + +* IS[Reference Number] - Issue Section (see issue-analysis.md): [Summary of what was done] + +## GitHub Issues + +### GH-[Issue Number] + +[All content from mcp_github_issue_read method get] +```` + +#### Field Value Example + +````markdown +* Working `title`: feat(agents): add batch triage support +* Working `body`: + ```markdown + ## Summary + Add batch label operations to the triage workflow agent. + ``` +* Working `labels`: feature, agents +* Working `milestone`: v2.2.0 +```` + +### handoff.md + +Handoff file requirements: + +* Agents must include a reference to each issue defined in issues-plan.md. +* Agents must order entries with Create actions first, Update actions second, Link actions third, Close actions fourth, and No Change entries last. +* Agents must include a markdown checkbox next to each issue with a summary. +* Agents must include project-relative paths to all planning files. +* Agents must update the Summary section whenever the Issues section changes. + +Checkbox state semantics for execution consumption: + +* `- [ ]` (unchecked): Pending operation. The execution stage must process this entry. +* `- [x]` (checked): Completed operation. The execution stage must skip this entry during resumed execution. + +This convention enables resumable execution. When an execution run is interrupted and restarted, the execution stage reads checkbox states to determine which operations remain pending. + +#### Template + +```markdown +# GitHub Issue Operations Handoff + +## Planning Files + +* .copilot-tracking/github-issues///issue-analysis.md +* .copilot-tracking/github-issues///issues-plan.md +* .copilot-tracking/github-issues///planning-log.md +* .copilot-tracking/github-issues///handoff.md + +## Summary + +| Action | Count | +| --------- | ------------------ | +| Create | {{create_count}} | +| Update | {{update_count}} | +| Link | {{link_count}} | +| Close | {{close_count}} | +| No Change | {{no_change_count}} | + +## Issues + +### Create + +- [ ] {{title}} + - Labels: {{labels}}, Milestone: {{milestone}}, Assignee: {{assignee}} + - Body: {{summary}} + - Parent: #{{parent_issue_number}} (sub-issue link) + - Similarity: {{similarity_category}} to #{{existing_issue}}, {{rationale}} + +### Update + +- [ ] #{{issue_number}}: {{title}} + - Action: {{update_action}} + - Changes: {{field_changes}} + - Rationale: {{reason}} + +### Link (Sub-Issues) + +- [ ] Link #{{child}} as sub-issue of #{{parent}} + +### Close + +- [ ] Close #{{issue_number}} + - Reason: {{state_reason}} (completed|not_planned|duplicate) + - Duplicate of: #{{duplicate_of}} (if applicable) + +### No Change + +- [ ] (No Change) #{{issue_number}}: {{title}} + - {{rationale}} +``` + +### handoff-logs.md + +handoff-logs.md records per-issue processing results during execution. The execution workflow must create this file and append entries as each operation completes. + +#### Template + +```markdown +# GitHub Issue Operations Log + +## Execution Summary + +| Metric | Value | +| --------- | -------------- | +| Started | {{timestamp}} | +| Completed | {{timestamp}} | +| Succeeded | {{count}} | +| Failed | {{count}} | +| Skipped | {{count}} | + +## Operations + +### {{action}} - IS[Reference Number] - {{title}} + +* **Status**: [one of, Success|Failed|Skipped] +* **Issue Number**: #{{issue_number}} (or {{TEMP-N}} โ†’ #{{actual_number}}) +* **Action**: {{action}} +* **Details**: {{details}} +* **Error**: [(Optional) error message if failed] +* **Timestamp**: {{timestamp}} +``` + +## Search Protocol + +Goal: Deterministic, resumable discovery of existing GitHub issues. + +### Step 1: Build Keyword Groups + +Agents must build an ordered list where each group contains 1-4 specific terms (multi-word phrases allowed) joined by spaces or OR-equivalent constructs. + +Example keyword groups for a batch triage feature: + +* Group 1: `"batch triage" OR "bulk triage"` +* Group 2: `"label automation" OR "auto-label"` +* Group 3: `"needs-triage" OR "untriaged"` + +### Step 2: Compose GitHub Search Syntax + +Agents must format the `query` parameter for `mcp_github_search_issues`: + +```text +# Issues by keyword +repo:owner/repo is:issue "search term" + +# Issues by milestone +repo:owner/repo is:issue milestone:"v2.2.0" is:open + +# Issues by label combination +repo:owner/repo is:issue label:needs-triage label:enhancement + +# Issues with no milestone +repo:owner/repo is:issue no:milestone is:open + +# Issues by assignee +repo:owner/repo is:issue assignee:username is:open + +# Cross-label search for triage +repo:owner/repo is:issue label:needs-triage -label:bug -label:enhancement + +# Text search within issue bodies +repo:owner/repo is:issue "acceptance criteria" in:body is:open +``` + +### Step 3: Execute Search and Paginate + +Agents must execute `mcp_github_search_issues` with the constructed query and paginate results using `perPage` (max 100) and `page` parameters. + +Agents must filter results to identify candidates for similarity assessment: + +* Search results must contain terms matching the planned issue's core concepts. +* Issue state must align with the query intent (open for active work, any for comprehensive search). +* Issue must not already be tracked in the planning log. + +### Step 4: Hydrate Results + +For each candidate, agents must fetch full details using `mcp_github_issue_read` with method `get` and update planning-log.md under the Discovered GitHub Issues section. + +### Step 5: Assess Similarity + +Agents must perform similarity assessment for each candidate (see the Similarity Assessment Framework section). + +## Similarity Assessment Framework + +Analyze the relationship between a planned issue and each discovered issue through aspect-by-aspect comparison. + +### Comparison Aspects + +1. Compare titles to identify the core intent of each. Determine whether both describe the same goal or outcome. +2. Compare body content to determine whether both address the same problem or user need. Note scope differences. +3. Calculate label overlap between existing and proposed labels. High overlap is a strong signal of similarity. +4. Evaluate whether both issues target the same milestone or release scope. + +When a field is absent from the discovered issue: + +* Missing body: Agents should use title and labels to infer scope and must apply the Uncertain category when insufficient information remains. +* Missing labels: Agents should compare against title and body content only. Labels carry less weight in the assessment. +* Different issue types: Evaluate whether the planned issue should become a sub-issue of the discovered issue. + +### Similarity Categories + +| Category | Meaning | Action | +| --------- | -------------------------------------------------------- | ------------------------------- | +| Match | Same issue; creating both would duplicate effort | Update existing issue | +| Similar | Related enough that consolidation may be appropriate | Review with user before deciding | +| Distinct | Different issues with minimal overlap | Create new issue | +| Uncertain | Insufficient information or conflicting signals | Request user guidance | + +### Assessment Template + +For each comparison, record the assessment using this format: + +```markdown +### Issue Similarity Assessment + +| Aspect | Existing #{{number}} | Proposed Issue | Match Level | +| ---------------- | ------------------------ | ------------------------ | ------------------------ | +| Title | {{existing_title}} | {{proposed_title}} | {{High/Medium/Low/None}} | +| Body/Description | {{existing_summary}} | {{proposed_summary}} | {{High/Medium/Low/None}} | +| Labels | {{existing_labels}} | {{proposed_labels}} | {{overlap_count}}/{{total}} | +| Milestone | {{existing_milestone}} | {{proposed_milestone}} | {{Same/Different/None}} | + +**Category:** {{Match/Similar/Distinct/Uncertain}} +**Recommended Action:** {{Update existing/Create new/Needs review/Skip}} +**Rationale:** {{explanation}} +``` + +### Recording Similarity Assessments + +Record each assessment in planning-log.md under a Discovered GitHub Issues section with: + +* Issue number and title of the discovered issue +* Category assigned (Match, Similar, Distinct, or Uncertain) +* Brief rationale explaining the classification +* Recommended action based on the category + +Format: `GH-{number}: {Category} - {rationale}` + +Example: + +```markdown +## Discovered GitHub Issues + +* GH-42: Similar - Batch triage feature overlaps with label automation goals; scope is broader (full triage vs label-only) +* GH-55: Match - Same user goal for automated milestone assignment; existing issue covers planned scope +* GH-71: Distinct - Infrastructure CI pipeline is unrelated to triage workflow +``` + +## Human Review Triggers + +Agents must request user guidance when: + +* Either issue lacks a title or body +* Labels diverge significantly but titles align +* Cross-milestone items are discovered (planned issue targets one milestone, discovered issue targets another) +* Security-labeled issues are found (issues carrying `security` or `vulnerability` labels) +* Milestone-changing operations are proposed (moving an issue from one milestone to another) +* The relationship is genuinely ambiguous after analysis +* Similarity assessment yields Uncertain for more than two candidates against the same planned issue +* A planned Close action targets an issue with open sub-issues + +## Label Taxonomy Reference + +The repository uses 17 labels organized by purpose. Labels influence milestone assignment through the EVEN/ODD versioning strategy. + +| Label | Description | Versioning | +| ----------------- | -------------------------------------------- | --------------------------- | +| `bug` | Something is not working | EVEN (stable fix) | +| `feature` | New capability or functionality | ODD (pre-release) | +| `enhancement` | Improvement to existing functionality | EVEN or ODD | +| `documentation` | Improvements or additions to documentation | EVEN or ODD | +| `maintenance` | Chores, refactoring, dependency updates | EVEN (stable) | +| `security` | Security vulnerability or hardening | EVEN (stable, expedited) | +| `breaking-change` | Incompatible API or behavior change | ODD (pre-release only) | +| `needs-triage` | Requires label and milestone assignment | None (pre-assignment) | +| `duplicate` | This issue already exists | None (closed immediately) | +| `wontfix` | This will not be worked on | None (closed) | +| `good-first-issue`| Good for newcomers | EVEN or ODD | +| `help-wanted` | Extra attention is needed | EVEN or ODD | +| `question` | Further information is requested | None (informational) | +| `agents` | Related to agent files | EVEN or ODD | +| `prompts` | Related to prompt files | EVEN or ODD | +| `instructions` | Related to instructions files | EVEN or ODD | +| `infrastructure` | CI/CD, workflows, build tooling | EVEN (stable) | + +### Label-to-Title Pattern Mapping + +When issue titles follow conventional commit format, agents should map patterns to labels: + +| Issue Title Pattern | Suggested Labels | +| ----------------------- | --------------------------- | +| `feat(agents):` | feature, agents | +| `fix(scripts):` | bug | +| `chore(ci):` | maintenance, infrastructure | +| `refactor(workflows):` | maintenance | +| `docs(templates):` | documentation | +| No conventional pattern | needs-triage (retain) | + +## Milestone Conventions + +Milestones follow the EVEN/ODD versioning strategy: + +* **EVEN milestones** (v2.0, v2.2.0, v4.0): Stable releases. Bug fixes, security patches, maintenance, documentation, and low-risk enhancements. +* **ODD milestones** (v1.0, v2.3.0, v3.0): Pre-release and development. New features, breaking changes, experimental capabilities, and high-risk enhancements. + +### Milestone Assignment Recommendations + +| Issue Characteristic | Recommended Milestone | +| --------------------------------- | --------------------- | +| Bug fix (production) | Current EVEN | +| Security vulnerability | Current EVEN (expedited) | +| Maintenance and refactoring | Current EVEN | +| Documentation improvement | Current EVEN | +| New feature | Next ODD | +| Breaking change | Next ODD | +| Experimental capability | Next ODD | +| Infrastructure improvement | Current EVEN | +| Low-risk enhancement | Current EVEN | +| High-risk enhancement | Next ODD | + +When uncertain about milestone assignment, agents should default to the next ODD milestone and flag for human review. + +## Issue Field Matrix + +Track field usage explicitly so downstream automation can rely on consistent data. The matrix defines required and optional fields per operation type. These field requirements apply to both issues and pull requests. When targeting a pull request, pass the PR number as `issue_number` (see the Pull Request Field Operations section in the MCP Tool Catalog). + +| Field | Create | Update | Link | Close | +| ------------- | -------- | -------- | -------- | -------- | +| title | REQUIRED | Optional | N/A | N/A | +| body | REQUIRED | Optional | N/A | N/A | +| labels | REQUIRED | Optional | N/A | N/A | +| assignees | Optional | Optional | N/A | N/A | +| milestone | Optional | Optional | N/A | N/A | +| issue_number | N/A | REQUIRED | REQUIRED | REQUIRED | +| state | N/A | Optional | N/A | REQUIRED | +| state_reason | N/A | N/A | N/A | REQUIRED | +| sub_issue_id | N/A | N/A | REQUIRED | N/A | +| duplicate_of | N/A | N/A | N/A | Optional | +| type | Optional | Optional | N/A | N/A | + +Rules: + +* Create operations must provide title, body, and at least one label. +* Update operations must provide issue_number and at least one field to change. +* Link operations must provide both issue_number (parent) and sub_issue_id (child). +* Close operations must provide issue_number, state set to `closed`, and a state_reason (one of: `completed`, `not_planned`, `duplicate`). +* When closing as `duplicate`, the `duplicate_of` field should reference the original issue number. +* Call `mcp_github_list_issue_types` before using the `type` field to confirm the organization supports issue types. + +## Three-Tier Autonomy Model + +The autonomy model controls confirmation gates during issue operations. The consuming workflow file must specify the active tier. When no tier is specified, agents should default to Partial Autonomy. + +### Full Autonomy + +No confirmation gates. Agents must execute all operations autonomously. + +* Agents must create issues without user confirmation. +* Agents must update issues without user confirmation. +* Agents must establish sub-issue links without user confirmation. +* Agents must close issues without user confirmation. +* Suitable for well-defined, low-risk batch operations with high-confidence similarity assessments. + +### Partial Autonomy + +Gate on create and close operations. Auto-execute updates and links. + +* Create operations: Agents must present the planned issue for user review before executing. +* Close operations: Agents must present the close rationale for user review before executing. +* Update operations: Agents must execute without confirmation. +* Link operations: Agents must execute without confirmation. +* Suitable for most TPM workflows where creation and deletion carry higher risk. + +### Manual + +Gate on all operations. Agents must present each for confirmation. + +* Create operations: Agents must present for user review. +* Update operations: Agents must present for user review. +* Link operations: Agents must present for user review. +* Close operations: Agents must present for user review. +* Suitable for sensitive backlogs, unfamiliar repositories, or first-time pipeline execution. + +## Temporary ID Mapping + +Handoff files use `{{TEMP-N}}` placeholders for planned issues that do not yet exist. The execution stage maintains a mapping table as issues are created, resolving references in subsequent operations. + +Placeholder format: `{{TEMP-1}}`, `{{TEMP-2}}`, `{{TEMP-3}}`, incrementing sequentially. + +During execution, resolve each placeholder to the actual issue number returned by `mcp_github_issue_write`: + +```text +{{TEMP-1}} โ†’ #42 (created) +{{TEMP-2}} โ†’ #43 (created) +{{TEMP-3}} โ†’ #44 (created) +``` + +Resolution rules: + +* Agents must create parent issues before child issues so that parent issue numbers are available for sub-issue linking. +* When a `{{TEMP-N}}` reference appears in a sub-issue link operation, agents must resolve it from the mapping table before calling `mcp_github_sub_issue_write`. +* Agents must record the mapping in handoff-logs.md as each issue is created. +* If a `{{TEMP-N}}` reference cannot be resolved (creation failed), agents must skip dependent operations and log the failure. + +## State Persistence Protocol + +Agents must update planning-log.md as information is discovered to ensure continuity when context is summarized. + +### Pre-Summarization Capture + +Before summarization occurs, agents must capture in planning-log.md: + +* Full paths to all working files with a summary of each file's purpose +* Any uncaptured information that belongs in planning files +* Issue numbers already reviewed +* Issue numbers pending review +* Current phase and remaining steps +* Outstanding search criteria + +### Post-Summarization Recovery + +VS Code Copilot periodically compresses conversation history into a `` block when the context window approaches capacity. When the recovered context contains a `` block with only one tool call, agents must recover state before continuing: + +1. List the working folder with `list_dir` under `.copilot-tracking/github-issues///`. +2. Read planning-log.md to rebuild context. +3. Notify the user that context is being rebuilt and confirm the approach before proceeding. + +Recovery notification format: + +```markdown +## Resuming After Context Summarization + +Context history was summarized. Rebuilding from planning files: + +**Analyzing**: [planning-log.md summary] + +Next steps: +* [Planned actions] + +Proceed with this approach? +``` + +--- + +Brought to you by microsoft/hve-core diff --git a/.github/instructions/github-backlog-triage.instructions.md b/.github/instructions/github-backlog-triage.instructions.md new file mode 100644 index 00000000..17ff6095 --- /dev/null +++ b/.github/instructions/github-backlog-triage.instructions.md @@ -0,0 +1,302 @@ +--- +description: 'Triage workflow for GitHub issue backlog management - automated label suggestion, milestone assignment, and duplicate detection' +applyTo: '**/.copilot-tracking/github-issues/triage/**' +maturity: experimental +--- + +# GitHub Backlog Triage Instructions + +## Purpose and Scope + +This workflow analyzes untriaged GitHub issues, suggests labels based on conventional commit title patterns, assigns milestones using the EVEN/ODD versioning strategy, and detects duplicates through similarity assessment. + +Follow all instructions from #file:./github-backlog-planning.instructions.md while executing this workflow. + +Follow community interaction guidelines from #file:./community-interaction.instructions.md when posting comments visible to external contributors. + +## Inputs + +* `${input:owner}`: (Required) Repository owner (username or organization). +* `${input:repo}`: (Required) Repository name. +* `${input:maxIssues:20}`: (Optional, defaults to 20) Maximum number of untriaged issues to process per batch. +* `${input:milestone}`: (Optional) Override milestone name. When provided, skip milestone discovery and use this value for all non-duplicate issues. +* `${input:autonomy:partial}`: (Optional, defaults to partial) Autonomy tier controlling confirmation gates. Values: `full`, `partial`, `manual`. See the Three-Tier Autonomy Model in the planning specification. + +### Autonomy Behavior for Triage Operations + +| Operation | Full | Partial | Manual | +| -------------------- | ------------ | ------------ | ------------ | +| Label assignment | Auto-execute | Auto-execute | Gate on user | +| Milestone assignment | Auto-execute | Auto-execute | Gate on user | +| Duplicate closure | Auto-execute | Gate on user | Gate on user | +| needs-triage removal | Auto-execute | Auto-execute | Gate on user | + +## Required Phases + +### Phase 1: Analyze + +Fetch and analyze untriaged issues to build a comprehensive triage assessment. Proceed to Phase 2 when all fetched issues have been analyzed and recorded. + +#### Step 1: Discover Available Milestones + +Before analyzing issues, determine the current EVEN and next ODD milestones. When `${input:milestone}` is provided, skip this step and use the override value. + +1. Search for recent issues with milestone assignments using `mcp_github_search_issues` to identify active milestone names. +2. Derive the current EVEN milestone and next ODD milestone from the discovered names. +3. Record the discovered milestones in planning-log.md for reference during analysis. + +When milestone discovery yields no results, prompt the user for milestone names before proceeding. + +#### Step 2: Fetch Untriaged Issues + +Search for issues carrying the `needs-triage` label using `mcp_github_search_issues` with the following query pattern: + +```text +repo:{owner}/{repo} is:issue is:open label:needs-triage +``` + +Paginate results using `perPage` and `page` parameters, limiting to `${input:maxIssues}` total issues. + +When no untriaged issues are found, inform the user and end the workflow. No further phases apply. + +#### Step 3: Hydrate Issue Details + +For each returned issue, fetch full details using `mcp_github_issue_read` with `method: 'get'` to retrieve body content, existing labels, and current milestone. Also fetch current labels using `mcp_github_issue_read` with `method: 'get_labels'` to capture the complete label set for each issue. + +#### Step 4: Analyze Each Issue + +For each untriaged issue, perform the following analysis: + +1. Parse the title against the conventional commit title pattern mapping table to determine suggested type labels. +2. Extract scope keywords from `type(scope):` patterns and map them to scope labels. Scope extraction applies to all conventional commit types, not only specific patterns. +3. Examine the body content for additional context: + * Identify scope indicators not captured by the title pattern (file paths, directory references, component names). + * Note acceptance criteria that inform priority assessment. + * Extract technical context that clarifies issue intent for similarity comparison. +4. Review existing labels for conflicts or gaps (for example, an issue labeled `enhancement` with a `fix:` title prefix). +5. Search for potential duplicates using the similarity assessment framework per templates in the planning specification. +6. Evaluate milestone fit based on the EVEN/ODD strategy and the priority assessment criteria defined in this file. + +#### Step 5: Record Analysis + +Create planning-log.md in `.copilot-tracking/github-issues/triage/{{YYYY-MM-DD}}/` to track progress. Update the log as each issue is analyzed, recording: + +* Issue number and title +* Current labels (from hydration) +* Suggested labels with rationale +* Suggested milestone with rationale +* Duplicate candidates with similarity category +* Priority assessment result + +### Phase 2: Plan + +Produce a triage plan for user review and execute confirmed recommendations. This phase completes when all confirmed recommendations have been applied and planning-log.md reflects final state. + +#### Step 1: Generate Triage Plan + +Create triage-plan.md in `.copilot-tracking/github-issues/triage/{{YYYY-MM-DD}}/` with a recommendation row per issue. Use the triage plan template defined in the Output section of this file. + +#### Step 2: Present for Review + +Present the triage plan to the user, highlighting: + +* Issues with high-confidence label and milestone suggestions +* Issues flagged as potential duplicates +* Issues requiring manual review (ambiguous titles, conflicting labels, uncertain similarity) + +When `${input:autonomy}` is `full`, proceed directly to Step 3 without waiting for user confirmation. When `partial`, gate on duplicate closures only. When `manual`, wait for user confirmation of the entire plan. + +#### Step 3: Execute Confirmed Recommendations + +On user confirmation (or immediately under full autonomy), apply the approved recommendations. + +For non-duplicate issues, consolidate label assignment, milestone assignment, and `needs-triage` removal into a single API call per issue: + +1. Compute the new label set: `(current_labels - "needs-triage") + suggested_labels`. +2. Call `mcp_github_issue_write` with `method: 'update'`, `labels: [computed_set]`, and `milestone: suggested_milestone`. + +The `labels` parameter uses replacement semantics. The computed set MUST include all labels to retain, all suggested labels to add, and MUST exclude `needs-triage`. + +For confirmed duplicates, apply the comment-before-closure pattern: + +1. Post a comment using `mcp_github_add_issue_comment` with the Scenario 7 (Closing a Duplicate Issue) template from `community-interaction.instructions.md`, filling `{{original_number}}` with the matched issue number. +2. Close the issue using `mcp_github_issue_write` with `method: 'update'`, `state: 'closed'`, `state_reason: 'duplicate'`, and `duplicate_of` set to the original issue number. + +For linked pull requests, propagate the milestone assignment to each associated PR: + +1. Search for PRs referencing the issue by calling `mcp_github_search_pull_requests` with query `repo:{owner}/{repo} {issue_number}` to find PRs that mention the issue number in their title or body. +2. Inspect the issue body and comments via `mcp_github_issue_read` with `method: 'get'` and `method: 'get_comments'` for PR references (GitHub PR URLs or `#N` cross-references) that the search may have missed. +3. For each discovered PR missing the target milestone, call `mcp_github_issue_write` with `method: 'update'`, passing the PR number as `issue_number` and `milestone: suggested_milestone`. + +The Issues API accepts PR numbers because GitHub treats pull requests as a superset of issues sharing the same number space (see the Pull Request Field Operations section in the planning specification). + +Group issues by suggested label when multiple issues share the same recommendation to maintain batch efficiency. Update planning-log.md checkboxes as each operation completes. + +## Conventional Commit Title Pattern to Label Mapping + +When issue titles follow conventional commit format, map patterns to labels using this table. + +| Title Pattern | Suggested Labels | Description | +| --------------------------------- | --------------------------------- | ----------------------- | +| `feat:` or `feat(scope):` | `feature` | New functionality | +| `fix:` or `fix(scope):` | `bug` | Bug fix | +| `docs:` or `docs(scope):` | `documentation` | Documentation change | +| `chore:` or `chore(scope):` | `maintenance` | Maintenance task | +| `refactor:` | `maintenance` | Code refactoring | +| `test:` | `maintenance` | Test changes | +| `ci:` | `maintenance`, `infrastructure` | CI/CD changes | +| `perf:` | `enhancement` | Performance improvement | +| `style:` | `maintenance` | Code style changes | +| `build:` | `infrastructure` | Build system changes | +| `security:` | `security` | Security fix | +| `breaking:` or `BREAKING CHANGE` | `breaking-change` | Breaking change | + +When a title does not match any conventional commit pattern, retain the `needs-triage` label and flag the issue for manual review. + +## Scope Keyword to Scope Label Mapping + +Extract scope keywords from the conventional commit title pattern `type(scope):` and map them to scope labels. + +| Scope Keyword | Scope Label | +| ---------------- | -------------- | +| `(agents)` | `agents` | +| `(prompts)` | `prompts` | +| `(instructions)` | `instructions` | + +Additional scope keywords MAY be mapped when they align with the label taxonomy defined in the planning specification. Scope keywords not present in the taxonomy (for example, `scripts`, `ci`, `workflows`, `templates`) SHOULD be noted in the analysis log as body context rather than assigned as labels. + +## Milestone Recommendation + +Milestone assignment follows the EVEN/ODD versioning strategy defined in the planning specification. Apply these recommendations based on issue characteristics. + +| Issue Characteristic | Recommended Milestone | Rationale | +| --------------------------- | -------------------------- | ---------------------------------------------- | +| Bug fix | Current EVEN (stable) | Stable releases receive production fixes | +| Security fix | Current EVEN (expedited) | Security patches ship in the nearest stable release | +| Maintenance or refactoring | Current EVEN (stable) | Low-risk changes stabilize in EVEN releases | +| Documentation improvement | Current EVEN (stable) | Documentation ships with stable releases | +| New feature | Next ODD (pre-release) | Features incubate in pre-release milestones | +| Breaking change | Next major milestone | Breaking changes require a major version bump | +| Infrastructure improvement | Current EVEN (stable) | CI/CD and build changes stabilize in EVEN releases | + +When uncertain about milestone assignment, default to the next ODD milestone and flag the issue for human review. + +## Duplicate Detection + +For each untriaged issue, search for potential duplicates using the similarity assessment framework from the planning specification. + +### Search Strategy + +Build search queries from the issue title and body: + +1. Extract 2-4 keyword groups from the issue title. +2. Execute `mcp_github_search_issues` for each keyword group scoped to the repository. +3. Assess similarity of returned results against the untriaged issue using the assessment template from the planning specification. + +### Duplicate Resolution + +| Similarity Category | Action | +| ------------------- | ---------------------------------------------------------------------- | +| Match | Suggest closing the untriaged issue as duplicate with a reference to the original. | +| Similar | Flag both issues for user review with a comparison summary. | +| Distinct | Proceed with label and milestone assignment. | +| Uncertain | Request user guidance before taking action. | + +When a Match is found, record the original issue number in the triage plan for the `duplicate_of` field. The Close operation MUST include `state_reason: 'duplicate'` per the issue field matrix in the planning specification. + +Duplicate closure follows the comment-before-closure pattern: + +1. Post a comment using `mcp_github_add_issue_comment` with the Scenario 7 (Closing a Duplicate Issue) template from `community-interaction.instructions.md`, filling `{{original_number}}` with the matched issue number. +2. Close the issue using `mcp_github_issue_write` with `method: 'update'`, `state: 'closed'`, `state_reason: 'duplicate'`, and `duplicate_of` set to the original issue number. + +## Priority Assessment + +Assess priority based on the suggested label to determine triage ordering. Process higher-priority issues first. + +| Priority | Label(s) | Handling | +| -------- | ------------------------------ | ------------------------------------------------ | +| Highest | `security` | Flag for immediate attention. Assign to current EVEN milestone with expedited notation. | +| High | `bug` | Assign to current EVEN milestone. Prioritize in triage plan. | +| Normal | `feature`, `enhancement` | Assign to appropriate milestone per EVEN/ODD strategy. | +| Lower | `documentation`, `maintenance` | Assign to current EVEN milestone. Process after higher-priority items. | + +Issues with the `breaking-change` label SHOULD be escalated to the user regardless of other labels, as breaking changes affect release planning. + +## Error Handling + +Handle API failures and edge cases during triage execution: + +* When a label or milestone update fails due to rate limiting, log the failure in planning-log.md and retry after the rate limit window resets. Continue processing remaining issues. +* When `mcp_github_issue_write` returns a validation error (for example, an invalid milestone name), log the error, skip the affected issue, and flag it for manual review in the triage plan. +* When `mcp_github_search_issues` returns no results for a duplicate search query, record "no duplicates found" and proceed with label and milestone assignment. +* When an issue has been modified between analysis and execution (labels or state changed externally), re-fetch the issue details before applying updates to avoid overwriting concurrent changes. +* When the comment step of a comment-before-closure pattern fails, log the failure in planning-log.md and proceed with the closure call. The closure carries the authoritative state change; the comment provides contributor context. + +## Output + +The triage workflow produces output files in `.copilot-tracking/github-issues/triage/{{YYYY-MM-DD}}/`. + +### triage-plan.md Template + +Planning markdown files MUST start and end with the directives defined in the planning specification. + +```markdown + + +# Triage Plan - {{YYYY-MM-DD}} + +* **Repository**: {{owner}}/{{repo}} +* **Issues Analyzed**: {{count}} +* **Date**: {{YYYY-MM-DD}} + +## Summary + +| Action | Count | +| --------------- | ------------------ | +| Label + Assign | {{label_count}} | +| Close Duplicate | {{duplicate_count}} | +| Manual Review | {{review_count}} | + +## Triage Recommendations + +| Issue | Title | Suggested Labels | Suggested Milestone | Duplicates Found | Priority | Action | +| ----- | ----- | ---------------- | ------------------- | ---------------- | -------- | ------ | +| #{{number}} | {{title}} | {{labels}} | {{milestone}} | {{duplicate_refs}} | {{priority}} | {{action}} | + +## Issues Requiring Manual Review + +### #{{number}}: {{title}} + +* **Reason**: {{reason for manual review}} +* **Current Labels**: {{existing_labels}} +* **Suggested Labels**: {{suggested_labels}} +* **Notes**: {{additional context}} + +## Duplicate Pairs + +### #{{untriaged_number}} duplicates #{{original_number}} + +* **Similarity Category**: Match +* **Rationale**: {{explanation}} +* **Recommended Action**: Close #{{untriaged_number}} as duplicate of #{{original_number}} + +``` + +### planning-log.md + +Use the planning-log.md template from the planning specification. Set the planning type to `Triage` and track each issue through analysis, planning, and execution. + +## Success Criteria + +Triage is complete when: + +* All fetched issues (up to `${input:maxIssues}`) with the `needs-triage` label have been analyzed for label suggestions, milestone recommendations, and duplicate candidates. +* A triage-plan.md exists with a recommendation row for every analyzed issue. +* The user has reviewed and confirmed (or adjusted) the triage plan, respecting the active autonomy tier. +* Confirmed recommendations have been executed via consolidated API calls (labels assigned, milestones set, `needs-triage` removed, duplicates closed). +* planning-log.md reflects the final state of all operations with checkboxes marking completion. +* Any failed operations have been logged and either retried or flagged for manual follow-up. + +--- + +Brought to you by microsoft/hve-core diff --git a/.github/instructions/github-backlog-update.instructions.md b/.github/instructions/github-backlog-update.instructions.md new file mode 100644 index 00000000..fc328be7 --- /dev/null +++ b/.github/instructions/github-backlog-update.instructions.md @@ -0,0 +1,226 @@ +--- +description: 'Execution workflow for GitHub issue backlog management - consumes planning handoffs and executes issue operations' +applyTo: '**/.copilot-tracking/github-issues/**/handoff-logs.md' +maturity: experimental +--- + +# GitHub Backlog Update Instructions + +Follow all instructions from #file:./github-backlog-planning.instructions.md for planning file templates, field definitions, search protocols, and state persistence. + +Follow community interaction guidelines from #file:./community-interaction.instructions.md when posting comments visible to external contributors. + +## Purpose and Scope + +The execution protocol processes a handoff plan file to create, update, link, and close GitHub issues in batch. The workflow consumes handoff.md (or triage-plan.md) produced by the discovery or triage workflows and executes planned operations against the GitHub API via MCP tools. + +All operations MUST execute sequentially. Parallel execution is not supported due to dependency chains between Create, Link, and Update operations. + +### Inputs + +* `${input:handoffFile}`: Path to handoff.md or triage-plan.md containing planned issue operations (required) +* `${input:owner}`: Repository owner (inferred from handoff file if not provided) +* `${input:repo}`: Repository name (inferred from handoff file if not provided) +* `${input:autonomy}`: Autonomy tier controlling confirmation gates (one of: `full`, `partial`, `manual`; defaults to `partial`) +* `${input:dryRun}`: When `true`, simulate all operations without executing (defaults to `false`) + +### Outputs + +* handoff-logs.md created next to ${input:handoffFile} containing per-operation processing status and results +* Issues created, updated, linked, or closed in the target GitHub repository + +### Trigger Conditions + +These instructions apply when processing issue operations from a handoff.md or triage-plan.md file through MCP GitHub tool calls. + +## Issue Hierarchy + +Issues follow a parent-child hierarchy via sub-issue relationships: + +1. Epic or tracking issue (top level) +2. Individual issues (children of tracking issue) +3. Sub-tasks (children of individual issues) + +Parent issues MUST be created before children to ensure sub-issue linking resolves correctly. + +## Required Steps + +### Step 1: Initialize or Resume + +When handoff-logs.md exists next to ${input:handoffFile}: + +* Read handoff-logs.md and ${input:handoffFile}. +* Identify operations with unchecked `[ ]` status. +* Rebuild the temporary ID mapping from previously completed Create entries (the Issue Number field in each completed log entry records the `{{TEMP-N}}` to `#actual` mapping). +* Resume processing in priority order: Create โ†’ Update โ†’ Link โ†’ Close, starting from the first unchecked operation in that sequence. + +When handoff-logs.md does not exist: + +* Create handoff-logs.md using the template from #file:./github-backlog-planning.instructions.md. +* Populate the Operations section from ${input:handoffFile}. +* Record all inputs in the Execution Summary section. + +Validate the handoff before processing: + +* Confirm ${input:owner} and ${input:repo} are set (from inputs or parsed from the handoff file header). +* Verify all numeric issue references exist by calling `mcp_github_issue_read` with method `get` for each number. Skip `{{TEMP-N}}` placeholders during this validation since those issues do not exist yet. +* Verify label names are valid by calling `mcp_github_get_label` for each unique label in the plan. +* Call `mcp_github_list_issue_types` to confirm whether the organization supports issue types before using the `type` field. +* Map `{{TEMP-N}}` placeholders to execution order so parent issues are created before children that reference them. +* When validation fails for a non-critical field (invalid label, unknown milestone), log a warning and continue. When validation fails for a critical field (missing repository, authentication error), abort with a message. + +### Step 2: Process Operations + +Process operations in this fixed order, matching the handoff.md template sections: + +1. Create all issues (parents first, then children) via `mcp_github_issue_write` with method `create`. Each Create MUST include title, body, and at least one label per the Issue Field Matrix in #file:./github-backlog-planning.instructions.md. +2. Update existing issues via `mcp_github_issue_write` with method `update`. +3. Link sub-issues via `mcp_github_sub_issue_write` with method `add`, using `issue_number` for the parent and `sub_issue_id` for the child. +4. Close duplicate or resolved issues via `mcp_github_issue_write` with `state: 'closed'` and the appropriate `state_reason`. +5. Add comments for context via `mcp_github_add_issue_comment`. + +Checkpoint after each operation completes: + +* Check the autonomy tier to determine whether a confirmation gate is required. Refer to the Three-Tier Autonomy Model in #file:./github-backlog-planning.instructions.md for gate definitions. When the user declines a gated operation, mark it as `Skipped` in handoff-logs.md and continue. +* When `${input:dryRun}` is `true`, simulate the operation and log it as `dry-run` without executing (see the Dry Run Mode section). +* After each Create, resolve the `{{TEMP-N}}` placeholder to the actual issue number returned by `mcp_github_issue_write`. Record the mapping in handoff-logs.md. +* When a `{{TEMP-N}}` reference appears in a Link or Update operation, resolve it from the mapping table before calling the MCP tool. +* Update the checkbox to `[x]` in handoff.md after each operation completes. +* Append an entry to handoff-logs.md recording the issue number, action taken, and any notes. +* On failure, log the error and continue processing remaining operations. Do not abort the batch for a single failure. + +When an operation has no pending changes: + +* Mark the checkbox as `[x]` in handoff.md with a note: "No changes required." +* Skip API calls for that item. +* Continue to the next operation in the processing queue. + +### Step 3: Finalize and Report + +* Re-read handoff-logs.md and compare against ${input:handoffFile}. +* Process any missed operations that were skipped due to dependency failures and have since been unblocked. Limit this retry pass to one additional iteration; log any operations still blocked after the retry as `Failed`. +* Cross-check created issues against the plan to confirm all `{{TEMP-N}}` placeholders resolved. +* Generate a handoff summary with counts: issues created, updated, closed, linked, failed, and skipped. +* Provide a completion report listing all processed items with issue numbers. + +## Supported Operations + +| Operation | MCP Tool | Method | Required Fields | +| ---------------- | ------------------------------ | -------- | ------------------------------------------------ | +| Create | `mcp_github_issue_write` | `create` | owner, repo, title, body, labels | +| Update | `mcp_github_issue_write` | `update` | owner, repo, issue_number | +| Close | `mcp_github_issue_write` | `update` | owner, repo, issue_number, state, state_reason | +| Add Labels | `mcp_github_issue_write` | `update` | owner, repo, issue_number, labels | +| Set Milestone | `mcp_github_issue_write` | `update` | owner, repo, issue_number, milestone | +| Add Sub-issue | `mcp_github_sub_issue_write` | `add` | owner, repo, issue_number, sub_issue_id | +| Add Comment | `mcp_github_add_issue_comment` | N/A | owner, repo, issue_number, body | +| Set PR Milestone | `mcp_github_issue_write` | `update` | owner, repo, issue_number (PR number), milestone | +| Set PR Labels | `mcp_github_issue_write` | `update` | owner, repo, issue_number (PR number), labels | +| Set PR Assignees | `mcp_github_issue_write` | `update` | owner, repo, issue_number (PR number), assignees | + +Pull request field operations use `mcp_github_issue_write` because GitHub treats pull requests as a superset of issues sharing the same number space. Pass the PR number as `issue_number` to set milestones, labels, or assignees on a pull request. The `mcp_github_update_pull_request` tool does not support these fields. + +When an operation produces community-visible output (closing issues, requesting information, acknowledging contributions), follow the scenario templates in #file:./community-interaction.instructions.md. Apply the comment-before-closure pattern: call `mcp_github_add_issue_comment` with the appropriate scenario template before any state-changing call such as `mcp_github_issue_write` with closure. + +Refer to the Issue Field Matrix and Pull Request Field Operations sections in #file:./github-backlog-planning.instructions.md for complete field requirements per operation type. + +## Error Handling + +Each error scenario describes the expected behavior. Unrecognized errors SHOULD be logged and processing SHOULD continue with remaining operations. + +### Failed Create + +Log the error in handoff-logs.md with `Failed` status. Skip dependent child issues and sub-issue links that reference the failed parent. Continue processing remaining operations. + +### Failed Update + +Log the error in handoff-logs.md with `Failed` status. Continue processing remaining operations. + +### Issue Not Found (404) + +When an Update, Close, or Link operation targets an issue that no longer exists, log the error in handoff-logs.md with `Failed` status and continue. This can occur when an issue is deleted between planning and execution. + +### Rate Limit (429) + +Pause and retry up to three times with exponential backoff. Note the delay in handoff-logs.md. If retries are exhausted, log the error and continue with remaining operations. + +### Authentication or Permission Error (401/403) + +Abort processing and notify the user. Do not retry authentication errors. + +### Invalid Label + +Log a warning in handoff-logs.md. Skip the invalid label and continue applying other field changes. + +### Invalid Milestone + +Log a warning in handoff-logs.md. Skip the milestone assignment and continue applying other field changes. + +### Missing Parent for Sub-issue Link + +Leave the Link operation unchecked with a `Pending: parent` note. Revisit during the Step 3 retry pass. + +### Transient Network Failure + +Retry up to three times with exponential backoff. If failures persist, log the error and continue with remaining operations. + +## Conversation Guidance + +### Internal Operator Updates + +Keep the user informed during processing: + +* Use markdown formatting with proper paragraph spacing. +* Use emojis sparingly to indicate status (success, warning, error). +* Provide brief updates after each operation completes. +* Avoid overwhelming the user with verbose output; summarize progress at natural checkpoints (after all Creates, after all Updates, and so on). + +### Community-Facing Comments + +Comments posted to GitHub issues or pull requests are visible to external contributors. These comments follow a different voice and tone than internal operator updates. + +* Apply the scenario templates from #file:./community-interaction.instructions.md for all community-visible comments. +* Match the Tone Calibration Matrix in that file. Tone ranges from warm and genuine for acknowledgments to respectful and direct for scope closures to constructive and specific for information requests. +* Fill all template placeholders with specific, actionable details rather than generic language. + +## Autonomy Levels + +The autonomy model controls confirmation gates during execution. Defaults to Partial Autonomy when `${input:autonomy}` is not specified. Refer to the Three-Tier Autonomy Model in #file:./github-backlog-planning.instructions.md for the full specification and gate definitions. + +When the user declines a gated operation, mark it as `Skipped` in handoff-logs.md and continue to the next operation. + +## Dry Run Mode + +When `${input:dryRun}` is `true`: + +* Simulate all operations without calling MCP tools that modify state. +* Read-only validation calls (`mcp_github_issue_read`, `mcp_github_get_label`) still execute to verify references. +* Generate handoff-logs.md with all operations marked as `dry-run` status. +* Present the execution summary for user review. +* Re-invoke with `${input:dryRun}` set to `false` to execute the plan. + +## Handoff File Format + +The execution workflow consumes handoff.md and produces handoff-logs.md. Both templates are defined in #file:./github-backlog-planning.instructions.md. + +### handoff.md (consumed) + +Read the Issues section of handoff.md. Each checkbox entry represents one operation. Checked entries (`[x]`) are already complete (from a prior execution run); unchecked entries (`[ ]`) are pending. + +### handoff-logs.md (produced) + +Create handoff-logs.md next to the handoff file. Append an entry after each operation completes. Use the template and field definitions from #file:./github-backlog-planning.instructions.md. The `dry-run` status value extends the template's defined values (`Success`, `Failed`, `Skipped`) for dry run mode operations. + +## Success Criteria + +Execution is complete when: + +* All planned operations from handoff.md are either executed or logged with a final status. +* All `{{TEMP-N}}` placeholders are resolved to actual issue numbers (or logged as failed). +* handoff-logs.md contains an entry for every operation in the plan. +* The Execution Summary in handoff-logs.md reflects accurate counts for succeeded, failed, and skipped operations. +* A completion report has been presented to the user with issue numbers. + +--- + +Brought to you by microsoft/hve-core diff --git a/.github/instructions/writing-style.instructions.md b/.github/instructions/writing-style.instructions.md index 51f51c1d..ee1c65cf 100644 --- a/.github/instructions/writing-style.instructions.md +++ b/.github/instructions/writing-style.instructions.md @@ -17,6 +17,8 @@ Writing voice adapts to context while maintaining professionalism: * Adapt tone and structure to match purpose and audience * Preserve clarity regardless of complexity +For community-facing communication patterns, follow the guidelines in `community-interaction.instructions.md`. + ### Formal Contexts Use these conventions for strategic documents, architecture decisions, and official communications: @@ -63,12 +65,12 @@ Avoid these common patterns that reduce clarity and create clutter. Do not use em dashes (โ€”) for parenthetical statements, explanations, or dramatic pauses. Use these alternatives instead: -| Instead of Em Dash | Use This | Example | -| ------------------ | -------- | ------- | -| Parenthetical aside | Commas | "The system, when enabled, logs all events." | -| Explanation | Colons | "One option remains: refactor the module." | -| Emphasis | Periods | Create a new sentence when emphasizing a point. | -| Supplementary info | Parentheses | Use for truly supplementary information. | +| Instead of Em Dash | Use This | Example | +| ------------------- | ----------- | ------------------------------------------------ | +| Parenthetical aside | Commas | "The system, when enabled, logs all events." | +| Explanation | Colons | "One option remains: refactor the module." | +| Emphasis | Periods | Create a new sentence when emphasizing a point. | +| Supplementary info | Parentheses | Use for truly supplementary information. | ### Bolded-Prefix List Items @@ -112,13 +114,13 @@ Organize content to help readers find and understand information: Use GitHub-flavored markdown alerts for important callouts. Each alert type serves a specific purpose: -| Alert | Purpose | -| ----- | ------- | -| `[!NOTE]` | Useful information users should know when skimming | -| `[!TIP]` | Helpful advice for doing things better or more easily | -| `[!IMPORTANT]` | Key information users need to achieve their goal | -| `[!WARNING]` | Urgent info needing immediate attention to avoid problems | -| `[!CAUTION]` | Advises about risks or negative outcomes of certain actions | +| Alert | Purpose | +| -------------- | ----------------------------------------------------------- | +| `[!NOTE]` | Useful information users should know when skimming | +| `[!TIP]` | Helpful advice for doing things better or more easily | +| `[!IMPORTANT]` | Key information users need to achieve their goal | +| `[!WARNING]` | Urgent info needing immediate attention to avoid problems | +| `[!CAUTION]` | Advises about risks or negative outcomes of certain actions | ```markdown > [!NOTE] @@ -141,12 +143,13 @@ Use GitHub-flavored markdown alerts for important callouts. Each alert type serv Match pronouns to context and purpose: -| Context | Preferred Pronouns | Example | -| ------- | ------------------ | ------- | -| Team/organizational voice | "we", "our" | "We recommend using..." | -| Instructional/tutorial | "you", "your" | "You can configure..." | -| Personal insight/rationale | "I" | "I prefer this approach because..." | -| Neutral/technical | Impersonal constructions | "This configuration enables..." | +| Context | Preferred Pronouns | Example | +| -------------------------- | ------------------------ | ---------------------------------------------------------------- | +| Team/organizational voice | "we", "our" | "We recommend using..." | +| Instructional/tutorial | "you", "your" | "You can configure..." | +| Personal insight/rationale | "I" | "I prefer this approach because..." | +| Neutral/technical | Impersonal constructions | "This configuration enables..." | +| Community interaction | "we", "you" | "Thank you for reporting this. We'll investigate and follow up." | ## Clarity Principles @@ -161,10 +164,11 @@ Clarity takes priority while balancing brevity: Adaptability is the hallmark of effective writing style. Shift register based on content purpose: -| Formality Level | Use For | Characteristics | -| --------------- | ------- | --------------- | -| High | Strategic plans, executive summaries, architecture decisions | Structured, precise, authoritative | -| Medium | Technical documentation, READMEs, contributing guides | Clear, professional, balanced | -| Lower | Internal notes, casual updates, quick references | Direct, concise, conversational | +| Formality Level | Use For | Characteristics | +| --------------- | ------------------------------------------------------------- | ---------------------------------- | +| High | Strategic plans, executive summaries, architecture decisions | Structured, precise, authoritative | +| Medium | Technical documentation, READMEs, contributing guides | Clear, professional, balanced | +| Lower | Internal notes, casual updates, quick references | Direct, concise, conversational | +| Community | Issue/PR comments, contributor acknowledgments, closure messages | Warm, appreciative, scope-focused | Regardless of formality level, maintain professionalism and precision. diff --git a/.github/prompts/github-add-issue.prompt.md b/.github/prompts/github-add-issue.prompt.md index c8c95090..88551449 100644 --- a/.github/prompts/github-add-issue.prompt.md +++ b/.github/prompts/github-add-issue.prompt.md @@ -1,304 +1,86 @@ --- -agent: "agent" -description: "Add a GitHub issue to the backlog using discovered issue templates from .github/ISSUE_TEMPLATE/" -maturity: stable +description: 'Create a GitHub issue using discovered repository templates and conversational field collection' +agent: 'github-backlog-manager' +argument-hint: "[templateName=...] [title=...] [labels=...]" +maturity: experimental --- -# Add GitHub Issue to Backlog +# Add GitHub Issue -This prompt is invoked by `github-issue-manager.agent.md` for issue creation workflow. -It can also be run standalone for direct issue creation tasks. +Discover available issue templates from the repository, collect required and optional fields through conversation, create the issue via GitHub MCP tools, and log the result for tracking. -Follow all instructions from #file:../instructions/markdown.instructions.md - -## Role - -You WILL create GitHub issues by discovering available issue templates and collecting the necessary information. You WILL guide users through the process conversationally and ensure all required fields are collected before creation. - -## General User Conversation Guidance - -When a user wants to create an issue: - -1. Discover available issue templates from `.github/ISSUE_TEMPLATE/` -2. Present template options if multiple exist -3. Collect required and optional field values conversationally -4. Create the issue via GitHub MCP tools -5. Log the creation to an artifact file for tracking - -Be conversational and guide users step-by-step. Ask one question at a time and provide examples proactively. +Follow all instructions from #file:../instructions/github-backlog-planning.instructions.md for shared conventions and the GitHub MCP Tool Catalog. ## Inputs -* **${input:templateName}**: Specific template to use (optional, will discover if not provided) -* **${input:title}**: Issue title (optional, will prompt if not provided) -* **${input:body}**: Issue body content (optional, will prompt if not provided) -* **${input:labels}**: Comma-separated labels (optional) -* **${input:assignees}**: Comma-separated assignees (optional) - -## Protocol - -### 1. Template Discovery - -You WILL discover and parse available issue templates from `.github/ISSUE_TEMPLATE/` directory. - -1. Use `list_dir` to check if `.github/ISSUE_TEMPLATE/` exists -2. If directory exists: - * Enumerate all `.yml` and `.md` files in the directory - * For each template file, use `read_file` to load content - * Parse YAML frontmatter to extract: - * `name`: Template display name - * `about`: Template description - * `title`: Default issue title pattern - * `labels`: Default labels array - * `assignees`: Default assignees array - * For `.yml` forms, parse the `body` array to extract field definitions: - * Field `type`: input, textarea, dropdown, checkboxes, markdown - * Field `id`: Unique identifier for the field - * Field `attributes`: Contains label, description, placeholder, options - * Field `validations`: Contains required flag - * Build a template registry with all discovered templates -3. If directory does not exist or is empty: - * Use generic fallback with basic fields: title, body, labels, assignees - * Inform user that no custom templates were found - -**YAML Form Template Structure**: - -```yaml -name: Bug Report -description: File a bug report -title: "fix: " -labels: ["bug", "triage"] -assignees: - - octocat -body: - - type: markdown - attributes: - value: | - Thanks for taking the time to fill out this bug report! - - type: input - id: contact - attributes: - label: Contact Details - description: How can we get in touch with you if we need more info? - placeholder: ex. email@example.com - validations: - required: false - - type: textarea - id: what-happened - attributes: - label: What happened? - description: Also tell us, what did you expect to happen? - placeholder: Tell us what you see! - validations: - required: true -``` - -**Markdown Template Structure**: - -```markdown ---- -name: Feature request -about: Suggest an idea for this project -title: '' -labels: enhancement -assignees: '' ---- - -**Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -**Describe the solution you'd like** -A clear and concise description of what you want to happen. -``` - -### 2. Template Selection - -You WILL allow user to select which template to use or specify custom fields. - -1. If `${input:templateName}` is provided, locate that template in the registry -2. If not provided and multiple templates exist: - * Present list of available templates with names and descriptions - * Ask user to select a template by name or number - * Wait for user response -3. If only one template exists, use it automatically -4. If no templates exist, proceed with generic field collection - -### 3. Field Collection - -You WILL collect all required and optional field values from the user. +* `${input:templateName}`: (Optional) Specific template name to use. When not provided, discover available templates and present options. +* `${input:title}`: (Optional) Issue title. When not provided, prompt during field collection. +* `${input:body}`: (Optional) Issue body content. When not provided, prompt during field collection. +* `${input:labels}`: (Optional) Comma-separated labels to apply. +* `${input:assignees}`: (Optional) Comma-separated assignees. -1. Extract field definitions from selected template or use generic fields -2. For each required field: - * Check if value was provided in inputs (e.g., `${input:title}`) - * If not provided, prompt user with field label and description - * Validate that required fields are not empty -3. For each optional field: - * Check if value was provided in inputs - * If not provided, ask user if they want to provide a value - * Accept empty values for optional fields -4. Apply template defaults: - * Use template's default title pattern if user didn't override - * Merge template's default labels with user-provided labels: - * Remove duplicates (case-insensitive comparison) - * Order: template labels first, then user-provided labels - * Normalize to lowercase for consistency - * Merge template's default assignees with user-provided assignees: - * Remove duplicates (case-insensitive comparison) - * Order: template assignees first, then user-provided assignees - * Normalize to lowercase for consistency -5. Build final issue data structure +## Required Steps -**Conversation Flow Example**: +The workflow proceeds through five steps: resolve repository context, discover available templates, collect issue details from the user, create the issue, and log the result as a tracking artifact. -```text -Agent: I found 3 issue templates: -1. Bug Report - File a bug report -2. Feature Request - Suggest an idea for this project -3. Documentation - Report missing or incorrect documentation +### Step 1: Resolve Repository Context -Which template would you like to use? (1-3) +Establish the target repository and verify access before proceeding. -User: 1 +1. Call `mcp_github_get_me` to verify repository access and determine the authenticated user. +2. Derive the repository owner and name from the active workspace git remote or user input. +3. Call `mcp_github_list_issue_types` with the owner parameter to determine whether the organization supports issue types. Record valid type values for use during issue creation. -Agent: Great! Let's create a Bug Report. +### Step 2: Discover Templates -What happened? (Required) -Please describe the bug you encountered. +Locate and parse issue templates from the repository. -User: The login button doesn't work on mobile devices +1. Use `list_dir` to check whether `.github/ISSUE_TEMPLATE/` exists in the repository. +2. When the directory exists, enumerate `.yml` and `.md` template files and read each with `read_file`. Extract the template name, description, default title pattern, default labels, default assignees, and field definitions from YAML frontmatter and body content. +3. When the directory does not exist or is empty, proceed with generic fields (title, body, labels, assignees) and inform the user that no custom templates were found. -Agent: Would you like to provide contact details? (Optional) -How can we get in touch if we need more info? +### Step 3: Collect Issue Details -User: john@example.com +Select a template and gather field values through conversation. -Agent: Creating issue... -``` +1. When `${input:templateName}` matches a discovered template, use it. When multiple templates exist and no input was provided, present the available options and ask the user to select one. When only one template exists, use it automatically. +2. For each required field not already provided through inputs, prompt the user with the field label and description. Validate that required fields are not empty before continuing. +3. For optional fields not provided through inputs, ask the user whether they want to supply a value. +4. Merge template defaults with user-provided values for labels and assignees, removing duplicates. +5. When the organization supports issue types (from Step 1), include the type field in collection if the template or user specifies one. -### 4. Issue Creation +### Step 4: Create Issue -You WILL create the GitHub issue using MCP tools. +Submit the issue to GitHub and confirm the result. -1. Use `mcp_github_create_issue` tool with collected data: - * `title`: Final issue title - * `body`: Formatted issue body with all field values using markdown structure: - * **Field Name**: Value (for each collected field) - * Blank line between each field for readability - * Preserve original field formatting and line breaks - * Example: "**Description**: User's issue description\n\n**Priority**: High" - * `labels`: Array of label strings - * `assignees`: Array of assignee usernames -2. Handle tool response: - * On success: Extract issue number and URL from response - * On failure: Report error to user and suggest retry or corrections -3. Confirm creation with user, providing issue number and URL +1. Call `mcp_github_issue_write` with `method: 'create'`, supplying the owner, repo, title, formatted body, labels, and assignees collected in previous steps. Include the `type` parameter only when the organization supports issue types and a type was selected. +2. On success, extract the issue number and URL from the response and confirm creation with the user. +3. On failure, report the error and suggest corrections or a retry. -**MCP Tool Call Structure Example**: +### Step 5: Log Artifact -```json -{ - "tool": "mcp_github_create_issue", - "parameters": { - "title": "fix: login button doesn't work on mobile devices", - "body": "**What happened?**\nThe login button doesn't work on mobile devices\n\n**Contact Details**\njohn@example.com", - "labels": ["bug", "triage"], - "assignees": ["octocat"] - } -} -``` +Record the created issue for tracking purposes. -**Expected Response**: +1. Create or append to an artifact file in `.copilot-tracking/github-issues/` using the filename pattern `issue-{number}.md`. +2. Include the issue number, URL, creation timestamp, template used, applied labels, assignees, and field values. +3. Confirm the artifact location to the user. -```json -{ - "number": 42, - "html_url": "https://github.com/owner/repo/issues/42", - "state": "open", - "title": "fix: login button doesn't work on mobile devices" -} -``` - -### 5. Artifact Logging - -You WILL log issue creation to artifact file for tracking and reference. - -1. Create or append to artifact file in `.copilot-tracking/github-issues/` -2. Use filename pattern: `issue-{number}.md` -3. Include in artifact: - * Issue number and URL - * Creation timestamp - * Template used - * All field values provided - * Issue state and metadata -4. Confirm artifact location to user - -**Artifact File Template**: - -```markdown -# GitHub Issue #42 - -**Created**: 2025-01-15T10:30:00Z -**URL**: https://github.com/owner/repo/issues/42 -**State**: open -**Template**: Bug Report - -## Metadata - -* **Labels**: bug, triage -* **Assignees**: @octocat -* **Milestone**: None -* **Projects**: None - -## Content - -### Title - -fix: login button doesn't work on mobile devices - -### Body - -**What happened?** -The login button doesn't work on mobile devices - -**Contact Details** -john@example.com - -## Timeline - -* 2025-01-15T10:30:00Z - Issue created via GitHub MCP -``` - -## Output Requirements - -After successful completion, you must provide: - -1. **Issue Confirmation**: - * Issue number and clickable URL - * Issue title - * Applied labels and assignees - * Current state (always "open" for new issues) - -2. **Artifact Location**: - * Full path to created artifact file - * Brief summary of logged information +## Success Criteria -3. **Next Steps** (optional suggestions): - * Link to view the issue on GitHub - * Suggest adding comments or updating the issue - * Mention related issues or templates +* Repository context is resolved and access is verified before template discovery. +* All available templates are discovered and presented when multiple exist. +* Required fields are validated before issue creation. +* The issue is created with correct metadata including labels, assignees, and type when supported. +* An artifact file is created in `.copilot-tracking/github-issues/` with issue details. ## Error Handling -* **Template Directory Missing**: Use generic fallback fields, inform user -* **Template Parse Error**: Skip malformed template, continue with others -* **Required Field Missing**: Re-prompt user until value provided -* **Issue Creation Failure**: Display error message, suggest corrections -* **MCP Tool Unavailable**: Inform user to install GitHub MCP extension +* Template directory missing: proceed with generic fields and inform the user. +* Template parse error: skip the malformed template, continue with remaining templates, and warn the user. +* Required field missing after prompting: re-prompt until a value is provided. +* Issue creation failure: display the error message and suggest corrections. +* Organization does not support issue types: omit the type parameter silently. -## Success Criteria +--- -* Issue successfully created on GitHub with correct metadata -* Artifact file created in `.copilot-tracking/github-issues/` -* User receives confirmation with issue number and URL -* All required fields validated before creation -* Template defaults properly applied +Proceed with creating the GitHub issue following the Required Steps. diff --git a/.github/prompts/github-discover-issues.prompt.md b/.github/prompts/github-discover-issues.prompt.md new file mode 100644 index 00000000..ff439f1b --- /dev/null +++ b/.github/prompts/github-discover-issues.prompt.md @@ -0,0 +1,128 @@ +--- +description: 'Discover GitHub issues through user-centric queries, artifact-driven analysis, or search-based exploration and produce planning files for review' +agent: 'github-backlog-manager' +argument-hint: "documents=... [milestone=...] [searchTerms=...]" +maturity: experimental +--- + +# Discover GitHub Issues + +Classify the discovery path based on user intent and available inputs, execute the appropriate discovery workflow, assess similarity against existing issues, and produce planning files for review. Three discovery paths are supported: user-centric queries (Path A), artifact-driven analysis from documents (Path B), and search-based exploration (Path C). + +Follow all instructions from #file:../instructions/github-backlog-discovery.instructions.md while executing this workflow. +Follow all instructions from #file:../instructions/github-backlog-planning.instructions.md for shared conventions. + +## Inputs + +* `${input:documents}`: (Optional) Document paths or attached files (PRDs, RFCs, ADRs) to analyze for issue extraction. Triggers Path B when provided. +* `${input:milestone}`: (Optional) Target milestone name or number to scope searches. +* `${input:searchTerms}`: (Optional) Keywords or phrases for search-based discovery. Triggers Path C when provided without documents. +* `${input:includeSubIssues:false}`: (Optional, defaults to false) Fetch sub-issues for each discovered issue. +* `${input:autonomy:partial}`: (Optional, defaults to partial) Autonomy tier controlling confirmation gates during handoff review. Values: `full`, `partial`, `manual`. + +## Required Steps + +The workflow proceeds through four steps: classify the discovery path, execute discovery for the selected path, assess similarity and plan actions (Path B only), then assemble planning files and present for review (Path B only). + +### Step 1: Classify and Initialize + +Resolve the repository owner and name from the active workspace context or user input before classifying the discovery path. + +1. Call `mcp_github_get_me` to verify repository access and determine the authenticated user. +2. Classify the discovery path based on inputs and user intent: + * Path A (User-Centric): User requests assigned issues, milestone progress, or their own work without referencing artifacts or search terms. + * Path B (Artifact-Driven): Documents, PRDs, or requirements are provided via `${input:documents}` or conversation. User requests issue creation or updates from artifacts. + * Path C (Search-Based): User provides `${input:searchTerms}` directly without artifacts or assignment context. +3. When Path B is selected, create the planning folder at `.copilot-tracking/github-issues/discovery//` and initialize *planning-log.md*. When the organization supports issue types, call `mcp_github_list_issue_types` with the owner parameter. + +When neither documents nor search terms are provided and user intent does not indicate assigned-issue retrieval, ask the user to clarify their discovery goal before proceeding. + +### Step 2: Execute Discovery + +Run the discovery workflow for the classified path. Paths A and C produce a conversational summary and complete the workflow. Path B continues to Steps 3 and 4. + +#### Path A: User-Centric Discovery + +1. Build a search query with `repo:{owner}/{repo} is:issue assignee:{username}`. Apply `milestone:` and `label:` qualifiers when `${input:milestone}` or label context is provided. +2. Execute `mcp_github_search_issues` and paginate until all results are retrieved. +3. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `${input:includeSubIssues}` is true, also fetch sub-issues with `method: 'get_sub_issues'`. +4. Present results grouped by state and labels. +5. Log discovered issues in *planning-log.md* and deliver a conversational summary with counts and relevant issue links. +6. The workflow is complete for Path A. Skip Steps 3 and 4. + +#### Path B: Artifact-Driven Discovery + +1. Read each document referenced in `${input:documents}` to completion. +2. Extract discrete requirements, acceptance criteria, and action items using the Document Parsing Guidelines in the discovery instructions. +3. Record each extracted requirement as a candidate issue entry in *issue-analysis.md* with: temporary ID, suggested title in conventional commit format, body summary, suggested labels, suggested milestone, and source reference. +4. When a document section contains more than 5 sub-requirements, flag the section for epic-level hierarchy grouping in *planning-log.md*. +5. Build keyword groups from extracted requirements per the Search Protocol in the planning specification. +6. Compose GitHub search queries scoped to `repo:{owner}/{repo}` using `mcp_github_search_issues`. Apply the `milestone:` qualifier when `${input:milestone}` is provided. +7. Execute searches for each keyword group and paginate results. +8. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `${input:includeSubIssues}` is true, also fetch sub-issues with `method: 'get_sub_issues'`. +9. Log search queries, result counts, and progress in *planning-log.md*. +10. Continue to Step 3. + +#### Path C: Search-Based Discovery + +1. Build search queries from `${input:searchTerms}` scoped to `repo:{owner}/{repo}` using `mcp_github_search_issues`. Apply the `milestone:` qualifier when `${input:milestone}` is provided. +2. Execute searches and paginate results. +3. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `${input:includeSubIssues}` is true, also fetch sub-issues with `method: 'get_sub_issues'`. +4. Present results grouped by state and labels. +5. Log discovered issues in *planning-log.md* and deliver a conversational summary with counts and relevant issue links. +6. The workflow is complete for Path C. Skip Steps 3 and 4. + +### Step 3: Assess Similarity and Plan Actions + +This step applies to Path B only. Assess similarity between discovered issues and extracted candidates, then categorize each into an action. + +1. For each fetched issue, assess similarity against the candidate set using the Similarity Assessment Framework from the planning specification. Classify each pair as Match, Similar, Distinct, or Uncertain. +2. De-duplicate results across keyword groups. Retain the highest similarity category when the same issue appears in multiple searches. +3. Categorize each candidate into an action: + * Create: Distinct candidates with no existing coverage. Draft new issues with conventional commit titles, labels, and milestones per the planning specification conventions. + * Update: Match candidates where existing issues need field changes. Merge new requirements while preserving existing content. + * Link: Candidates that establish parent-child or cross-reference relationships between issues. + * Close: Existing issues superseded by new candidates or resolved by current work. Set `state_reason` per the Issue Field Matrix. +4. When a requirement decomposes into more than 5 sub-requirements, create an epic-level tracking issue as the parent and plan individual issues as sub-issues. Use `{{TEMP-N}}` placeholders for issues not yet created per the Temporary ID Mapping convention. +5. Record all planned operations in *issue-analysis.md* and *issues-plan.md* per templates in the planning specification. Include similarity assessments, recommended actions, and rationale for each entry. +6. Update *planning-log.md* with the current phase status and similarity assessment results. + +Pause and request user guidance when human review triggers are met, including: ambiguous requirements, multiple Similar results for a single candidate, missing parent issues, `breaking-change` label candidates, Uncertain assessments, or planned milestone changes. + +### Step 4: Assemble Handoff and Present + +This step applies to Path B only. Produce the handoff file and present the discovery results for review. + +1. Build *handoff.md* per the template in the planning specification. Order entries as: Create first, Update second, Link third, Close fourth, No Change last. +2. Include checkboxes, summaries, relationships, and artifact references for each entry. +3. Add a Planning Files section with project-relative paths to all generated files (*planning-log.md*, *issue-analysis.md*, *issues-plan.md*, *handoff.md*). +4. Apply the Three-Tier Autonomy Model from the planning specification to determine confirmation gates based on `${input:autonomy}`. When no tier is specified, default to Partial Autonomy. +5. Verify consistency across *issue-analysis.md*, *issues-plan.md*, and *handoff.md*. Resolve discrepancies before presenting. +6. Present the handoff for user review, highlighting items that trigger human review. +7. Record the final state in *planning-log.md* with phase completion status. + +## Success Criteria + +* The discovery path is classified before executing any searches or document parsing. +* All provided documents are analyzed for actionable items when Path B is selected. +* Existing backlog is searched using `mcp_github_search_issues` with keyword groups from extracted requirements or user-provided terms. +* Similarity assessments classify each candidate-to-existing-issue pair as Match, Similar, Distinct, or Uncertain. +* All four action categories (Create, Update, Link, Close) are represented in the plan when applicable. +* Hierarchy grouping produces epic-level tracking issues when a requirement has more than 5 sub-requirements. +* Path B produces *planning-log.md*, *issue-analysis.md*, *issues-plan.md*, and *handoff.md* in `.copilot-tracking/github-issues/discovery//`. +* Paths A and C produce *planning-log.md* and a conversational summary. +* The handoff is presented for review before any execution occurs. Discovery does not execute issue operations. + +## Error Handling + +* No inputs provided: ask the user to provide documents, search terms, or clarify their discovery intent before proceeding. +* Search returns no results: suggest broadening search terms and retry with alternative keyword groups. Log the empty search in *planning-log.md*. +* Ambiguous matches: flag as Uncertain and present both candidates for user review rather than auto-categorizing. +* Large document: process sections incrementally with progress updates recorded in *planning-log.md* after each section. +* API rate limit: pause and retry with exponential backoff. Log the pause in *planning-log.md*. +* Missing labels in repository: warn the user and note the missing label in *planning-log.md*. Proceed with remaining labels. +* Context summarization: when conversation history is compressed, recover state from *planning-log.md* per the State Persistence Protocol in the planning specification before continuing. + +--- + +Proceed with discovering GitHub issues following the Required Steps. diff --git a/.github/prompts/github-execute-backlog.prompt.md b/.github/prompts/github-execute-backlog.prompt.md new file mode 100644 index 00000000..940a7986 --- /dev/null +++ b/.github/prompts/github-execute-backlog.prompt.md @@ -0,0 +1,78 @@ +--- +description: 'Execute a GitHub backlog plan by creating, updating, linking, closing, and commenting on issues from a handoff file' +agent: 'github-backlog-manager' +argument-hint: "handoff=... [autonomy={full|partial|manual}] [dryRun={true|false}]" +maturity: experimental +--- + +# Execute GitHub Backlog Plan + +Process a handoff plan file to execute planned issue operations against the GitHub API. The workflow initializes (or resumes) execution state, processes operations in hierarchy order, and produces a completion report with issue numbers. + +Follow all instructions from #file:../instructions/github-backlog-update.instructions.md while executing this workflow. +Follow all instructions from #file:../instructions/github-backlog-planning.instructions.md for shared conventions. + +## Inputs + +* `${input:handoff}`: (Required) Path to the handoff plan file (handoff.md or triage-plan.md). +* `${input:autonomy:partial}`: (Optional, defaults to partial) Autonomy tier controlling confirmation gates. Values: `full`, `partial`, `manual`. +* `${input:dryRun:false}`: (Optional, defaults to false) When true, simulate all operations without modifying state. + +## Required Steps + +The workflow proceeds through three steps: initialize or resume execution state, process operations in fixed hierarchy order, then finalize and present a completion report. + +### Step 1: Initialize or Resume + +Establish execution context and determine whether this is a new run or a resumption. + +1. Call `mcp_github_get_me` to verify repository access and determine the authenticated user. +2. Read the handoff plan from `${input:handoff}`. When the file is not found, ask the user for the correct path before continuing. +3. Resolve the repository owner and name from the handoff file header or the active workspace context. +4. Call `mcp_github_list_issue_types` with the owner parameter to determine whether the repository supports issue types and confirm valid type values before processing. +5. Check whether handoff-logs.md already exists next to `${input:handoff}`: + * When it exists, rebuild the `{{TEMP-N}}` mapping from completed Create entries and resume from the first unchecked operation per the Initialize or Resume instructions in the update instructions. + * When it does not exist, create handoff-logs.md using the template from the planning specification and populate it from the handoff file. +6. Validate the handoff per the validation checks in the update instructions. Skip `{{TEMP-N}}` placeholders during numeric reference validation since those issues do not exist yet. Abort on critical failures (missing repository, authentication error); warn and continue on non-critical failures (invalid label, unknown milestone). +7. Present an execution summary to the user for confirmation before proceeding. + +### Step 2: Process Operations + +Execute operations in the fixed order defined by the update instructions: Create (parents first, then children), Update, Link, Close, Comment. + +1. Process each operation category in sequence, following the Supported Operations table and checkpoint protocol in the update instructions. +2. After each Create, resolve the corresponding `{{TEMP-N}}` placeholder to the actual issue number and record the mapping in handoff-logs.md. +3. Apply confirmation gates per the Three-Tier Autonomy Model in the planning specification based on `${input:autonomy}`. When the user declines a gated operation, mark it as `Skipped` in handoff-logs.md and continue. +4. When `${input:dryRun}` is true, simulate operations per the Dry Run Mode section of the update instructions without executing state-modifying calls. +5. Update checkboxes in the handoff file and append entries to handoff-logs.md after each operation per the checkpoint protocol. On failure, log the error and continue processing remaining operations. + +### Step 3: Finalize and Report + +Verify results and present a completion report. + +1. Re-read handoff-logs.md and compare against the original handoff plan. +2. Process any missed operations that were blocked by dependency failures and have since been unblocked. Limit this retry pass to one additional iteration per the finalization instructions. +3. Cross-check that all `{{TEMP-N}}` placeholders resolved to actual issue numbers. +4. Generate a completion summary with counts for issues created, updated, linked, closed, failed, and skipped. Present the summary with issue numbers. +5. When failures occurred, list each failed operation with its error message and suggest corrective actions. + +## Success Criteria + +* All planned operations from the handoff file are executed or logged with a final status in handoff-logs.md. +* All `{{TEMP-N}}` placeholders are resolved to actual issue numbers or logged as failed. +* handoff-logs.md next to `${input:handoff}` contains an entry for every operation. +* A completion report with issue numbers has been presented to the user. + +## Error Handling + +* Handoff file not found: ask the user for the correct path rather than failing silently. +* Authentication or permission error (401/403): abort processing and notify the user. +* Rate limit (429): pause and retry with exponential backoff per the error handling in the update instructions. +* Invalid issue references: skip the operation, log a warning in handoff-logs.md, and continue per the error handling in the update instructions. +* Missing parent for sub-issue link: defer the link operation and revisit during the Step 3 retry pass per the dependency resolution in the update instructions. +* API or transient failures: log the error, continue with remaining operations, and report all failures in the final summary per the error handling in the update instructions. +* Context summarization: when conversation history is compressed, recover state from handoff-logs.md per the State Persistence Protocol in the planning specification before continuing. + +--- + +Proceed with executing the backlog plan from `${input:handoff}` following the Required Steps. diff --git a/.github/prompts/github-sprint-plan.prompt.md b/.github/prompts/github-sprint-plan.prompt.md new file mode 100644 index 00000000..e76d9f86 --- /dev/null +++ b/.github/prompts/github-sprint-plan.prompt.md @@ -0,0 +1,109 @@ +--- +description: 'Plan a GitHub milestone sprint by analyzing issue coverage, identifying gaps, and organizing work into a prioritized sprint backlog' +agent: 'github-backlog-manager' +argument-hint: "milestone=... [documents=...] [sprintGoal=...] [capacity=...] [autonomy={full|partial|manual}]" +maturity: experimental +--- + +# Plan GitHub Sprint + +Analyze a GitHub milestone, assess issue coverage against the full label taxonomy and optional planning documents, and produce a prioritized sprint plan with gap analysis and dependency awareness. + +Follow all instructions from #file:../instructions/github-backlog-planning.instructions.md (the planning specification) for shared conventions, templates, and the label taxonomy. + +When documents are provided, follow the Document Parsing Guidelines from [github-backlog-discovery.instructions.md](../instructions/github-backlog-discovery.instructions.md) (the discovery instructions) for requirement extraction and similarity assessment. + +Follow the Conventional Commit Title Pattern to Label Mapping, Scope Keyword to Scope Label Mapping, Priority Assessment, and Milestone Recommendation sections from [github-backlog-triage.instructions.md](../instructions/github-backlog-triage.instructions.md) (the triage instructions) for label mapping, priority assessment, and milestone recommendations. + +## Inputs + +* `${input:milestone}`: (Required) Target milestone name or number for the sprint. +* `${input:documents}`: (Optional) File paths or URLs of source documents (PRDs, RFCs, ADRs) for cross-referencing against milestone issues. +* `${input:sprintGoal}`: (Optional) Sprint goal or theme description to focus prioritization. +* `${input:capacity}`: (Optional) Team capacity or issue count limit for the sprint. +* `${input:autonomy:partial}`: (Optional, defaults to partial) Autonomy tier controlling confirmation gates. Values: `full`, `partial`, `manual`. See the Three-Tier Autonomy Model in the planning specification. + +## Required Steps + +This workflow proceeds through four steps: fetch the milestone issues, analyze coverage and gaps, produce the sprint plan, then review and execute approved changes. Planning artifacts are written to `.copilot-tracking/github-issues/sprint/{{milestone-kebab}}/` where `{{milestone-kebab}}` is the milestone name normalized to kebab-case (for example, `v2-2-0`). + +### Step 1: Fetch Milestone and Issues + +Resolve the repository context, verify access, and retrieve all issues assigned to the target milestone. + +1. Determine the repository owner and name from workspace context (remote URL, open files, or user input). +2. Call `mcp_github_get_me` to verify authenticated access to the repository. +3. Create the planning directory at `.copilot-tracking/github-issues/sprint/{{milestone-kebab}}/` and initialize *planning-log.md* following the template in the planning specification. +4. Fetch open issues for the milestone using `mcp_github_search_issues` with query `repo:{owner}/{repo} milestone:"{milestone}" is:open`. Paginate until all results are retrieved. +5. Fetch closed issues for progress context using `mcp_github_search_issues` with query `repo:{owner}/{repo} milestone:"{milestone}" is:closed`. +6. Hydrate each open issue via `mcp_github_issue_read` with `method: 'get'` to retrieve body content, labels, and assignments. Also fetch sub-issues with `method: 'get_sub_issues'` on issues with sub-issue relationships or titles suggesting tracking scope (epics, umbrella issues, feature aggregations). +7. Flag issues carrying the `needs-triage` label. When more than half of open issues are untriaged, recommend running triage via *github-triage-issues.prompt.md* before sprint planning and note this as a triage prerequisite in the planning log. Continue analysis on triaged issues. +8. Record the milestone inventory in *planning-log.md* with issue counts by state and label category. + +### Step 2: Analyze Coverage and Gaps + +Categorize milestone issues using the full label taxonomy, build a coverage matrix, and identify gaps through document cross-referencing when source documents are provided. + +1. Categorize each open issue by its labels using the Label Taxonomy Reference in the planning specification. Map each issue to one or more of the 17 defined labels. +2. Build a coverage matrix showing which scope labels (`agents`, `prompts`, `instructions`, `infrastructure`) are represented in the milestone and which are absent. +3. Identify issues missing labels or carrying conflicting label combinations. Apply the conventional commit title pattern mapping from the triage instructions to suggest corrections. +4. When `${input:documents}` is provided, read each document and extract discrete requirements following the Document Parsing Guidelines in the discovery instructions. Assess similarity between extracted requirements and existing milestone issues using the Similarity Assessment Framework in the planning specification. +5. Record gap findings: requirements from documents with no matching milestone issue, scope labels with no coverage, and milestone issues with incomplete acceptance criteria. +6. Check for blocked or dependent issues by inspecting sub-issue hierarchy relationships discovered in Step 1. +7. Record the analysis in *sprint-analysis.md* within the planning directory, including the coverage matrix, gap list, and similarity assessments. + +### Step 3: Produce Sprint Plan + +Prioritize issues, apply capacity constraints, and assemble the sprint plan with work themes and dependency chains. + +1. Assign priority ranks following the Priority Assessment table in the triage instructions: security issues highest, bugs high, features aligned with `${input:sprintGoal}` medium-high, other features and enhancements medium, documentation and maintenance lower. +2. When `${input:capacity}` is provided, include only the top-ranked issues up to the capacity limit. When not provided, include all open issues and note the total count. +3. Identify issues to defer to the next milestone based on priority rank exceeding capacity, missing readiness (no labels, incomplete descriptions), or misalignment with the EVEN/ODD versioning strategy in the planning specification. +4. Group prioritized issues into logical work themes based on shared scope labels (for example, `agents`, `prompts`, `instructions`). +5. Identify dependency chains where parent issues should complete before child issues, using sub-issue relationships from Step 1. +6. For each gap identified in Step 2 (unmatched document requirements), plan a new issue using `{{TEMP-N}}` placeholders per the Temporary ID Mapping convention in the planning specification. Include a suggested title in conventional commit format, labels, milestone, and source references. +7. Generate *sprint-plan.md* in the planning directory containing: sprint goal (from `${input:sprintGoal}` or inferred from milestone description), coverage matrix, prioritized issue table, gap analysis with suggested new issues, deferred issues with rationale, dependency chains, and risk items. +8. Generate *handoff.md* per the template in the planning specification, ordering entries as: Create (new issues from gaps) first, Update (label corrections, milestone moves) second, Link (sub-issue relationships) third, Close (duplicate or resolved items) fourth, No Change last. + +### Step 4: Review and Execute + +Present the sprint plan for review and execute approved changes according to the active autonomy tier. + +1. Present the sprint plan as a structured summary including: + * Prioritized issue table with columns: Priority Rank, Issue #, Title, Labels, Dependencies, Notes + * Deferred issues table with columns: Issue #, Title, Reason for Deferral + * New issues to create from gap analysis with suggested titles and labels + * Risk items requiring attention (blocked issues, stale issues, missing acceptance criteria) +2. Apply autonomy gates from the Three-Tier Autonomy Model in the planning specification. Under full autonomy, proceed without confirmation. Under partial autonomy, gate on new issue creation and milestone moves. Under manual autonomy, gate on all operations. +3. Execute approved changes following the fixed processing order from the planning specification: Create (parents first, resolving `{{TEMP-N}}` placeholders to actual issue numbers), Update, Link, Close. +4. For each operation, call `mcp_github_issue_write` with `method: 'update'` or `method: 'create'` as appropriate. When updating labels, compute the full replacement set: `(current_labels - removed_labels) + added_labels`. +5. Propagate the sprint milestone to linked pull requests: + 1. Search for PRs already tagged with the milestone by calling `mcp_github_search_pull_requests` with `milestone:"{milestone}" repo:{owner}/{repo}`. + 2. Search for PRs associated with milestone issues by calling `mcp_github_search_pull_requests` with `repo:{owner}/{repo} {issue_number}` for each milestone issue, collecting PRs that mention the issue in their title or body. + 3. For each discovered PR missing the target milestone, call `mcp_github_issue_write` with `method: 'update'`, passing the PR number as `issue_number` and `milestone` set to the sprint milestone number. The Issues API accepts PR numbers because GitHub treats pull requests as a superset of issues sharing the same number space (see the Pull Request Field Operations section in the planning specification). +6. Create *handoff-logs.md* in the planning directory using the template from the planning specification if it does not already exist. Update checkboxes in *handoff.md* and append results to *handoff-logs.md* as each operation completes. +7. Update *planning-log.md* with execution results including issue numbers, actions taken, and final sprint statistics. + +## Success Criteria + +* All open issues assigned to the target milestone have been fetched, hydrated, and categorized by the full label taxonomy. +* A coverage matrix identifies which scope labels are represented and which have gaps. +* When documents are provided, extracted requirements have been assessed for similarity against existing milestone issues. +* The sprint plan includes prioritized issues within capacity constraints, deferred items with rationale, and dependency chains. +* Planning artifacts exist in `.copilot-tracking/github-issues/sprint/{{milestone-kebab}}/`: *planning-log.md*, *sprint-analysis.md*, *sprint-plan.md*, *handoff.md*, and *handoff-logs.md*. +* The user has reviewed the plan and confirmed or adjusted recommended changes, respecting the active autonomy tier. +* Approved changes have been executed and recorded in *handoff-logs.md* with checkbox tracking. + +## Error Handling + +* No issues in milestone: Report the empty milestone and suggest running discovery via *github-discover-issues.prompt.md* to populate it. +* Excessive untriaged issues (more than half carrying `needs-triage`): Recommend running triage via *github-triage-issues.prompt.md* before sprint planning. Continue analysis on triaged issues. +* Milestone not found: List available milestones by searching recent issues with `mcp_github_search_issues` and prompt for the correct milestone name. +* Circular dependencies: Flag the circular chain for user resolution and exclude affected issues from dependency ordering. +* Rate limiting: Log the failure in *planning-log.md*, wait for the rate limit window to reset, and retry the operation. +* Context summarization: When conversation context is summarized, recover state by reading *planning-log.md* and resuming from the last completed step. +* Authentication failure: Report the access error from `mcp_github_get_me` and prompt for repository details. + +--- + +Proceed with planning the sprint for the specified milestone following the Required Steps. diff --git a/.github/prompts/github-triage-issues.prompt.md b/.github/prompts/github-triage-issues.prompt.md new file mode 100644 index 00000000..074f74ed --- /dev/null +++ b/.github/prompts/github-triage-issues.prompt.md @@ -0,0 +1,84 @@ +--- +description: 'Triage untriaged GitHub issues with automated label suggestions, milestone assignment, and duplicate detection' +agent: 'github-backlog-manager' +maturity: experimental +--- + +# Triage GitHub Issues + +Fetch all open GitHub issues carrying the `needs-triage` label, analyze each for label and milestone recommendations, detect duplicates, and produce a triage plan for review before execution. + +Follow all instructions from #file:../instructions/github-backlog-triage.instructions.md while executing this workflow. +Follow all instructions from #file:../instructions/github-backlog-planning.instructions.md for shared conventions. + +## Inputs + +* `${input:milestone}`: (Optional) Target milestone override. When provided, skip milestone discovery and use this value for all non-duplicate issues. +* `${input:maxIssues:20}`: (Optional, defaults to 20) Maximum issues to process per batch. +* `${input:autonomy:partial}`: (Optional, defaults to partial) Autonomy tier controlling confirmation gates. Values: `full`, `partial`, `manual`. + +## Required Steps + +The workflow proceeds through three steps: fetch untriaged issues with milestone context, analyze each issue for labels and duplicates, then present a triage plan and execute confirmed recommendations. + +### Step 1: Fetch Untriaged Issues + +Resolve the repository owner and name from the active workspace context or user input before constructing queries. + +1. When `${input:milestone}` is not provided, discover the current EVEN and next ODD milestones by searching recent issues with milestone assignments via `mcp_github_search_issues`. Record the discovered milestones in planning-log.md. Delegate EVEN/ODD classification to the Milestone Recommendation section of the triage instructions. +2. Search for open issues carrying the `needs-triage` label using `mcp_github_search_issues` with the query `repo:{owner}/{repo} is:issue is:open label:needs-triage`. +3. Limit results to the `${input:maxIssues}` count using the `perPage` parameter. +4. For each returned issue, fetch full details with `mcp_github_issue_read` using method `get`, then fetch the complete label set using method `get_labels`. Both calls are needed for replacement semantics during execution. +5. Create the planning directory at `.copilot-tracking/github-issues/triage/{{YYYY-MM-DD}}/` and record fetched issues in planning-log.md. + +When no untriaged issues are found, inform the user and suggest broadening the search (for example, removing label filters or checking for issues without any labels). + +### Step 2: Analyze and Classify + +For each fetched issue, perform these analyses and build triage recommendations. + +1. Parse the title against the Conventional Commit Title Pattern to Label Mapping table in the triage instructions. Titles without a recognized pattern retain the `needs-triage` label for manual review. +2. Extract scope keywords from the title and map them to scope labels per the Scope Keyword to Scope Label Mapping in the triage instructions. Note unrecognized scopes as body context rather than assigning them as labels. +3. Assess priority using the Priority Assessment table in the triage instructions. Issues carrying the `breaking-change` or `security` label trigger escalation to the user regardless of autonomy tier. +4. Recommend a milestone using the discovered EVEN/ODD context. When `${input:milestone}` is provided, use it as the default target. Delegate assignment logic to the Milestone Recommendation section of the triage instructions. +5. Search for similar open issues using keyword groups from the title. Assess similarity using the Similarity Assessment Framework from the planning specification and flag potential duplicates with their category (Match, Similar, Distinct, or Uncertain). +6. Review existing labels (from the `get_labels` hydration in Step 1) for conflicts with suggested labels. Flag divergences for user review per the human review triggers in the planning specification. + +Record the analysis in triage-plan.md using the template from the Output section of the triage instructions. + +### Step 3: Present and Execute + +Present the triage plan to the user as a summary table. + +```markdown +| Issue | Title | Suggested Labels | Suggested Milestone | Duplicates Found | Priority | Action | +| ----- | ----- | ---------------- | ------------------- | ---------------- | -------- | ------ | +``` + +Execution follows the `${input:autonomy}` tier per the Three-Tier Autonomy Model in the planning specification. Under `partial` (default), label assignments, milestone assignments, and `needs-triage` removal auto-execute, but duplicate closures gate on user approval. Under `full`, all operations execute immediately. Under `manual`, every operation gates on user confirmation. + +1. Collect user confirmation or modifications per the active autonomy tier before applying gated changes. +2. For each confirmed non-duplicate issue, compute the replacement label set as `(current_labels - "needs-triage") + suggested_labels` and apply labels, milestone, and `needs-triage` removal in a single `mcp_github_issue_write` call with `method: 'update'`. The `labels` parameter uses replacement semantics: include all labels to retain, all labels to add, and exclude `needs-triage`. +3. For confirmed Match-category duplicates, close using `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'duplicate'`, and `duplicate_of` referencing the original issue. +4. Update planning-log.md with execution results for each processed issue. + +## Success Criteria + +* All fetched issues have triage recommendations with label suggestions, milestone assignments, and duplicate assessments. +* The triage plan has been reviewed per the active autonomy tier before execution. +* Labels and milestones are applied using replacement semantics in consolidated API calls. +* The `needs-triage` label is removed from all processed issues. +* Planning artifacts are created in `.copilot-tracking/github-issues/triage/{{YYYY-MM-DD}}/`. + +## Error Handling + +* No untriaged issues found: inform the user and suggest broadening search criteria or checking for issues without any labels. +* API rate limit: pause and retry with exponential backoff. Log the pause in planning-log.md. +* Missing label: warn the user and skip label application for that issue. Log the missing label in planning-log.md. +* Duplicate detection ambiguous: flag the issue as Uncertain and present both candidates for user review rather than auto-closing. +* Concurrent modification: when an issue has been modified between analysis and execution (labels or state changed externally), re-fetch details before applying updates to avoid overwriting changes. +* Bulk operation threshold: when processing more than 10 issues in a single batch, present a confirmation summary before executing, even under full autonomy. + +--- + +Proceed with triaging untriaged GitHub issues following the Required Steps. diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md index 40304a10..ec6f1eaa 100644 --- a/docs/getting-started/install.md +++ b/docs/getting-started/install.md @@ -190,7 +190,7 @@ These artifacts are useful during your workflow session but are ephemeral by des Some HVE-Core agents use MCP (Model Context Protocol) servers to integrate with Azure DevOps, GitHub, or documentation services. These are optional enhancements; agents work without MCP configuration. -If you use agents like `ado-prd-to-wit` or `github-issue-manager`, see [MCP Server Configuration](mcp-configuration.md) for setup instructions. That guide includes: +If you use agents like `ado-prd-to-wit` or `github-backlog-manager`, see [MCP Server Configuration](mcp-configuration.md) for setup instructions. That guide includes: * Which agents require which MCP servers * Complete configuration templates diff --git a/docs/getting-started/mcp-configuration.md b/docs/getting-started/mcp-configuration.md index 7d1e85eb..1dbd5d25 100644 --- a/docs/getting-started/mcp-configuration.md +++ b/docs/getting-started/mcp-configuration.md @@ -33,13 +33,13 @@ Configuring both is unnecessary unless you work across platforms. If you use oth ## Agent MCP Dependencies -| Agent | MCP Servers Used | Notes | -|----------------------|--------------------------|---------------------------------| -| ado-prd-to-wit | ado, microsoft-docs | ADO work item creation | -| github-issue-manager | github | GitHub issue management | -| task-researcher | context7, microsoft-docs | Documentation lookup (optional) | -| task-planner | context7, microsoft-docs | Documentation lookup (optional) | -| rpi-agent | Varies by subagent | Delegates to specialized agents | +| Agent | MCP Servers Used | Notes | +|------------------------|--------------------------|---------------------------------| +| ado-prd-to-wit | ado, microsoft-docs | ADO work item creation | +| github-backlog-manager | github | GitHub backlog management | +| task-researcher | context7, microsoft-docs | Documentation lookup (optional) | +| task-planner | context7, microsoft-docs | Documentation lookup (optional) | +| rpi-agent | Varies by subagent | Delegates to specialized agents | Agents without MCP dependencies work without any MCP configuration. diff --git a/extension/README.md b/extension/README.md index 206aac98..b4ca6e6a 100644 --- a/extension/README.md +++ b/extension/README.md @@ -12,7 +12,7 @@ Specialized AI assistants for specific development tasks: #### Development Workflow -- **github-issue-manager** - Manage GitHub issues efficiently +- **github-backlog-manager** - Consolidated GitHub backlog management with community interaction - **pr-review** - Comprehensive pull request review assistant - **rpi-agent** - Professional evidence-backed agent with structured subagent delegation for research, codebase discovery, and complex tasks - **task-implementor** - Implement tasks from detailed plans diff --git a/extension/package.json b/extension/package.json index ee7f00a8..105dbe74 100644 --- a/extension/package.json +++ b/extension/package.json @@ -61,9 +61,9 @@ "description": "Develop a multi-page Streamlit dashboard" }, { - "name": "github-issue-manager", - "path": "./.github/agents/github-issue-manager.agent.md", - "description": "Interactive GitHub issue management with conversational workflows for filing, navigating, and searching issues" + "name": "github-backlog-manager", + "path": "./.github/agents/github-backlog-manager.agent.md", + "description": "Orchestrator agent for GitHub backlog management workflows including triage, discovery, sprint planning, and execution - Brought to you by microsoft/hve-core" }, { "name": "hve-core-installer", @@ -185,7 +185,27 @@ { "name": "github-add-issue", "path": "./.github/prompts/github-add-issue.prompt.md", - "description": "Add a GitHub issue to the backlog using discovered issue templates from .github/ISSUE_TEMPLATE/" + "description": "Create a GitHub issue using discovered repository templates and conversational field collection" + }, + { + "name": "github-discover-issues", + "path": "./.github/prompts/github-discover-issues.prompt.md", + "description": "Discover GitHub issues through user-centric queries, artifact-driven analysis, or search-based exploration and produce planning files for review" + }, + { + "name": "github-execute-backlog", + "path": "./.github/prompts/github-execute-backlog.prompt.md", + "description": "Execute a GitHub backlog plan by creating, updating, linking, closing, and commenting on issues from a handoff file" + }, + { + "name": "github-sprint-plan", + "path": "./.github/prompts/github-sprint-plan.prompt.md", + "description": "Plan a GitHub milestone sprint by analyzing issue coverage, identifying gaps, and organizing work into a prioritized sprint backlog" + }, + { + "name": "github-triage-issues", + "path": "./.github/prompts/github-triage-issues.prompt.md", + "description": "Triage untriaged GitHub issues with automated label suggestions, milestone assignment, and duplicate detection" }, { "name": "prompt-analyze", @@ -277,7 +297,12 @@ { "name": "commit-message-instructions", "path": "./.github/instructions/commit-message.instructions.md", - "description": "Required instructions for creating all commit messages - Brought to you by microsoft/edge-ai" + "description": "Required instructions for creating all commit messages - Brought to you by microsoft/hve-core" + }, + { + "name": "community-interaction-instructions", + "path": "./.github/instructions/community-interaction.instructions.md", + "description": "Community interaction voice, tone, and response templates for GitHub-facing agents and prompts" }, { "name": "csharp-tests-instructions", @@ -294,6 +319,31 @@ "path": "./.github/instructions/git-merge.instructions.md", "description": "Required protocol for Git merge, rebase, and rebase --onto workflows with conflict handling and stop controls." }, + { + "name": "github-backlog-discovery-instructions", + "path": "./.github/instructions/github-backlog-discovery.instructions.md", + "description": "Discovery protocol for GitHub backlog management - artifact-driven, user-centric, and search-based issue discovery" + }, + { + "name": "github-backlog-planning-instructions", + "path": "./.github/instructions/github-backlog-planning.instructions.md", + "description": "Reference specification for GitHub backlog management tooling - planning files, search protocols, similarity assessment, and state persistence" + }, + { + "name": "github-backlog-triage-instructions", + "path": "./.github/instructions/github-backlog-triage.instructions.md", + "description": "Triage workflow for GitHub issue backlog management - automated label suggestion, milestone assignment, and duplicate detection" + }, + { + "name": "github-backlog-update-instructions", + "path": "./.github/instructions/github-backlog-update.instructions.md", + "description": "Execution workflow for GitHub issue backlog management - consumes planning handoffs and executes issue operations" + }, + { + "name": "hve-core-location-instructions", + "path": "./.github/instructions/hve-core-location.instructions.md", + "description": "Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree." + }, { "name": "markdown-instructions", "path": "./.github/instructions/markdown.instructions.md", From 11941a00aae8bcb1605526dcef6a12ab02c2c43f Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Fri, 6 Feb 2026 20:13:03 -0800 Subject: [PATCH 2/8] fix(prompts): replace untriaged with not yet triaged in triage description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ๐Ÿ”ง - Generated by Copilot --- .github/prompts/github-triage-issues.prompt.md | 2 +- extension/package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/prompts/github-triage-issues.prompt.md b/.github/prompts/github-triage-issues.prompt.md index 074f74ed..e488d474 100644 --- a/.github/prompts/github-triage-issues.prompt.md +++ b/.github/prompts/github-triage-issues.prompt.md @@ -1,5 +1,5 @@ --- -description: 'Triage untriaged GitHub issues with automated label suggestions, milestone assignment, and duplicate detection' +description: 'Triage GitHub issues not yet triaged with automated label suggestions, milestone assignment, and duplicate detection' agent: 'github-backlog-manager' maturity: experimental --- diff --git a/extension/package.json b/extension/package.json index 105dbe74..abba9a44 100644 --- a/extension/package.json +++ b/extension/package.json @@ -205,7 +205,7 @@ { "name": "github-triage-issues", "path": "./.github/prompts/github-triage-issues.prompt.md", - "description": "Triage untriaged GitHub issues with automated label suggestions, milestone assignment, and duplicate detection" + "description": "Triage GitHub issues not yet triaged with automated label suggestions, milestone assignment, and duplicate detection" }, { "name": "prompt-analyze", From 8baf6a913e438687e232c383f5febda2a575ab8e Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Fri, 6 Feb 2026 20:33:20 -0800 Subject: [PATCH 3/8] fix(agents): address code review feedback on backlog manager and community interaction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - align tracking path table with planning spec scope conventions - remove opaque Decision D1 policy exemption note - remove undocumented pull_request_review_write tool reference ๐Ÿ”ง - Generated by Copilot --- .../agents/github-backlog-manager.agent.md | 21 ++++++++----------- .../community-interaction.instructions.md | 2 +- 2 files changed, 10 insertions(+), 13 deletions(-) diff --git a/.github/agents/github-backlog-manager.agent.md b/.github/agents/github-backlog-manager.agent.md index e80693b5..095e2be1 100644 --- a/.github/agents/github-backlog-manager.agent.md +++ b/.github/agents/github-backlog-manager.agent.md @@ -34,13 +34,10 @@ Central orchestrator for GitHub backlog management that classifies incoming requ Workflow conventions, planning file templates, similarity assessment, and the three-tier autonomy model are defined in the [backlog planning instructions](../instructions/github-backlog-planning.instructions.md). Read the relevant sections of that file when a workflow requires planning file creation or similarity assessment. Architecture and design rationale are documented in `.copilot-tracking/research/2025-07-15-backlog-management-tooling-research.md` when available. -> [!NOTE] -> This orchestrator ships under lead maintainer exemption authority per Decision D1. Backlog management is a distinct domain from task planning, and the agent-acceptance policy for planning agents does not apply. - ## Core Directives * Classify every request before dispatching. Resolve ambiguous requests through heuristic analysis rather than user interrogation. -* Maintain state files in `.copilot-tracking/github-issues///` for every workflow run. +* Maintain state files in `.copilot-tracking/github-issues///` for every workflow run per directory conventions in the [planning specification](../instructions/github-backlog-planning.instructions.md). * Default to Partial autonomy unless the user specifies otherwise. * Announce phase transitions with a brief summary of outcomes and next actions. * Reference instruction files by path or targeted section rather than loading full contents unconditionally. @@ -76,15 +73,15 @@ Transition to Phase 2 once classification is confirmed. ### Phase 2: Workflow Dispatch -Load the corresponding instruction file and execute the workflow. Each run creates a date-stamped tracking directory under `.copilot-tracking/github-issues/`. +Load the corresponding instruction file and execute the workflow. Each run creates a tracking directory under `.copilot-tracking/github-issues/` using the scope conventions from the [planning specification](../instructions/github-backlog-planning.instructions.md). -| Workflow | Instruction Source | Tracking Path | -| --------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -| Triage | [github-backlog-triage.instructions.md](../instructions/github-backlog-triage.instructions.md) | `.copilot-tracking/github-issues/triage/{{date}}/` | -| Discovery | [github-backlog-discovery.instructions.md](../instructions/github-backlog-discovery.instructions.md) | `.copilot-tracking/github-issues/discovery/{{date}}/` | -| Sprint Planning | Discovery followed by Triage as a coordinated sequence | `.copilot-tracking/github-issues/sprint/{{date}}/` | -| Execution | [github-backlog-update.instructions.md](../instructions/github-backlog-update.instructions.md) | `.copilot-tracking/github-issues/execution/{{date}}/` | -| Single Issue | Per-issue operations from [github-backlog-update.instructions.md](../instructions/github-backlog-update.instructions.md) | `.copilot-tracking/github-issues/execution/{{date}}/` | +| Workflow | Instruction Source | Tracking Path | +| --------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | +| Triage | [github-backlog-triage.instructions.md](../instructions/github-backlog-triage.instructions.md) | `.copilot-tracking/github-issues/triage/{{YYYY-MM-DD}}/` | +| Discovery | [github-backlog-discovery.instructions.md](../instructions/github-backlog-discovery.instructions.md) | `.copilot-tracking/github-issues/discovery/{{scope-name}}/` | +| Sprint Planning | Discovery followed by Triage as a coordinated sequence | `.copilot-tracking/github-issues/sprint/{{milestone-kebab}}/` | +| Execution | [github-backlog-update.instructions.md](../instructions/github-backlog-update.instructions.md) | `.copilot-tracking/github-issues/execution/{{YYYY-MM-DD}}/` | +| Single Issue | Per-issue operations from [github-backlog-update.instructions.md](../instructions/github-backlog-update.instructions.md) | `.copilot-tracking/github-issues/execution/{{YYYY-MM-DD}}/` | For each dispatched workflow: diff --git a/.github/instructions/community-interaction.instructions.md b/.github/instructions/community-interaction.instructions.md index ba890e29..59c140d5 100644 --- a/.github/instructions/community-interaction.instructions.md +++ b/.github/instructions/community-interaction.instructions.md @@ -248,7 +248,7 @@ Triggered when a PR review identifies specific changes needed before the PR can Post via: -1. `mcp_github_add_issue_comment` with the change request, or `mcp_github_pull_request_review_write` with method `create` and event `REQUEST_CHANGES`. +1. `mcp_github_add_issue_comment` with the change request. #### Scenario 16: Redirecting to Discussions From 319a84fdb449efe255b071d2044d85627a9cf14a Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Sat, 7 Feb 2026 09:43:19 -0800 Subject: [PATCH 4/8] feat(extension): add prerelease npm script aliases for dual-channel packaging MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - add extension:prepare:prerelease and extension:package:prerelease npm scripts - update PACKAGING.md with prerelease commands in prepare, package, and pre-release sections ๐Ÿ“ฆ - Generated by Copilot --- extension/PACKAGING.md | 27 +++++++++++++++++++++------ package.json | 2 ++ 2 files changed, 23 insertions(+), 6 deletions(-) diff --git a/extension/PACKAGING.md b/extension/PACKAGING.md index 8f9e03f9..8822945c 100644 --- a/extension/PACKAGING.md +++ b/extension/PACKAGING.md @@ -69,11 +69,17 @@ The extension is automatically packaged and published through GitHub Actions: First, update `package.json` with discovered agents, prompts, and instructions: ```bash -# Discover components and update package.json +# Discover components and update package.json (Stable channel) pwsh ./scripts/extension/Prepare-Extension.ps1 # Or use npm script npm run extension:prepare + +# For PreRelease channel (includes preview and experimental artifacts) +pwsh ./scripts/extension/Prepare-Extension.ps1 -Channel PreRelease + +# Or use npm script +npm run extension:prepare:prerelease ``` The preparation script automatically: @@ -89,12 +95,18 @@ The preparation script automatically: Then package the extension: ```bash -# Package using version from package.json +# Package using version from package.json (Stable channel) pwsh ./scripts/extension/Package-Extension.ps1 # Or use npm script npm run extension:package +# Package for PreRelease channel +pwsh ./scripts/extension/Package-Extension.ps1 -PreRelease + +# Or use npm script +npm run extension:package:prerelease + # Package with specific version pwsh ./scripts/extension/Package-Extension.ps1 -Version "1.0.3" @@ -222,12 +234,15 @@ Users can switch between channels in VS Code via the "Switch to Pre-Release Vers Package for the pre-release channel with the `-PreRelease` switch: ```bash -# Package for pre-release channel (includes experimental agents) -pwsh ./scripts/extension/Package-Extension.ps1 -Version "1.1.0" -PreRelease - -# Prepare with PreRelease channel filtering first +# Prepare with PreRelease channel filtering pwsh ./scripts/extension/Prepare-Extension.ps1 -Channel PreRelease +# Or use npm script +npm run extension:prepare:prerelease + +# Package for pre-release channel (includes experimental agents) pwsh ./scripts/extension/Package-Extension.ps1 -Version "1.1.0" -PreRelease +# Or use npm script for default version +npm run extension:package:prerelease ``` The `-PreRelease` switch adds `--pre-release` to the vsce command, marking the package for the Marketplace pre-release track. diff --git a/package.json b/package.json index 66e969de..b1176b51 100644 --- a/package.json +++ b/package.json @@ -18,7 +18,9 @@ "lint:all": "npm run format:tables && npm run lint:md && npm run lint:ps && npm run lint:yaml && npm run lint:links && npm run lint:frontmatter && npm run lint:version-consistency", "format:tables": "markdown-table-formatter \"**/*.md\"", "extension:prepare": "pwsh ./scripts/extension/Prepare-Extension.ps1", + "extension:prepare:prerelease": "pwsh ./scripts/extension/Prepare-Extension.ps1 -Channel PreRelease", "extension:package": "pwsh ./scripts/extension/Package-Extension.ps1", + "extension:package:prerelease": "pwsh ./scripts/extension/Package-Extension.ps1 -PreRelease", "validate:copyright": "pwsh -File scripts/linting/Test-CopyrightHeaders.ps1" }, "devDependencies": { From f7e3dcf8fac679078c6b8ad6fbb7531fc92841b9 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Sat, 7 Feb 2026 09:43:34 -0800 Subject: [PATCH 5/8] feat(instructions): add comment action type and refine triage for unclassified issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - add Comment operation to planning handoff template and field matrix - retain needs-triage on unclassified issues across all autonomy tiers - create planning folder for all discovery paths, not just Path B - update execution priority to include Comment after Close ๐Ÿท๏ธ - Generated by Copilot --- .../github-backlog-discovery.instructions.md | 10 +++--- .../github-backlog-planning.instructions.md | 36 +++++++++++-------- .../github-backlog-triage.instructions.md | 25 ++++++++----- .../github-backlog-update.instructions.md | 2 +- .../prompts/github-discover-issues.prompt.md | 3 +- .../prompts/github-triage-issues.prompt.md | 9 ++--- 6 files changed, 53 insertions(+), 32 deletions(-) diff --git a/.github/instructions/github-backlog-discovery.instructions.md b/.github/instructions/github-backlog-discovery.instructions.md index 2b7ed46e..9a25b6da 100644 --- a/.github/instructions/github-backlog-discovery.instructions.md +++ b/.github/instructions/github-backlog-discovery.instructions.md @@ -87,8 +87,9 @@ Execution: 3. Execute `mcp_github_search_issues` and paginate until all results are retrieved. 4. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `${input:includeSubIssues}` is true, also fetch sub-issues. 5. Present results grouped by state and labels. -6. Log discovered issues in *planning-log.md* and deliver a conversational summary. -7. Skip Phases 2-3; no planning files are required for user-centric discovery. +6. Create the planning folder at `.copilot-tracking/github-issues/discovery//` and initialize *planning-log.md*. +7. Log discovered issues in *planning-log.md* and deliver a conversational summary. +8. Skip Phases 2-3; no additional planning files beyond *planning-log.md* are required for user-centric discovery. #### Path B: Artifact-Driven Discovery @@ -148,8 +149,9 @@ Execution: 3. Execute `mcp_github_search_issues` for each query and paginate results. 4. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `${input:includeSubIssues}` is true, also fetch sub-issues. 5. Present results grouped by state and labels. -6. Log discovered issues in *planning-log.md* and deliver a conversational summary. -7. Skip Phases 2-3; no planning files are required for search-based discovery. +6. Create the planning folder at `.copilot-tracking/github-issues/discovery//` and initialize *planning-log.md*. +7. Log discovered issues in *planning-log.md* and deliver a conversational summary. +8. Skip Phases 2-3; no additional planning files beyond *planning-log.md* are required for search-based discovery. ### Phase 2: Plan Issues diff --git a/.github/instructions/github-backlog-planning.instructions.md b/.github/instructions/github-backlog-planning.instructions.md index 82c734c0..bf964afb 100644 --- a/.github/instructions/github-backlog-planning.instructions.md +++ b/.github/instructions/github-backlog-planning.instructions.md @@ -336,7 +336,7 @@ Phase tracking applies when the consuming workflow file defines phases (see the Handoff file requirements: * Agents must include a reference to each issue defined in issues-plan.md. -* Agents must order entries with Create actions first, Update actions second, Link actions third, Close actions fourth, and No Change entries last. +* Agents must order entries with Create actions first, Update actions second, Link actions third, Close actions fourth, Comment actions fifth, and No Change entries last. * Agents must include a markdown checkbox next to each issue with a summary. * Agents must include project-relative paths to all planning files. * Agents must update the Summary section whenever the Issues section changes. @@ -368,6 +368,7 @@ This convention enables resumable execution. When an execution run is interrupte | Update | {{update_count}} | | Link | {{link_count}} | | Close | {{close_count}} | +| Comment | {{comment_count}} | | No Change | {{no_change_count}} | ## Issues @@ -397,6 +398,12 @@ This convention enables resumable execution. When an execution run is interrupte - Reason: {{state_reason}} (completed|not_planned|duplicate) - Duplicate of: #{{duplicate_of}} (if applicable) +### Comment + +- [ ] Comment on #{{issue_number}} + - Body: {{comment_body}} + - Rationale: {{reason}} + ### No Change - [ ] (No Change) #{{issue_number}}: {{title}} @@ -637,19 +644,19 @@ When uncertain about milestone assignment, agents should default to the next ODD Track field usage explicitly so downstream automation can rely on consistent data. The matrix defines required and optional fields per operation type. These field requirements apply to both issues and pull requests. When targeting a pull request, pass the PR number as `issue_number` (see the Pull Request Field Operations section in the MCP Tool Catalog). -| Field | Create | Update | Link | Close | -| ------------- | -------- | -------- | -------- | -------- | -| title | REQUIRED | Optional | N/A | N/A | -| body | REQUIRED | Optional | N/A | N/A | -| labels | REQUIRED | Optional | N/A | N/A | -| assignees | Optional | Optional | N/A | N/A | -| milestone | Optional | Optional | N/A | N/A | -| issue_number | N/A | REQUIRED | REQUIRED | REQUIRED | -| state | N/A | Optional | N/A | REQUIRED | -| state_reason | N/A | N/A | N/A | REQUIRED | -| sub_issue_id | N/A | N/A | REQUIRED | N/A | -| duplicate_of | N/A | N/A | N/A | Optional | -| type | Optional | Optional | N/A | N/A | +| Field | Create | Update | Link | Close | Comment | +| ------------ | -------- | -------- | -------- | -------- | -------- | +| title | REQUIRED | Optional | N/A | N/A | N/A | +| body | REQUIRED | Optional | N/A | N/A | REQUIRED | +| labels | REQUIRED | Optional | N/A | N/A | N/A | +| assignees | Optional | Optional | N/A | N/A | N/A | +| milestone | Optional | Optional | N/A | N/A | N/A | +| issue_number | N/A | REQUIRED | REQUIRED | REQUIRED | REQUIRED | +| state | N/A | Optional | N/A | REQUIRED | N/A | +| state_reason | N/A | N/A | N/A | REQUIRED | N/A | +| sub_issue_id | N/A | N/A | REQUIRED | N/A | N/A | +| duplicate_of | N/A | N/A | N/A | Optional | N/A | +| type | Optional | Optional | N/A | N/A | N/A | Rules: @@ -658,6 +665,7 @@ Rules: * Link operations must provide both issue_number (parent) and sub_issue_id (child). * Close operations must provide issue_number, state set to `closed`, and a state_reason (one of: `completed`, `not_planned`, `duplicate`). * When closing as `duplicate`, the `duplicate_of` field should reference the original issue number. +* Comment operations must provide issue_number and body (passed to `mcp_github_add_issue_comment`). * Call `mcp_github_list_issue_types` before using the `type` field to confirm the organization supports issue types. ## Three-Tier Autonomy Model diff --git a/.github/instructions/github-backlog-triage.instructions.md b/.github/instructions/github-backlog-triage.instructions.md index 17ff6095..13e8af83 100644 --- a/.github/instructions/github-backlog-triage.instructions.md +++ b/.github/instructions/github-backlog-triage.instructions.md @@ -24,12 +24,14 @@ Follow community interaction guidelines from #file:./community-interaction.instr ### Autonomy Behavior for Triage Operations -| Operation | Full | Partial | Manual | -| -------------------- | ------------ | ------------ | ------------ | -| Label assignment | Auto-execute | Auto-execute | Gate on user | -| Milestone assignment | Auto-execute | Auto-execute | Gate on user | -| Duplicate closure | Auto-execute | Gate on user | Gate on user | -| needs-triage removal | Auto-execute | Auto-execute | Gate on user | +| Operation | Full | Partial | Manual | +| --------------------------------- | ------------ | ------------ | ------------ | +| Label assignment | Auto-execute | Auto-execute | Gate on user | +| Milestone assignment | Auto-execute | Auto-execute | Gate on user | +| Duplicate closure | Auto-execute | Gate on user | Gate on user | +| needs-triage removal (classified) | Auto-execute | Auto-execute | Gate on user | + +Unclassified issues (titles without a recognized conventional commit pattern) retain `needs-triage` across all autonomy tiers. Label and milestone suggestions still apply, but `needs-triage` is not removed. ## Required Phases @@ -110,13 +112,20 @@ When `${input:autonomy}` is `full`, proceed directly to Step 3 without waiting f On user confirmation (or immediately under full autonomy), apply the approved recommendations. -For non-duplicate issues, consolidate label assignment, milestone assignment, and `needs-triage` removal into a single API call per issue: +For classified non-duplicate issues (title matched a recognized conventional commit pattern), consolidate label assignment, milestone assignment, and `needs-triage` removal into a single API call per issue: 1. Compute the new label set: `(current_labels - "needs-triage") + suggested_labels`. 2. Call `mcp_github_issue_write` with `method: 'update'`, `labels: [computed_set]`, and `milestone: suggested_milestone`. The `labels` parameter uses replacement semantics. The computed set MUST include all labels to retain, all suggested labels to add, and MUST exclude `needs-triage`. +For unclassified non-duplicate issues (title did not match any recognized pattern), apply suggested labels while retaining `needs-triage`: + +1. Compute the new label set: `current_labels + suggested_labels`. +2. Call `mcp_github_issue_write` with `method: 'update'`, `labels: [computed_set]`, and `milestone: suggested_milestone`. + +The `labels` parameter uses replacement semantics. The computed set MUST include all existing labels (including `needs-triage`), plus any suggested labels. + For confirmed duplicates, apply the comment-before-closure pattern: 1. Post a comment using `mcp_github_add_issue_comment` with the Scenario 7 (Closing a Duplicate Issue) template from `community-interaction.instructions.md`, filling `{{original_number}}` with the matched issue number. @@ -293,7 +302,7 @@ Triage is complete when: * All fetched issues (up to `${input:maxIssues}`) with the `needs-triage` label have been analyzed for label suggestions, milestone recommendations, and duplicate candidates. * A triage-plan.md exists with a recommendation row for every analyzed issue. * The user has reviewed and confirmed (or adjusted) the triage plan, respecting the active autonomy tier. -* Confirmed recommendations have been executed via consolidated API calls (labels assigned, milestones set, `needs-triage` removed, duplicates closed). +* Confirmed recommendations have been executed via consolidated API calls (labels assigned, milestones set, `needs-triage` removed from classified issues, duplicates closed). * planning-log.md reflects the final state of all operations with checkboxes marking completion. * Any failed operations have been logged and either retried or flagged for manual follow-up. diff --git a/.github/instructions/github-backlog-update.instructions.md b/.github/instructions/github-backlog-update.instructions.md index fc328be7..9c537670 100644 --- a/.github/instructions/github-backlog-update.instructions.md +++ b/.github/instructions/github-backlog-update.instructions.md @@ -52,7 +52,7 @@ When handoff-logs.md exists next to ${input:handoffFile}: * Read handoff-logs.md and ${input:handoffFile}. * Identify operations with unchecked `[ ]` status. * Rebuild the temporary ID mapping from previously completed Create entries (the Issue Number field in each completed log entry records the `{{TEMP-N}}` to `#actual` mapping). -* Resume processing in priority order: Create โ†’ Update โ†’ Link โ†’ Close, starting from the first unchecked operation in that sequence. +* Resume processing in priority order: Create โ†’ Update โ†’ Link โ†’ Close โ†’ Comment, starting from the first unchecked operation in that sequence. When handoff-logs.md does not exist: diff --git a/.github/prompts/github-discover-issues.prompt.md b/.github/prompts/github-discover-issues.prompt.md index ff439f1b..d893da52 100644 --- a/.github/prompts/github-discover-issues.prompt.md +++ b/.github/prompts/github-discover-issues.prompt.md @@ -33,7 +33,8 @@ Resolve the repository owner and name from the active workspace context or user * Path A (User-Centric): User requests assigned issues, milestone progress, or their own work without referencing artifacts or search terms. * Path B (Artifact-Driven): Documents, PRDs, or requirements are provided via `${input:documents}` or conversation. User requests issue creation or updates from artifacts. * Path C (Search-Based): User provides `${input:searchTerms}` directly without artifacts or assignment context. -3. When Path B is selected, create the planning folder at `.copilot-tracking/github-issues/discovery//` and initialize *planning-log.md*. When the organization supports issue types, call `mcp_github_list_issue_types` with the owner parameter. +3. Create the planning folder at `.copilot-tracking/github-issues/discovery//` and initialize *planning-log.md*. +4. When Path B is selected and the organization supports issue types, call `mcp_github_list_issue_types` with the owner parameter. When neither documents nor search terms are provided and user intent does not indicate assigned-issue retrieval, ask the user to clarify their discovery goal before proceeding. diff --git a/.github/prompts/github-triage-issues.prompt.md b/.github/prompts/github-triage-issues.prompt.md index e488d474..dc65128a 100644 --- a/.github/prompts/github-triage-issues.prompt.md +++ b/.github/prompts/github-triage-issues.prompt.md @@ -58,16 +58,17 @@ Present the triage plan to the user as a summary table. Execution follows the `${input:autonomy}` tier per the Three-Tier Autonomy Model in the planning specification. Under `partial` (default), label assignments, milestone assignments, and `needs-triage` removal auto-execute, but duplicate closures gate on user approval. Under `full`, all operations execute immediately. Under `manual`, every operation gates on user confirmation. 1. Collect user confirmation or modifications per the active autonomy tier before applying gated changes. -2. For each confirmed non-duplicate issue, compute the replacement label set as `(current_labels - "needs-triage") + suggested_labels` and apply labels, milestone, and `needs-triage` removal in a single `mcp_github_issue_write` call with `method: 'update'`. The `labels` parameter uses replacement semantics: include all labels to retain, all labels to add, and exclude `needs-triage`. -3. For confirmed Match-category duplicates, close using `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'duplicate'`, and `duplicate_of` referencing the original issue. -4. Update planning-log.md with execution results for each processed issue. +2. For each confirmed non-duplicate issue whose title matched a recognized conventional commit pattern, compute the replacement label set as `(current_labels - "needs-triage") + suggested_labels` and apply labels, milestone, and `needs-triage` removal in a single `mcp_github_issue_write` call with `method: 'update'`. The `labels` parameter uses replacement semantics: include all labels to retain, all labels to add, and exclude `needs-triage`. +3. For each confirmed non-duplicate issue whose title did not match a recognized pattern, compute the replacement label set as `current_labels + suggested_labels` (retaining `needs-triage`) and apply labels and milestone in a single `mcp_github_issue_write` call with `method: 'update'`. The `labels` parameter uses replacement semantics: include all existing labels including `needs-triage`, plus all suggested labels. +4. For confirmed Match-category duplicates, close using `mcp_github_issue_write` with `state: 'closed'`, `state_reason: 'duplicate'`, and `duplicate_of` referencing the original issue. +5. Update planning-log.md with execution results for each processed issue. ## Success Criteria * All fetched issues have triage recommendations with label suggestions, milestone assignments, and duplicate assessments. * The triage plan has been reviewed per the active autonomy tier before execution. * Labels and milestones are applied using replacement semantics in consolidated API calls. -* The `needs-triage` label is removed from all processed issues. +* The `needs-triage` label is removed from all classified issues. Unclassified issues retain `needs-triage` for manual review. * Planning artifacts are created in `.copilot-tracking/github-issues/triage/{{YYYY-MM-DD}}/`. ## Error Handling From 4289ee283f67873eaa4ca40698daa503778d78eb Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Sat, 7 Feb 2026 20:33:21 -0800 Subject: [PATCH 6/8] fix(instructions): set inactivity closure time periods in community interaction templates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - set stale issue closure period to 74 days (60-day stale + 14-day grace) - set stale PR closure period to 21 days (14-day stale + 7-day grace) ๐Ÿ”ง - Generated by Copilot --- .github/instructions/community-interaction.instructions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/instructions/community-interaction.instructions.md b/.github/instructions/community-interaction.instructions.md index 59c140d5..2299decf 100644 --- a/.github/instructions/community-interaction.instructions.md +++ b/.github/instructions/community-interaction.instructions.md @@ -172,7 +172,7 @@ Post via: Triggered when an issue has had no activity for an extended period and lacks sufficient information to act on. Tone is neutral and informational with no blame and a clear reopen path. -> Closing this issue due to inactivity over the past {{time_period}}. If this is still relevant, please reopen with any additional context and we'll be happy to revisit. +> Closing this issue due to inactivity over the past 74 days. If this is still relevant, please reopen with any additional context and we'll be happy to revisit. Post via: @@ -183,7 +183,7 @@ Post via: Triggered when a PR has had no activity for an extended period and has fallen behind the base branch. Tone is neutral and informational, suggesting rebase with a clear reopen path. -> Closing this PR due to inactivity over the past {{time_period}}. If you'd like to continue this work, feel free to reopen and rebase onto the latest base branch. We're happy to resume the review. +> Closing this PR due to inactivity over the past 21 days. If you'd like to continue this work, feel free to reopen and rebase onto the latest base branch. We're happy to resume the review. Post via: From d2e8b3e85d8467369d3d8919b2f7e950f9467c55 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Sat, 7 Feb 2026 20:54:08 -0800 Subject: [PATCH 7/8] fix(agents): address unresolved review comments on backlog pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - change handoff prompt values from filenames to slash commands - fix template blockquote links to use absolute URLs with owner/repo vars - add execution as a valid planning type in backlog planning spec ๐Ÿ”ง - Generated by Copilot --- .github/agents/github-backlog-manager.agent.md | 10 +++++----- .../instructions/community-interaction.instructions.md | 10 +++++----- .../github-backlog-planning.instructions.md | 1 + 3 files changed, 11 insertions(+), 10 deletions(-) diff --git a/.github/agents/github-backlog-manager.agent.md b/.github/agents/github-backlog-manager.agent.md index 095e2be1..db189307 100644 --- a/.github/agents/github-backlog-manager.agent.md +++ b/.github/agents/github-backlog-manager.agent.md @@ -13,19 +13,19 @@ tools: handoffs: - label: "Discover" agent: github-backlog-manager - prompt: github-discover-issues.prompt.md + prompt: /github-discover-issues - label: "Triage" agent: github-backlog-manager - prompt: github-triage-issues.prompt.md + prompt: /github-triage-issues - label: "Sprint" agent: github-backlog-manager - prompt: github-sprint-plan.prompt.md + prompt: /github-sprint-plan - label: "Execute" agent: github-backlog-manager - prompt: github-execute-backlog.prompt.md + prompt: /github-execute-backlog - label: "Save" agent: memory - prompt: checkpoint.prompt.md + prompt: /checkpoint --- # GitHub Backlog Manager diff --git a/.github/instructions/community-interaction.instructions.md b/.github/instructions/community-interaction.instructions.md index 2299decf..3c1a5894 100644 --- a/.github/instructions/community-interaction.instructions.md +++ b/.github/instructions/community-interaction.instructions.md @@ -69,7 +69,7 @@ Template placeholders used across scenarios: Triggered when a contributor opens their first issue or PR in the repository. Tone is warm and genuine, encouraging first engagement. -> Welcome to the project, @{{contributor}}! ๐ŸŽ‰ Thank you for your first contribution. Please review our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and expectations. A maintainer will review your submission within the next few business days. +> Welcome to the project, @{{contributor}}! ๐ŸŽ‰ Thank you for your first contribution. Please review our [CONTRIBUTING.md](https://github.com/{{owner}}/{{repo}}/blob/main/CONTRIBUTING.md) for guidelines and expectations. A maintainer will review your submission within the next few business days. Post via: @@ -109,7 +109,7 @@ Post via: Triggered when a contributor reports a security vulnerability through any channel. Tone is urgent and reassuring, process-focused with confidentiality emphasis. -> Thank you for reporting this security concern, @{{contributor}}. We take security seriously and will investigate promptly. Please review our [SECURITY.md](SECURITY.md) for next steps on the responsible disclosure process. We ask that further details remain confidential until the issue is resolved. +> Thank you for reporting this security concern, @{{contributor}}. We take security seriously and will investigate promptly. Please review our [SECURITY.md](https://github.com/{{owner}}/{{repo}}/blob/main/SECURITY.md) for next steps on the responsible disclosure process. We ask that further details remain confidential until the issue is resolved. Post via: @@ -280,7 +280,7 @@ Triggered when a conversation becomes unproductive, personal, or heated, but has > We appreciate everyone's engagement on this topic. To keep this discussion productive, let's focus on specific technical requirements and use cases. > -> Our [Code of Conduct](CODE_OF_CONDUCT.md) applies to all interactions. Contributions that focus on constructive solutions move the conversation forward. +> Our [Code of Conduct](https://github.com/{{owner}}/{{repo}}/blob/main/CODE_OF_CONDUCT.md) applies to all interactions. Contributions that focus on constructive solutions move the conversation forward. Post via: @@ -290,9 +290,9 @@ Post via: Triggered when a conversation has crossed Code of Conduct boundaries or de-escalation has been insufficient. Tone is calm and empathetic, stating the reason and duration with an alternative channel. -> This conversation is being locked for {{time_period}} to allow a cooling-off period. Our [Code of Conduct](CODE_OF_CONDUCT.md) outlines the expectations for all community interactions. +> This conversation is being locked for {{time_period}} to allow a cooling-off period. Our [Code of Conduct](https://github.com/{{owner}}/{{repo}}/blob/main/CODE_OF_CONDUCT.md) outlines the expectations for all community interactions. > -> If you need to continue this discussion, please reach out to the maintainers through the channels listed in [SUPPORT.md](SUPPORT.md). +> If you need to continue this discussion, please reach out to the maintainers through the channels listed in [SUPPORT.md](https://github.com/{{owner}}/{{repo}}/blob/main/SUPPORT.md). Post via: diff --git a/.github/instructions/github-backlog-planning.instructions.md b/.github/instructions/github-backlog-planning.instructions.md index bf964afb..dbbdd4be 100644 --- a/.github/instructions/github-backlog-planning.instructions.md +++ b/.github/instructions/github-backlog-planning.instructions.md @@ -108,6 +108,7 @@ Valid `` values: * `triage`: Issue triage, label assignment, and duplicate detection * `sprint`: Sprint planning and milestone organization * `backlog`: Backlog refinement and prioritization +* `execution`: Issue creation, update, and closure from finalized plans Normalization rules for ``: From a4139593fb99dd7d09fb232087bc745b2c320ad9 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Mon, 9 Feb 2026 17:31:08 -0800 Subject: [PATCH 8/8] refactor(instructions): remove input variable declarations from backlog instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - remove Inputs sections from discovery, triage, and update instructions - replace body `${input:}` references with plain parameter names - align update instructions to use `handoff` matching prompt canonical name ๐Ÿ”ง - Generated by Copilot --- .../github-backlog-discovery.instructions.md | 27 ++++++------------ .../github-backlog-triage.instructions.md | 18 ++++-------- .../github-backlog-update.instructions.md | 28 +++++++------------ 3 files changed, 23 insertions(+), 50 deletions(-) diff --git a/.github/instructions/github-backlog-discovery.instructions.md b/.github/instructions/github-backlog-discovery.instructions.md index 9a25b6da..65f7b200 100644 --- a/.github/instructions/github-backlog-discovery.instructions.md +++ b/.github/instructions/github-backlog-discovery.instructions.md @@ -10,17 +10,6 @@ Discover GitHub issues through three paths: user-centric queries, artifact-drive ## Scope -**Inputs**: - -| Input | Required | Description | -| --------------------------- | -------- | ---------------------------------------------------------------- | -| `${input:owner}` | Yes | Repository owner, user or organization | -| `${input:repo}` | Yes | Repository name | -| `${input:milestone}` | No | Milestone name or number to scope searches | -| `${input:documents}` | No | File paths or URLs of source documents (PRDs, RFCs, ADRs) | -| `${input:searchTerms}` | No | Keywords or phrases to supplement extracted terms | -| `${input:includeSubIssues}` | No | Fetch sub-issues for each discovered issue (default: `false`) | - **Discovery path selection**: * User-centric (Path A): User requests their issues, assigned work, or milestone progress without referencing artifacts @@ -49,7 +38,7 @@ Paths A and C produce a conversational summary with counts and relevant issue li * `mcp_github_search_issues`: Search with `assignee:` qualifier scoped to `repo:{owner}/{repo}` * Key params: `query` (required), `owner`, `repo`, `perPage`, `page` * `mcp_github_issue_read`: Hydrate results with `method: 'get'` for full details - * When `${input:includeSubIssues}` is true, also call with `method: 'get_sub_issues'` + * When `includeSubIssues` is true, also call with `method: 'get_sub_issues'` **Artifact-driven discovery (Path B)**: @@ -83,9 +72,9 @@ Use when: Execution: 1. Call `mcp_github_get_me` to determine the authenticated user. -2. Build a search query with `repo:{owner}/{repo} is:issue assignee:{username}`. Apply `milestone:` and `label:` qualifiers when `${input:milestone}` or label context is provided. +2. Build a search query with `repo:{owner}/{repo} is:issue assignee:{username}`. Apply `milestone:` and `label:` qualifiers when `milestone` or label context is provided. 3. Execute `mcp_github_search_issues` and paginate until all results are retrieved. -4. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `${input:includeSubIssues}` is true, also fetch sub-issues. +4. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `includeSubIssues` is true, also fetch sub-issues. 5. Present results grouped by state and labels. 6. Create the planning folder at `.copilot-tracking/github-issues/discovery//` and initialize *planning-log.md*. 7. Log discovered issues in *planning-log.md* and deliver a conversational summary. @@ -95,7 +84,7 @@ Execution: Use when: -* Documents, PRDs, or requirements are provided via `${input:documents}` or conversation +* Documents, PRDs, or requirements are provided via `documents` or conversation * User explicitly requests issue creation or updates from artifacts Skip conditions: @@ -109,9 +98,9 @@ Execution: 3. Read each document to completion and extract discrete requirements, acceptance criteria, and action items using the document parsing guidelines in this file. 4. Record each extracted requirement as a candidate issue entry in *issue-analysis.md* with: temporary ID, suggested title in conventional commit format, body summary, suggested labels, suggested milestone, and source reference. 5. Build keyword groups from extracted requirements per the Search Protocol in *github-backlog-planning.instructions.md*. -6. Compose GitHub search queries scoped to `repo:{owner}/{repo}`. Apply `milestone:` qualifier when `${input:milestone}` is provided. +6. Compose GitHub search queries scoped to `repo:{owner}/{repo}`. Apply `milestone:` qualifier when `milestone` is provided. 7. Execute `mcp_github_search_issues` for each keyword group and paginate results. -8. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `${input:includeSubIssues}` is true, also fetch sub-issues. +8. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `includeSubIssues` is true, also fetch sub-issues. 9. Assess similarity between each fetched issue and the candidate set using the Similarity Assessment Framework in *github-backlog-planning.instructions.md*. Classify each pair as Match, Similar, Distinct, or Uncertain. 10. De-duplicate results across keyword groups; retain the highest similarity category when the same issue appears in multiple searches. 11. Log all progress in *planning-log.md* with search queries, result counts, and similarity assessments. @@ -145,9 +134,9 @@ Use when: Execution: 1. Call `mcp_github_get_me` to verify repository access. -2. Build search queries from `${input:searchTerms}` scoped to `repo:{owner}/{repo}`. Apply `milestone:` qualifier when `${input:milestone}` is provided. +2. Build search queries from `searchTerms` scoped to `repo:{owner}/{repo}`. Apply `milestone:` qualifier when `milestone` is provided. 3. Execute `mcp_github_search_issues` for each query and paginate results. -4. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `${input:includeSubIssues}` is true, also fetch sub-issues. +4. Hydrate each result via `mcp_github_issue_read` with `method: 'get'`. When `includeSubIssues` is true, also fetch sub-issues. 5. Present results grouped by state and labels. 6. Create the planning folder at `.copilot-tracking/github-issues/discovery//` and initialize *planning-log.md*. 7. Log discovered issues in *planning-log.md* and deliver a conversational summary. diff --git a/.github/instructions/github-backlog-triage.instructions.md b/.github/instructions/github-backlog-triage.instructions.md index 13e8af83..388bd33e 100644 --- a/.github/instructions/github-backlog-triage.instructions.md +++ b/.github/instructions/github-backlog-triage.instructions.md @@ -14,15 +14,7 @@ Follow all instructions from #file:./github-backlog-planning.instructions.md whi Follow community interaction guidelines from #file:./community-interaction.instructions.md when posting comments visible to external contributors. -## Inputs - -* `${input:owner}`: (Required) Repository owner (username or organization). -* `${input:repo}`: (Required) Repository name. -* `${input:maxIssues:20}`: (Optional, defaults to 20) Maximum number of untriaged issues to process per batch. -* `${input:milestone}`: (Optional) Override milestone name. When provided, skip milestone discovery and use this value for all non-duplicate issues. -* `${input:autonomy:partial}`: (Optional, defaults to partial) Autonomy tier controlling confirmation gates. Values: `full`, `partial`, `manual`. See the Three-Tier Autonomy Model in the planning specification. - -### Autonomy Behavior for Triage Operations +## Autonomy Behavior for Triage Operations | Operation | Full | Partial | Manual | | --------------------------------- | ------------ | ------------ | ------------ | @@ -41,7 +33,7 @@ Fetch and analyze untriaged issues to build a comprehensive triage assessment. P #### Step 1: Discover Available Milestones -Before analyzing issues, determine the current EVEN and next ODD milestones. When `${input:milestone}` is provided, skip this step and use the override value. +Before analyzing issues, determine the current EVEN and next ODD milestones. When `milestone` is provided, skip this step and use the override value. 1. Search for recent issues with milestone assignments using `mcp_github_search_issues` to identify active milestone names. 2. Derive the current EVEN milestone and next ODD milestone from the discovered names. @@ -57,7 +49,7 @@ Search for issues carrying the `needs-triage` label using `mcp_github_search_iss repo:{owner}/{repo} is:issue is:open label:needs-triage ``` -Paginate results using `perPage` and `page` parameters, limiting to `${input:maxIssues}` total issues. +Paginate results using `perPage` and `page` parameters, limiting to `maxIssues` total issues. When no untriaged issues are found, inform the user and end the workflow. No further phases apply. @@ -106,7 +98,7 @@ Present the triage plan to the user, highlighting: * Issues flagged as potential duplicates * Issues requiring manual review (ambiguous titles, conflicting labels, uncertain similarity) -When `${input:autonomy}` is `full`, proceed directly to Step 3 without waiting for user confirmation. When `partial`, gate on duplicate closures only. When `manual`, wait for user confirmation of the entire plan. +When `autonomy` is `full`, proceed directly to Step 3 without waiting for user confirmation. When `partial`, gate on duplicate closures only. When `manual`, wait for user confirmation of the entire plan. #### Step 3: Execute Confirmed Recommendations @@ -299,7 +291,7 @@ Use the planning-log.md template from the planning specification. Set the planni Triage is complete when: -* All fetched issues (up to `${input:maxIssues}`) with the `needs-triage` label have been analyzed for label suggestions, milestone recommendations, and duplicate candidates. +* All fetched issues (up to `maxIssues`) with the `needs-triage` label have been analyzed for label suggestions, milestone recommendations, and duplicate candidates. * A triage-plan.md exists with a recommendation row for every analyzed issue. * The user has reviewed and confirmed (or adjusted) the triage plan, respecting the active autonomy tier. * Confirmed recommendations have been executed via consolidated API calls (labels assigned, milestones set, `needs-triage` removed from classified issues, duplicates closed). diff --git a/.github/instructions/github-backlog-update.instructions.md b/.github/instructions/github-backlog-update.instructions.md index 9c537670..36ab5a7e 100644 --- a/.github/instructions/github-backlog-update.instructions.md +++ b/.github/instructions/github-backlog-update.instructions.md @@ -16,17 +16,9 @@ The execution protocol processes a handoff plan file to create, update, link, an All operations MUST execute sequentially. Parallel execution is not supported due to dependency chains between Create, Link, and Update operations. -### Inputs - -* `${input:handoffFile}`: Path to handoff.md or triage-plan.md containing planned issue operations (required) -* `${input:owner}`: Repository owner (inferred from handoff file if not provided) -* `${input:repo}`: Repository name (inferred from handoff file if not provided) -* `${input:autonomy}`: Autonomy tier controlling confirmation gates (one of: `full`, `partial`, `manual`; defaults to `partial`) -* `${input:dryRun}`: When `true`, simulate all operations without executing (defaults to `false`) - ### Outputs -* handoff-logs.md created next to ${input:handoffFile} containing per-operation processing status and results +* handoff-logs.md created next to `handoff` containing per-operation processing status and results * Issues created, updated, linked, or closed in the target GitHub repository ### Trigger Conditions @@ -47,9 +39,9 @@ Parent issues MUST be created before children to ensure sub-issue linking resolv ### Step 1: Initialize or Resume -When handoff-logs.md exists next to ${input:handoffFile}: +When handoff-logs.md exists next to `handoff`: -* Read handoff-logs.md and ${input:handoffFile}. +* Read handoff-logs.md and `handoff`. * Identify operations with unchecked `[ ]` status. * Rebuild the temporary ID mapping from previously completed Create entries (the Issue Number field in each completed log entry records the `{{TEMP-N}}` to `#actual` mapping). * Resume processing in priority order: Create โ†’ Update โ†’ Link โ†’ Close โ†’ Comment, starting from the first unchecked operation in that sequence. @@ -57,12 +49,12 @@ When handoff-logs.md exists next to ${input:handoffFile}: When handoff-logs.md does not exist: * Create handoff-logs.md using the template from #file:./github-backlog-planning.instructions.md. -* Populate the Operations section from ${input:handoffFile}. +* Populate the Operations section from `handoff`. * Record all inputs in the Execution Summary section. Validate the handoff before processing: -* Confirm ${input:owner} and ${input:repo} are set (from inputs or parsed from the handoff file header). +* Confirm `owner` and `repo` are set (from inputs or parsed from the handoff file header). * Verify all numeric issue references exist by calling `mcp_github_issue_read` with method `get` for each number. Skip `{{TEMP-N}}` placeholders during this validation since those issues do not exist yet. * Verify label names are valid by calling `mcp_github_get_label` for each unique label in the plan. * Call `mcp_github_list_issue_types` to confirm whether the organization supports issue types before using the `type` field. @@ -82,7 +74,7 @@ Process operations in this fixed order, matching the handoff.md template section Checkpoint after each operation completes: * Check the autonomy tier to determine whether a confirmation gate is required. Refer to the Three-Tier Autonomy Model in #file:./github-backlog-planning.instructions.md for gate definitions. When the user declines a gated operation, mark it as `Skipped` in handoff-logs.md and continue. -* When `${input:dryRun}` is `true`, simulate the operation and log it as `dry-run` without executing (see the Dry Run Mode section). +* When `dryRun` is `true`, simulate the operation and log it as `dry-run` without executing (see the Dry Run Mode section). * After each Create, resolve the `{{TEMP-N}}` placeholder to the actual issue number returned by `mcp_github_issue_write`. Record the mapping in handoff-logs.md. * When a `{{TEMP-N}}` reference appears in a Link or Update operation, resolve it from the mapping table before calling the MCP tool. * Update the checkbox to `[x]` in handoff.md after each operation completes. @@ -97,7 +89,7 @@ When an operation has no pending changes: ### Step 3: Finalize and Report -* Re-read handoff-logs.md and compare against ${input:handoffFile}. +* Re-read handoff-logs.md and compare against `handoff`. * Process any missed operations that were skipped due to dependency failures and have since been unblocked. Limit this retry pass to one additional iteration; log any operations still blocked after the retry as `Failed`. * Cross-check created issues against the plan to confirm all `{{TEMP-N}}` placeholders resolved. * Generate a handoff summary with counts: issues created, updated, closed, linked, failed, and skipped. @@ -185,19 +177,19 @@ Comments posted to GitHub issues or pull requests are visible to external contri ## Autonomy Levels -The autonomy model controls confirmation gates during execution. Defaults to Partial Autonomy when `${input:autonomy}` is not specified. Refer to the Three-Tier Autonomy Model in #file:./github-backlog-planning.instructions.md for the full specification and gate definitions. +The autonomy model controls confirmation gates during execution. Defaults to Partial Autonomy when `autonomy` is not specified. Refer to the Three-Tier Autonomy Model in #file:./github-backlog-planning.instructions.md for the full specification and gate definitions. When the user declines a gated operation, mark it as `Skipped` in handoff-logs.md and continue to the next operation. ## Dry Run Mode -When `${input:dryRun}` is `true`: +When `dryRun` is `true`: * Simulate all operations without calling MCP tools that modify state. * Read-only validation calls (`mcp_github_issue_read`, `mcp_github_get_label`) still execute to verify references. * Generate handoff-logs.md with all operations marked as `dry-run` status. * Present the execution summary for user review. -* Re-invoke with `${input:dryRun}` set to `false` to execute the plan. +* Re-invoke with `dryRun` set to `false` to execute the plan. ## Handoff File Format