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