This document describes the label system for plugin-dev.
- labels.yml: Source of truth for all repository labels
- LABELS.md: This documentation file
- workflows/sync-labels.yml: Automated workflow that syncs label definitions on push to main
Standard GitHub labels for issue/PR classification:
| Label | Color | Description |
|---|---|---|
bug |
 |
Something isn't working |
documentation |
 |
Improvements or additions |
duplicate |
 |
Already exists |
enhancement |
 |
New feature or request |
invalid |
 |
Doesn't seem right |
question |
 |
Further information requested |
refactor |
 |
Code restructuring without behavior change |
chore |
 |
Maintenance tasks |
wontfix |
 |
Will not be worked on |
Identify which part of the codebase (cool blue/purple tones):
| Label | Color | Description |
|---|---|---|
component:agent |
 |
Agents layer |
component:command |
 |
Commands layer |
component:docs |
 |
Documentation files |
component:hook |
 |
Hooks layer |
component:skill |
 |
Skills layer |
component:marketplace |
 |
Marketplace manifest |
component:mcp |
 |
MCP integration |
Labels for plugin development concerns (warm coral/pink family):
| Label | Color | Description |
|---|---|---|
scope:triggering |
 |
Trigger phrase/description issues |
scope:validation |
 |
Plugin validation concerns |
Urgency classification (heat map: hot → cool):
| Label | Color | Description |
|---|---|---|
priority:critical |
 |
Blocking, security, or breaking |
priority:high |
 |
Important but not blocking |
priority:medium |
 |
Should be addressed |
priority:low |
 |
Nice to have |
Current work state:
| Label | Color | Description |
|---|---|---|
status:blocked |
 |
Blocked by dependencies |
status:in-progress |
 |
Work in progress |
status:needs-repro |
 |
Needs reproduction steps |
status:needs-review |
 |
Ready for review |
status:needs-design |
 |
Needs design decision |
status:analyzed |
 |
Analyzed by Claude |
needs-analysis |
 |
Request Claude analysis |
Time estimates:
| Label | Color | Description |
|---|---|---|
effort:small |
 |
< 1 hour |
effort:medium |
 |
1-4 hours |
effort:large |
 |
> 4 hours |
| Label | Color | Description |
|---|---|---|
good first issue |
 |
Good for newcomers |
help wanted |
 |
Extra attention needed |
idea |
 |
Feature idea or suggestion |
showcase |
 |
Community showcase |
| Label | Color | Description |
|---|---|---|
dependencies |
|
Dependency updates |
github-actions |
 |
GitHub Actions updates |
Type of change:
| Label | Color | Description |
|---|---|---|
breaking |
 |
Breaking change (major version) |
automation |
 |
CI/CD and workflow improvements |
optimization |
 |
Performance improvements |
| Label | Color | Description |
|---|---|---|
triage |
 |
Needs initial review |
stale |
|
No recent activity |
pinned |
 |
Never mark as stale |
roadmap |
|
Long-term roadmap item |
| Label | Color | Description |
|---|---|---|
experiment |
 |
Experimental/testing |
security |
 |
Security-related |
reverted |
 |
Merged but later reverted |
Every issue and PR should have:
- One type label: bug, enhancement, documentation, refactor, chore, etc.
- One priority label: priority:critical, priority:high, priority:medium, priority:low
- One effort label: effort:small, effort:medium, effort:large
Apply when relevant:
- Component labels: When the change affects specific plugin components
- Scope labels: When the change affects triggering or validation
- Status labels: To track work progress
- Category labels: For breaking changes, automation, or optimization work
- Community labels: For contributor-friendly issues
Common label combinations for plugin-dev:
| Scenario | Labels |
|---|---|
| Skill not triggering | bug, component:skill, scope:triggering |
| New agent feature | enhancement, component:agent, priority:* |
| Marketplace manifest issue | bug, component:marketplace, priority:* |
| Validation script fix | bug, component:docs, automation |
| MCP integration enhancement | enhancement, component:mcp, effort:* |
| Hook development docs | documentation, component:hook, effort:small |
| Command triggering bug | bug, component:command, scope:triggering |
| Plugin architecture design | enhancement, status:needs-design, roadmap |
| Dependabot PR | chore, dependencies, effort:small |
-
Update labels.yml (source of truth):
- name: "new-label" color: "ff6ec7" description: "Description here"
-
Update LABELS.md with the new label documentation
-
Create a PR - the workflow runs in dry-run mode to preview
-
Merge to main - the label is created automatically
- Update labels.yml with new color/description
- Update LABELS.md documentation
- Create a PR - preview changes in dry-run mode
- Merge to main - changes applied automatically
Deleting labels requires manual action - the automated workflow only creates and updates labels (never deletes) for safety.
-
Remove from labels.yml
-
Remove from LABELS.md
-
Delete from GitHub manually:
gh label delete "label-name" --yes
| Category | Color Family | Rationale |
|---|---|---|
| Type | GitHub defaults | Familiar to all GitHub users |
| Component | Cool blues/purples | Technical, structural feel |
| Scope | Warm coral/pink | Distinct from components, user-facing issues |
| Priority | Heat map (red → green) | Intuitive urgency indication |
| Status | Soft pastels | Non-distracting state indicators |
| Effort | Green → red gradient | Easy (green) to hard (red) |
| Category | Semantic colors | Breaking=red, automation=green |
| Workflow | Neutral greys | Background process labels |
- Prefixed labels: Use colons for categories (
component:,scope:,priority:,status:,effort:) - Standard labels: Keep GitHub defaults as-is (
bug,help wanted,good first issue) - Multi-word labels: Use hyphens for custom labels, keep spaces for GitHub ecosystem compatibility
- Case: All lowercase
Current total: ~49 labels
Balanced for good organization without overwhelming contributors. Check labels.yml for the complete list.