> ## Documentation Index > Fetch the complete documentation index at: https://haico.gr/docs/llms.txt > Use this file to discover all available pages before exploring further. # Labels reference > The canonical label taxonomy and when to apply each label. # 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`](https://github.com/petrosrapto/HAICO/blob/main/.github/labels.yml) (the source of truth) and are created on the GitHub side by [`.github/scripts/init-labels.sh`](https://github.com/petrosrapto/HAICO/blob/main/.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](https://github.com/petrosrapto/HAICO/blob/main/.github/workflows/labeler.yml) 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](https://github.com/petrosrapto/HAICO/blob/main/.github/release-drafter-dev.yml) categories. | Label | Use for | Release Drafter category | | ------------------ | ---------------------------------------------------------- | ------------------------ | | `type:bug` | A defect; current behaviour is wrong. | 🐞 Bug fixes | | `type:enhancement` | A new capability or visible improvement. | ✨ Features | | `type:refactor` | Restructuring with no behaviour change. | 🛠️ Refactors | | `type:docs` | Documentation work (READMEs, `docs/`, ADRs). | 📚 Documentation | | `type:test` | Test additions or improvements; no production-code change. | 🧪 Tests | | `type:chore` | Maintenance, dependency bumps, tooling. | 🔧 Chores & maintenance | ### `area:*`: where in the codebase Pick exactly one. The [labeler workflow](https://github.com/petrosrapto/HAICO/blob/main/.github/workflows/labeler.yml) auto-applies these on PRs by matching changed paths to the [labeler config](https://github.com/petrosrapto/HAICO/blob/main/.github/labeler.yml). | Label | Path globs | Owners | | ----------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------- | | `area:backend` | `backend/**` | Backend reviewers via [CODEOWNERS](https://github.com/petrosrapto/HAICO/blob/main/.github/CODEOWNERS) | | `area:frontend` | `frontend/**` | Frontend reviewers via CODEOWNERS | | `area:deployment` | `deployment/**` | Deployment reviewers via CODEOWNERS | | `area:docs` | `docs/**`, top-level `*.md` | Docs reviewers via CODEOWNERS | | `area:ci` | `.github/**`, `.githooks/**` | CI reviewers via CODEOWNERS | 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. | Label | Meaning | | ------------------- | ----------------------------------------------------------------- | | `priority:critical` | Drop everything. Production is broken or a vulnerability is live. | | `priority:high` | Should ship in the next release. | | `priority:medium` | Within the quarter. | | `priority:low` | Nice to have; ship when it fits. | ### `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). | Label | Meaning | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `needs-triage` | Auto-applied by issue forms. Awaiting first maintainer pass. | | `needs-info` | Reporter must clarify or provide repro before this can move forward. | | `blocked` | Cannot proceed until an upstream issue or external dependency lands. | | `wontfix` | Out of scope; will be closed with explanation. | | `duplicate` | Another issue tracks this; close with a link. | | `status:stale` | Applied by the [stale bot](https://github.com/petrosrapto/HAICO/blob/main/.github/workflows/stale.yml) after 180 days of inactivity. | ### `path:*`: which development pathway The single most consequential triage label. See [ADR-0002](/docs/adr/0002-dual-development-pathways). | Label | Meaning | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path:traditional` | Human-authored. Default; absence of any `path:*` means traditional. | | `path:ai-automation` | AI-agent eligible; adding it (or assigning `HAI-Coco` to the issue) triggers the AI pathway's **plan** step on the default **Copilot** engine (alias of `path:ai-automation-copilot`). The maintainer adds it; Coco then plans the issue, warns on any higher-risk traits, and a human authorizes with `/approve-plan` (see the [pathway guidance](/docs/repository-foundation#2-what-trivial-means--when-to-use-the-ai-pathway)). See [ai-pathway.md](/docs/ai-pathway). | | `path:ai-automation-claude` | AI pathway on the **Claude** engine (seat-free, needs `ANTHROPIC_API_KEY`). | | `path:ai-automation-codex` | AI pathway on the **Codex / OpenAI** engine (needs `OPENAI_API_KEY`). | | `path:ai-automation-copilot` | AI pathway on the **Copilot** engine (needs a Copilot seat / `COPILOT_GITHUB_TOKEN`). | 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](/docs/ai-pathway#24-labels). ### `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. | Label | Meaning | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ai:review` | Marker for PRs under AI review. The review runs once when the PR is marked ready for review, or on demand when a maintainer comments `/review`; the workflows are the per-engine `ai-review-*` and `ai-review-ondemand-*` variants (see [ai-pathway.md](/docs/ai-pathway)). | The pathway and its workflows are documented in [`docs/ai-pathway.md`](/docs/ai-pathway). ### `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`](https://github.com/petrosrapto/HAICO/blob/main/.github/workflows/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](/docs/ai-pathway). | Label | Meaning | | ------------------------------ | ------------------------------------------------------------------------------ | | `stage:planning` | Coco is drafting the plan (issue labelled; draft PR not open yet). | | `stage:awaiting-plan-approval` | Plan PR is open; **your turn**: review it and comment `/approve-plan`. | | `stage:implementing` | Plan approved; Coco is implementing and CI is running. | | `stage:awaiting-dev-promotion` | Implemented and CI is green; **your turn**: comment `/promote dev`. | | `stage:testing-dev` | Deployed to dev; **your turn**: test, then mark Ready for review (or `/coco`). | | `stage:reviewing` | In review (Coco's automated review plus a human reviewer). | | `stage:awaiting-merge` | Approved; **your turn**: a human does the final squash merge. | ### Community labels | Label | Use | | ------------------ | ----------------------------------------------------------------------- | | `good first issue` | Newcomer-friendly. Under 2 hours, no internal docs needed. | | `help wanted` | Maintainers welcome a contribution but won't get to it soon themselves. | ### `effort:*`: rough sizing Advisory; the reviewer's mental budget when they decide what to pick up this week. | Label | Roughly | | ---------- | ------------ | | `effort:S` | \~1 hour | | `effort:M` | \~half a day | | `effort:L` | 1+ day | *** ## 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`](https://github.com/petrosrapto/HAICO/blob/main/.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. *** ## 4. Sources and related docs * [`docs/community-guide.md`](/docs/community-guide): how triage and the lifecycle look from a contributor's seat. * [`docs/maintainers-handbook.md`](/docs/maintainers-handbook): the maintainer's triage routine and label discipline. * [`docs/repository-foundation.md` §6.7](/docs/repository-foundation): the rationale and history behind the taxonomy. * [`.github/labels.yml`](https://github.com/petrosrapto/HAICO/blob/main/.github/labels.yml): source of truth. * [`.github/labeler.yml`](https://github.com/petrosrapto/HAICO/blob/main/.github/labeler.yml): `area:*` auto-application rules.