Heretek-AI/awesome-opencode
1
0 Fork 0
mirror of https://github.com/Heretek-AI/awesome-opencode.git synced 2026-11-07 02:35:58 -10:00
Code Issues Packages Projects Releases Wiki Activity

docs: catalog policy, contributing guide, schema reference and review-loop rules

Browse Source 
docs/policy.md is the reference the bots link to (admission, V2 rule, V1 sunset, health and removal, discovery, automation map). contributing.md documents the issue form, scaffolder and fields. The review-loop prompts now defer schema/duplicate/V2 checks to CI, drop the 6-month activity rule, and require merging through PRs instead of pushing to main. Translated READMEs link to this repo's contributing guide.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
John SmithandClaude Opus 5.5 committed 2026-10-17 13:00:33 -04:00
1 parent 72f26afbec
commit 91287042b8
8 files changed
+232 -149
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.opencode/commands/review.md
+1 -1
View File
@@ -5,7 +5,7 @@ description: Review an open PR or issue for quality and OpenCode v2 compatibilit
You are the maintainer review agent for `Heretek-AI/awesome-opencode`.
Your task is to review the specified PR or issue (or the next item in the backlog queue) against the OpenCode V2 compatibility and quality standards.
Follow the guidelines defined in `prompts/opencode-review-loop.md`:
Follow the guidelines defined in `prompts/opencode-review-loop.md`, including its "Deterministic Pre-Checks" and "Merging Rules" sections (labels and the `validate` check already cover schema, duplicates and V2 markers; merge only with `gh pr merge`, never by pushing to main):
1. Check if the target repo is public, maintained, and safe (no crypto/spam).
2. Check OpenCode V2 compatibility:
- For plugins: does it use `@opencode/plugin` and `Plugin.define` (V2), or legacy `@opencode-ai/plugin` (V1)?
README.ru-RU.md
+6 -6
View File
@@ -65,7 +65,7 @@
> Полный список см. в [English README](README.md#plugins).
<br>
<a href="https://github.com/awesome-opencode/awesome-opencode/blob/main/contributing.md"><b>➕ Добавить плагин через PR</b></a>
<a href="https://github.com/Heretek-AI/awesome-opencode/blob/main/contributing.md"><b>➕ Добавить плагин через PR</b></a>
</details>
<br>
@@ -80,7 +80,7 @@
> Полный список см. в [English README](README.md#themes).
<br>
<a href="https://github.com/awesome-opencode/awesome-opencode/blob/main/contributing.md"><b>➕ Добавить тему через PR</b></a>
<a href="https://github.com/Heretek-AI/awesome-opencode/blob/main/contributing.md"><b>➕ Добавить тему через PR</b></a>
</details>
<br>
@@ -95,7 +95,7 @@
> Полный список см. в [English README](README.md#agents).
<br>
<a href="https://github.com/awesome-opencode/awesome-opencode/blob/main/contributing.md"><b>➕ Добавить агента через PR</b></a>
<a href="https://github.com/Heretek-AI/awesome-opencode/blob/main/contributing.md"><b>➕ Добавить агента через PR</b></a>
</details>
<br>
@@ -110,7 +110,7 @@
> Полный список см. в [English README](README.md#projects).
<br>
<a href="https://github.com/awesome-opencode/awesome-opencode/blob/main/contributing.md"><b>➕ Добавить проект через PR</b></a>
<a href="https://github.com/Heretek-AI/awesome-opencode/blob/main/contributing.md"><b>➕ Добавить проект через PR</b></a>
</details>
<br>
@@ -125,7 +125,7 @@
> Полный список см. в [English README](README.md#resources).
<br>
<a href="https://github.com/awesome-opencode/awesome-opencode/blob/main/contributing.md"><b>➕ Добавить ресурс через PR</b></a>
<a href="https://github.com/Heretek-AI/awesome-opencode/blob/main/contributing.md"><b>➕ Добавить ресурс через PR</b></a>
</details>
<br><br>
@@ -133,7 +133,7 @@
<div align="center">
<h3>🤝 Участие</h3>
Нашли отличный проект для Opencode? <br>
<a href="https://github.com/awesome-opencode/awesome-opencode/blob/main/contributing.md"><b>Отправьте Pull Request</b></a>, чтобы добавить его в список!
<a href="https://github.com/Heretek-AI/awesome-opencode/blob/main/contributing.md"><b>Отправьте Pull Request</b></a>, чтобы добавить его в список!
<br><br>
<sub>Выпущено под лицензией <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0 1.0 Universal</a>.</sub>
</div>
README.zh-CN.md
+6 -6
View File
@@ -65,7 +65,7 @@
> 完整列表请查看 [English README](README.md#plugins)。
<br>
<a href="https://github.com/awesome-opencode/awesome-opencode/blob/main/contributing.md"><b>➕ 通过 PR 添加插件</b></a>
<a href="https://github.com/Heretek-AI/awesome-opencode/blob/main/contributing.md"><b>➕ 通过 PR 添加插件</b></a>
</details>
<br>
@@ -80,7 +80,7 @@
> 完整列表请查看 [English README](README.md#themes)。
<br>
<a href="https://github.com/awesome-opencode/awesome-opencode/blob/main/contributing.md"><b>➕ 通过 PR 添加主题</b></a>
<a href="https://github.com/Heretek-AI/awesome-opencode/blob/main/contributing.md"><b>➕ 通过 PR 添加主题</b></a>
</details>
<br>
@@ -95,7 +95,7 @@
> 完整列表请查看 [English README](README.md#agents)。
<br>
<a href="https://github.com/awesome-opencode/awesome-opencode/blob/main/contributing.md"><b>➕ 通过 PR 添加智能体</b></a>
<a href="https://github.com/Heretek-AI/awesome-opencode/blob/main/contributing.md"><b>➕ 通过 PR 添加智能体</b></a>
</details>
<br>
@@ -110,7 +110,7 @@
> 完整列表请查看 [English README](README.md#projects)。
<br>
<a href="https://github.com/awesome-opencode/awesome-opencode/blob/main/contributing.md"><b>➕ 通过 PR 添加项目</b></a>
<a href="https://github.com/Heretek-AI/awesome-opencode/blob/main/contributing.md"><b>➕ 通过 PR 添加项目</b></a>
</details>
<br>
@@ -125,7 +125,7 @@
> 完整列表请查看 [English README](README.md#resources)。
<br>
<a href="https://github.com/awesome-opencode/awesome-opencode/blob/main/contributing.md"><b>➕ 通过 PR 添加资源</b></a>
<a href="https://github.com/Heretek-AI/awesome-opencode/blob/main/contributing.md"><b>➕ 通过 PR 添加资源</b></a>
</details>
<br><br>
@@ -133,7 +133,7 @@
<div align="center">
<h3>🤝 贡献</h3>
发现了优秀的 Opencode 相关项目？<br>
<a href="https://github.com/awesome-opencode/awesome-opencode/blob/main/contributing.md"><b>提交 Pull Request</b></a> 将其添加到列表中！
<a href="https://github.com/Heretek-AI/awesome-opencode/blob/main/contributing.md"><b>提交 Pull Request</b></a> 将其添加到列表中！
<br><br>
<sub>基于 <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0 1.0 Universal</a> 发布。</sub>
</div>
contributing.md
+53 -42
View File
@@ -1,60 +1,71 @@
# Contribution Guidelines
Thank you for contributing to `awesome-opencode`! Add your entries via YAML files—no need to edit README.md directly.
Thank you for contributing to `awesome-opencode`! Every entry is a YAML file under `data/`; the README and the [search site](https://heretek-ai.github.io/awesome-opencode/) are generated from those files. **Never edit `README.md` directly**: PRs that do are rejected by the `validate` check.
## How to Add an Entry
## Option 1: the issue form (recommended)
### Step 1: Fork & Clone
[Open an "Add an entry" issue](https://github.com/Heretek-AI/awesome-opencode/issues/new?template=add-entry.yml). A bot validates the fields, checks OpenCode V2 compatibility for plugins, comments with the result, and opens the pull request for you. To fix something, edit the issue; the PR updates itself.
```bash
git clone https://github.com/YOUR-USERNAME/awesome-opencode.git
cd awesome-opencode
```
## Option 2: a pull request
### Step 2: Create YAML File
1. Fork and clone the repo, then run `npm ci`.
2. Create the entry. The scaffolder writes a correctly formatted file and runs the V2 check:
Create a YAML file in the appropriate category folder under `data/`:
- `data/plugins/` - OpenCode plugins and extensions
- `data/themes/` - Color schemes and visual themes
- `data/agents/` - AI agents and subagents
- `data/projects/` - Tools, GUIs, integrations, and utilities
- `data/resources/` - Guides, templates, and configurations
```bash
npm run new -- --category plugins --repo https://github.com/owner/repo \
--tagline "Short summary" --topics memory,context [--npm package-name] [--path packages/x]
```
**Filename:** kebab-case (e.g., `my-plugin.yaml`)
Or write `data/<category>/<name>.yaml` by hand (kebab-case filename):
### Step 3: Add YAML Content
```yaml
name: Quota Board
repo: https://github.com/owner/opencode-quota-board
npm: opencode-quota-board
tagline: Provider quotas and reset countdowns in the OpenCode sidebar
description: Adds quota bars, reset countdowns and credit balances to the OpenCode V2 TUI.
kind: plugin
topics:
- cost
- providers
compat: v2
```
```yaml
name: Your Plugin Name
repo: https://github.com/owner/repo-name
tagline: Short punchy summary (max 120 chars, shown in collapsed view)
description: Longer description explaining what it does and why it's useful.
```
3. Run `npm run validate`, then open the PR. CI runs the same checks and comments with anything to fix.
### Step 4: Submit PR
## Fields
```bash
git checkout -b add-my-plugin
git add data/plugins/my-plugin.yaml
git commit -m "docs: add my-plugin to plugins"
git push origin add-my-plugin
```
| Field | Required | Notes |
| :--- | :--- | :--- |
| `name` | yes | Max 80 characters |
| `repo` | yes | Repository **root** URL (GitHub, GitLab, Codeberg, Gitee; gists allowed). No `/tree/`, `/blob/`, npm pages or websites |
| `path` | no | Folder inside a monorepo, e.g. `packages/my-plugin` |
| `npm` | no | Package name; strongly recommended for plugins (used for the V2 check and health checks) |
| `tagline` | yes | Max 120 characters. Quote it if it contains `: ` (e.g. `tagline: "Plain: no jargon"`) |
| `description` | yes | Max 1500 characters |
| `kind` | yes | `plugin`, `theme`, `agent`, `skill`, `mcp-server`, `client`, `tool`, `config`, `guide` or `fork` |
| `topics` | yes | 1–3 of: memory, context, orchestration, workflow, providers, cost, notifications, sessions, code-quality, security, git, remote, web, ui, voice, media, docs, environment, observability, integrations, code-intel, prompting, domain. The first is used for README grouping |
| `compat` | plugins | `v2`, `v1` or `unknown`; CI verifies it. Other categories may omit it |
| `also` | no | Secondary kinds, e.g. `[mcp-server]` for a plugin that also ships an MCP server |
| `scope`, `tags`, `min_version`, `homepage`, `installation` | no | See [docs/schema-design.md](docs/schema-design.md) |
Open a Pull Request on GitHub.
Unknown fields are rejected, so typos like `repository:` or `install:` are caught.
## Entry Requirements
Which category? `plugins` for OpenCode plugin packages, `themes` for color themes, `agents` for agent configs and skill packs, `projects` for clients, GUIs, MCP servers, tools and forks, `resources` for guides, configs and starters.
- [ ] **Relevant** - Directly related to OpenCode
- [ ] **Public** - Repository is publicly accessible
- [ ] **Maintained** - Active commits within the last 6 months
- [ ] **Unique** - Not a duplicate of existing entry
- [ ] **Complete** - All required fields included
## What gets accepted
## What Happens After PR?
See the [catalog policy](docs/policy.md). In short:
1. **Validation runs** - Automated checks verify YAML format
2. **Maintainer review** - Content and relevance verified
3. **Merge** - Once approved
4. **README auto-generates** - List updates automatically
- **Relevant**: works with OpenCode.
- **Public**: the repository is public and not archived.
- **V2 for new plugins**: depends on `@opencode/plugin` and uses `Plugin.define`. V1 plugin PRs are held with the `needs-v2` label; a nightly job re-checks them and unblocks the PR automatically once the plugin migrates.
- **Unique**: one entry per repository (per `path` for monorepos).
- **No crypto**: no cryptocurrency, token or trading projects.
No need to edit README.md—it regenerates from YAML files.
## What happens after you submit
1. **`validate` check**: schema, duplicates, generated-file edits and the V2 check. Required to merge.
2. **Triage**: a bot labels the PR (`ready`, `needs-v2`, `needs-metadata` or `needs-human`) and comments with the results.
3. **Maintainer review and merge.**
4. **README, registry and search site regenerate automatically.**
docs/policy.md
+63
View File
@@ -0,0 +1,63 @@
# Catalog Policy
How entries get into the catalog, how they are kept honest, and when they leave. Automation enforces most of this; this page is the reference it links to.
## Admission
An entry must:
- work with OpenCode;
- point at a public, non-archived repository root (`path` for a monorepo folder);
- be the only entry for that repository and path;
- not be a cryptocurrency, token or trading project (zero tolerance);
- pass `npm run validate` (schema, field limits, kind/category fit).
### OpenCode V2 requirement for new plugins
New entries in `data/plugins/` must use the V2 plugin API: depend on an `@opencode/*` package (normally `@opencode/plugin`) and export `Plugin.define({ id, setup(ctx) })`. Pre-release V2 builds published under the old name (`@opencode-ai/[email protected]*`, `@next`, `@beta`, or `@opencode-ai/client`) also count. Packages that ship both V1 and V2 entry points count as V2.
The `validate` check detects this from, in order: the entry's `npm` package, `package.json` files in the repository (at `path`, the root and `packages/*` / `plugins/*`), then the source code. Results:
| Detected | New plugin PR | Meaning |
| :--- | :--- | :--- |
| `v2` | passes | `@opencode/*` dependency or `Plugin.define` found |
| `v1` | blocked, labeled `needs-v2` | Only `@opencode-ai/plugin`/`sdk` 1.x, or a legacy V1 plugin function without `Plugin.define` |
| `unknown` | passes with `needs-human` | Nothing conclusive found; a maintainer verifies by hand. Adding `npm` or `path` usually resolves it |
PRs labeled `needs-v2` are re-checked every night. When the target migrates, the bot relabels the PR, fills in any missing fields on same-repo branches, re-runs `validate` and tells the author. **After 60 days still on V1, the PR is closed**; reopen it or resubmit through the issue form after migrating.
Themes, agents, projects and resources are not blocked on V2. Their `compat` is informational (`v2`/`v1` when they use the SDK, otherwise `n/a`).
## Existing V1 plugins: sunset on 2027-01-01
Plugins already in the catalog that are V1-only carry a `V1 only` badge in the README and on the site. **After 2027-01-01 they are removed** by the nightly health job's removal PR unless they have migrated (the check runs again before removal). Plugins with `unknown` compatibility are listed in the health report for manual verification before that date.
## Health checks and removal
A nightly job checks every entry and maintains the **Catalog health report** issue.
| Finding | Action |
| :--- | :--- |
| Repository renamed or transferred | Bot PR updates the `repo` URL |
| Repository archived, deleted (404), or npm package deprecated | Listed in the report; **removal PR after 30 days** if it doesn't recover |
| V1-only plugin after 2027-01-01 | Removal PR |
| No push for 6–12 months / 12+ months | `quiet` / `stale` badge on the site. **Never removed for inactivity alone**: small, finished tools are fine |
Removal PRs are reviewed like any other PR; closing one keeps the entries until the next run proposes them again. Git history is the archive; there is no separate retired list.
## Discovery
A weekly scout searches npm for packages published since V2 shipped that depend on `@opencode/*`, keeps public, licensed, non-archived, non-fork repositories that are not already listed or in an open PR, and ranks them by weekly downloads, then stars. It posts a **Scout** issue; a maintainer ticking a candidate's box makes the bot open a PR for it. Add a package or repo to [`discovery/declined.txt`](../discovery/declined.txt) to stop suggesting it.
## Automation map
| Workflow | When | What |
| :--- | :--- | :--- |
| `validate-pr.yml` | every PR | Required `validate` check |
| `triage.yml` | PR opened/updated | Labels and a results comment (base-branch code only) |
| `generate-readme.yml` | push to main | README.md and dist/registry.json; fails without writing on any invalid entry |
| `site.yml` | push to main, daily | Search site on GitHub Pages |
| `health.yml` | daily | Health report issue, rename and removal PRs |
| `reprobe.yml` | daily | Re-checks `needs-v2` PRs |
| `scout.yml` | weekly | Scout issue with V2 plugin candidates |
| `issues.yml` | issue opened/edited | Issue-form submissions and scout acceptances become PRs |
docs/schema-design.md
+63 -90
View File
@@ -31,8 +31,6 @@ awesome-opencode/
│ │ └── *.yaml
│ ├── resources/
│ │ └── *.yaml # Guides, configs, MCP servers, tools, commands
│ ├── forks/
│ │ └── *.yaml
│ └── examples/
│ └── *.yaml # Exemplar files showing all fields
└── docs/
@@ -114,7 +112,7 @@ Guides, configurations, MCP servers, tools, and commands that enhance the OpenCo
### 2.6 Fork (`fork`)
Modified builds of OpenCode itself with custom features or patches. Forks maintain compatibility while adding functionality.
Modified builds of OpenCode itself with custom features or patches. Forks maintain compatibility while adding functionality. They live in `data/projects/` with `kind: fork`.
**Example Use Cases:**
- Custom builds with enterprise features
@@ -194,39 +192,44 @@ If `scope` is set to `[global, project]` and both global and project configs def
## 4. YAML Schema
The awesome-opencode registry uses a flexible schema with four required fields and several optional fields for enhanced discoverability.
`data/schema.json` defines the fields; `scripts/utils/catalog.js` adds rules that need the whole catalog (one entry per repository and `path`, `kind` must fit the category directory, `compat` required for plugins, no placeholder repo owners, no mis-encoded text). Unknown fields are rejected (`additionalProperties: false`).
### Required Fields
| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Display name for the extension (human-readable) |
| `repo` | string | Repository URL (HTTPS format, e.g., `https://github.com/user/repo`) |
| `tagline` | string | Short punchy summary, max 120 characters |
| `description` | string | Full description (can be multi-line) |
| `name` | string | Display name, max 80 characters |
| `repo` | string | Repository root URL on GitHub, GitLab, Codeberg or Gitee (gists and GitHub discussions also accepted). No `/tree/` or `/blob/` paths, npm pages or websites |
| `tagline` | string | Short summary, max 120 characters |
| `description` | string | Full description, max 1500 characters |
| `kind` | enum | `plugin`, `theme`, `agent`, `skill`, `mcp-server`, `client`, `tool`, `config`, `guide`, `fork` |
| `topics` | array | 1–3 of the fixed topic list (see `data/schema.json`); the first is the primary topic used for README grouping |
| `compat` | enum | Required for `data/plugins/` only: `v2`, `v1` or `unknown` (verified by CI). Other categories: optional, `v2`/`v1` when they use the SDK, otherwise `n/a` |
### Optional Fields
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `path` | string | - | Folder inside a monorepo, e.g. `packages/my-plugin` |
| `npm` | string | - | npm package name; used for the V2 check, health checks and the npm link |
| `also` | array | - | Secondary kinds (e.g. `[mcp-server]`), cross-listed on the site |
| `scope` | array | `[global]` | Installation scope: `[global]`, `[project]`, or `[global, project]` |
| `tags` | array | `[]` | Strings for filtering and discoverability |
| `min_version` | string | - | Minimum OpenCode version required (semver, e.g., `"1.0.0"`) |
| `tags` | array | `[]` | Free-form search keywords (not rendered; use `topics` for categorization) |
| `min_version` | string | - | Minimum OpenCode version required (semver, e.g., `"2.0.0"`) |
| `homepage` | string | - | Documentation URL if different from repository |
| `installation` | string | - | Detailed installation instructions (markdown format) |
### Type Derivation
### Kind per Category
Extension type is **not stored in YAML** - it's derived from the directory location:
The directory is the coarse bucket (and the `type` downstream consumers see); `kind` says what the entry actually is.
| Directory | Type |
|-----------|------|
| Directory | Allowed `kind` |
|-----------|----------------|
| `data/plugins/` | `plugin` |
| `data/themes/` | `theme` |
| `data/agents/` | `agent` |
| `data/projects/` | `project` |
| `data/resources/` | `resource` |
| `data/forks/` | `fork` |
| `data/agents/` | `agent`, `skill` |
| `data/projects/` | `client`, `tool`, `mcp-server`, `skill`, `agent`, `fork` |
| `data/resources/` | `guide`, `config`, `mcp-server`, `skill`, `tool` |
### Minimal Valid Entry
@@ -235,32 +238,43 @@ name: My Extension
repo: https://github.com/user/my-extension
tagline: A brief description of what this does
description: A longer explanation of the extension.
kind: plugin
topics:
- workflow
compat: v2
```
### Complete Entry (All Fields)
```yaml
name: My Extension
repo: https://github.com/user/my-extension
tagline: A brief tagline (max 120 chars)
repo: https://github.com/user/my-monorepo
path: packages/my-extension
npm: opencode-my-extension
homepage: https://example.com/docs
tagline: "A brief tagline: quote it when it contains a colon"
description: |
A longer description explaining
the extension in detail.
kind: plugin
also:
- mcp-server
topics:
- memory
- context
compat: v2
scope:
- global
- project
tags:
- productivity
- ai
min_version: "1.0.0"
homepage: https://example.com/docs
min_version: "2.0.0"
installation: |
## Installation
```bash
git clone https://github.com/user/my-extension ~/.config/opencode/plugin/my-extension
```
Add `opencode-my-extension` to the `plugin` list in `opencode.json`.
```
Use `npm run new` to scaffold an entry and `npm run fmt` to rewrite entries in canonical key order with safe quoting.
### Examples Directory
Full exemplar files for each extension type are available in `data/examples/`:
@@ -272,7 +286,7 @@ Full exemplar files for each extension type are available in `data/examples/`:
| Agent | `data/examples/agent.yaml` |
| Project | `data/examples/project.yaml` |
| Resource | `data/examples/resource.yaml` |
| Fork | `data/examples/fork.yaml` |
| Fork | `data/examples/fork.yaml` (forks now live in `data/projects/` with `kind: fork`) |
---
@@ -347,6 +361,12 @@ The awesome-opencode schema is designed for seamless conversion to downstream pl
| `homepage` | `homepageUrl` | Documentation URL |
| `installation` | `installation` | Markdown content |
| `min_version` | `minVersion` | Semver string |
| `path` | `repoPath` | Monorepo folder (added 2026-10) |
| `npm` | `npmPackage` | npm package name (added 2026-10) |
| `kind` | `kind` | What the entry is (added 2026-10) |
| `also` | `also` | Secondary kinds (added 2026-10) |
| `topics` | `topics` | Use-case topics (added 2026-10) |
| `compat` | `compat` | `v2`, `v1`, `unknown` or `n/a`; plugins default to `unknown` (added 2026-10) |
### Conversion Example
@@ -422,9 +442,11 @@ When an agent assists with installation, it can:
Future improvements to the contribution process:
1. **Schema Validation**: CI checks YAML validity and required fields
2. **Preview Tool**: Generate opencode.cafe JSON preview for PRs
3. **Link Checking**: Verify `repo` and `homepage` URLs are accessible
Implemented in 2026-10; see [policy.md](policy.md#automation-map):
1. **Schema Validation**: the required `validate` check runs on every PR
2. **V2 Compatibility Check**: plugins are probed for `@opencode/*` and `Plugin.define`
3. **Link Checking**: the nightly health job tracks renamed, archived, missing and deprecated targets
---
@@ -439,7 +461,8 @@ Future improvements to the contribution process:
| `agent` | `data/agents/` |
| `project` | `data/projects/` |
| `resource` | `data/resources/` |
| `fork` | `data/forks/` |
Forks are entries in `data/projects/` with `kind: fork`; see "Kind per Category" in section 4.
### Minimal Valid Entry
@@ -479,69 +502,19 @@ installation: |
### Commands
```bash
# Validate schema and entries
node scripts/validate.js
# Regenerate README
node scripts/generate-readme.js
npm run validate # schema and catalog rules for every entry
npm run generate # regenerate README.md
npm run new -- --category plugins --repo <url> --tagline "..." --topics memory
npm run fmt # canonical formatting for all entries
```
---
## 9. Future Work
## 9. Status
Remaining tasks for the awesome-opencode registry.
### 9.1 Update Contributing Guide
Update `contributing.md` to:
- Reference `data/examples/` directory for full field documentation
- Document optional fields (`scope`, `tags`, `min_version`, `homepage`, `installation`)
- Explain scope behavior and defaults
### 9.2 README Generation Enhancements (Optional)
Update `scripts/generate-readme.js` to optionally display:
- Tags for entries that have them
- Scope indicators
- Type badges derived from directory
### 9.3 Export Script for Downstream Platforms
Create `scripts/export-json.js` to generate JSON for platforms like opencode.cafe:
```javascript
// Pseudocode
for each file in data/{category}/*.yaml:
entry = parseYAML(file)
entry.type = category // derived from directory
entry.productId = filename // derived from filename
output.push(mapFields(entry))
writeJSON(output)
```
**Field mapping:**
| YAML | JSON Output |
|------|-------------|
| `name` | `displayName` |
| `repo` | `repoUrl` |
| `tagline` | `tagline` |
| `description` | `description` |
| (directory) | `type` |
| (filename) | `productId` |
| `scope` | `scope` (default `["global"]`) |
| `tags` | `tags` (default `[]`) |
| `homepage` | `homepageUrl` |
| `installation` | `installation` |
| `min_version` | `minVersion` |
**Usage:**
```bash
node scripts/export-json.js > dist/registry.json
node scripts/export-json.js --pretty > dist/registry.json
```
The contributing guide, README enhancements (topic/kind grouping, V1/V2 badges, counts, recently added) and the JSON export described in earlier versions of this document are implemented. Catalog rules are in [policy.md](policy.md).
---
*Document Version: 1.2*
*Last Updated: 2026-01-12*
*Document Version: 2.0*
*Last Updated: 2026-10-17*
prompts/opencode-review-loop.md
+20 -2
View File
@@ -44,7 +44,7 @@ Even if code is technically compatible, it must meet the quality standards of `a
1. **Relevance**: Directly enhances or integrates with the OpenCode ecosystem.
2. **Maintenance & Health**:
* Repository is public, accessible, and not archived.
* Recent commit activity (ideally active within the last 6 months).
* Not archived, deleted or deprecated (inactivity alone is fine; see docs/policy.md).
* Not abandoned or broken.
3. **Safety & Policy**:
* **STRICT PROHIBITION**: Zero tolerance for cryptocurrency, tokens, Web3 trading bots, or token pumps (per repository governance policy).
@@ -71,7 +71,7 @@ Assign one of the following verdicts to every reviewed item:
| **`APPROVE_AND_MERGE`** | High quality, active, fully compatible with OpenCode V2, valid YAML. | Recommend merging PR. |
| **`NEEDS_V2_UPDATE`** | Good concept and maintained, but currently implemented with legacy V1 plugin API (`@opencode-ai/plugin`). | Request update from author to migrate to `@opencode/plugin` / `Plugin.define`. |
| **`NEEDS_METADATA_FIX`** | Good project, but YAML has schema errors (e.g. tagline > 120 chars, invalid category, missing fields). | Request author adjust YAML. |
| **`REJECT_ABANDONED`** | Repository deleted, 404, archived, or no commits in > 1 year. | Recommend closing. |
| **`REJECT_ABANDONED`** | Repository deleted (404), archived, or npm package deprecated. | Recommend closing. |
| **`REJECT_POLICY`** | Crypto, spam, duplicate, or unrelated to OpenCode. | Recommend closing with reason. |
| **`ISSUE_CONVERT_TO_PR`** | (For Issues) Listing suggestion is high quality and V2 compatible. | Recommend creating catalog entry YAML. |
| **`ISSUE_CLOSE`** | (For Issues) Bug report meant for upstream core, invalid, or already resolved. | Recommend closing with guidance. |
@@ -114,3 +114,21 @@ When executing the loop:
3. **Validate Schema**: Check the YAML formatting against `data/schema.json`.
4. **Render JSON Verdict**: Output the structured assessment JSON.
5. **Report & Proceed**: Provide a clear, human-readable executive summary followed by the next queued item.
---
## Deterministic Pre-Checks (run these first; do not re-derive them)
The repository now automates everything mechanical. Your job is the judgment calls only.
1. **Do not hand-check schema, URLs, duplicates or V2 markers.** The required `validate` check (`scripts/check-pr.js`) and the triage bot already do, and the PR carries labels: `ready`, `needs-v2`, `needs-metadata`, `needs-human`. Read them with `gh pr view <n> --json labels,statusCheckRollup`.
2. **V2 detection authority is `scripts/utils/compat.js`.** Run `node -e "require('./scripts/utils/compat').probeCompat([{key:'x',repo:'<url>',npm:'<pkg>',plugin:true}]).then(r=>console.log(r.get('x')))"` instead of reading package.json by hand. Pre-release V2 pins (`@opencode-ai/[email protected]*`, `@next`, `@opencode-ai/client`) are V2; `@opencode-ai/[email protected]` is V1.
3. **Only review PRs whose `validate` check is green** (or labeled `needs-human`, where you resolve the open question). A PR with no `validate` run can get one with `gh workflow run validate-pr.yml --ref <headRefName>`.
4. **Your verdict covers:** relevance to OpenCode, real utility (not a duplicate in spirit), safety/policy (zero tolerance for crypto/token/trading), and copy quality of `tagline`/`description`/`topics`.
5. **Inactivity is not a rejection reason.** Archived, deleted or npm-deprecated targets are; see `docs/policy.md`. The old "commits within 6 months" bar no longer applies.
## Merging Rules
- Merge with `gh pr merge <n> --squash` so the required check applies. **Never push catalog changes directly to `main`** and never "apply" a PR by committing its files separately; if a PR needs edits, push them to the PR branch.
- Before merging anything you edited, run `npm run validate && npm run generate` locally and confirm both exit 0.
- New entries must include `kind`, `topics` and (for plugins) `compat`; `npm run fmt` fixes formatting.
prompts/opencode-standalone-loop.md
+20 -2
View File
@@ -32,7 +32,7 @@ OpenCode V2 completely replaced the legacy V1 plugin system with a domain-driven
1. **Relevance**: Directly enhances or integrates with the OpenCode ecosystem.
2. **Active Maintenance**:
* Repository is public, accessible, and not archived.
* Has commits within the last 6 months (not abandoned).
* Not archived, deleted or deprecated (inactivity alone is fine; see docs/policy.md).
3. **Safety & Policy**:
* **STRICT PROHIBITION**: Zero tolerance for cryptocurrency, tokens, or Web3 trading pumps.
* No malicious scripts or credential stealers.
@@ -48,7 +48,7 @@ OpenCode V2 completely replaced the legacy V1 plugin system with a domain-driven
- **`APPROVE_AND_MERGE`**: High quality, active, fully OpenCode V2 compatible, schema valid.
- **`NEEDS_V2_UPDATE`**: High quality concept, but built on legacy V1 plugin APIs (`@opencode-ai/plugin`). Needs migration to `@opencode/plugin` / `Plugin.define`.
- **`NEEDS_METADATA_FIX`**: Good project, but YAML has schema errors (e.g. tagline too long, wrong folder).
- **`REJECT_ABANDONED`**: Target repo deleted, 404, archived, or no commits in > 1 year.
- **`REJECT_ABANDONED`**: Target repo deleted (404), archived, or npm package deprecated.
- **`REJECT_POLICY`**: Crypto, token pump, duplicate, or unrelated to OpenCode.
- **`ISSUE_CONVERT_TO_PR`**: (For Issues) Submission request is high quality and V2 compatible; needs a catalog YAML created.
- **`ISSUE_CLOSE`**: (For Issues) Off-topic, upstream core bug report, answered, or invalid.
@@ -72,3 +72,21 @@ OpenCode V2 completely replaced the legacy V1 plugin system with a domain-driven
- Record the structured assessment in `reviews/review_results.json`.
4. **Continue the Loop**:
Process through the queue in batches, maintaining clean logs in `reviews/summary.md`.
---
## Deterministic Pre-Checks (run these first; do not re-derive them)
The repository now automates everything mechanical. Your job is the judgment calls only.
1. **Do not hand-check schema, URLs, duplicates or V2 markers.** The required `validate` check (`scripts/check-pr.js`) and the triage bot already do, and the PR carries labels: `ready`, `needs-v2`, `needs-metadata`, `needs-human`. Read them with `gh pr view <n> --json labels,statusCheckRollup`.
2. **V2 detection authority is `scripts/utils/compat.js`.** Run `node -e "require('./scripts/utils/compat').probeCompat([{key:'x',repo:'<url>',npm:'<pkg>',plugin:true}]).then(r=>console.log(r.get('x')))"` instead of reading package.json by hand. Pre-release V2 pins (`@opencode-ai/[email protected]*`, `@next`, `@opencode-ai/client`) are V2; `@opencode-ai/[email protected]` is V1.
3. **Only review PRs whose `validate` check is green** (or labeled `needs-human`, where you resolve the open question). A PR with no `validate` run can get one with `gh workflow run validate-pr.yml --ref <headRefName>`.
4. **Your verdict covers:** relevance to OpenCode, real utility (not a duplicate in spirit), safety/policy (zero tolerance for crypto/token/trading), and copy quality of `tagline`/`description`/`topics`.
5. **Inactivity is not a rejection reason.** Archived, deleted or npm-deprecated targets are; see `docs/policy.md`. The old "commits within 6 months" bar no longer applies.
## Merging Rules
- Merge with `gh pr merge <n> --squash` so the required check applies. **Never push catalog changes directly to `main`** and never "apply" a PR by committing its files separately; if a PR needs edits, push them to the PR branch.
- Before merging anything you edited, run `npm run validate && npm run generate` locally and confirm both exit 0.
- New entries must include `kind`, `topics` and (for plugins) `compat`; `npm run fmt` fixes formatting.