Summary

Add a declarative labels.yml file and accompanying GitHub Actions workflow to manage repository labels as code, replacing ad-hoc manual label creation and ensuring label consistency across the repository lifecycle.

Acceptance Criteria

• New file .github/labels.yml defining all repository labels with name, color, and description
• New GitHub Actions workflow that synchronizes labels from labels.yml to the repository
• Workflow triggers on push to main when labels.yml changes, plus manual workflow_dispatch
• Existing labels not defined in labels.yml are preserved (no destructive sync) unless explicitly configured otherwise
• All current repository labels are captured in the initial labels.yml
• Documentation in the workflow file or README explains how to add/modify labels

Technical Details

Labels File Format

# .github/labels.yml
- name: feature
  color: "a2eeef"
  description: "New feature or request"
- name: bug
  color: "d73a4a"
  description: "Something isn't working"
- name: maintenance
  color: "0075ca"
  description: "Maintenance and chores"
# ... all other labels

Workflow Options

Several community actions support label-as-code workflows:

• EndBug/label-sync — Popular, supports additive and destructive sync modes
• micnncim/action-label-syncer — Lightweight alternative
• Custom script using gh label CLI commands

The workflow should default to additive mode (create and update labels, but do not delete labels missing from the file) to prevent accidental label removal.

Current Labels to Capture

All existing repository labels should be exported to labels.yml as the initial baseline, including the newly created codespaces label (#512).

Dependencies

• chore(github-metadata): add codespaces label for Codespaces-related issues #512 — The codespaces label created in that issue should be included in the initial labels.yml

How to Build This

This is an infrastructure-as-code implementation task using the task-implementor workflow.

Workflow: /task-research → /task-plan → /task-implement → /task-review

Phase 1: Research

Source Material

• This issue body
• #file:.github/workflows/main.yml (workflow pattern reference)
• #file:.github/workflows/pr-validation.yml (workflow pattern reference)
• #file:.github/instructions/hve-core/workflows.instructions.md (workflow conventions)

Steps

1. Type /clear to start a fresh context.
2. Attach or open the files listed above.
3. Copy and run this prompt:

/task-research topic="declarative GitHub label management with labels.yml"

Research approaches for managing GitHub repository labels as code. Investigate:

1. Popular label sync actions (EndBug/label-sync, crazy-max/ghaction-github-labeler,
   github/issue-labeler) and their YAML schema differences
2. The current set of labels on microsoft/hve-core (from the issue body and repo settings)
3. Label YAML schema options: name, color, description, aliases (for renaming)
4. Workflow trigger options: push to main (labels.yml changes), workflow_dispatch, schedule
5. How other Microsoft repos manage labels declaratively
6. Whether the sync action should delete labels not in the YAML file or only add/update
7. Workflow permissions needed (issues: write, or specific label permissions)

Output: Research document at .copilot-tracking/research/{{YYYY-MM-DD}}-label-management-research.md

Phase 2: Plan

Source Material

• Research document from Phase 1

Steps

1. Type /clear to start a fresh context.
2. Open the research document from Phase 1.
3. Copy and run this prompt:

/task-plan

Create an implementation plan for declarative label management. The plan should
cover the labels.yml schema, the sync workflow definition, and migration of the
current label set into the YAML file. Include action version pinning with SHA hashes
per repository conventions.

Output: Plan at .copilot-tracking/plans/ and details at .copilot-tracking/details/

Phase 3: Implement

Source Material

• Plan from Phase 2

Steps

1. Type /clear to start a fresh context.
2. Open the plan document from Phase 2.
3. Copy and run this prompt:

/task-implement

Implement the declarative label management system. Create .github/labels.yml with
the current label set, create the label-sync workflow, and ensure action versions
are SHA-pinned per repository conventions.

Output: New files created, changes log at .copilot-tracking/changes/

Phase 4: Review

Source Material

• Plan from Phase 2
• Changes log from Phase 3

Steps

1. Type /clear to start a fresh context.
2. Open the plan and changes log.
3. Copy and run this prompt:

/task-review

Review the label management implementation. Run these validation commands:
- npm run lint:yaml (validate labels.yml and workflow YAML)
Verify that the labels.yml contains all current repository labels, the workflow
uses SHA-pinned action references, and permissions are minimally scoped.

Output: Review log at .copilot-tracking/reviews/

After Review

• Pass: All criteria met. Create a PR referencing this issue.
• Iterate: Review found issues. Run /clear, return to Phase 3 with the review feedback.
• Escalate: Fundamental design issue discovered. Run /clear, return to Phase 1 to research the gap.

Authoring Standards

• Workflow files follow .github/instructions/hve-core/workflows.instructions.md
• Action references use SHA pinning with version comments
• YAML formatting follows repository conventions

Success Criteria

• .github/labels.yml contains all current repository labels
• Label-sync workflow runs on push to main and workflow_dispatch
• All action references are SHA-pinned
• Workflow permissions are minimally scoped
• npm run lint:yaml passes