HAICO Repository Foundation: Community-First Setup with Dual Development Pathways

This document is the prerequisite for the AI-automation guide (github-projects-copilot-automation.md). It describes the foundation a serious community-facing repository needs before any AI automation is layered on top. Two ideas drive the design:

Two development pathways coexist. A traditional pathway (human author, human review, human merge) is the default and the one that handles meaningful work (logic changes, refactors, architecture, anything that touches a decision). An AI-assisted pathway is opt-in per issue and only used for trivial changes (cosmetic fixes, single-layer bugs, mechanical refactors, doc updates). The AI pathway is an accelerator on top of the traditional pathway, not a replacement for it.
The repository is community-first. It targets external contributors and visibility (stars, citations, references). The structure mirrors what mature open-source projects use (Apache and CNCF projects) so that arriving contributors recognise the conventions without reading a manual.

The other two guides (going-public.md and the two automation guides) layer on top of this one. This guide should be read before flipping the repo public or wiring AI workflows.

1. Two pathways, one repository

The two pathways converge at the same review gate and use the same branch-protection rules. The only thing that changes is who writes the code. A reviewer should not be able to tell from the PR template whether the author was a human or the AI agent, because the standards are identical.

2. What “trivial” means: when to use the AI pathway

The AI pathway is opt-in per issue, applied by a maintainer at triage time. The default is traditional. The label is the entry signal: once an issue is path:ai-automation, Coco plans it, warns about any higher-risk traits in the plan, and a human authorizes the work with /approve-plan (see ADR-0002). It is no longer a hard checklist gate: a single “risky” trait does not disqualify the issue, it just gets surfaced for the assignee to weigh. Route an issue to the AI pathway when it is well-scoped and you would be comfortable reviewing Coco’s diff. The plan stage assesses and records these traits so you see the shape of the work before approving:

Size and layer span (one layer is typical; spanning frontend and backend is fine when the work is mechanical and well-scoped).
Database schema changes or migrations.
New runtime dependencies (new package.json or pyproject.toml entries).
Public-API contract changes (new endpoints, changed response shapes).
Whether an architectural decision is involved (an ADR may be warranted).

Coco raises an explicit ⚠️ warning in the plan only for the two genuinely higher-risk traits: a security-sensitive surface (auth, crypto, file uploads, deserialization), or a destructive or irreversible database migration. A warning is a flag for you, not a refusal: you approve with /approve-plan to have Coco implement it in full, or you re-route to a human by relabelling path:traditional.

Typical AI-pathway changes

Cosmetic fixes: CSS spacing, copy text, accessibility labels, error messages.
Localized bugs: a state bug in one React component, a None check missing in one Python helper.
Test additions for existing endpoints (happy-path + obvious edge case).
Documentation updates that don’t require subject-matter judgment.
Dependency version bumps with no breaking changes (Dependabot already handles these; noted here so contributors know not to file an issue).

When to prefer the traditional pathway

Larger work (new endpoints, DB schema changes and migrations, cross-cutting changes) is now allowed on the AI pathway when you approve the plan; Coco warns on security-sensitive surfaces and destructive or irreversible migrations so you can decide. Still prefer the traditional pathway when:

The design is the hard part, not the typing.
The change needs an ADR (Architecture Decision Record); the ADR itself stays human-authored.
It is the most security-critical code (core auth or crypto) and you would not want an agent authoring it even with a warning.
It needs performance benchmarking and judgment.

The maintainer labels the issue accordingly during triage; see §7.

3. Gap analysis: what’s here, what’s missing

3.1 What HAICO has today

Path	What it is
`.github/CODEOWNERS`	Single fallback rule: every file → `@petrosrapto` (see §3.3).
`.github/ISSUE_TEMPLATE/`	Four YAML issue forms (`bug_report`, `feature_request`, `docs`, `refactor`) plus `config.yml` (issue chooser + contact links).
`.github/labels.yml` + `scripts/init-labels.sh`	The label taxonomy as the single source of truth, with an idempotent script that applies it.
`.github/labeler.yml` + `workflows/labeler.yml`	Auto-labels PRs with `area:*` by changed path.
`.github/release-drafter-dev.yml` / `-prod.yml` + their workflows	Running draft release notes for the dev and prod channels.
`.github/workflows/stale.yml`	Conservative stale-issue / PR bot.
`.github/dependabot.yml`	Weekly updates for `github-actions`, `pip` (backend), `npm` (frontend), and `docker` (backend / frontend / dev / prod), grouped and labelled.
`.github/pull_request_template.md`	PR template with linked-issue keywords, a Conventional-Commits title check, an ADR reminder, and pathway selection.
`.github/workflows/branch-name.yml`	Server-side branch-name enforcement.
`.github/workflows/ci.yml`	Lint, test, build, deploy.
`.githooks/pre-push`	Client-side branch-name enforcement (opt-in).
`README.md`	Project description, badges, and a documentation index.
`CONTRIBUTING.md`	Branching model, branch-naming, release procedure.
`CODE_OF_CONDUCT.md`	Contributor Covenant; surfaced on the Community Standards page.
`GOVERNANCE.md` / `MAINTAINERS.md` / `SUPPORT.md`	Decision process, current maintainers, and where to get help.
`SECURITY.md`	Vulnerability reporting.
`NOTICE`	Apache 2.0 § 4(d) attribution notices.
`.all-contributorsrc`	Contributor-recognition config.
`LICENSE`	Apache 2.0.
`docs/adr/`	Architecture Decision Records (template + ADR-0000 through ADR-0004).

