morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #1977] [CLOSED] feat(plugin): make the repository installable as a Claude Code and Codex plugin #4945

New issue

Closed

opened 2026-10-31 00:57:14 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 00:57:14 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/1977
Author: @GamerDubz
Created: 10/11/2026
Status: ❌ Closed

Base: main ← Head: feat/claude-code-plugin

📝 Commits (10+)

6649e8e feat(plugin): make the repository installable as a Claude Code plugin
4c945f5 feat(plugin): add a Codex plugin manifest and self-hosted marketplaces
15a5e08 fix(release): treat the plugin manifests as release-version metadata
d206a19 Merge remote-tracking branch 'origin/main' into feat/claude-code-plugin
a34e48b test(release): cover plugin manifests in the publication history check
2aea370 fix(plugin): declare the capabilities Codex plugin validation requires
d3359eb fix(plugin): give the Codex plugin server REA's 30-second startup timeout
e8e265a docs(plugin): tell plugin users how to check readiness without rea setup
2f134aa docs(plugin): run the plugin readiness check through npx
102661c fix(plugin): pin the plugin server launch to the release version

📊 Changes

15 files changed (+516 additions, -15 deletions)

View changed files

➕ .agents/plugins/marketplace.json (+20 -0)
📝 .agents/skills/reverse-engineer-anything/SKILL.md (+3 -0)
📝 .agents/skills/reverse-engineer-anything/references/connection-and-recovery.md (+28 -1)
➕ .claude-plugin/marketplace.json (+17 -0)
➕ .claude-plugin/plugin.json (+31 -0)
➕ .codex-plugin/plugin.json (+50 -0)
📝 .oxfmtrc.json (+2 -0)
📝 docs/installation.md (+59 -0)
📝 docs/releasing.md (+2 -1)
📝 release-please-config.json (+20 -0)
📝 scripts/lib/release-checkpoint.mjs (+28 -0)
📝 scripts/lib/release-notes.mjs (+46 -1)
📝 tests/boundary/filesystem/releaseCheckpoint.test.ts (+50 -1)
📝 tests/boundary/filesystem/releaseNotes.test.ts (+58 -2)
📝 tests/conformance/releaseConfiguration.test.ts (+102 -9)

📄 Description

Summary

REA cannot be listed in a Claude Code plugin directory or marketplace. Their validators look for .claude-plugin/plugin.json at the plugin root and reject the repository without it ("No plugin.json — this folder is not a plugin"). This adds that manifest, a matching Codex manifest, and marketplace files so the repository can be added as a marketplace directly. No issue is linked: I hit this while trying to submit REA to a plugin directory and went straight to the fix.

Problem and expected behavior

Use case: a Claude Code or Codex user installs REA from a plugin directory or marketplace and gets the reverse-engineer-anything skill plus the rea MCP server, kept current with releases, without running npx rea-agents setup. Today the repository fails directory validation, so that path does not exist.

Change and scope

.claude-plugin/plugin.json — new manifest at the repository root. It bundles the authored reverse-engineer-anything skill straight from .agents/skills/ and registers the existing stdio server as npx -y rea-agents@<release version> mcp.
.codex-plugin/plugin.json — the same skill and server for Codex, plus Codex interface display metadata (name, descriptions, three default prompts; no logo assets).
.claude-plugin/marketplace.json and .agents/plugins/marketplace.json — make the repository a single-plugin marketplace for Claude Code and Codex, each pointing at the repository root.
release-please-config.json — bumps both manifest version fields with each release, so installed plugins refresh the bundled skill at release time rather than on every main commit.
docs/installation.md — short "Agent plugins and marketplaces" section.

Intentionally not included: the maintainer skills (rea-changelog-update, rea-tool-design) are not exposed; no change to rea setup; the plugin does not configure providers.

Server version (updated at 102661c). Both manifests pin the launch to the release version (npx -y rea-agents@6.4.0 mcp), and Release Please rewrites $.mcpServers.rea.args[1] with $.version each release. The earlier revision used @latest; reviewers asked for the pin and the guide's exact-version rule requires it. Simulated with release-please 17.3.0's JSON updater for a 6.5.0 release: two lines change per manifest. Because that updater reserializes with JSON.stringify, both manifests are stored in that form and exempted from oxfmt.

Contract and boundary impact

Semantic owner and earliest changed stage: not applicable (distribution metadata only).
CLI and MCP/tool-catalog contract: none.
Provider, bridge, target-format, or platform compatibility: none.
Evidence, artifact, provenance, or reconstruction contract: none.
Process execution, authorization, cleanup, or containment impact: none in REA. The plugin makes Claude Code launch the same npx … mcp command the MCP Registry entry describes.
Generated metadata, package, or installation impact: adds a new installation path (Claude Code plugin). package.json#files is untouched, so the npm tarball is unchanged. The manifest points at the authored skill in .agents/skills/reverse-engineer-anything/; no build outputs are committed.

