ci: add plugin bundle validation and update contribution guidelines

- Add validate-plugin-pr.py script that checks new/modified plugins for:
  - Valid plugin.json with required fields (name, version, description, repository, license)
  - composerIcon in interface section pointing to existing file
  - Icon file format/size validation (SVG preferred, max 50KB)
  - README entry exists for the plugin
  - Semver version format, slug-safe plugin name
- Add validate-plugin-pr.yml workflow triggered on plugin path changes
- Update CONTRIBUTING.md with full plugin bundle spec and icon requirements
- Update plugin-submission.yml issue template to require icon path

Author: internet-dot

.github/ISSUE_TEMPLATE/plugin-submission.yml

@@ -27,6 +27,14 @@ body:
       placeholder: "Briefly describe the plugin's functionality..."
     validations:
       required: true
+  - type: input
+    id: icon
+    attributes:
+      label: Icon File Path
+      description: Path to your plugin icon relative to the repo root (e.g. assets/icon.svg). See CONTRIBUTING.md for icon requirements.
+      placeholder: "assets/icon.svg"
+    validations:
+      required: true
   - type: input
     id: author
     attributes:
@@ -41,8 +49,8 @@ body:
       label: Category
       description: Which section should this plugin be listed under?
       options:
-        - Community Plugins
-        - Plugin Development (tools/frameworks)
+        - Development & Workflow
+        - Tools & Integrations
     validations:
       required: true
   - type: checkboxes
@@ -51,7 +59,9 @@ body:
       label: Checklist
       description: Please confirm the following
       options:
-        - label: Plugin has a valid `.codex-plugin/plugin.json` manifest
+        - label: Plugin has a valid `.codex-plugin/plugin.json` manifest with `composerIcon` set
+          required: true
+        - label: Plugin includes an icon (SVG preferred, 512x512px recommended)
           required: true
         - label: Plugin is functional and well-documented
           required: true

.github/workflows/validate-plugin-pr.yml

@@ -0,0 +1,26 @@
+name: Validate Plugin PR
+
+on:
+  pull_request:
+    paths:
+      - "plugins/**"
+      - ".agents/plugins/marketplace.json"
+      - "plugins.json"
+
+permissions:
+  contents: read
+  id-token: none
+
+jobs:
+  validate:
+    name: Validate plugin bundles
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Validate changed plugin bundles
+        run: python3 scripts/validate-plugin-pr.py --base-ref origin/${{ github.base_ref }}

CONTRIBUTING.md

@@ -6,27 +6,105 @@ Thanks for helping grow the Codex plugin ecosystem!
 
 1. **Fork** this repository
 2. **Add your entry** to the appropriate section in `README.md`
-3. **Follow the format** — use the existing table structure
-4. **Submit a PR** with a clear description
+3. **Add your plugin bundle** under `plugins/<owner>/<repo>/`
+4. **Follow the format** described below
+5. **Submit a PR** with a clear description
 
-## Requirements
+## Plugin Bundle Requirements
+
+Every plugin submission must include a bundle under `plugins/<owner>/<repo>/` with the following structure:
+
+```
+plugins/<owner>/<repo>/
+  .codex-plugin/
+    plugin.json        # Required - plugin manifest
+  assets/
+    icon.svg           # Required - plugin icon (SVG preferred, PNG acceptable)
+  ...                  # Other plugin files (skills, commands, etc.)
+```
+
+### plugin.json
+
+Must be valid JSON at `.codex-plugin/plugin.json` with at minimum:
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "What this plugin does",
+  "repository": "https://github.com/<owner>/<repo>",
+  "license": "MIT",
+  "interface": {
+    "displayName": "My Plugin",
+    "shortDescription": "Brief one-liner",
+    "composerIcon": "./assets/icon.svg"
+  }
+}
+```
+
+**Required fields:**
+- `name` - machine-readable plugin identifier
+- `version` - semver version string
+- `description` - what the plugin does
+- `repository` - GitHub repository URL
+- `license` - SPDX license identifier
+- `interface.composerIcon` - path to the icon file (relative to plugin root)
+
+### Icon
+
+- **Format:** SVG preferred. PNG also accepted.
+- **Size:** 512x512px recommended. Must read clearly at small sizes (32x32).
+- **Location:** `assets/icon.svg` (or `assets/icon.png`)
+- **Style:** Simple, distinctive. Avoid text-heavy designs.
+- **File size:** Keep under 50KB. Optimize SVGs (no embedded raster images).
+
+## README Entry Format
+
+Add your plugin as a single line in the appropriate category section:
+
+```markdown
+- [Plugin Name](https://github.com/<owner>/<repo>) - One-line description of what it does.
+```
+
+Rules:
+- One plugin per line
+- Alphabetical order within each category
+- Description must be a single sentence
+- Link must point to the GitHub repository root
+
+## Additional Requirements
 
 - Plugin must have a **public GitHub repository**
-- Must include a valid `.codex-plugin/plugin.json` manifest
-- Must be **functional** — no placeholders or stub repos
+- Must be **functional** with a valid `.codex-plugin/plugin.json` manifest
+- Must include an **icon** as described above
 - Include a **description** that explains what the plugin does
-- Link to the **author** (GitHub username or organization)
+- **One plugin per PR** (unless adding multiple related plugins)
 
 ## Categories
 
-- **Official Plugins** — Only OpenAI-curated plugins go here
-- **Community Plugins** — All third-party plugins
-- **Plugin Development** — Tools, templates, and frameworks for building plugins
-- **Guides & Articles** — Tutorials, blog posts, and documentation
+- **Development & Workflow** - Tools for coding, planning, and development workflows
+- **Tools & Integrations** - External service integrations and utilities
+
+## PR Checklist
+
+Before submitting, verify:
+
+- [ ] README.md entry is alphabetically sorted within its category
+- [ ] Plugin bundle exists under `plugins/<owner>/<repo>/`
+- [ ] `.codex-plugin/plugin.json` exists and is valid JSON
+- [ ] `composerIcon` field is set in `plugin.json` interface section
+- [ ] Icon file exists at the path referenced by `composerIcon`
+- [ ] All links in the README entry are valid
+- [ ] No placeholder or TODO values in plugin.json
+
+## CI Checks
+
+All PRs are automatically validated. The CI will check:
 
-## PR Guidelines
+1. **Alphabetical order** - README entries must be sorted within each section
+2. **Plugin manifest** - `plugin.json` must exist and contain required fields
+3. **Icon presence** - `composerIcon` must point to an existing file
+4. **Marketplace sync** - `plugins.json` and `marketplace.json` stay in sync with README
+5. **Markdown links** - All URLs in README must be reachable
 
-- One plugin per PR (unless adding multiple related plugins)
-- Keep descriptions concise (one line)
-- Alphabetize within categories
-- Test that all links work before submitting
+If CI fails, check the logs for specific errors and fix before re-pushing.