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

# Repository foundation

> The foundation a community-facing repository needs, and the dual development pathways.

# 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](/docs/github-projects-copilot-automation)). It describes the *foundation* a serious community-facing repository needs before any AI automation is layered on top.

Two ideas drive the design:

1. **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.
2. **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](https://github.com/petrosrapto/HAICO/blob/main/docs/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

```mermaid theme={null}
flowchart TD
    A["New GitHub Issue<br/>via issue form"] -->|"triage by maintainer · add labels · add to Project board"| B["Maintainer decides the pathway<br/>based on the criteria in §2"]
    B --> T["path:traditional · default<br/>external or internal author<br/>fork, branch, PR to develop<br/>CODEOWNERS, reviewer, CI green"]
    B --> AI["path:ai-automation<br/>maintainer adds path:ai-automation<br/>Coco opens draft PR, plan comment<br/>CODEOWNERS, reviewer, AI review, CI"]
    T --> M["merge to develop<br/>dev deploy<br/>promote to main"]
    AI --> M
```

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](/docs/adr/0002-dual-development-pathways)). 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](#65-add-architecture-decision-records-adrs)); 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`](https://github.com/petrosrapto/HAICO/blob/main/.github/CODEOWNERS)                                                                                                                                                       | Single fallback rule: every file → `@petrosrapto` (see §3.3).                                                                                 |
| [`.github/ISSUE_TEMPLATE/`](https://github.com/petrosrapto/HAICO/blob/main/.github/ISSUE_TEMPLATE)                                                                                                                                              | Four YAML issue forms (`bug_report`, `feature_request`, `docs`, `refactor`) plus `config.yml` (issue chooser + contact links).                |
| [`.github/labels.yml`](https://github.com/petrosrapto/HAICO/blob/main/.github/labels.yml) + [`scripts/init-labels.sh`](https://github.com/petrosrapto/HAICO/blob/main/.github/scripts/init-labels.sh)                                           | The label taxonomy as the single source of truth, with an idempotent script that applies it.                                                  |
| [`.github/labeler.yml`](https://github.com/petrosrapto/HAICO/blob/main/.github/labeler.yml) + [`workflows/labeler.yml`](https://github.com/petrosrapto/HAICO/blob/main/.github/workflows/labeler.yml)                                           | Auto-labels PRs with `area:*` by changed path.                                                                                                |
| [`.github/release-drafter-dev.yml`](https://github.com/petrosrapto/HAICO/blob/main/.github/release-drafter-dev.yml) / [`-prod.yml`](https://github.com/petrosrapto/HAICO/blob/main/.github/release-drafter-prod.yml) + their workflows          | Running draft release notes for the dev and prod channels.                                                                                    |
| [`.github/workflows/stale.yml`](https://github.com/petrosrapto/HAICO/blob/main/.github/workflows/stale.yml)                                                                                                                                     | Conservative stale-issue / PR bot.                                                                                                            |
| [`.github/dependabot.yml`](https://github.com/petrosrapto/HAICO/blob/main/.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`](https://github.com/petrosrapto/HAICO/blob/main/.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`](https://github.com/petrosrapto/HAICO/blob/main/.github/workflows/branch-name.yml)                                                                                                                         | Server-side branch-name enforcement.                                                                                                          |
| [`.github/workflows/ci.yml`](https://github.com/petrosrapto/HAICO/blob/main/.github/workflows/ci.yml)                                                                                                                                           | Lint, test, build, deploy.                                                                                                                    |
| [`.githooks/pre-push`](https://github.com/petrosrapto/HAICO/blob/main/.githooks/pre-push)                                                                                                                                                       | Client-side branch-name enforcement (opt-in).                                                                                                 |
| [`README.md`](https://github.com/petrosrapto/HAICO/blob/main/README.md)                                                                                                                                                                         | Project description, badges, and a documentation index.                                                                                       |
| [`CONTRIBUTING.md`](https://github.com/petrosrapto/HAICO/blob/main/CONTRIBUTING.md)                                                                                                                                                             | Branching model, branch-naming, release procedure.                                                                                            |
| [`CODE_OF_CONDUCT.md`](https://github.com/petrosrapto/HAICO/blob/main/CODE_OF_CONDUCT.md)                                                                                                                                                       | Contributor Covenant; surfaced on the Community Standards page.                                                                               |
| [`GOVERNANCE.md`](https://github.com/petrosrapto/HAICO/blob/main/GOVERNANCE.md) / [`MAINTAINERS.md`](https://github.com/petrosrapto/HAICO/blob/main/MAINTAINERS.md) / [`SUPPORT.md`](https://github.com/petrosrapto/HAICO/blob/main/SUPPORT.md) | Decision process, current maintainers, and where to get help.                                                                                 |
| [`SECURITY.md`](https://github.com/petrosrapto/HAICO/blob/main/SECURITY.md)                                                                                                                                                                     | Vulnerability reporting.                                                                                                                      |
| [`NOTICE`](https://github.com/petrosrapto/HAICO/blob/main/NOTICE)                                                                                                                                                                               | Apache 2.0 § 4(d) attribution notices.                                                                                                        |
| [`.all-contributorsrc`](https://github.com/petrosrapto/HAICO/blob/main/.all-contributorsrc)                                                                                                                                                     | Contributor-recognition config.                                                                                                               |
| [`LICENSE`](https://github.com/petrosrapto/HAICO/blob/main/LICENSE)                                                                                                                                                                             | Apache 2.0.                                                                                                                                   |
| [`docs/adr/`](/docs/adr/index)                                                                                                                                                                                                                       | 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](#69-configure-github-discussions)                                                                                                                                |
| Community Project board                            | **Essential** | [§6.10](#610-create-the-community-project-board) ; described in [`.github/project/README.md`](https://github.com/petrosrapto/HAICO/blob/main/.github/project/README.md) |
| Repo topics, description, social preview           | **Essential** | [§6.8](#68-polish-the-readme-and-repository-card)                                                                                                                       |
| CodeQL workflow (code scanning)                    | **Essential** | covered in [going-public.md](https://github.com/petrosrapto/HAICO/blob/main/docs/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](#62-add-the-missing-root-files)            |
| `.github/PULL_REQUEST_TEMPLATE/` (multiple templates) | Optional | [§6.6](#66-convert-templates-to-yaml-issue-forms) |
| `.github/DISCUSSION_TEMPLATE/`                        | Optional | [§6.9](#69-configure-github-discussions)          |

"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

1. **Issue filed** via the *Bug report* or *Feature request* form (§6.6).
2. **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.
3. **Claim**: a contributor comments "I'd like to take this" and the maintainer assigns the issue. (For internal contributors, self-assignment is fine.)
4. **Fork + branch** per [CONTRIBUTING.md](https://github.com/petrosrapto/HAICO/blob/main/CONTRIBUTING.md)'s naming rules.
5. **PR opened** against `develop` with the PR template filled in.
6. **CI runs**: lint, test, build, [branch-name validation](https://github.com/petrosrapto/HAICO/blob/main/.github/workflows/branch-name.yml).
7. **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.
8. **Merge** by maintainer (squash). Branch auto-deleted.
9. **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](/docs/ai-pathway), a
provider-agnostic agent run by `gh-aw` on the repo's own API key, so no maintainer
needs a Copilot seat. The summary:

1. **Issue filed**: same forms as above.
2. **Triage**: maintainer adds `path:ai-automation`; Coco opens a **draft PR** → `develop` and posts its **plan as the first comment**.
3. **Approve the plan**: maintainer comments `/approve-plan` on the PR; Coco implements into that same PR.
4. **CI**: same CI as the traditional pathway runs on the implementation push and on each later push.
5. **Promote**: `/promote dev` comment pushes the dev tag; CI deploys to dev and the assignee is pinged to test.
6. **Iterate**: `/coco X` makes Coco push more commits; CI re-runs, and no review fires on these pushes.
7. **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).
8. **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](https://github.com/petrosrapto/HAICO/blob/main/docs/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](https://github.com/petrosrapto/HAICO/blob/main/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`](https://github.com/petrosrapto/HAICO/blob/main/.github/workflows/branch-name.yml) and [`.githooks/pre-push`](https://github.com/petrosrapto/HAICO/blob/main/.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*:

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 **Discussion → ⋯ 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: 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 "Development" sidebar

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:

```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 (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:

1. Tag and publish the GitHub Release (notes can be auto-drafted by Release Drafter, see §11).
2. 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](https://github.com/petrosrapto/HAICO/blob/main/docs/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](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) 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](https://github.com/petrosrapto/HAICO/blob/main/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:

```markdown theme={null}
# 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`

```markdown theme={null}
# 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:

```markdown theme={null}
# 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](https://allcontributors.org) 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:

```json theme={null}
{
  "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:

```yaml theme={null}
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:

```yaml theme={null}
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](/docs/automations)). Two channel-specific configs ([`.github/release-drafter-dev.yml`](https://github.com/petrosrapto/HAICO/blob/main/.github/release-drafter-dev.yml) and [`.github/release-drafter-prod.yml`](https://github.com/petrosrapto/HAICO/blob/main/.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](https://keepachangelog.com/en/1.1.0/) 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](https://adr.github.io/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](/docs/adr/0002-dual-development-pathways)).

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`:

```yaml theme={null}
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`:

```yaml theme={null}
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`:

```yaml theme={null}
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`:

```yaml theme={null}
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`](https://github.com/petrosrapto/HAICO/blob/main/.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:

```markdown theme={null}
## 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:

```bash theme={null}
# 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):

1. **Hero**: project name + tagline (one sentence describing what it *does*, not what it *is*).
2. **Badges**: build status, license, latest release, stars. Keep it to \~5; more looks performative.
3. **Demo**: a 30-second GIF or a screenshot strip. The single highest-ROI addition available.
4. **Why HAI-Co²?**: one paragraph for the audience (researchers? AI/UX teams? educators?).
5. **Quickstart**: 3–5 commands that get to a running demo.
6. **Architecture**: link to `docs/architecture.md` and the paper.
7. **Contributing**: link to `CONTRIBUTING.md` and `docs/repository-foundation.md`.
8. **Community**: link to Discussions; mention Code of Conduct.
9. **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](/docs/github-projects-copilot-automation#step-51--decide-on-the-project-shape). **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:

* [ ] Description
* [ ] README
* [ ] Code of conduct
* [ ] Contributing
* [ ] License
* [ ] Security policy
* [ ] Issue templates
* [ ] Pull request template

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](https://github.com/petrosrapto/HAICO/blob/main/docs/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:

1. Read it. If it's a duplicate or wontfix → label and close with a kind message.
2. If under-specified → add `needs-info`, ask the question, await reply.
3. 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:

1. Flip the repo to public per [going-public.md](https://github.com/petrosrapto/HAICO/blob/main/docs/going-public.md).
2. 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.
3. Then layer the AI pathway, following [ai-pathway.md](/docs/ai-pathway).

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](/docs/automations) gives the lifecycle-oriented functional overview of every live automation.

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

[`actions/labeler`](https://github.com/actions/labeler). Workflow:

```yaml theme={null}
# .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:

```yaml theme={null}
# .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`](https://github.com/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`](https://github.com/actions/stale). Recommended config:

```yaml theme={null}
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

* [GitHub Docs: Setting up your project for healthy contributions](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions)
* [GitHub Docs: About community profiles for public repositories](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/about-community-profiles-for-public-repositories)
* [GitHub Docs: Syntax for issue forms](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms)
* [GitHub Docs: Configuring issue templates for your repository](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository)
* [GitHub Docs: Best practices for repositories](https://docs.github.com/en/repositories/creating-and-managing-repositories/best-practices-for-repositories)
* [GitHub Docs: About Discussions](https://docs.github.com/en/discussions/quickstart)
* [Contributor Covenant 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)
* [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
* [MADR: Markdown Architecture Decision Records](https://adr.github.io/madr/)
* [actions/labeler](https://github.com/actions/labeler)
* [release-drafter/release-drafter](https://github.com/release-drafter/release-drafter)
* [actions/stale](https://github.com/actions/stale)
* [all-contributors specification](https://allcontributors.org/)