Evidence and regression coverage

Tests added or updated: tests/conformance/releaseConfiguration.test.ts now expects both plugin manifests in the Release Please extra-files and asserts each manifest version matches package.json. The previous expectation failed on this branch before the update.
Base reproduction or other evidence: executed — a plugin-directory validator run against main reported the missing .claude-plugin/plugin.json as its one blocking issue.
User-visible CLI/MCP output: not applicable.
Remaining proof gaps: no live Claude Code or Codex session loaded the plugin, so skill discovery and MCP start-up through the plugin are unverified end to end in both clients. The Claude per-skill skills path form is source-derived from other published plugins that use it. The Codex files are source-derived from openai/codex (core-plugins/src/manifest.rs, marketplace.rs, loader.rs, ext/skills/src/loader/discovery.rs): legacy manifests accept an inline mcpServers object and a skills path array, scan skill roots recursively (so a root that is itself one skill folder is found), and resolve a local marketplace source of ./ to the repository root. Codex was not installed to confirm this at runtime.

Validation performed

All on Windows 11, Node 24.21.0, at 15a5e08:

claude plugin validate . (Claude Code 2.1.283) — passed for the plugin manifest and for .claude-plugin/marketplace.json.
npm run check — passed (6 tasks; lint 0 errors; architecture guards passed).
npm run docs:check — passed.
npx vitest run tests/conformance/releaseConfiguration.test.ts — 7 passed.
npx vitest run tests/boundary/filesystem/releaseCheckpoint.test.ts — 35 passed, 4 skipped.
npm pack --dry-run — passed; 1,271 files, none of the plugin or marketplace files are in the tarball.
npm run verify:package — did not complete: after a successful build, the "repository skill" step failed with spawn npm ENOENT (the script spawns npm without a shell, which Windows cannot resolve). No Linux environment was available locally; relying on CI for this gate.

Not run: a live Claude Code or Codex session loading the plugin, and no real-provider lanes.

Update at `d3359eb`

Merged current main (d206a19): the four failing checks on the first CI run were also failing on main at the base that run used (55b6148) and were fixed upstream in 89f5e48.
npm run check and npm run docs:check — passed on the merged tree (Windows).
tests/conformance/releaseConfiguration.test.ts — 8 passed (Windows), including a new test for the Codex interface fields.
tests/boundary/filesystem/releaseNotes.test.ts — 5 passed on Linux (Node 24.18.0) at the test commit; removing either plugin manifest from the allowlist fails the publication history test. This file does not run on Windows.
tests/boundary/filesystem/qwenClientConfiguration.test.ts — 3 of 12 fail on my Windows host, identically on unmodified main; not investigated.
npm run verify:package — passed on Linux (Node 24.18.0, cloud sandbox) at 2aea370: all 18 stages completed, exit 0. npm pack --dry-run there: 1,402 files, no plugin or marketplace paths in the tarball.
d3359eb adds startup_timeout_sec: 30 to the Codex server entry with a conformance test (9 passed); npm run check passed. verify:package was not rerun on this last commit.
Still not run: a live Codex session, and Codex's validate_plugin.py (read, not executed). The Codex skills path and the marketplace source binding are open in review.

Compatibility, safety, and release

Breaking changes or migration steps: none.
Real Hopper/Ghidra, browser, or OS coverage: none run; nothing provider-related changed.
Package or release metadata impact: Release Please gains two extra-files ($.version in .claude-plugin/plugin.json and .codex-plugin/plugin.json).
Security, privacy, process, or containment review: both manifests run a version-pinned rea-agents through npx. A user who has both the plugin and a rea setup registration would get two rea servers; the doc section says to use one.

Review checklist

