# Contribution Guidelines

Thanks for helping curate the list. One thing to know before anything else:

> **`README.md`, `projects.yaml`, `TAGS.md`, `harnesses.json`, `harnesses.jsonld`, and `llms.txt` are all generated by [`scripts/generate.py`](scripts/generate.py).** A PR that edits them directly can't be merged — the next regeneration would erase it. Every accepted suggestion gets ported into `generate.py` (by you or by the maintainer), and you get co-author credit on the landing commit either way.

## Suggest a project (fastest)

[Open an issue](https://github.com/RyanAlberts/best-of-Agent-Harnesses/issues/new) titled `Add project: <name>` with:

- the repo URL,
- one sentence on what the **harness** is (the agent loop, tool wiring, approval/recovery model — as opposed to the UI shell),
- the category you'd file it under (see the [README contents](README.md#contents)).

That's enough — porting, tagging, and scoring happen on this side.

## Add a project yourself (PR)

Edit `scripts/generate.py` in three places, then regenerate:

1. **`PROJECTS`** — add a `Project(...)` entry to the right category list:

    ```python
    Project("AgentBox", "madarco/agentbox",
            "Runs multiple coding agents in parallel, each in its own sandboxed VM ... The **harness** contribution is the VM-per-agent isolation layer; whichever agent runs inside owns the loop.",
            "slightly complex (VM-per-agent sandbox, parallel fan-out)", labels=["javascript"]),
    ```

    - The description names the **harness** (bold the word) and contrasts it with the UI shell where relevant.
    - The fourth field must start with a tier: `super simple` → `mostly simple` → `slightly complex` → `complex`, followed by a short parenthetical.
    - `oss=` markers: `✅` standard OSS (default) · `⚠️ <license>` source-available/restricted · `❓` missing or unclear.

2. **`META`** — stars, plus the most useful "show me it in action" link:

    ```python
    "madarco/agentbox": (238, "https://github.com/madarco/agentbox#readme", "Parallel agents quick start"),
    ```

    Star counts are auto-refreshed weekly — the number just needs to be roughly current.

3. **`AXES`** — score the two behavior axes (vocabulary and definitions are in the comment above the dict):

    ```python
    "madarco/agentbox": ("n/a", "n/a"),   # doesn't own the agent loop
    ```

Then run:

```sh
python3 scripts/generate.py
python3 -m pytest tests/ -q
```

and commit **both** your `generate.py` change and the regenerated output files. CI runs the same tests (including a full site build) on your PR.

## Curation bar

- No personal repos with single-digit stars or fewer than ~10 commits.
- No archived/abandoned projects — the weekly refresh auto-moves archived repos to the [Graveyard](README.md#graveyard).
- When an official version supersedes a community fork, the official one is listed.
- In scope: harnesses, orchestration frameworks, and harness techniques — the runtime around the model, not model wrappers or prompt collections.

Promising projects that don't clear the bar yet get pinned to the README's [🔭 On the radar](README.md#-on-the-radar) section — a submission that lands there isn't rejected, it's queued. Radar entries graduate into the ranked list as they mature.

## Corrections and updates

Wrong description, example link, tier, or axes score for a project you maintain? Open an issue or a small PR against `generate.py` — maintainer corrections are merged fast. Don't submit star-count updates; the weekly rescore handles those.

## Show your listing

If your project is featured, you're welcome to add the badge to your README:

[![Best of Agent Harnesses](https://img.shields.io/badge/%F0%9F%8F%86_Best_of-Agent_Harnesses-5ac4bf)](https://github.com/RyanAlberts/best-of-Agent-Harnesses)

```md
[![Best of Agent Harnesses](https://img.shields.io/badge/%F0%9F%8F%86_Best_of-Agent_Harnesses-5ac4bf)](https://github.com/RyanAlberts/best-of-Agent-Harnesses)
```

## Code of Conduct

All members of the project community must abide by the [Contributor Covenant, version 2.0](./.github/CODE_OF_CONDUCT.md). Instances of unacceptable behavior may be reported by contacting a project maintainer.