diff --git a/README.md b/README.md index 7dd709a..4bddf82 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,51 @@ # Rokk Club Agent Plugins -Rokk Club publishes portable agent plugins for Codex and Claude Code from one repository. Plugins are added one at a time under [`plugins/`](plugins/README.md). +Plugins for Codex and Claude Code that review code, inspect agent configuration, record workflow friction, and help agents write for human readers. Choose individual plugins from the catalogs below; both clients use the same shared [`plugins/`](plugins/README.md) tree. ## Marketplaces -Codex reads `.agents/plugins/marketplace.json` and installs packages that follow the [Agent Plugins v1 specification](https://agent-plugins.org/specification). +Use a client with plugin marketplace support. Codex reads [`.agents/plugins/marketplace.json`](.agents/plugins/marketplace.json). Run in a terminal: ```sh codex plugin marketplace add letsrokk/agent-plugins ``` -Claude Code reads `.claude-plugin/marketplace.json`. +Claude Code reads [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json). Run inside Claude Code: ```text /plugin marketplace add letsrokk/agent-plugins ``` -Both catalogs reference the same package directories. Portable components stay shared; client-specific manifests and components live beside them only when required. +Both catalogs reference the same package directories. Packages use the [Agent Plugins v1 specification](https://agent-plugins.org/specification) as a base, with native client manifests where required. See the [compatibility rules](docs/plugin-development.md#choosing-portable-or-native-loading). + +Adding a marketplace makes its plugins available; install the ones you want separately. See [Claude Code’s plugin management guide](https://code.claude.com/docs/en/discover-plugins) for client controls. + +## Try a plugin + +After adding the marketplace, install Agent Doctor to inspect your project’s agent settings. + +Codex, in a terminal: + +```sh +codex plugin add agent-doctor@rokk-club-codex-plugins +codex plugin list +``` + +Confirm `agent-doctor` is installed. For Claude Code, run: + +```text +/plugin install agent-doctor@rokk-club-claude-plugins +``` + +Open `/plugin` and confirm Agent Doctor is installed and enabled. Start a fresh session in your project and ask: + +```text +Use the inspect-agent-config skill to audit this project’s settings and instructions. +``` + +Expect findings about the active client’s project configuration, with evidence and suggested fixes. The audit does not change your files. Configuration inspection needs no Node.js runtime; inspecting plugin usage requires Node.js 24 or later. See [Agent Doctor](plugins/agent-doctor/README.md). + +Papercuts and Read the Room require Node.js 24 or later on the client process’s `PATH`. For their automatic startup instructions in Codex, review and trust the installed hook in `/hooks`, then start a fresh session. Follow each plugin’s activation instructions below. ## Plugins @@ -24,7 +53,7 @@ Both catalogs reference the same package directories. Portable components stay s #### papercuts ![Codex](assets/agent-badges/codex.svg) ![Claude Code](assets/agent-badges/claude-code.svg) -Give coding agents a durable local journal for material workflow friction. +Give coding agents a durable local journal for material workflow friction. See [requirements, privacy, and activation](plugins/papercuts/README.md). Codex: @@ -40,7 +69,7 @@ Claude: #### agent-doctor ![Codex](assets/agent-badges/codex.svg) ![Claude Code](assets/agent-badges/claude-code.svg) -Inspect and troubleshoot Codex and Claude configuration, then review recent sessions to count exact plugin or skill usage and summarize successes, problems, and incomplete calls. +Inspect Codex and Claude Code configuration and count plugin or skill usage in local sessions. See [usage and requirements](plugins/agent-doctor/README.md). Codex: @@ -56,7 +85,7 @@ Claude: #### read-the-room ![Codex](assets/agent-badges/codex.svg) ![Claude Code](assets/agent-badges/claude-code.svg) -Shape clear communication for human readers across agent sessions, version control, issue trackers, knowledge bases, and chat applications. +Shape clear communication for human readers across agent sessions, version control, issue trackers, knowledge bases, and chat applications. See [activation and examples](plugins/read-the-room/README.md). Codex: @@ -72,13 +101,13 @@ Claude: #### copywriter ![Codex](assets/agent-badges/codex.svg) ![Claude Code](assets/agent-badges/claude-code.svg) -Transform substantive source material into grounded taglines, READMEs, local landing pages, editable pitch decks, and illustrated articles. See [usage and capability requirements](plugins/copywriter/README.md) and the [tested compatibility record](plugins/copywriter/packaging/compatibility.md). +Transform substantive source material into grounded taglines, READMEs, local landing pages, editable pitch decks, and illustrated articles. See [usage and capability requirements](plugins/copywriter/README.md) and the [tested compatibility record](plugins/copywriter/packaging/compatibility.md). End-to-end installed invocation remains unverified in that record. Articles require your draft, outline, or substantive notes. ### Ports #### eli5 ![Codex](assets/agent-badges/codex.svg) -Explain any topic with a dead-simple visual explainer that uses big pictures and few words. +Explain unfamiliar topics with big visuals and few words. See [an example and port attribution](plugins/eli5/README.md). Codex: @@ -88,7 +117,7 @@ codex plugin add eli5@rokk-club-codex-plugins #### pr-review-toolkit ![Codex](assets/agent-badges/codex.svg) -Review pull requests and local changes for code quality, tests, comments, error handling, and type design, then simplify code after the review passes. +Review pull requests and local changes for bugs, test coverage, comments, error handling, and type invariants. Reviews are advisory; simplification requires an explicit request. See [usage and adaptation details](plugins/pr-review-toolkit/README.md). Codex: @@ -98,7 +127,7 @@ codex plugin add pr-review-toolkit@rokk-club-codex-plugins #### code-simplifier ![Codex](assets/agent-badges/codex.svg) -Simplify a precise code scope without changing observable behavior. +Simplify a precise code scope without changing observable behavior. See [usage and adaptation details](plugins/code-simplifier/README.md). Codex: @@ -110,11 +139,19 @@ codex plugin add code-simplifier@rokk-club-codex-plugins Follow the full [plugin development workflow](docs/plugin-development.md). -1. Create `plugins//plugin.json` using the Agent Plugins v1 schema. +1. Create `plugins//plugin.json` using Agent Plugins v1 metadata; follow the documented native-loading exceptions where needed. 2. Add the plugin components in their standard locations. 3. Add the compatibility manifest for each target catalog. 4. Add a matching entry to one or both marketplace catalogs. -5. Run the repository validation commands before committing. +5. With Node.js 24 or later, run these commands from the repository root before committing: + +```sh +npm ci --ignore-scripts --no-audit --no-fund +npm test +npm run validate +``` + +The test suite should pass, and validation should print `Marketplace validation passed.` Scripted plugins also require their own test and validation entrypoints; see the development workflow. ## License