With these in place, the repository now meets the community-first bar this guide describes. The remaining gaps below are mostly GitHub UI settings to confirm and a few optional files not yet added.

3.2 What remains

Most of the foundation files are now in place (§3.1). What remains falls into three groups. GitHub UI settings (no repo file, confirm in repository settings):

Item	Tier	Reference
GitHub Discussions enabled + categories configured	Essential	§6.9
Community Project board	Essential	§6.10 ; described in `.github/project/README.md`
Repo topics, description, social preview	Essential	§6.8
CodeQL workflow (code scanning)	Essential	covered in going-public.md

Satisfied a different way (no dedicated file by design):

Item	How it’s handled
`CHANGELOG.md`	Superseded by Release Drafter (`release-drafter-dev.yml` / `-prod.yml`).
`ROADMAP.md`	A saved view on the community Project board, not a file.

Optional files not yet added:

Item	Tier	Reference
`.github/FUNDING.yml`	Optional	§6.2
`.github/PULL_REQUEST_TEMPLATE/` (multiple templates)	Optional	§6.6
`.github/DISCUSSION_TEMPLATE/`	Optional	§6.9

“Essential” items are blockers for public launch / community readiness. “Optional” items are nice once the community is active enough to feel the pain they solve.

3.3 The CODEOWNERS file needs work

The current file is one line:

* @petrosrapto

That is fine for a solo maintainer, but it means every path requires the maintainer’s approval: CODEOWNERS picks reviewers for every PR (including the agent’s), and external contributors will not have anyone else to ping. Even with one maintainer, paths are mapped to areas (and later to people as maintainers are onboarded):

# Default
*                              @petrosrapto

# Areas
/backend/                      @petrosrapto
/frontend/                     @petrosrapto
/deployment/                   @petrosrapto
/.github/                      @petrosrapto
/docs/                         @petrosrapto

It looks redundant today, but it documents the intent, and the moment a second maintainer is added for any area, only a single line changes.

4. What belongs in `.github/`

GitHub surfaces a specific set of metadata files at the moments contributors act: opening an issue, opening a PR, reading the front page. The discipline that keeps a community-facing repository legible is to spend effort on the files contributors actually see and treat the rest as housekeeping. A modest, well-chosen .github/ beats an exhaustive one.

4.1 The files that matter

File / dir	What it is	Why it matters
`README.md`	Front page; links to the docs and the live demo.	First impression. It links out to the deeper docs rather than re-hosting everything.
`LICENSE` + `NOTICE`	Apache 2.0 licence and the attribution notices it requires (§ 4(d)).	Without `NOTICE`, a re-distributor of HAICO is technically out of compliance with Apache 2.0.
`.github/CONTRIBUTING.md` (or root `CONTRIBUTING.md`)	The contribution guide.	Surfaced on the “New issue” and “Open a pull request” pages. Either location works; GitHub picks up the `.github/` variant automatically.
`.github/pull_request_template.md`	Pre-fills the PR body.	Surfaced when a PR is opened.
`.github/ISSUE_TEMPLATE/` + `config.yml`	The issue templates and the issue-chooser config.	The `config.yml` disables blank issues and routes non-issues (e.g. “Ask a question → Discussions”).

4.2 Issue templates worth having

Beyond the standard bug report and feature request, a separate refactor-proposal template earns its place: refactoring discussion has a different shape than a bug or a feature, and giving it its own form keeps that conversation structured. Release-tracking templates (one for bugfix releases, one for feature releases) are a useful optional addition once release cadence picks up. The principle that drives the whole directory: a repository can hold a lot of files in .github/, but the ones that matter are the ones contributors see. Effort goes into the issue-chooser config, the PR template, Discussions, the README, and the Project board. The rest is housekeeping.

4.3 Discussions

The Discussions tab anchors the parts of community that are not issues: questions, ideas, show-and-tell. Keep at least one pinned discussion at the top to orient new visitors. HAICO’s category set is defined in §6.9.

5. The dual-pathway lifecycle in detail

Here is what each pathway looks like from issue to deploy, side by side. Both end at the same place; only the implementer differs.

5.1 Traditional pathway

