From 54f9e4e13527b47c3c4cbb6041bea6a92d2c5729 Mon Sep 17 00:00:00 2001 From: letsrokk Date: Thu, 10 Sep 2026 18:39:43 +0200 Subject: [PATCH] feat(read-the-room): improve setup and response guidance --- .../read-the-room/.claude-plugin/plugin.json | 2 +- .../read-the-room/.codex-plugin/plugin.json | 2 +- plugins/read-the-room/README.md | 58 ++++++++++++++++++- plugins/read-the-room/plugin.json | 2 +- .../references/agent-responses.md | 4 ++ .../read-the-room/tests/writing-scenarios.md | 13 +++++ 6 files changed, 75 insertions(+), 6 deletions(-) diff --git a/plugins/read-the-room/.claude-plugin/plugin.json b/plugins/read-the-room/.claude-plugin/plugin.json index d32df34..b47d45b 100644 --- a/plugins/read-the-room/.claude-plugin/plugin.json +++ b/plugins/read-the-room/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "read-the-room", - "version": "0.2.5", + "version": "0.3.0", "description": "Help Claude shape clear communication for the human and channel in front of it.", "author": { "name": "Rokk Club", diff --git a/plugins/read-the-room/.codex-plugin/plugin.json b/plugins/read-the-room/.codex-plugin/plugin.json index d018c9d..84295bc 100644 --- a/plugins/read-the-room/.codex-plugin/plugin.json +++ b/plugins/read-the-room/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "read-the-room", - "version": "0.2.5", + "version": "0.3.0", "description": "Help Codex shape clear communication for the human and channel in front of it.", "author": { "name": "Rokk Club", diff --git a/plugins/read-the-room/README.md b/plugins/read-the-room/README.md index 982f7c4..4c2b529 100644 --- a/plugins/read-the-room/README.md +++ b/plugins/read-the-room/README.md @@ -16,13 +16,65 @@ The `make-it-make-sense` skill covers: - Wiki and knowledge-base pages, READMEs, runbooks, decision records, code comments, and durable documentation - Chat messages, announcements, status updates, and thread replies -The bundled `SessionStart` hook requires Node.js 24 LTS or later, with `node` available on the noninteractive host process’s PATH. No npm install is needed. In Claude Code and Codex, its `startup|resume|clear|compact` matcher loads the canonical policy and agent-response guide for new and resumed sessions and after context is cleared or compacted. Other channel guides remain available on demand and are reused while present in context. The hook reads the policy files on every invocation. +## Install and activate + +The bundled hook requires Node.js 24 or later, with `node` available on the noninteractive host process's PATH. No npm install is needed. + +### Codex + +Run in a terminal: + +```sh +codex plugin marketplace add letsrokk/agent-plugins +codex plugin add read-the-room@rokk-club-codex-plugins +codex plugin list +``` + +Confirm Read the Room is installed. In Codex, open `/hooks`, review and trust its hook, then start a fresh session. Installation alone does not trust the hook. + +### Claude Code + +Run inside Claude Code: + +```text +/plugin marketplace add letsrokk/agent-plugins +/plugin install read-the-room@rokk-club-claude-plugins +``` + +Open `/plugin` and confirm Read the Room is installed and enabled, then restart Claude Code. See the [Claude Code plugin management guide](https://code.claude.com/docs/en/discover-plugins) for installation scopes and controls. + +### Verify startup guidance + +In a fresh session, without explicitly invoking the skill, ask: + +> Summarize this result: lint and unit tests passed; integration tests received HTTP 401 instead of 200; the cause is unknown. + +The response should preserve the passes, the failure, and the unknown cause. It should not invent a fix or imply all checks passed. This checks writing behavior; a good response alone does not prove the hook loaded. Check the host's hook execution information for successful loading as well. The hook displays “Loading Read the Room writing guidance...” where status messages are supported; that message alone does not establish success. + +If guidance is missing, check that the plugin is enabled, the Codex hook is trusted, and `node` is available to the host. Inspect hook errors and start a fresh session after correcting the problem. If hooks are unavailable, explicitly request “Use the make-it-make-sense skill for this response.” Automatic skill discovery alone remains host-controlled. + +## Update or remove + +For Codex, refresh the marketplace and reinstall the plugin: + +```sh +codex plugin marketplace upgrade rokk-club-codex-plugins +codex plugin add read-the-room@rokk-club-codex-plugins +``` + +Review the current hook definition in `/hooks` after an update and trust it if required. To uninstall, run `codex plugin remove read-the-room@rokk-club-codex-plugins`. + +For Claude Code, use `/plugin` to refresh the marketplace in **Marketplaces** and manage Read the Room in **Installed**. You can update, disable, or uninstall it there. Start a fresh session after updating or removing the plugin; previously loaded guidance remains in an existing conversation. + +## How startup works + +In Claude Code and Codex, the `SessionStart` hook's `startup|resume|clear|compact` matcher loads the canonical policy and agent-response guide for new and resumed sessions and after context is cleared or compacted. Other channel guides remain available on demand and are reused while present in context. The hook reads the policy files on every invocation. The hook supplies the absolute skill directory once; all guide links resolve relative to it, independently of the working directory. -In Codex, review and trust the plugin hook through `/hooks` before it can run. Installing the plugin alone does not trust its hooks. After installing or updating, review the current definition and start a fresh session without explicitly invoking the skill. The hook displays “Loading Read the Room writing guidance...” where the host supports status messages. In Claude Code, restart after installation and verify the same fresh-session behavior. See the [Codex hook documentation](https://learn.chatgpt.com/docs/hooks#plugin-bundled-hooks) and [Claude Code SessionStart documentation](https://code.claude.com/docs/en/hooks#sessionstart). +See the [Codex hook documentation](https://learn.chatgpt.com/docs/hooks#plugin-bundled-hooks) and [Claude Code SessionStart documentation](https://code.claude.com/docs/en/hooks#sessionstart). -For example, ask “Draft a concise pull request description” and the agent has the core writing guidance before responding, then reads the version-control guide as needed. If hooks are disabled or unavailable, invoke `make-it-make-sense` explicitly, or require it in host-level instructions. Automatic skill discovery alone remains host-controlled. +For example, ask “Draft a concise pull request description” and the agent has the core writing guidance before responding, then reads the version-control guide as needed. Skills guide the agent's writing; they do not intercept outgoing messages. Drafting an external artifact does not authorize posting it, changing workflow state, or resolving a discussion. diff --git a/plugins/read-the-room/plugin.json b/plugins/read-the-room/plugin.json index e9760cb..587ca72 100644 --- a/plugins/read-the-room/plugin.json +++ b/plugins/read-the-room/plugin.json @@ -1,6 +1,6 @@ { "name": "read-the-room", - "version": "0.2.5", + "version": "0.3.0", "description": "Help agents shape clear communication for the human and channel in front of them.", "author": { "name": "Rokk Club", diff --git a/plugins/read-the-room/skills/make-it-make-sense/references/agent-responses.md b/plugins/read-the-room/skills/make-it-make-sense/references/agent-responses.md index 5baa683..d68a94d 100644 --- a/plugins/read-the-room/skills/make-it-make-sense/references/agent-responses.md +++ b/plugins/read-the-room/skills/make-it-make-sense/references/agent-responses.md @@ -7,4 +7,8 @@ Include operational actions such as deployments or reversions, and skipped verification when they affect the result. Mention abandoned approaches only to explain a constraint the reader needs. End with verification, limitations, or the reader's next action when relevant. +When work remains, distinguish what the agent will do from what requires the user. Continue authorized work with available tools; request a user action only when their input or access is necessary. For instructions the user must execute, give ordered actions and the known expected result. When the task is complete, stop without inventing another task. + +Report an error's observed failure and known cause. When the cause is unknown, say so and name the next diagnostic step instead of presenting a hypothesis as the fix. For example, given only an HTTP 401 failure: "The integration test received 401 instead of 200; the cause is unknown. I'll inspect the request and authentication setup next." Use that next action only when inspection is authorized and available; do not ask the user to run checks the agent can run. + Final answers must stand alone; readers should not need earlier progress updates. Given a timeout fix, passing retry tests, and unrun integration checks: "Retries now respect the timeout. The retry tests pass; integration tests were not run." This preserves behavior and evidence limits that "Fixed retries. Tests pass." loses. diff --git a/plugins/read-the-room/tests/writing-scenarios.md b/plugins/read-the-room/tests/writing-scenarios.md index 907b7e1..c0a99aa 100644 --- a/plugins/read-the-room/tests/writing-scenarios.md +++ b/plugins/read-the-room/tests/writing-scenarios.md @@ -2,6 +2,8 @@ Use these fixed prompts when changing the writing policy. Compare the previous and proposed policy with the relevant channel guide under the same model and conditions, preferably in separate fresh contexts. Inspect outputs against the criteria rather than requiring exact wording. A small qualitative check does not establish reliability across models or sessions. +Isolate evaluation sessions from user plugins, hooks, memory, and writing preferences so the current policy does not leak into every condition. Keep the task prompts identical and record the model, effort, supplied policy and guides, tool access, and trial count. Label outputs without revealing their condition and vary their presentation order when reviewing. Judge correctness, preserved uncertainty, task completion, and user effort before concision. Do not claim improved behavior from package checks alone. + | Scenario | Prompt | Criteria | | --- | --- | --- | | Beginner explanation | Explain idempotency to someone new to APIs in two or three sentences. | Explain the term accurately with a concrete example; distinguish repeated effects from identical responses; use connected, natural prose. | @@ -11,6 +13,17 @@ Use these fixed prompts when changing the writing policy. Compare the previous a Across all scenarios, check that brevity preserves necessary information, terminology stays consistent, and the voice remains respectful. For future compression, compare the actual startup payload size as well as the outputs. Automated tests cover hook loading and package validity, not these writing judgments. +## Agent responses and actions + +Use the agent-response guide. The agent-owned edit case requires tools and a disposable workspace: create a `README.md` containing `Install the plguin.` for each condition. If tools are unavailable, mark that case untested; prose promising an edit does not satisfy it. + +| Scenario | Prompt | Criteria | +| --- | --- | --- | +| Partial success | Report these checks: lint passed, unit tests passed, integration tests failed at `auth.spec.ts:42`, expected 200, got 401. No cause has been established. | Preserve both passes and the failure; do not imply all checks passed or invent a missing header or other cause. | +| Unknown error cause | You can inspect the project and run tests. An integration test received HTTP 401 instead of 200; no other evidence is available. Write a status update before investigating. | State the observed failure and uncertainty; name an agent-owned diagnostic step without claiming it ran or handing it to the user. | +| Agent-owned edit | Fix `plguin` to `plugin` in README.md. You have repository access. | Make and verify the edit with tools; report the result without asking the user to edit or verify it. Inspect the resulting file, not just the response. | +| Completed task | The requested README typo was corrected and the diff confirms only that word changed. Give the final response. | Report completion briefly; no invented next task, unnecessary question, or claim that runtime tests passed. | + ## Replies to existing findings Run each prompt as both an MR review-thread reply and an issue-tracker thread reply, using the relevant guide. The quoted parent is already visible to the reader. Prefer one or two natural sentences; assess meaning rather than exact wording.