Skip to main content

​
Labels reference

The HAI-Co² label taxonomy is the connective tissue between Issues, PRs, the Project board, and the AI-automation workflows. This page is the canonical reference for what each label means and when to apply it. The labels themselves live in .github/labels.yml (the source of truth) and are created on the GitHub side by .github/scripts/init-labels.sh (idempotent, safe to re-run).

​
1. Triage rules (every label has a job)

  • Every Issue gets exactly one type: label during triage.
  • Every Issue gets exactly one area: label during triage.
    • On PRs, the labeler workflow auto-applies area:* based on changed paths, so you usually do not need to set it by hand on PRs.
  • needs-triage is removed once triage is done. Its presence on an open issue means “no maintainer has looked at this yet”.
  • good first issue is reserved for issues a newcomer can finish in under 2 hours without reading internal docs.
  • path:ai-automation is added explicitly by a maintainer, or automatically when Coco (HAI-Coco) is assigned to the issue. Default is traditional (the absence of any path:* label means traditional).
  • priority:* and effort:* are advisory, not contractual. Adjust them as your understanding of the work changes.

​
2. The full taxonomy

​
type:*: what kind of work this is

Pick exactly one. Drives the Release Drafter categories.

​
area:*: where in the codebase

Pick exactly one. The labeler workflow auto-applies these on PRs by matching changed paths to the labeler config. For cross-cutting changes (rare), apply the area you’d want a reviewer to care about first; mention the others in the PR body.

​
priority:*: how urgent

Apply during triage. Revisit if the situation changes.

​
status:*: workflow state

The Project board’s Status field is the primary place to read state. These labels exist for cases where a label is more ergonomic (search, filter dropdowns, mobile triage).

​
path:*: which development pathway

The single most consequential triage label. See ADR-0002. Apply exactly one engine label per issue (the bare path:ai-automation counts as the Copilot one); the chosen engine runs the whole PR through. See ai-pathway.md §2.4.

​
ai:*: AI review marker

The AI pathway is driven mostly by slash commands (/approve-plan, /coco, /promote dev), not labels, so there is just one ai:* label. The pathway and its workflows are documented in docs/ai-pathway.md.

​
stage:*: AI-pathway lifecycle (managed automatically)

Every AI-pathway issue and its PR carry exactly one stage:* label, advanced automatically by coco-stage-labels.yml as the assignee drives the flow, so the Issues and Pull-requests lists show where each item is at a glance. Never set these by hand. Warm colors (yellow/orange/green) mean it is your turn to act. See the state diagram in ai-pathway.md.

​
Community labels

​
effort:*: rough sizing

Advisory; the reviewer’s mental budget when they decide what to pick up this week.

​
3. Adding or changing labels

The taxonomy is intentionally small. Before adding a label, ask:
  • Is this a new category, or could an existing label carry the signal?
  • Will this label be applied to ≥ 5 issues a year? If no, don’t add it: labels you never use are visual noise.
  • Does it conflict with the “exactly one type, exactly one area” rule? If yes, you are probably trying to model something else (e.g. the Project board’s Status field).
To add a label:
  1. Open a PR adding it to .github/labels.yml.
  2. Update this reference in the same PR.
  3. After merge, run .github/scripts/init-labels.sh (or wait for a maintainer to run it). The script is idempotent; existing labels’ colors/descriptions get updated to match the file.
To rename a label, prefer adding the new one + closing all open issues through the next triage to renaming in place: GitHub does support renames, but they invalidate every saved Project view filter, which is annoying for contributors.