Issue filed via the Bug report or Feature request form (§6.6).
Triage by a maintainer (§7): apply labels (type:*, area:*, priority:*), set path:traditional (or no path label, since traditional is the default), add to the Project board.
Claim: a contributor comments “I’d like to take this” and the maintainer assigns the issue. (For internal contributors, self-assignment is fine.)
Fork + branch per CONTRIBUTING.md’s naming rules.
PR opened against develop with the PR template filled in.
CI runs: lint, test, build, branch-name validation.
Reviews:
- CODEOWNERS approval (mandatory).
- Coco’s automated AI review (comment-only, on path:ai-automation PRs), which catches obvious issues.
- Optional: human peer-review from another contributor.
Merge by maintainer (squash). Branch auto-deleted.
Deploy: maintainer pushes dev-vX.Y.Z tag; existing CI deploys to dev.

5.2 AI-assisted pathway

The as-built pathway is documented in ai-pathway.md, a provider-agnostic agent run by gh-aw on the repo’s own API key, so no maintainer needs a Copilot seat. The summary:

Issue filed: same forms as above.
Triage: maintainer adds path:ai-automation; Coco opens a draft PR → develop and posts its plan as the first comment.
Approve the plan: maintainer comments /approve-plan on the PR; Coco implements into that same PR.
CI: same CI as the traditional pathway runs on the implementation push and on each later push.
Promote: /promote dev comment pushes the dev tag; CI deploys to dev and the assignee is pinged to test.
Iterate: /coco X makes Coco push more commits; CI re-runs, and no review fires on these pushes.
Review: the assignee marks the PR Ready for review, which runs Coco’s automated review once (comment-only, never an approval; it leads with a 🟢/🟡/🔴 decision).
Merge: same human gate: only a maintainer can merge, and the reviewer is pinged on approval.

5.3 What is identical between pathways

Branch-naming convention.
Target branch (develop).
CI checks (must all pass).
CODEOWNERS approval requirement.
Branch protection rules (signed commits, required reviews, etc.).
Merge strategy (squash, branch deletion).
Deploy mechanism (tags drive the existing CI).

5.4 What is different

Concern	Traditional	AI-assisted
Implementer	Human contributor	Coco (gh-aw AI agent)
Where feedback goes	PR review comments addressed to the author	PR comments with `/coco`
Iteration speed	Human-paced	Minutes per round
Approved-for	Any change in scope	Any change the maintainer approves via `/approve-plan` (§2)
Maintainer effort	Same review effort	Same review effort (this is the point: quality bar doesn’t drop)

The AI pathway is not “cheaper review”. It is “cheaper authorship”.

5.5 How Issues, PRs, and Discussions link together

The lifecycle above only works if the links between artefacts are machine-readable. GitHub provides several mechanisms; adopt them consistently so the audit trail is automatic. Quick answer to a common question, “does the issue number go in the PR title?” No. Use Closes #123 in the PR body (not the title). The body keyword creates the “Linked PR” relationship and auto-closes the issue on merge. PR titles stay descriptive (Conventional Commits style); the issue↔PR link is a body concern.

Closing keywords (PR body → Issue)

In the PR body, use one of:

Keyword	Effect
`Closes #123` / `Closed #123`	Auto-close on merge into the default branch.
`Fixes #123` / `Fixed #123`	Same; preferred wording for bugs.
`Resolves #123` / `Resolved #123`	Same.
`Refs #123` or just `#123`	Reference only, no auto-close. Use for partial work or related issues.

Rules of thumb:

