From 25641370c418beaa0ed9e57eceed169a06ae8f3e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 20 Dec 2025 16:54:33 +0000
Subject: [PATCH 1/3] Initial plan


From d6d77a4c3f6df03b3b8686c2b6912f6b31f10845 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 20 Dec 2025 17:02:04 +0000
Subject: [PATCH 2/3] Add comprehensive label usage guidelines to
 CONTRIBUTING.md

Co-authored-by: mnkiefer <8320933+mnkiefer@users.noreply.github.com>
---
 CONTRIBUTING.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 41f6040ca79..d35386947d7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -227,6 +227,120 @@ For detailed guidelines and decision tree, see [specs/breaking-cli-rules.md](spe
 - Ensure all tests pass (`make test`)
 - Test manually with real workflows when possible
 
+## 🏷️ Label Guidelines
+
+### Purpose of Labels
+
+Labels help organize and triage issues for better project management. Use labels to:
+- Categorize issue type (bug, enhancement, documentation)
+- Indicate priority level
+- Mark workflow automation status
+- Identify component areas
+
+### Label Categories
+
+#### Type Labels (choose one)
+- **bug** - Something isn't working correctly
+- **enhancement** - New feature or improvement request
+- **documentation** - Documentation improvements or additions
+- **question** - Questions about usage or behavior
+- **testing** - Test-related issues
+
+#### Priority Labels (optional)
+- **priority-high** - Critical issues requiring immediate attention
+- **priority-medium** - Important but not urgent
+- **priority-low** - Nice-to-have improvements
+
+#### Component Labels (optional, choose multiple if needed)
+- **cli** - Command-line interface
+- **workflow** - Workflow compilation and processing
+- **mcp** - MCP server integration
+- **actions** - GitHub Actions integration
+- **engine** - AI engine configuration
+
+#### Workflow Automation Labels (managed by automation)
+- **ai-generated** - Issue created by AI workflow (Plan Command, etc.)
+- **plan** - Planning issue with sub-tasks
+- **ai-inspected** - Issue reviewed by AI workflow
+- **smoke-copilot** - Smoke test results
+
+#### Status Labels
+- **good first issue** - Suitable for new contributors
+- **dependencies** - Dependency updates
+
+### Label Usage Best Practices
+
+#### When to Add Labels
+
+**During Issue Creation:**
+- Add a type label (bug, enhancement, documentation, etc.)
+- Add priority if urgent
+- Add relevant component labels
+
+**During Triage:**
+- Review and update labels based on discussion
+- Add `good first issue` for newcomer-friendly tasks
+- Set priority based on impact
+
+**Automation Labels:**
+- `ai-generated` and `plan` are automatically added by workflows
+- These should not be manually added or removed
+- They help track AI-assisted issue creation and planning
+
+#### When to Remove Labels
+
+**For Workflow Labels:**
+- `plan` labels may be removed after all sub-tasks are completed
+- Keep `ai-generated` for historical tracking
+- Don't remove automation labels unless the issue was incorrectly tagged
+
+**For Other Labels:**
+- Update priority labels as urgency changes
+- Remove incorrect type or component labels during triage
+
+#### Label Lifecycle
+
+**AI-Generated Planning Issues:**
+1. Created with `plan` + `ai-generated` labels
+2. Add type and component labels for better categorization
+3. Monitor sub-task completion
+4. Consider removing `plan` label when all sub-tasks are complete
+5. Close issue when work is done, keeping labels for historical reference
+
+**Manual Issues:**
+1. Created with type label (bug, enhancement, etc.)
+2. Add component and priority labels during triage
+3. Update labels as issue evolves
+4. Close when resolved
+
+### Label Hygiene
+
+**Regular Maintenance:**
+- Review unlabeled issues weekly and add appropriate labels
+- Update priority labels as project needs change
+- Ensure all open issues have at least a type label
+
+**Avoiding Label Overload:**
+- Use 2-4 labels per issue for effective filtering
+- Don't duplicate information (e.g., title already says "bug")
+- Prefer specific component labels over generic ones
+
+### Label Taxonomy
+
+**Current Label Structure:**
+```
+Type: bug, enhancement, documentation, question, testing
+Priority: priority-high, priority-medium, priority-low
+Component: cli, workflow, mcp, actions, engine, automation
+Workflow: ai-generated, plan, ai-inspected, smoke-copilot
+Status: good first issue, dependencies
+```
+
+This taxonomy provides clear filtering while avoiding label sprawl. Use GitHub's issue search to combine labels effectively:
+- `is:issue is:open label:bug label:priority-high` - Critical bugs
+- `is:issue is:open label:enhancement label:good first issue` - Beginner-friendly enhancements
+- `is:issue is:open label:plan` - Active planning issues
+
 ## 🔄 Pull Request Process
 
 1. **Before submitting:**

From 50b9a101bedf0ba8ddfaa69d0806136153d10891 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 20 Dec 2025 17:38:53 +0000
Subject: [PATCH 3/3] Move label guidelines to specs/labels.md per reviewer
 request

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 CONTRIBUTING.md | 116 +-------------------------------
 specs/labels.md | 171 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 173 insertions(+), 114 deletions(-)
 create mode 100644 specs/labels.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d35386947d7..d243262f9ca 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -72,12 +72,14 @@ make recompile
 - Use the GitHub issue tracker to report bugs
 - Include detailed steps to reproduce the issue
 - Include version information (`./gh-aw version`)
+- Follow label guidelines (see [Label Guidelines](specs/labels.md))
 
 ### Suggesting Features
 
 - Open an issue describing your feature request
 - Explain the use case and how it would benefit users
 - Include examples if applicable
+- Apply appropriate labels (see [Label Guidelines](specs/labels.md))
 
 ### Contributing Code
 
@@ -227,120 +229,6 @@ For detailed guidelines and decision tree, see [specs/breaking-cli-rules.md](spe
 - Ensure all tests pass (`make test`)
 - Test manually with real workflows when possible
 
-## 🏷️ Label Guidelines
-
-### Purpose of Labels
-
-Labels help organize and triage issues for better project management. Use labels to:
-- Categorize issue type (bug, enhancement, documentation)
-- Indicate priority level
-- Mark workflow automation status
-- Identify component areas
-
-### Label Categories
-
-#### Type Labels (choose one)
-- **bug** - Something isn't working correctly
-- **enhancement** - New feature or improvement request
-- **documentation** - Documentation improvements or additions
-- **question** - Questions about usage or behavior
-- **testing** - Test-related issues
-
-#### Priority Labels (optional)
-- **priority-high** - Critical issues requiring immediate attention
-- **priority-medium** - Important but not urgent
-- **priority-low** - Nice-to-have improvements
-
-#### Component Labels (optional, choose multiple if needed)
-- **cli** - Command-line interface
-- **workflow** - Workflow compilation and processing
-- **mcp** - MCP server integration
-- **actions** - GitHub Actions integration
-- **engine** - AI engine configuration
-
-#### Workflow Automation Labels (managed by automation)
-- **ai-generated** - Issue created by AI workflow (Plan Command, etc.)
-- **plan** - Planning issue with sub-tasks
-- **ai-inspected** - Issue reviewed by AI workflow
-- **smoke-copilot** - Smoke test results
-
-#### Status Labels
-- **good first issue** - Suitable for new contributors
-- **dependencies** - Dependency updates
-
-### Label Usage Best Practices
-
-#### When to Add Labels
-
-**During Issue Creation:**
-- Add a type label (bug, enhancement, documentation, etc.)
-- Add priority if urgent
-- Add relevant component labels
-
-**During Triage:**
-- Review and update labels based on discussion
-- Add `good first issue` for newcomer-friendly tasks
-- Set priority based on impact
-
-**Automation Labels:**
-- `ai-generated` and `plan` are automatically added by workflows
-- These should not be manually added or removed
-- They help track AI-assisted issue creation and planning
-
-#### When to Remove Labels
-
-**For Workflow Labels:**
-- `plan` labels may be removed after all sub-tasks are completed
-- Keep `ai-generated` for historical tracking
-- Don't remove automation labels unless the issue was incorrectly tagged
-
-**For Other Labels:**
-- Update priority labels as urgency changes
-- Remove incorrect type or component labels during triage
-
-#### Label Lifecycle
-
-**AI-Generated Planning Issues:**
-1. Created with `plan` + `ai-generated` labels
-2. Add type and component labels for better categorization
-3. Monitor sub-task completion
-4. Consider removing `plan` label when all sub-tasks are complete
-5. Close issue when work is done, keeping labels for historical reference
-
-**Manual Issues:**
-1. Created with type label (bug, enhancement, etc.)
-2. Add component and priority labels during triage
-3. Update labels as issue evolves
-4. Close when resolved
-
-### Label Hygiene
-
-**Regular Maintenance:**
-- Review unlabeled issues weekly and add appropriate labels
-- Update priority labels as project needs change
-- Ensure all open issues have at least a type label
-
-**Avoiding Label Overload:**
-- Use 2-4 labels per issue for effective filtering
-- Don't duplicate information (e.g., title already says "bug")
-- Prefer specific component labels over generic ones
-
-### Label Taxonomy
-
-**Current Label Structure:**
-```
-Type: bug, enhancement, documentation, question, testing
-Priority: priority-high, priority-medium, priority-low
-Component: cli, workflow, mcp, actions, engine, automation
-Workflow: ai-generated, plan, ai-inspected, smoke-copilot
-Status: good first issue, dependencies
-```
-
-This taxonomy provides clear filtering while avoiding label sprawl. Use GitHub's issue search to combine labels effectively:
-- `is:issue is:open label:bug label:priority-high` - Critical bugs
-- `is:issue is:open label:enhancement label:good first issue` - Beginner-friendly enhancements
-- `is:issue is:open label:plan` - Active planning issues
-
 ## 🔄 Pull Request Process
 
 1. **Before submitting:**
diff --git a/specs/labels.md b/specs/labels.md
new file mode 100644
index 00000000000..51c78c4b34d
--- /dev/null
+++ b/specs/labels.md
@@ -0,0 +1,171 @@
+---
+description: Label usage guidelines for GitHub Agentic Workflows issue tracking
+---
+
+# Label Guidelines
+
+## Purpose of Labels
+
+Labels help organize and triage issues for better project management. Use labels to:
+- Categorize issue type (bug, enhancement, documentation)
+- Indicate priority level
+- Mark workflow automation status
+- Identify component areas
+
+## Label Categories
+
+### Type Labels (choose one)
+- **bug** - Something isn't working correctly
+- **enhancement** - New feature or improvement request
+- **documentation** - Documentation improvements or additions
+- **question** - Questions about usage or behavior
+- **testing** - Test-related issues
+
+### Priority Labels (optional)
+- **priority-high** - Critical issues requiring immediate attention
+- **priority-medium** - Important but not urgent
+- **priority-low** - Nice-to-have improvements
+
+### Component Labels (optional, choose multiple if needed)
+- **cli** - Command-line interface
+- **workflow** - Workflow compilation and processing
+- **mcp** - MCP server integration
+- **actions** - GitHub Actions integration
+- **engine** - AI engine configuration
+
+### Workflow Automation Labels (managed by automation)
+- **ai-generated** - Issue created by AI workflow (Plan Command, etc.)
+- **plan** - Planning issue with sub-tasks
+- **ai-inspected** - Issue reviewed by AI workflow
+- **smoke-copilot** - Smoke test results
+
+### Status Labels
+- **good first issue** - Suitable for new contributors
+- **dependencies** - Dependency updates
+
+## Label Usage Best Practices
+
+### When to Add Labels
+
+**During Issue Creation:**
+- Add a type label (bug, enhancement, documentation, etc.)
+- Add priority if urgent
+- Add relevant component labels
+
+**During Triage:**
+- Review and update labels based on discussion
+- Add `good first issue` for newcomer-friendly tasks
+- Set priority based on impact
+
+**Automation Labels:**
+- `ai-generated` and `plan` are automatically added by workflows
+- These should not be manually added or removed
+- They help track AI-assisted issue creation and planning
+
+### When to Remove Labels
+
+**For Workflow Labels:**
+- `plan` labels may be removed after all sub-tasks are completed
+- Keep `ai-generated` for historical tracking
+- Don't remove automation labels unless the issue was incorrectly tagged
+
+**For Other Labels:**
+- Update priority labels as urgency changes
+- Remove incorrect type or component labels during triage
+
+### Label Lifecycle
+
+**AI-Generated Planning Issues:**
+1. Created with `plan` + `ai-generated` labels
+2. Add type and component labels for better categorization
+3. Monitor sub-task completion
+4. Consider removing `plan` label when all sub-tasks are complete
+5. Close issue when work is done, keeping labels for historical reference
+
+**Manual Issues:**
+1. Created with type label (bug, enhancement, etc.)
+2. Add component and priority labels during triage
+3. Update labels as issue evolves
+4. Close when resolved
+
+## Label Hygiene
+
+**Regular Maintenance:**
+- Review unlabeled issues weekly and add appropriate labels
+- Update priority labels as project needs change
+- Ensure all open issues have at least a type label
+
+**Avoiding Label Overload:**
+- Use 2-4 labels per issue for effective filtering
+- Don't duplicate information (e.g., title already says "bug")
+- Prefer specific component labels over generic ones
+
+## Label Taxonomy
+
+**Current Label Structure:**
+```
+Type: bug, enhancement, documentation, question, testing
+Priority: priority-high, priority-medium, priority-low
+Component: cli, workflow, mcp, actions, engine, automation
+Workflow: ai-generated, plan, ai-inspected, smoke-copilot
+Status: good first issue, dependencies
+```
+
+This taxonomy provides clear filtering while avoiding label sprawl. Use GitHub's issue search to combine labels effectively:
+- `is:issue is:open label:bug label:priority-high` - Critical bugs
+- `is:issue is:open label:enhancement label:good first issue` - Beginner-friendly enhancements
+- `is:issue is:open label:plan` - Active planning issues
+
+## Label Distribution Analysis
+
+### Current State
+
+Analysis of the repository (as of December 2024) shows:
+- **Total open issues**: 35
+- **Issues with `plan`**: 16 (45.7%)
+- **Issues with `ai-generated`**: 16 (45.7%)
+- **Perfect overlap**: All `plan` issues also have `ai-generated`
+- **Unlabeled issues**: 0 (excellent!)
+
+### Key Findings
+
+**The label distribution is healthy and working as intended.** The high percentage of workflow labels reflects active AI-assisted planning, not a labeling problem.
+
+**Why this is not a concern:**
+1. Labels reflect actual project activity (active AI planning)
+2. Clear distinction between automated and manual issues
+3. Effective filtering with label combinations
+4. Transparent AI attribution
+5. Additional labels (type, component, priority) provide needed categorization
+
+### Recommendations
+
+✅ **Keep current structure** - No changes needed to `plan`/`ai-generated` labels
+- Working as designed
+- Serves clear purpose for tracking AI-generated planning issues
+- Enables effective filtering with combinations
+
+❌ **Do not create `plan-*` subcategories** - Adds complexity without benefit
+- Current system handles this with `is:open` / `is:closed` filters
+- Would fragment label space
+
+🔄 **Optional** (low priority): Remove `plan` label after sub-tasks complete
+- Would make it an "active planning" indicator
+- Keep `ai-generated` for historical tracking
+- Not required, current approach is also valid
+
+✅ **Monitor** for true label skew
+- Watch type/priority labels (not workflow labels)
+- Quarterly review recommended
+- Warning signs: A type label exceeding 60% of open issues
+
+## Success Metrics
+
+✅ Zero unlabeled open issues  
+✅ Clear distinction between automated and manual issues  
+✅ Effective filtering with label combinations  
+✅ Transparent AI attribution maintained
+
+---
+
+**Last Updated**: December 2024