> ## Documentation Index > Fetch the complete documentation index at: https://dev.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.md). | 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.md#2-what-trivial-means--when-to-use-the-ai-pathway)). See [ai-pathway.md](/docs/ai-pathway.md). | | `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.md#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.md)). | 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.md). | 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 | ### `skip-changelog`: keep a PR out of the release notes The escape hatch for PRs that must not appear in a release. [Release Drafter](https://github.com/petrosrapto/HAICO/blob/main/.github/release-drafter-dev.yml) reads it through its `pre-exclude` category, which drops the PR before the notes are generated and before the next version is resolved, so the PR neither shows up in the notes nor influences the version bump. Apply it by hand; nothing sets it automatically. | Label | Use for | | - | - | | `skip-changelog` | Reverts of unreleased work, release plumbing, anything not worth a line in the notes. | *** ## 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.