From 91287042b8dc89e7708e9c66b1b1b8d62f2b4896 Mon Sep 17 00:00:00 2001 From: John Smith Date: Sat, 17 Oct 2026 13:00:33 -0400 Subject: [PATCH] docs: catalog policy, contributing guide, schema reference and review-loop rules 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 --- .opencode/commands/review.md | 2 +- README.ru-RU.md | 12 +-- README.zh-CN.md | 12 +-- contributing.md | 95 +++++++++-------- docs/policy.md | 63 ++++++++++++ docs/schema-design.md | 153 ++++++++++++---------------- prompts/opencode-review-loop.md | 22 +++- prompts/opencode-standalone-loop.md | 22 +++- 8 files changed, 232 insertions(+), 149 deletions(-) create mode 100644 docs/policy.md diff --git a/.opencode/commands/review.md b/.opencode/commands/review.md index 64dbac1..cdf677b 100644 --- a/.opencode/commands/review.md +++ b/.opencode/commands/review.md @@ -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)? diff --git a/README.ru-RU.md b/README.ru-RU.md index 8cd5182..8123cd6 100644 --- a/README.ru-RU.md +++ b/README.ru-RU.md @@ -65,7 +65,7 @@ > Полный список см. в [English README](README.md#plugins).
-➕ Добавить плагин через PR +➕ Добавить плагин через PR
@@ -80,7 +80,7 @@ > Полный список см. в [English README](README.md#themes).
-➕ Добавить тему через PR +➕ Добавить тему через PR
@@ -95,7 +95,7 @@ > Полный список см. в [English README](README.md#agents).
-➕ Добавить агента через PR +➕ Добавить агента через PR
@@ -110,7 +110,7 @@ > Полный список см. в [English README](README.md#projects).
-➕ Добавить проект через PR +➕ Добавить проект через PR
@@ -125,7 +125,7 @@ > Полный список см. в [English README](README.md#resources).
-➕ Добавить ресурс через PR +➕ Добавить ресурс через PR

@@ -133,7 +133,7 @@

🤝 Участие

Нашли отличный проект для Opencode?
-Отправьте Pull Request, чтобы добавить его в список! +Отправьте Pull Request, чтобы добавить его в список!

Выпущено под лицензией CC0 1.0 Universal.
diff --git a/README.zh-CN.md b/README.zh-CN.md index 2204004..343b1c2 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -65,7 +65,7 @@ > 完整列表请查看 [English README](README.md#plugins)。
-➕ 通过 PR 添加插件 +➕ 通过 PR 添加插件
@@ -80,7 +80,7 @@ > 完整列表请查看 [English README](README.md#themes)。
-➕ 通过 PR 添加主题 +➕ 通过 PR 添加主题
@@ -95,7 +95,7 @@ > 完整列表请查看 [English README](README.md#agents)。
-➕ 通过 PR 添加智能体 +➕ 通过 PR 添加智能体
@@ -110,7 +110,7 @@ > 完整列表请查看 [English README](README.md#projects)。
-➕ 通过 PR 添加项目 +➕ 通过 PR 添加项目
@@ -125,7 +125,7 @@ > 完整列表请查看 [English README](README.md#resources)。
-➕ 通过 PR 添加资源 +➕ 通过 PR 添加资源

@@ -133,7 +133,7 @@

🤝 贡献

发现了优秀的 Opencode 相关项目？
-提交 Pull Request 将其添加到列表中！ +提交 Pull Request 将其添加到列表中！

基于 CC0 1.0 Universal 发布。
diff --git a/contributing.md b/contributing.md index 232146d..dcacefd 100644 --- a/contributing.md +++ b/contributing.md @@ -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//.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.** diff --git a/docs/policy.md b/docs/policy.md new file mode 100644 index 0000000..db24823 --- /dev/null +++ b/docs/policy.md @@ -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/plugin@0.0.0-beta-*`, `@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 | diff --git a/docs/schema-design.md b/docs/schema-design.md index 4ff3e81..6a06320 100644 --- a/docs/schema-design.md +++ b/docs/schema-design.md @@ -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 --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* diff --git a/prompts/opencode-review-loop.md b/prompts/opencode-review-loop.md index 23f2e35..66836f2 100644 --- a/prompts/opencode-review-loop.md +++ b/prompts/opencode-review-loop.md @@ -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 --json labels,statusCheckRollup`. +2. **V2 detection authority is `scripts/utils/compat.js`.** Run `node -e "require('./scripts/utils/compat').probeCompat([{key:'x',repo:'',npm:'',plugin:true}]).then(r=>console.log(r.get('x')))"` instead of reading package.json by hand. Pre-release V2 pins (`@opencode-ai/plugin@0.0.0-beta-*`, `@next`, `@opencode-ai/client`) are V2; `@opencode-ai/plugin@1.x` 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 `. +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 --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. diff --git a/prompts/opencode-standalone-loop.md b/prompts/opencode-standalone-loop.md index b3c7269..2f71763 100644 --- a/prompts/opencode-standalone-loop.md +++ b/prompts/opencode-standalone-loop.md @@ -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 --json labels,statusCheckRollup`. +2. **V2 detection authority is `scripts/utils/compat.js`.** Run `node -e "require('./scripts/utils/compat').probeCompat([{key:'x',repo:'',npm:'',plugin:true}]).then(r=>console.log(r.get('x')))"` instead of reading package.json by hand. Pre-release V2 pins (`@opencode-ai/plugin@0.0.0-beta-*`, `@next`, `@opencode-ai/client`) are V2; `@opencode-ai/plugin@1.x` 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 `. +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 --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.