> ## 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.

# Community guide

> How the community works: where to file what, and how an issue moves from filed to deployed.

# Community guide

This guide describes **how the HAI-Co² community works**: where to file what, how an Issue moves from filed to deployed, and the conventions that keep the project legible to outside contributors. If you are about to file an issue, open a PR, or start a Discussion, you are in the right place.

***

## 1. Two development pathways

HAI-Co² accepts contributions on two pathways that converge at the same review gate. The bar for merging is identical. Only the *author* differs.

| Pathway                       | Author                | When                                                       |
| ----------------------------- | --------------------- | ---------------------------------------------------------- |
| `path:traditional` (default)  | Human contributor     | The default, and anything you would rather a human author. |
| `path:ai-automation` (opt-in) | Coco (gh-aw AI agent) | Well-scoped changes a maintainer approves.                 |

A maintainer applies the `path:*` label during triage. The default is traditional; the absence of a path label means traditional. On the AI pathway the maintainer also picks the engine via the label (`path:ai-automation` = Claude by default, or `-codex` / `-copilot`); see the [maintainers' handbook](/docs/maintainers-handbook).

On the AI pathway a maintainer labels the issue, Coco plans it and **warns** in the plan about any higher-risk traits, and a human authorizes the work by commenting `/approve-plan` on the PR. It is not a hard checklist: the plan surfaces traits like a DB schema change or migration, a new dependency, a public-API change, or an architectural decision, and Coco raises an explicit ⚠️ warning only for a security-sensitive surface (auth, crypto, file uploads, deserialization) or a destructive or irreversible migration. The maintainer approves with `/approve-plan`, or re-routes to a human with `path:traditional`. See [ADR-0002](/docs/adr/0002-dual-development-pathways) for the rationale.

Once on the AI pathway, a `stage:*` label tracks progress automatically (`stage:planning` through `stage:awaiting-merge`), so you can see at a glance where each item is; the full state diagram and the commands that drive each transition are in [ai-pathway.md](/docs/ai-pathway).

### Examples

* **`path:ai-automation`**: "Submit button is misaligned on mobile", "Add missing `None` check in `agents/retrieval.py`", "Add a happy-path test for `POST /api/preferences`".
* **`path:traditional`**: "Add OAuth login support", "Migrate the checkpointer to use Redis", "Improve type coverage across the entire backend".

***

## 2. Where to file what

| You want to…                    | Use                                                                                                                     |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Ask a usage question            | [🙏 Q\&A discussion](https://github.com/petrosrapto/HAICO/discussions/categories/q-a)                                   |
| Propose an open-ended idea      | [💡 Ideas discussion](https://github.com/petrosrapto/HAICO/discussions/categories/ideas), promote to Issue when ready   |
| Report a bug                    | [Bug Report issue form](https://github.com/petrosrapto/HAICO/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml)           |
| Propose a well-scoped feature   | [Feature Request issue form](https://github.com/petrosrapto/HAICO/blob/main/.github/ISSUE_TEMPLATE/feature_request.yml) |
| Propose a refactor              | [Refactor Proposal issue form](https://github.com/petrosrapto/HAICO/blob/main/.github/ISSUE_TEMPLATE/refactor.yml)      |
| Report a docs issue             | [Documentation issue form](https://github.com/petrosrapto/HAICO/blob/main/.github/ISSUE_TEMPLATE/docs.yml)              |
| Share what you built            | [🙌 Show and tell discussion](https://github.com/petrosrapto/HAICO/discussions/categories/show-and-tell)                |
| Discuss the paper               | [📚 Research discussion](https://github.com/petrosrapto/HAICO/discussions/categories/research)                          |
| Coordinate as a maintainer      | [🛠️ Contributor lounge discussion](https://github.com/petrosrapto/HAICO/discussions/categories/contributor-lounge)     |
| Report a security vulnerability | [SECURITY.md](https://github.com/petrosrapto/HAICO/blob/main/SECURITY.md) (**never** a public issue)                    |

### Why the split between Issues and Discussions

* The **Issues** tab is a clean inventory of *work*. Each open issue represents a decided change, scoped enough that someone could pick it up.
* **Discussions** is where ideas *incubate*. Open-ended threads belong here until consensus emerges and they can be promoted to an Issue.
* **Q\&A** never becomes an Issue; the answer stays in the discussion thread and benefits the next person who searches.

***

## 3. Issue lifecycle

```
filed → triaged → claimed → PR opened → CI green → reviewed → merged → deployed → closed
```

The same lifecycle, showing where the two pathways diverge and rejoin at the shared review gate:

```mermaid theme={null}
flowchart TD
    A["Issue filed (via form)"] --> B["Maintainer triage + labels"]
    B --> C{"Pathway?"}
    C -->|"path:traditional"| D["Human author branches from develop"]
    C -->|"path:ai-automation"| E["Coco drafts plan, human runs /approve-plan"]
    D --> F["PR opened against develop"]
    E --> F
    F --> G["CODEOWNERS review + CI green"]
    G --> H["Squash-merge to develop, issue auto-closes"]
    H --> I["Push dev-vX.Y.Z, CI deploys to dev"]
    I --> J["Fast-forward develop to main, push vX.Y.Z"]
    J --> K["CI deploys to production"]
```

### Filing

Use one of the [issue forms](https://github.com/petrosrapto/HAICO/blob/main/.github/ISSUE_TEMPLATE). The forms ask for the structured fields a reviewer will need anyway: area, repro steps, acceptance criteria, plus an optional **Reviewer(s)** field (on the AI pathway, the reviewer(s) requested on Coco's plan PR come from it, defaulting to the repo's `REVIEWER_LOGIN` when blank). Filling them up front saves a round trip.

### Triage

A maintainer reviews new issues at least weekly. Triage produces:

* One `type:*` label (`type:bug`, `type:enhancement`, …).
* One `area:*` label (`area:backend`, `area:frontend`, …).
* One `priority:*` label and one `effort:*` label.
* A pathway decision (`path:ai-automation` or no path label = traditional).
* Optionally `good first issue` if the change is newcomer-friendly.
* Removal of `needs-triage`.
* Adding the issue to the Project board and (if appropriate) a milestone.

Target: every issue triaged within 7 days. See the [labels reference](/docs/labels-reference) for the full taxonomy.

### Claiming

Comment "I'd like to take this" and wait for a maintainer to assign. For internal contributors with write access, self-assignment is fine. For AI issues, the maintainer adds the `path:ai-automation` label, which sets the pathway in motion (Coco drafts a plan).

### Implementation

For human authors:

1. Fork (if external) and create a branch from `develop`. Naming follows [`<type>/<short-kebab-description>`](https://github.com/petrosrapto/HAICO/blob/main/CONTRIBUTING.md#branch-naming-convention).
2. Implement the change. Write tests. Run `pytest` / `npm run lint`.
3. Push the branch and open a PR against `develop`. The [PR template](https://github.com/petrosrapto/HAICO/blob/main/.github/pull_request_template.md) prompts for the right pieces.

For AI-pathway issues, Coco opens a draft PR with its plan as the first comment; once a maintainer comments `/approve-plan`, Coco implements into that same PR. The maintainer promotes to dev with `/promote dev`, tests there, and iterates by commenting `/coco <change>` on the PR. When satisfied, marking the PR ready for review runs Coco's automated review, and a human does the final merge.

### Linking the PR to the issue

In the PR **body** (not the title), use a closing keyword:

| Keyword                         | Effect on merge into `develop`   |
| ------------------------------- | -------------------------------- |
| `Closes #123` / `Closed #123`   | Auto-closes #123                 |
| `Fixes #45` / `Fixed #45`       | Same; preferred wording for bugs |
| `Resolves #67` / `Resolved #67` | Same                             |
| `Refs #99` or just `#99`        | Reference only (no auto-close)   |

Multi-issue PRs: each issue needs its own keyword, e.g. `Closes #123, closes #124`. Cross-repo: `Closes owner/repo#123`. Auto-close fires when the PR merges into the default branch (`develop`); the later promotion to `main` does **not** re-trigger.

### Review

* One CODEOWNERS approval is required.
* All CI checks must pass.
* Coco's automated review (on `path:ai-automation` PRs; see [ai-pathway.md](/docs/ai-pathway)) leaves comments; they are advisory, not blocking.
* A human reviewer (often the same maintainer who triaged) signs off.

### Merge

* **Squash merge.** The PR title (Conventional Commits) becomes the commit message; the PR body is appended below it.
* The branch is auto-deleted.
* The linked issue auto-closes on merge into `develop`.
* The Project board moves the issue to *Done*.

### Deploy

* A maintainer pushes `dev-vX.Y.Z` from `develop`. The existing CI workflow builds images and deploys to the dev environment.
* After validation on dev, the maintainer fast-forwards `develop → main` and pushes `vX.Y.Z`. The same CI workflow deploys to production.

***

## 4. PR title convention: Conventional Commits

Use `<type>(<scope>): <description>`:

* `feat(backend): add OAuth callback endpoint`
* `fix(frontend): correct submit-button alignment on mobile`
* `refactor(agents): extract retrieval factory`
* `docs: expand contributing guide with linking rules`
* `chore(deps): bump fastapi to 0.115`

Allowed `type` values: `feat`, `fix`, `hotfix`, `refactor`, `docs`, `test`, `chore`, `experiment`. They match the branch-name types in [CONTRIBUTING.md](https://github.com/petrosrapto/HAICO/blob/main/CONTRIBUTING.md).

Why this convention:

* The PR title becomes the squash-commit message: a readable `git log`.
* [Release Drafter](https://github.com/petrosrapto/HAICO/blob/main/.github/release-drafter-dev.yml) groups release notes by `type:` labels (auto-applied from the PR title).
* It is the most widely-adopted convention in open source, so there is no friction for arriving contributors.

**Do not** put `#123` in the title. GitHub auto-appends `(#PR_NUMBER)` on squash-merge, and the body contains the issue link.

***

## 5. Branch naming

Enforced by [`.github/workflows/branch-name.yml`](https://github.com/petrosrapto/HAICO/blob/main/.github/workflows/branch-name.yml) and locally by [`.githooks/pre-push`](https://github.com/petrosrapto/HAICO/blob/main/.githooks/pre-push) (opt-in).

`<type>/<short-kebab-description>`: see [CONTRIBUTING.md](https://github.com/petrosrapto/HAICO/blob/main/CONTRIBUTING.md#branch-naming-convention) for the full table. Optionally include the issue number after the type:

```
feature/123-oauth-login
fix/45-mobile-submit-alignment
```

Coco's PRs use a `gh-aw`-generated branch name automatically; both styles coexist.

***

## 6. Linking artefacts

The lifecycle is auditable because each artefact links to the others.

### Closing keywords (PR body → Issue)

See [§3, Linking the PR to the issue](#linking-the-pr-to-the-issue).

### Discussion → Issue promotion

The recommended flow for non-trivial features:

1. Someone files a **💡 Idea** discussion describing the use case.
2. Community + maintainers discuss; consensus emerges (or doesn't).
3. If consensus: a maintainer uses the discussion's **⋯ menu → "Convert to issue"**. The original Discussion remains, with a link to the new Issue.
4. Triage applies labels and (if appropriate) `path:ai-automation`.

For bugs, skip Discussions and file Issues directly. For usage questions, the answer never becomes an Issue.

### Task lists for epics

For work too large for one PR, the parent Issue lists child Issues:

```markdown theme={null}
## Sub-tasks
- [ ] #234 Backend handler
- [ ] #235 Frontend form
- [ ] #236 Migration script
```

GitHub renders these as live checkboxes; the parent shows `1 of 3 completed`. As each child PR merges with `Closes #234`, the parent's progress updates in real time. GitHub's newer **sub-issues** feature makes the parent/child relationship first-class: visible as a panel in the Issue UI and navigable in the Project board.

### The "Development" sidebar

The right sidebar of every Issue has a *Development* section. Use it when:

* A PR exists but does not include closing keywords.
* You want to associate a branch with an Issue before a PR exists.
* The PR targets a non-default branch and you still want the auto-close link.

Click **Create a branch** to spin up a properly-named, pre-linked branch in one step.

***

## 7. Cheat-sheet

| You want to…                     | Where                                    | How the link works                  |
| -------------------------------- | ---------------------------------------- | ----------------------------------- |
| Brainstorm an open-ended idea    | 💡 Idea discussion                       | Convert to Issue when decided       |
| Report a bug                     | Bug-report Issue form                    | Closing PR → auto-close on merge    |
| Propose a decided feature        | Feature-request Issue form               | Closing PR → auto-close on merge    |
| Propose a refactor               | Refactor Issue form                      | Closing PR → auto-close on merge    |
| Ask a usage question             | 🙏 Q\&A discussion                       | Maintainer marks accepted answer    |
| Implement work                   | PR with `Closes #N` in body              | Automatic on merge to `develop`     |
| Track an epic                    | Parent Issue with task list / sub-issues | Children auto-tick on merge         |
| Announce a release               | 📣 Announcement discussion               | Manual link to GitHub Release       |
| Record an architectural decision | `docs/adr/NNNN-*.md`                     | Link from Issue and PR descriptions |

***

## 8. Sources and related docs

* [`docs/maintainers-handbook.md`](/docs/maintainers-handbook): the maintainer-facing companion (triage, label discipline, release flow).
* [`docs/labels-reference.md`](/docs/labels-reference): the full taxonomy and what each label means.
* [`docs/adr/README.md`](/docs/adr/index): how we record architectural decisions.
* [`CONTRIBUTING.md`](https://github.com/petrosrapto/HAICO/blob/main/CONTRIBUTING.md): branching, release, PR rules.
* [`SUPPORT.md`](https://github.com/petrosrapto/HAICO/blob/main/SUPPORT.md): where to get help.
* [`SECURITY.md`](https://github.com/petrosrapto/HAICO/blob/main/SECURITY.md): vulnerability reporting.