Multi-issue PR: each issue needs its own keyword (e.g. Closes #123, closes #124).
Cross-repo: Closes owner/repo#123.
Auto-close only fires when the PR merges into the default branch. HAICO’s default is develop (set in going-public.md), so the develop-merge closes the issue. The later promotion to main does not re-trigger.
Closing keywords are also recognised inside commit messages, but PR-body is the canonical place: keep the single source of truth in the PR.

The PR template (§6.6) is updated to prompt for this.

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 track the branch-name types in CONTRIBUTING.md: feat, fix, hotfix, refactor, docs, test, chore, experiment. Why this convention:

The PR title becomes the squash-commit message after merge → readable git log.
Release Drafter (§11) groups release notes by type:.
It is the most widely-adopted convention in open source: zero friction for arriving contributors.

Do not put #123 in the title. GitHub auto-appends (#PR_NUMBER) (the PR number, not the issue number) on squash-merge, and that is enough to backtrack from git log to the PR, and the PR’s body contains the issue link. Putting both numbers in the title makes commit messages noisy.

Branch name convention

Already enforced by .github/workflows/branch-name.yml and .githooks/pre-push. Optionally include the issue number after the type for clarity:

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

Branch names are ephemeral (they vanish on squash-merge), so this is purely for the contributor’s own readability. Coco’s PRs get a gh-aw-generated branch name automatically; both styles coexist fine.

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 Discussion → ⋯ 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: file Issues directly. For usage questions, the answer never becomes an Issue: it stays in 🙏 Q&A and a maintainer marks an answer accepted. That keeps the Issues tab a clean inventory of work, not help requests. The right sidebar of every Issue has a Development section. Use it when:

A PR exists but does not include closing keywords (e.g. partial fix).
A branch needs to be associated with an Issue before a PR exists.
The PR targets a non-default branch (e.g. a release branch) and the auto-close link is still wanted.

Create a branch can be invoked directly from the Issue sidebar to spin up a properly-named, pre-linked branch in one step. (Handy for traditional-pathway work; the AI pathway instead starts automatically from the path:ai-automation label.)

Task lists and sub-issues 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 (2024+) makes the parent/child relationship first-class: visible as a panel in the Issue UI and navigable in the Project board. It applies when the epic needs more structure than a checklist or when the hierarchy should appear in Project views.

Announcing releases (PR ↔ Discussion)

PRs don’t auto-post to Discussions; this is the one manual link in the chain. For each vX.Y.Z release:

Tag and publish the GitHub Release (notes can be auto-drafted by Release Drafter, see §11).
Open a 📣 Announcement discussion summarising the release, linking the release page, and referencing notable PRs (#N) and resolved Issues (#M).

Announcement discussions are subscribable and surface in the Discussions tab, so they reach users who don’t watch the Releases tab. For HAICO, this is the single highest-leverage outreach mechanism short of social posts.

Cheat-sheet

Goal	Where to do it	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 an answer accepted
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

6. Step-by-step setup

These are done in order. After §6 the repo is community-ready; it can then be flipped public per going-public.md and the automation guides layered on top.

6.1: Decide your tier targets

The gap analysis (§3.2) is walked down to decide which Optional items apply; defaults are sensible. Tiers ship in this order: Essential → Recommended → Optional → Automation. Earlier tiers are not skipped.

6.2: Add the missing root files

These live at the repo root:

`CODE_OF_CONDUCT.md`

Uses the Contributor Covenant v2.1 verbatim. GitHub recognises it and surfaces it on the Insights → Community Standards page. The enforcement contact is the project security address (petrosrapto@gmail.com, the same one used in SECURITY.md).

`NOTICE`

Required for Apache 2.0 redistribution. The skeleton:

HAI-Co² (Human-AI Co-Construction) reference implementation
Copyright 2025 The HAI-Co² Authors

This product includes software developed at TU Darmstadt.
This product is licensed under the Apache License, Version 2.0;
see LICENSE for the full text.

This product bundles dependencies under their own licenses; see
the dependency manifests (backend/requirements.txt,
backend/requirements-test.txt, frontend/package-lock.json) for a
per-dependency list.

It is updated yearly. Long license texts are not put inline; that’s what LICENSE is for.

`GOVERNANCE.md`

A short document that answers: Who decides what gets merged? For a single-maintainer project today, the honest version reads:

# Governance

HAI-Co² is currently a single-maintainer project. Decisions are made by
@petrosrapto. As contributors grow, this document will be updated to reflect a
real governance model, likely a small steering committee (3–5 maintainers)
voting by lazy consensus, with a documented escalation path.

## Roles

- **Contributor**: anyone who has opened an issue, a PR, or a Discussion.
- **Maintainer**: a contributor with write access to this repository. The
  current list is in [MAINTAINERS.md](MAINTAINERS.md).
- **Lead maintainer**: the maintainer with final say in case of deadlock.
  Today this is @petrosrapto.

## Decision process

- Most decisions are made on a PR or in a Discussion by *lazy consensus*:
  if no maintainer objects within 7 days, the proposal is accepted.
- Decisions that change governance, licensing, or break public APIs require
  explicit approval from a majority of maintainers and the lead maintainer.

## Changes to this document

Open a PR. Governance changes require lead-maintainer approval.

Even at one maintainer, having this file says “this project takes contributors seriously”.

`MAINTAINERS.md`

# Maintainers

| Name | GitHub | Areas | Since |
|---|---|---|---|
| Petros Raptopoulos | [@petrosrapto](https://github.com/petrosrapto) | All | 2025 |

To become a maintainer, see [GOVERNANCE.md](GOVERNANCE.md).

`SUPPORT.md`

A two-sentence file that GitHub auto-links from the issue chooser. The <owner> placeholder resolves to the GitHub org/user that hosts the repo:

# Getting support

- **Questions or usage help** → [GitHub Discussions](https://github.com/<owner>/HAICO/discussions/categories/q-a)
- **Bug reports** → [open a Bug Report issue](https://github.com/<owner>/HAICO/issues/new?template=bug_report.yml)
- **Feature ideas** → [start an Idea discussion](https://github.com/<owner>/HAICO/discussions/categories/ideas) first; if it gathers support, open a Feature Request issue.
- **Security vulnerabilities** → see [SECURITY.md](SECURITY.md); **do not** open a public issue.

`.all-contributorsrc`

Config for the all-contributors bot. The bot listens for @all-contributors add @<user> for <contribution-type> comments on issues and PRs, updates this file, and regenerates a visual contributor table in README.md. Contribution types cover code as well as non-code work (ideas, bug, design, review, talk, tutorial, etc.), which is the main reason to prefer it over a hand-maintained AUTHORS file. The skeleton:

{
  "projectName": "HAICO",
  "projectOwner": "petrosrapto",
  "repoType": "github",
  "repoHost": "https://github.com",
  "files": ["README.md"],
  "imageSize": 100,
  "contributorsPerLine": 7,
  "contributors": [],
  "commit": false,
  "commitType": "docs",
  "skipCi": true
}

`.github/FUNDING.yml` (optional)

Deferred until sponsors are actually wanted. When added:

github: [petrosrapto]
# Or:
# open_collective: haico
# custom: ["https://example.com/sponsor"]

Expand `.github/dependabot.yml`

Beyond GitHub Actions, the config covers the language and container ecosystems:

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule: { interval: "weekly" }
  - package-ecosystem: "pip"
    directory: "/backend"
    schedule: { interval: "weekly" }
    groups:
      python-minor:
        update-types: ["minor", "patch"]
  - package-ecosystem: "npm"
    directory: "/frontend"
    schedule: { interval: "weekly" }
    groups:
      js-minor:
        update-types: ["minor", "patch"]
  - package-ecosystem: "docker"
    directory: "/deployment/dev"
    schedule: { interval: "weekly" }
  - package-ecosystem: "docker"
    directory: "/deployment/prod"
    schedule: { interval: "weekly" }

The groups: blocks collapse minor/patch bumps into one PR per ecosystem per week, which cuts review noise dramatically.

Expand `.github/CODEOWNERS`

See §3.3. Area-scoped rules are added so the file describes intent even when every owner is currently the same person.

6.3: Changelog strategy

HAICO uses Release Drafter and keeps no manual CHANGELOG.md (consistent with §3.1/§3.2 and automations.md §5). Two channel-specific configs (.github/release-drafter-dev.yml and .github/release-drafter-prod.yml) plus their workflows draft running release notes for the dev and prod channels. Each merged PR auto-categorises (based on labels) into the running draft for its channel; a maintainer reviews and publishes on tag. The discarded alternative was a manual CHANGELOG.md in Keep a Changelog format, updated by hand on each vX.Y.Z release. That is a fit only when releases are infrequent and curated, and it is superseded here by the two Release Drafter channels.

6.5: Add Architecture Decision Records (ADRs)

The docs/adr/ directory holds a docs/adr/0000-record-architecture-decisions.md (“Meta: architecture decisions are recorded in this directory”). It uses the MADR template: short, structured. Why this matters for the dual-pathway design: an ADR is the artefact that marks an architectural decision. A change that needs an ADR is flagged in Coco’s plan and the ADR itself stays human-authored; the agent implements only after a human approves the plan with /approve-plan (see ADR-0002). It is seeded with one or two real decisions that can be written today:

docs/adr/0001-two-branch-model.md (rationale for develop + main)
docs/adr/0002-dual-development-pathways.md (rationale for this guide)
docs/adr/0003-langgraph-for-agent-core.md (or whichever choice is most load-bearing in backend/).

6.6: Convert templates to YAML issue forms

The issue templates are YAML forms rather than Markdown. Forms give structured fields (text, dropdown, checkboxes) that are easier for humans to fill and easier for AI to parse. .github/ISSUE_TEMPLATE/bug_report.yml:

name: Bug report
description: Report a defect in HAI-Co²
title: "[bug] "
labels: ["type:bug", "needs-triage"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for filing! Please fill the fields below. For security
        vulnerabilities, do **not** use this form; see [SECURITY.md](https://github.com/<owner>/HAICO/blob/develop/SECURITY.md).
  - type: dropdown
    id: area
    attributes:
      label: Area
      options: [backend, frontend, deployment, docs, other]
    validations: { required: true }
  - type: textarea
    id: what
    attributes:
      label: What happened?
      description: A clear and concise description of the bug.
    validations: { required: true }
  - type: textarea
    id: repro
    attributes:
      label: Steps to reproduce
      description: A minimal sequence of steps that reproduces the bug.
    validations: { required: true }
  - type: textarea
    id: expected
    attributes:
      label: Expected behaviour
    validations: { required: true }
  - type: input
    id: version
    attributes:
      label: Version or commit
  - type: textarea
    id: env
    attributes:
      label: Environment
      placeholder: |
        OS:
        Browser (if frontend):
        Python/Node version:

.github/ISSUE_TEMPLATE/feature_request.yml:

name: Feature request
description: Propose a new capability
title: "[feat] "
labels: ["type:enhancement", "needs-triage"]
body:
  - type: markdown
    attributes:
      value: |
        If this is an open-ended idea, consider starting a
        [💡 Idea discussion](https://github.com/<owner>/HAICO/discussions/categories/ideas) first.
  - type: textarea
    id: problem
    attributes: { label: "Problem", description: "What user need is unmet today?" }
    validations: { required: true }
  - type: textarea
    id: proposal
    attributes: { label: "Proposed solution" }
    validations: { required: true }
  - type: textarea
    id: alternatives
    attributes: { label: "Alternatives considered" }
  - type: textarea
    id: acceptance
    attributes:
      label: "Acceptance criteria (checklist)"
      placeholder: |
        - [ ] ...
        - [ ] ...

A third template covers refactor proposals, a real third category, distinct from bugs and features: .github/ISSUE_TEMPLATE/refactor.yml:

name: Refactor proposal
description: Propose restructuring of existing code, no behaviour change
title: "[refactor] "
labels: ["type:refactor", "needs-triage", "path:traditional"]
body:
  - type: markdown
    attributes:
      value: |
        Refactors are **traditional-pathway** by default. If the refactor is
        contained to one file or is mechanical (e.g. type annotations,
        renames), a maintainer may re-label it `path:ai-automation`.
  - type: textarea
    id: current
    attributes: { label: "Current structure" }
    validations: { required: true }
  - type: textarea
    id: proposed
    attributes: { label: "Proposed structure" }
    validations: { required: true }
  - type: textarea
    id: rationale
    attributes: { label: "Rationale", description: "Why is this worth doing now?" }
    validations: { required: true }

And the config file, which is the single most undervalued file in the issue-template directory: .github/ISSUE_TEMPLATE/config.yml:

blank_issues_enabled: false
contact_links:
  - name: 🙏 Q&A (usage questions)
    url: https://github.com/<owner>/HAICO/discussions/categories/q-a
    about: For help using HAI-Co². Issues are for bugs and feature work.
  - name: 💡 Ideas (open-ended proposals)
    url: https://github.com/<owner>/HAICO/discussions/categories/ideas
    about: Brainstorm or build community support before filing a feature request.
  - name: 🔒 Security vulnerabilities
    url: https://github.com/<owner>/HAICO/security/advisories/new
    about: Use private vulnerability reporting. Do not open a public issue.

Disabling blank issues prevents the “just opened a blank issue with one line” problem.

Refining the pull request template

The .github/pull_request_template.md prompts for a closing keyword (see §5.5), makes the issue link explicit, adds a Conventional-Commits title reminder, and adds an ADR check for architectural changes:

## What does this PR do?
<!-- A clear description of the changes. -->

## Why is this change needed?
<!-- Explain the motivation. Link to a Discussion if this started there. -->

## Linked issue(s)
<!-- Use a closing keyword so the issue auto-closes on merge into `develop`.
     Examples:
       Closes  #123    : auto-closes #123 on merge
       Fixes   #45     : same; preferred wording for bugs
       Resolves #67    : same
       Refs    #99     : references without closing (use for partial work)
     Multi-issue:       Closes #1, closes #2
     Cross-repo:        Closes owner/repo#3
-->
Closes #

## How does it work?
<!-- Briefly describe the implementation approach. -->

## Checklist
- [ ] **PR targets `develop`** (not `main`)
- [ ] Linked an issue with `Closes #...` above (or this is a no-issue chore)
- [ ] PR title follows Conventional Commits (e.g. `feat(backend): ...`)
- [ ] Tests added/updated
- [ ] Linting passes (`npm run lint` / `pytest`)
- [ ] No secrets or credentials committed
- [ ] Documentation updated (if applicable)
- [ ] If this is an architectural change → ADR added under `docs/adr/`

## Screenshots
<!-- If applicable, add screenshots or recordings. -->

For multi-template repos (rare at this scale), a .github/PULL_REQUEST_TEMPLATE/ directory can hold several files (feature.md, hotfix.md, …) and contributors choose by appending ?template=feature.md to the new-PR URL. HAICO doesn’t need this yet.

6.7: Define the labels taxonomy

Labels are the connective tissue of the whole system: triage uses them, the Project board filters on them, the labeler workflow (§11) assigns them automatically, and the AI pathway dispatches on them. Standardise once.

Group	Labels
Type	`type:bug` `type:enhancement` `type:refactor` `type:docs` `type:test` `type:chore`
Area	`area:backend` `area:frontend` `area:deployment` `area:docs` `area:ci`
Priority	`priority:critical` `priority:high` `priority:medium` `priority:low`
Status	`needs-triage` `needs-info` `blocked` `wontfix` `duplicate`
Pathway	`path:traditional` `path:ai-automation` `path:ai-automation-claude` `path:ai-automation-codex` `path:ai-automation-copilot`
AI	`ai:review` (the pathway is driven by `/approve-plan`, `/coco`, `/promote dev` slash commands)
Community	`good first issue` `help wanted`
Effort	`effort:S` `effort:M` `effort:L`

They are created in one go with the gh CLI:

# Run from the repo root, after `brew install gh` and `gh auth login`.
.github/scripts/init-labels.sh

That script calls gh label create --force ... for each row. Once created, the labels survive forever; this is a one-time operation. A few rules so the taxonomy stays meaningful:

Every issue gets exactly one type: label during triage.
Every issue gets exactly one area: label during triage.
needs-triage is removed once the issue is triaged.
good first issue is reserved for issues a newcomer can finish in <2 hours without reading internal docs. Putting it on harder issues kills trust.
path:ai-automation is added explicitly by a maintainer. Default is traditional; the absence of path:traditional means traditional. The engine is chosen by which pathway label is applied: the bare path:ai-automation (= Claude) and -claude / -codex are seat-free; -copilot needs a Copilot seat. Apply exactly one.

6.8: Polish the README and repository card

The README is the single biggest determinant of star conversion, and warrants real time. Recommended structure (cherry-picking from the current one):

Hero: project name + tagline (one sentence describing what it does, not what it is).
Badges: build status, license, latest release, stars. Keep it to ~5; more looks performative.
Demo: a 30-second GIF or a screenshot strip. The single highest-ROI addition available.
Why HAI-Co²?: one paragraph for the audience (researchers? AI/UX teams? educators?).
Quickstart: 3–5 commands that get to a running demo.
Architecture: link to docs/architecture.md and the paper.
Contributing: link to CONTRIBUTING.md and docs/repository-foundation.md.
Community: link to Discussions; mention Code of Conduct.
License.

Then in Settings → General:

Description: one sentence (use the README’s tagline).
Website: link to the paper or to a project page.
Topics: 5–10 lowercase keywords (e.g. hai-co, langgraph, fastapi, nextjs, human-ai-collaboration, agent-framework, research).
A 1280×640 PNG social preview. This is the image that appears on Twitter/Mastodon/HN previews and it dramatically affects clicks.

6.9: Configure GitHub Discussions

Enable Discussions: Settings → General → Features → Discussions → ✓. Configure categories (Discussions tab → ⚙️ → Categories). Recommended set (the common defaults plus two HAICO-specific ones):

Category	Format	Purpose
📢 Announcements	Announcement	Maintainer-only post format; for releases and major news.
🛠️ Contributor lounge	Open-ended	Where contributors coordinate. (HAICO-specific.)
💬 General	Open-ended	Catch-all.
💡 Ideas	Open-ended	Where features incubate before becoming issues.
🙏 Q&A	Question/answer	Usage help. Has an “Accepted answer” UI.
📚 Research	Open-ended	Discussion of the Dutta et al. 2025 paper and related work. (HAICO-specific.)
🙌 Show and tell	Open-ended	Users sharing what they built with HAICO. Drives stars.

One welcome discussion is pinned in General explaining the dual-pathway model and where to file what; it is linked from the README too. (Optional) .github/DISCUSSION_TEMPLATE/q-a.yml and similar files give discussion authors structured prompts. Same syntax as issue forms.

6.10: Create the community Project board

Either a user-owned Project (owned by an individual) or an org-owned Project (owned by the GitHub org; required for multiple maintainers with equal access). For HAICO solo today, user-owned is fine; the project moves to org-owned once there are co-maintainers. Fields and views are defined in detail in github-projects-copilot-automation.md §5.1. For the foundation guide (this one), the minimum is:

Status field with Backlog, In Progress, Done.
A public roadmap view filtered to Status in (Backlog, In Progress), grouped by milestone or iteration. This view is the default so visitors land on the roadmap, not the table.
A Good first issues view filtered to label = "good first issue" AND Status = Backlog, linked from the README: it is the single most effective onboarding link for newcomers.

The richer status set (Ready for AI, On Dev, …) from the automation guide is added later, when the AI pathway is wired.

6.11: Configure Insights → Community Standards

The repo’s Insights → Community Standards page is a checklist of the files GitHub considers community-essential: After §6.2–§6.6 every box should be green. The repo is not flipped public until they are. The page is publicly visible once the repo is public and visitors do look at it.

6.12: Branch protection and review policy

Handled in going-public.md. The relevant rules are the same regardless of which pathway authored a PR; they stay strict and are not relaxed for AI PRs. The one thing to add before the public flip: CODEOWNERS review is required on develop and main. The default branch protection rule doesn’t require it.

6.13: A triage workflow (the human one)

Triage cadence is a maintainer’s choice; weekly is sustainable for a one-maintainer project. With 30 minutes blocked on the calendar, the Triage view of the Project board (filter Status = Backlog AND label = needs-triage) is opened and the queue is walked: For each issue:

Read it. If it’s a duplicate or wontfix → label and close with a kind message.
If under-specified → add needs-info, ask the question, await reply.
Otherwise:
- Set type:* (one).
- Set area:* (one).
- Set priority:* (one).
- Set effort:* (one).
- Decide pathway. If §2’s checklist is fully ticked → path:ai-automation (adding the label starts Coco). Otherwise → no path label (defaults to traditional).
- If newcomer-friendly → good first issue.
- Remove needs-triage.
- Add to a milestone if the issue is on the near-term roadmap.

The target is all issues triaged within 7 days of being opened. That is the metric contributors notice.

7. Connection to the automation guides

Once §6 is done and the repo is in the green:

Flip the repo to public per going-public.md.
Wait one or two weeks. Watch how real contributors arrive (or don’t). Improve the README and the issue forms based on what trips people up.
Then layer the AI pathway, following ai-pathway.md.

The automation guides assume this foundation is in place. They reuse the same labels, the same Project, the same review process; they just plug the AI agent (Coco) into the implementer slot when the pathway label says so.

8. What not to do

Don’t auto-close stale issues without a long timeout and a maintainer prompt. Aggressive stale bots are the single most-cited reason contributors leave projects. If one is adopted, it uses 180-day inactivity, two warnings, and a needs-info exemption.
Don’t accept AI-authored PRs to the traditional pathway. The pathway label is a contract: a path:traditional issue is implemented by a human. This keeps authorship aligned with the pathway the maintainer chose.
Don’t lower the review bar for AI PRs. The agent is bounded by human approval (/approve-plan), not a triviality gate, so the reviewer’s effort stays the same regardless of who authored the change.
Don’t make the AI pathway the default. It is opt-in. The triaging maintainer chooses.

9. Optional: stale bot, Release Drafter, labeler

These three are common open-source quality-of-life automations. They are not part of the AI-pathway automation; they’re foundation polish. All three are now configured in this repository; this section keeps the wiring rationale, while automations.md gives the lifecycle-oriented functional overview of every live automation.

9.1 Labeler (auto-label PRs by changed paths)

actions/labeler. Workflow:

# .github/workflows/labeler.yml
name: PR labeler
on: [pull_request_target]
jobs:
  label:
    runs-on: ubuntu-latest
    permissions: { contents: read, pull-requests: write }
    steps:
      - uses: actions/labeler@v5

Config:

# .github/labeler.yml
area:backend:
  - changed-files:
    - any-glob-to-any-file: ['backend/**']
area:frontend:
  - changed-files:
    - any-glob-to-any-file: ['frontend/**']
area:deployment:
  - changed-files:
    - any-glob-to-any-file: ['deployment/**']
area:docs:
  - changed-files:
    - any-glob-to-any-file: ['docs/**', '**/*.md']
area:ci:
  - changed-files:
    - any-glob-to-any-file: ['.github/**']

9.2 Release Drafter

release-drafter/release-drafter generates the next release’s notes from merged PRs, grouping by label. Two channel-specific configs (.github/release-drafter-dev.yml and .github/release-drafter-prod.yml) plus their workflows drive the dev and prod channels. This is HAICO’s changelog strategy (§6.3); there is no manual CHANGELOG.md.

9.3 Stale bot

actions/stale. Recommended config:

days-before-stale: 180          # not aggressive
days-before-close: 21           # plenty of time to respond
stale-issue-message: |
  This issue has had no activity for 180 days. It will be closed in 21 days
  unless someone reactivates it. To keep it open, just comment.
exempt-issue-labels: 'needs-info,blocked,help wanted,good first issue,priority:critical,priority:high'
exempt-pr-labels: 'wip,blocked'

Applied only after Phase 2: a stale bot should not bite before a maintenance rhythm is in place.

10. Sources

Community guide Maintainers handbook

​HAICO Repository Foundation: Community-First Setup with Dual Development Pathways

​1. Two pathways, one repository

​2. What “trivial” means: when to use the AI pathway

​Typical AI-pathway changes

​When to prefer the traditional pathway

​3. Gap analysis: what’s here, what’s missing

​3.1 What HAICO has today

​3.2 What remains

​3.3 The CODEOWNERS file needs work

​4. What belongs in .github/

​4.1 The files that matter

​4.2 Issue templates worth having

​4.3 Discussions

​5. The dual-pathway lifecycle in detail

​5.1 Traditional pathway

​5.2 AI-assisted pathway

​5.3 What is identical between pathways

​5.4 What is different

​5.5 How Issues, PRs, and Discussions link together

​Closing keywords (PR body → Issue)

​PR title convention: Conventional Commits

​Branch name convention

​Discussion → Issue promotion

​The “Development” sidebar

​Task lists and sub-issues for epics

​Announcing releases (PR ↔ Discussion)

​Cheat-sheet

​6. Step-by-step setup

​6.1: Decide your tier targets

​6.2: Add the missing root files

​CODE_OF_CONDUCT.md

​NOTICE

​GOVERNANCE.md

​MAINTAINERS.md

​SUPPORT.md

​.all-contributorsrc

​.github/FUNDING.yml (optional)

​Expand .github/dependabot.yml

​Expand .github/CODEOWNERS

​6.3: Changelog strategy

​6.5: Add Architecture Decision Records (ADRs)

​6.6: Convert templates to YAML issue forms

​Refining the pull request template

​6.7: Define the labels taxonomy

​6.8: Polish the README and repository card

​6.9: Configure GitHub Discussions

​6.10: Create the community Project board

​6.11: Configure Insights → Community Standards

​6.12: Branch protection and review policy

​6.13: A triage workflow (the human one)

​7. Connection to the automation guides

​8. What not to do

​9. Optional: stale bot, Release Drafter, labeler

​9.1 Labeler (auto-label PRs by changed paths)

​9.2 Release Drafter

​9.3 Stale bot

​10. Sources