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

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
Propose an open-ended idea	💡 Ideas discussion, promote to Issue when ready
Report a bug	Bug Report issue form
Propose a well-scoped feature	Feature Request issue form
Propose a refactor	Refactor Proposal issue form
Report a docs issue	Documentation issue form
Share what you built	🙌 Show and tell discussion
Discuss the paper	📚 Research discussion
Coordinate as a maintainer	🛠️ Contributor lounge discussion
Report a security vulnerability	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:

Filing

Use one of the issue forms. 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 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:

Fork (if external) and create a branch from develop. Naming follows <type>/<short-kebab-description>.
Implement the change. Write tests. Run pytest / npm run lint.
Push the branch and open a PR against develop. The PR template 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) 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. Why this convention:

The PR title becomes the squash-commit message: a readable git log.
Release Drafter 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 and locally by .githooks/pre-push (opt-in). <type>/<short-kebab-description>: see CONTRIBUTING.md 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.

Discussion → Issue promotion

The recommended flow for non-trivial features:

Someone files a 💡 Idea discussion describing the use case.
Community + maintainers discuss; consensus emerges (or doesn’t).
If consensus: a maintainer uses the discussion’s ⋯ menu → “Convert to issue”. The original Discussion remains, with a link to the new Issue.
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:

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

docs/maintainers-handbook.md: the maintainer-facing companion (triage, label discipline, release flow).
docs/labels-reference.md: the full taxonomy and what each label means.
docs/adr/README.md: how we record architectural decisions.
CONTRIBUTING.md: branching, release, PR rules.
SUPPORT.md: where to get help.
SECURITY.md: vulnerability reporting.

Community & contribution

CI & automation

Background

Community guide

Community guide

1. Two development pathways

Examples

2. Where to file what

Why the split between Issues and Discussions

3. Issue lifecycle

Filing

Triage

Claiming

Implementation

Linking the PR to the issue

Review

Merge

Deploy

4. PR title convention: Conventional Commits

5. Branch naming

6. Linking artefacts

Closing keywords (PR body → Issue)

Discussion → Issue promotion

Task lists for epics

The “Development” sidebar

7. Cheat-sheet

​Community guide

​1. Two development pathways

​Examples

​2. Where to file what

​Why the split between Issues and Discussions

​3. Issue lifecycle

​Filing

​Triage

​Claiming

​Implementation

​Linking the PR to the issue

​Review

​Merge

​Deploy

​4. PR title convention: Conventional Commits

​5. Branch naming

​6. Linking artefacts

​Closing keywords (PR body → Issue)

​Discussion → Issue promotion

​Task lists for epics

​The “Development” sidebar

​7. Cheat-sheet

​8. Sources and related docs

Community guide

1. Two development pathways

Examples

2. Where to file what

Why the split between Issues and Discussions

3. Issue lifecycle

Filing

Triage

Claiming

Implementation

Linking the PR to the issue

Review

Merge

Deploy

4. PR title convention: Conventional Commits

5. Branch naming

6. Linking artefacts

Closing keywords (PR body → Issue)

Discussion → Issue promotion

Task lists for epics

The “Development” sidebar

7. Cheat-sheet

8. Sources and related docs