This PR addresses a concrete problem or an agreed enhancement.
The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths. (Release configuration and manifest version alignment; plugin loading in a live client is not covered — see proof gaps.)
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output. (Not applicable: no CLI or MCP output changes.)
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🤖 Generated with Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/1977 **Author:** [@GamerDubz](https://github.com/GamerDubz) **Created:** 10/11/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `feat/claude-code-plugin` --- ### 📝 Commits (10+) - [`6649e8e`](https://github.com/morluto/rea/commit/6649e8e7ba247d8366d6be5af0288134cb92de63) feat(plugin): make the repository installable as a Claude Code plugin - [`4c945f5`](https://github.com/morluto/rea/commit/4c945f570d0b1d90cb8429f956fec6c83a2aafde) feat(plugin): add a Codex plugin manifest and self-hosted marketplaces - [`15a5e08`](https://github.com/morluto/rea/commit/15a5e08338e96b11f9c1eaab4def96b076f2cb4b) fix(release): treat the plugin manifests as release-version metadata - [`d206a19`](https://github.com/morluto/rea/commit/d206a19c7db0e203b71e2d0af7a83dcd26f1f8a4) Merge remote-tracking branch 'origin/main' into feat/claude-code-plugin - [`a34e48b`](https://github.com/morluto/rea/commit/a34e48b35b7f8949f0147328e904cd41981d4886) test(release): cover plugin manifests in the publication history check - [`2aea370`](https://github.com/morluto/rea/commit/2aea370e1ca61f79f2117e92a0bc626e619032b5) fix(plugin): declare the capabilities Codex plugin validation requires - [`d3359eb`](https://github.com/morluto/rea/commit/d3359ebef010e030a4dd1d1d32cb8a7a11aa707c) fix(plugin): give the Codex plugin server REA's 30-second startup timeout - [`e8e265a`](https://github.com/morluto/rea/commit/e8e265a0bc0b7232c49a91ad53bc38260da1ad3b) docs(plugin): tell plugin users how to check readiness without rea setup - [`2f134aa`](https://github.com/morluto/rea/commit/2f134aaa7e729fa1d7d4f86e925c4be95464b799) docs(plugin): run the plugin readiness check through npx - [`102661c`](https://github.com/morluto/rea/commit/102661ca6fd17b270ffa25e2397eb80c01b08044) fix(plugin): pin the plugin server launch to the release version ### 📊 Changes **15 files changed** (+516 additions, -15 deletions) <details> <summary>View changed files</summary> ➕ `.agents/plugins/marketplace.json` (+20 -0) 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+3 -0) 📝 `.agents/skills/reverse-engineer-anything/references/connection-and-recovery.md` (+28 -1) ➕ `.claude-plugin/marketplace.json` (+17 -0) ➕ `.claude-plugin/plugin.json` (+31 -0) ➕ `.codex-plugin/plugin.json` (+50 -0) 📝 `.oxfmtrc.json` (+2 -0) 📝 `docs/installation.md` (+59 -0) 📝 `docs/releasing.md` (+2 -1) 📝 `release-please-config.json` (+20 -0) 📝 `scripts/lib/release-checkpoint.mjs` (+28 -0) 📝 `scripts/lib/release-notes.mjs` (+46 -1) 📝 `tests/boundary/filesystem/releaseCheckpoint.test.ts` (+50 -1) 📝 `tests/boundary/filesystem/releaseNotes.test.ts` (+58 -2) 📝 `tests/conformance/releaseConfiguration.test.ts` (+102 -9) </details> ### 📄 Description ## Summary REA cannot be listed in a Claude Code plugin directory or marketplace. Their validators look for `.claude-plugin/plugin.json` at the plugin root and reject the repository without it ("No plugin.json — this folder is not a plugin"). This adds that manifest, a matching Codex manifest, and marketplace files so the repository can be added as a marketplace directly. No issue is linked: I hit this while trying to submit REA to a plugin directory and went straight to the fix. ## Problem and expected behavior Use case: a Claude Code or Codex user installs REA from a plugin directory or marketplace and gets the `reverse-engineer-anything` skill plus the `rea` MCP server, kept current with releases, without running `npx rea-agents setup`. Today the repository fails directory validation, so that path does not exist. ## Change and scope - `.claude-plugin/plugin.json` — new manifest at the repository root. It bundles the authored `reverse-engineer-anything` skill straight from `.agents/skills/` and registers the existing stdio server as `npx -y rea-agents@<release version> mcp`. - `.codex-plugin/plugin.json` — the same skill and server for Codex, plus Codex `interface` display metadata (name, descriptions, three default prompts; no logo assets). - `.claude-plugin/marketplace.json` and `.agents/plugins/marketplace.json` — make the repository a single-plugin marketplace for Claude Code and Codex, each pointing at the repository root. - `release-please-config.json` — bumps both manifest `version` fields with each release, so installed plugins refresh the bundled skill at release time rather than on every `main` commit. - `docs/installation.md` — short "Agent plugins and marketplaces" section. Intentionally not included: the maintainer skills (`rea-changelog-update`, `rea-tool-design`) are not exposed; no change to `rea setup`; the plugin does not configure providers. **Server version (updated at `102661c`).** Both manifests pin the launch to the release version (`npx -y rea-agents@6.4.0 mcp`), and Release Please rewrites `$.mcpServers.rea.args[1]` with `$.version` each release. The earlier revision used `@latest`; reviewers asked for the pin and the guide's exact-version rule requires it. Simulated with release-please 17.3.0's JSON updater for a 6.5.0 release: two lines change per manifest. Because that updater reserializes with `JSON.stringify`, both manifests are stored in that form and exempted from `oxfmt`. ## Contract and boundary impact - Semantic owner and earliest changed stage: not applicable (distribution metadata only). - CLI and MCP/tool-catalog contract: none. - Provider, bridge, target-format, or platform compatibility: none. - Evidence, artifact, provenance, or reconstruction contract: none. - Process execution, authorization, cleanup, or containment impact: none in REA. The plugin makes Claude Code launch the same `npx … mcp` command the MCP Registry entry describes. - Generated metadata, package, or installation impact: adds a new installation path (Claude Code plugin). `package.json#files` is untouched, so the npm tarball is unchanged. The manifest points at the authored skill in `.agents/skills/reverse-engineer-anything/`; no build outputs are committed. ## Evidence and regression coverage - Tests added or updated: `tests/conformance/releaseConfiguration.test.ts` now expects both plugin manifests in the Release Please `extra-files` and asserts each manifest `version` matches `package.json`. The previous expectation failed on this branch before the update. - Base reproduction or other evidence: executed — a plugin-directory validator run against `main` reported the missing `.claude-plugin/plugin.json` as its one blocking issue. - User-visible CLI/MCP output: not applicable. - Remaining proof gaps: no live Claude Code or Codex session loaded the plugin, so skill discovery and MCP start-up through the plugin are unverified end to end in both clients. The Claude per-skill `skills` path form is source-derived from other published plugins that use it. The Codex files are source-derived from `openai/codex` (`core-plugins/src/manifest.rs`, `marketplace.rs`, `loader.rs`, `ext/skills/src/loader/discovery.rs`): legacy manifests accept an inline `mcpServers` object and a `skills` path array, scan skill roots recursively (so a root that is itself one skill folder is found), and resolve a local marketplace source of `./` to the repository root. Codex was not installed to confirm this at runtime. ## Validation performed All on Windows 11, Node 24.21.0, at `15a5e08`: - `claude plugin validate .` (Claude Code 2.1.283) — passed for the plugin manifest and for `.claude-plugin/marketplace.json`. - `npm run check` — passed (6 tasks; lint 0 errors; architecture guards passed). - `npm run docs:check` — passed. - `npx vitest run tests/conformance/releaseConfiguration.test.ts` — 7 passed. - `npx vitest run tests/boundary/filesystem/releaseCheckpoint.test.ts` — 35 passed, 4 skipped. - `npm pack --dry-run` — passed; 1,271 files, none of the plugin or marketplace files are in the tarball. - `npm run verify:package` — did not complete: after a successful build, the "repository skill" step failed with `spawn npm ENOENT` (the script spawns `npm` without a shell, which Windows cannot resolve). No Linux environment was available locally; relying on CI for this gate. Not run: a live Claude Code or Codex session loading the plugin, and no real-provider lanes. ### Update at `d3359eb` - Merged current `main` (d206a19): the four failing checks on the first CI run were also failing on `main` at the base that run used (`55b6148`) and were fixed upstream in `89f5e48`. - `npm run check` and `npm run docs:check` — passed on the merged tree (Windows). - `tests/conformance/releaseConfiguration.test.ts` — 8 passed (Windows), including a new test for the Codex `interface` fields. - `tests/boundary/filesystem/releaseNotes.test.ts` — 5 passed on Linux (Node 24.18.0) at the test commit; removing either plugin manifest from the allowlist fails the publication history test. This file does not run on Windows. - `tests/boundary/filesystem/qwenClientConfiguration.test.ts` — 3 of 12 fail on my Windows host, identically on unmodified `main`; not investigated. - `npm run verify:package` — passed on Linux (Node 24.18.0, cloud sandbox) at `2aea370`: all 18 stages completed, exit 0. `npm pack --dry-run` there: 1,402 files, no plugin or marketplace paths in the tarball. - `d3359eb` adds `startup_timeout_sec: 30` to the Codex server entry with a conformance test (9 passed); `npm run check` passed. `verify:package` was not rerun on this last commit. - Still not run: a live Codex session, and Codex's `validate_plugin.py` (read, not executed). The Codex `skills` path and the marketplace `source` binding are open in review. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: none run; nothing provider-related changed. - Package or release metadata impact: Release Please gains two extra-files (`$.version` in `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json`). - Security, privacy, process, or containment review: both manifests run a version-pinned `rea-agents` through `npx`. A user who has both the plugin and a `rea setup` registration would get two `rea` servers; the doc section says to use one. ## Review checklist - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. (Release configuration and manifest version alignment; plugin loading in a live client is not covered — see proof gaps.) - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. (Not applicable: no CLI or MCP output changes.) - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 00:57:14 +00:00

closed this issue
added the
pull-request
label

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#4945

No description provided.

Rows
Columns