awesome-ai-dev-tools/docs/CONTRIBUTING.md

# Contributing

## Adding an Agent

Edit [`data/agents.yml`](../data/agents.yml) and add an entry:

```yaml
agents:
  - owner: github-username-or-org
    repo: repository-name
    description: Terminal coding agent that edits files and runs commands in your repo
    tags: [terminal, byo-model, interactive, community]
```

Required fields: `owner`, `repo`, `tags`

Optional fields: `description` (curated one-liner), `notes` (for clarifications or caveats)

## Field Reference

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `owner` | string | Yes | GitHub user or organization that owns the repo |
| `repo` | string | Yes | Repository name on GitHub |
| `tags` | list | Yes | Tags from the vocabulary below; at least one surface tag, at most one origin tag |
| `description` | string | No | Curated one-line description shown instead of the repo's GitHub description; one line, no `\|`, at most 140 characters |
| `notes` | string | No | Additional context or disclaimers |

### Writing a description

Say what the tool is (terminal agent, VS Code extension, editor, desktop app,
self-hosted server) and the one trait that sets it apart, in one plain sentence
with no trailing period. Base it on the repo's own README, like tags. Leave out
marketing adjectives, emoji, star counts, and model version names, which go
stale within months. Without a `description`, the README shows whatever the
repo's GitHub description says, which is often empty or vague.

## Scope

This list ranks **developer tools built around AI** — things a developer uses to
build software, where an LLM is central to what the tool does. In practice that
spans several shapes:

- **Coding agents** — they write, edit, or review code themselves.
- **Agent development environments (ADEs)** — their primary purpose is running and
  coordinating those agents: parallel worktrees, session management, remote or
  mobile control. Tag these `orchestration`.
- **AI-assisted editors, terminals, and review tools** — the developer stays in the
  driver's seat and the model accelerates the work.

The dividing line is **tools you use vs. building blocks you import**. Out of scope:
libraries and SDKs, agent frameworks meant to be built on, model weights, prompt or
skill collections, and dashboards that only observe a tool without being one.

A tool also has to be *about* software development. General-purpose assistants,
chat UIs, and multi-agent "digital workforce" apps — the ones whose specialists write
reports, decks, and marketing copy — do not qualify just because a developer could use
them, or because one of their agents happens to touch code. Judge the tool by what it is
built to do, not by the widest thing it can be pointed at.

### The star floor is hard

**1,000 stars minimum.** This is not a judgement call and is not waived for
individual entries, however good the tool is. The updater enforces it: any entry
below the floor is dropped from the ranking and reported as an `::error::` in the
Actions log (`enforceStarFloor` in `github.go`). Because star counts require the
API, `go run . -check` cannot catch this offline — a below-floor entry passes CI
and is then dropped by the next daily run, so check the count before opening a PR.

Maintenance requirements apply to every entry equally: no push in 6 months means
removal, and the daily run warns past 3 months.

## Tag Vocabulary

Tags replaced the old single-select `category` field, because one slot cannot
describe a tool that ships as a CLI, an editor plugin and a desktop app at the
same time — which most of them now do. An entry carries several tags across
five facets. `data/agents.yml` is the source of truth; the vocabulary itself
lives in `tagVocabulary` (`validate.go`) and reaches the dashboard through
the generated `dist/data.json`, so it is defined exactly once.

**Surface** — where you run it. At least one required.

- **terminal** — a CLI or TUI you run in a shell
- **editor-plugin** — extension for an existing editor (VS Code, JetBrains, Neovim)
- **ide** — a standalone editor or IDE
- **desktop** — a native or Electron/Tauri desktop app
- **web** — runs in a browser, hosted or local
- **self-hosted** — a server you deploy, with clients or editor plugins on top

**Model access** — which models it can drive.

- **byo-model** — bring your own: multiple providers, OpenAI-compatible endpoints, or OpenRouter
- **single-vendor** — built for one lab's models
- **local-models** — runs against local inference (Ollama, llama.cpp, vLLM, SGLang)

**Workflow** — how you work with it.

- **interactive** — conversational pair programming, you stay in the loop
- **autonomous** — takes a goal or issue and runs long stretches unattended
- **review** — reviews diffs or existing code rather than writing it
- **app-builder** — prompt-to-app scaffolding, with preview and deploy
- **research** — published as a research artifact or proof of concept
- **orchestration** — runs and coordinates *other* coding agents as its primary purpose (an ADE), rather than editing code itself

**Integration** — what it plugs into.

- **mcp** — speaks Model Context Protocol
- **acp** — speaks Agent Client Protocol
- **headless** — a non-interactive mode for scripting or CI

**Origin** — who publishes it. At most one.

- **vendor** — first-party tool from a model lab (Anthropic, OpenAI, Google, xAI, DeepSeek, Alibaba, Moonshot, …)
- **community** — everyone else

### The evidence rule

Apply a tag only when the repo's own README, docs, or GitHub topics support it.
Do not tag from reputation or from a blog post. Under-tagging is better than a
wrong tag: a missing tag hides a row from one filter, a wrong one sends someone
to a tool that cannot do what they need.

Deliberately **not** tags: model names (`gpt-4`, `sonnet`, `r1`) because they
churn within months, and implementation stacks (`rust`, `nextjs`) because they
say nothing about choosing the tool. GitHub topics are a drafting aid only —
12 of the tracked repos have no topics at all, including several in the top ten.

## Handling Duplicates and Changes

**Duplicate repos:** CI rejects them. `go run . -check` fails on a case-insensitive `owner/repo` match, so a duplicate never reaches a daily run. It also rejects unknown tags, a repeated tag, an entry with no surface tag, two origin tags, and any leftover `category:` key.

**Renamed repos:** GitHub redirects the old slug, so the updater keeps working — it prints a `::warning::` naming the new slug. Update `owner`/`repo` in `data/agents.yml` to the new slug and add the old key to `canonicalKeyMigrations` in `history.go`, or the repo's star history detaches and its deltas show `—`.

**Deprecation:** To remove an agent, delete its entry from `data/agents.yml`. The next run drops it from the README; its history stays in `data/history.jsonl`, so re-adding the entry later restores its star chart.

**Staleness:** An entry with no push in **6 months** is dropped. Past **3 months** the updater prints a `::warning::` naming the repo and its days idle, so the daily run surfaces candidates without anyone auditing the list by hand. Removal stays a human decision: a repo can go quiet between releases, and a historically significant one (`gpt-engineer`) is kept with a `notes` marker instead.
A repo the maintainers have **archived or declared deprecated** is different: it will never
be pushed again, so it is removed without waiting out the 6 months unless it earns the same
historical-significance exception.

## PR Review

- Keep PRs to changes in `data/agents.yml` only (do not edit `README.md` or `data/history.jsonl`)
- The daily GitHub Actions workflow (runs at 00:00 UTC) picks up merged PRs automatically
- No manual review required; the updater regenerates the README after your PR merges

For local testing before opening a PR, see [LOCAL_DEV.md](./LOCAL_DEV.md). A tag
or note change needs only `make build` — no GitHub token. `make test` runs
everything CI will.