@vasilvestre/opencode-plain-style 0.1.0 → 1.1.0

package/.opencode/plugins/plain-style.js

@@ -0,0 +1,46 @@
+// plain-style — OpenCode plugin, supports opencode v1.x and v2.x.
+//
+// Injects the plain-language rulebook (plain-style.md, beside this file) into
+// every chat's system prompt on every agent-loop LLM request, primary agent
+// and subagents alike.
+//
+// The default export is one object with both entrypoints (v2 migration guide:
+// https://opencode.ai/v2/docs/build/plugins/migrate-v1):
+// - v2 calls setup() and registers a "context" session hook; system parts are
+//   objects ({ type: "text", text }) there.
+// - v1 (object entrypoints need opencode >= 1.18.29) calls server() and gets
+//   the experimental.chat.system.transform hook; system entries there are
+//   plain strings. The hook must mutate output.system in place (push), because v1
+//   ignores a reassignment of output.system.
+//
+// Auto-discovered from .opencode/plugins/ in both versions, so no
+// opencode.json entry is needed. To register it by hand instead:
+// { "plugin": ["./.opencode/plugins/plain-style.js"] }  (opencode v1)
+// { "plugins": ["./.opencode/plugins/plain-style.js"] } (opencode v2)
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Read once at load; a missing file throws here so startup fails loud instead
+// of silently injecting nothing.
+const rulebook = fs.readFileSync(
+  path.join(path.dirname(fileURLToPath(import.meta.url)), 'plain-style.md'),
+  'utf8',
+);
+
+export default {
+  id: 'vasilvestre.opencode-plain-style',
+  async setup(ctx) {
+    await ctx.session.hook('context', (event) => {
+      event.system.push({ type: 'text', text: rulebook });
+    });
+  },
+  async server() {
+    return {
+      'experimental.chat.system.transform': async (_input, output) => {
+        output.system.push(rulebook);
+      },
+    };
+  },
+};

package/.opencode/plugins/plain-style.md

@@ -14,14 +14,14 @@ descriptions, and your explanations in chat. Code itself is exempt.
 3. Use present tense. "The function returns", not "the function will return".
 4. Keep sentences short: about 25 words or fewer. Split longer ones.
 5. Give one action per step. Never chain two actions with "and" in one step.
-6. Use the imperative for steps. "Run the tests", not "you should run the tests".
-7. Use "must" for requirements. Do not use "should", "may", or "might" for them.
+6. Use the imperative for steps. "Run the tests", not "running the tests".
+7. State requirements as facts, with "must". Do not soften requirements.
 8. Define every term and abbreviation on first use, unless it is common in
    software (for example: API, URL, JSON).
 9. Use one term per concept, and one concept per term. Do not alternate between
    synonyms like "workspace" and "project" for the same thing.
-10. Do not use vague intensifiers: very, really, quite, just, simply, actually,
-    basically, obviously. Delete them or state the fact they hide.
+10. Do not use vague intensifiers or words that signal laziness or condescension.
+    State the fact directly.
 11. Prefer lists and headings over walls of text. If a paragraph has more than
     four sentences, consider splitting it or making it a list.
 12. Put the most important information first: conclusion before explanation,
@@ -32,12 +32,19 @@ descriptions, and your explanations in chat. Code itself is exempt.
 14. Format code, commands, flags, file names, and paths in backticks.
 15. Be concrete. Replace "handle errors appropriately" with what to do:
     "log the error and return a 400 response".
+16. End with one line starting with "Next:". Name one concrete action the
+    reader can do.
+17. Do not use em dashes (—) or en dashes (–) as punctuation. Use commas,
+    colons, or parentheses. En dashes in numeric ranges like 2020–2026 are
+    the exception.
+18. Do not write "please" in instructions. Do not write "etc." or
+    "and so on". Complete the list or name the count.
 
 ## Code comments
 
 - Explain why the code exists, not what it does. The code shows what.
 - Do not leave commented-out code. Delete it. Git keeps the history.
-- Write TODO comments as `TODO(name): action — reason`, one line.
+- Write TODO comments as `TODO(name): action, reason`, one line.
 
 ## Commit messages
 

package/README.md

@@ -1,5 +1,9 @@
 # opencode-plain-style
 
+[![CI](https://github.com/vasilvestre/opencode-plain-style/actions/workflows/ci.yml/badge.svg)](https://github.com/vasilvestre/opencode-plain-style/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@vasilvestre/opencode-plain-style)](https://www.npmjs.com/package/@vasilvestre/opencode-plain-style)
+[![license](https://img.shields.io/npm/l/@vasilvestre/opencode-plain-style)](LICENSE)
+
 Plain-language writing rules for opencode agents, injected into every system prompt.
 
 **Measured effect: fully-compliant prose rises from 66.7% to 93.3% of runs (+26.6 points).**
@@ -17,16 +21,18 @@ Rules include:
 - Active voice, second person, present tense.
 - Sentences of 25 words or fewer.
 - Imperative mood for steps, one action per step.
-- `must` for requirements, never hedging modal verbs.
-- A banned list of vague intensifiers.
+- `must` for requirements, stated as facts without softening.
+- No vague intensifiers or words that signal laziness or condescension.
 - Lists and headings over walls of text, conclusion first.
+- One "Next:" line at the end naming a concrete action.
+- No em dashes as punctuation, no "please" in instructions, no "etc.".
 
 Because the injection happens per request, the rules survive context compaction.
 AGENTS.md instructions, by contrast, get summarized away during compaction.
 
 ## The rules, by example
 
-Five of the sixteen rules, before and after.
+Five of the nineteen rules, before and after.
 Full rulebook: [.opencode/plugins/plain-style.md](.opencode/plugins/plain-style.md).
 
 ```text
@@ -53,27 +59,98 @@ Rule: one action per step
 
 The pattern: every "before" hides a fact or an action. Every "after" states it.
 
+## Rule decisions
+
+Every rule in the rulebook earned its place through an A/B benchmark.
+Rules enter only if their compliance lift beats the measured dilution cost
+(~2.2 points per added rule) and they leave only if the model stays at ≥86.7%
+fully compliant without them. Ablations on two models found no rule cuttable.
+Full experiment history: [bench/README.md](bench/README.md).
+
+Decisions from the English Language proposal (2026-08-02):
+
+| Proposed rule                                              | Decision | Why                                            |
+| ---------------------------------------------------------- | -------- | ---------------------------------------------- |
+| Avoid belittling words (obviously, just, simply, ...)      | Adopted  | Folded into Rule 10, without the word list     |
+| Avoid passive voice                                        | Kept     | Already covered by Rule 1                      |
+| American English, title case, no Oxford commas,            | Not      | Not checkable by the scorer, and each injected |
+| gender-neutral pronouns, contractions allowed              | injected | rule costs ~2.2 points of dilution             |
+
+One design lesson shapes the phrasing: never list banned words in the rulebook.
+Weaker models echo the list and produce more violations, not fewer.
+Rules state what to do, not what to avoid by name.
+
 ## Install
 
-Add the package to the `plugin` array in `~/.config/opencode/opencode.json`:
+### Requirements
 
-```json
-{
-  "plugin": ["@vasilvestre/opencode-plain-style"]
-}
-```
+- opencode installed and runnable (`opencode --version` prints a version).
+- A config file at `~/.config/opencode/opencode.json`. Create it if it does not exist.
+
+### Steps
+
+1. Open `~/.config/opencode/opencode.json`.
+2. Add the package name to the plugin array. opencode v2 uses the `plugins` key, opencode v1 uses `plugin`:
+
+   ```json
+   {
+     "plugins": ["@vasilvestre/opencode-plain-style"]
+   }
+   ```
+
+   ```json
+   {
+     "plugin": ["@vasilvestre/opencode-plain-style"]
+   }
+   ```
+
+   opencode downloads the package from npm on the next start. You do not need to run `npm install`.
+
+3. Restart opencode.
+4. Verify the install. Ask the agent to describe a process. The answer must follow the rules: numbered steps, active voice, sentences of 25 words or fewer.
 
-Restart opencode. The plugin loads at startup and works for the primary agent and every subagent.
+The plugin loads at startup and works for the primary agent and every subagent.
+
+### Install from a local copy
+
+Use this to test changes before publishing, or to run a fork.
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/vasilvestre/opencode-plain-style.git
+   ```
+
+2. Point the config at the local plugin file:
+
+   ```json
+   {
+     "plugins": ["file:///absolute/path/to/opencode-plain-style/.opencode/plugins/plain-style.js"]
+   }
+   ```
+
+   opencode v1 uses the same URL under the `plugin` key. The path must be absolute and must point at the `.js` file, not the directory.
+
+3. Restart opencode.
+
+### Uninstall
+
+1. Remove the entry from the plugin array (`plugins` in opencode v2, `plugin` in v1) in `~/.config/opencode/opencode.json`.
+2. Restart opencode.
 
 ## How it works
 
-The plugin registers one hook: `experimental.chat.system.transform`.
-On each request it pushes the rulebook text into the system prompt array.
+The plugin exports one object with two entrypoints; opencode picks the one matching its version:
+
+- opencode v1 calls `server()`. It hooks `experimental.chat.system.transform` and pushes the rulebook text (a string) into the system prompt array on each request.
+- opencode v2 calls `setup()`. It registers a `context` session hook and appends a `{ type: "text" }` part to the system prompt.
+
 The rulebook is read from disk once at module load, so each request costs one array push and zero I/O.
-Total plugin code: about 25 lines, no dependencies.
+The plugin has no dependencies.
 
-Note: the hook is marked experimental in opencode.
-If opencode renames it, the plugin fails loudly at startup rather than injecting nothing.
+In opencode v1 the hook must mutate `output.system` in place: a reassignment is silently ignored.
+
+Note: v1 support needs opencode 1.18.29 or later (object-style plugin entrypoints).
 
 ## Example output
 
@@ -126,6 +203,9 @@ A/B design: same agent, same pinned model, two config replicas identical except
 Injection shifts probability; it does not guarantee compliance.
 For a hard guarantee, add deterministic linting (for example Vale) to CI.
 
+The table shows the original 16-rule baseline. The current 19-rule rulebook
+re-validated on the same model at +26.7 points (53.3% to 80.0%, 2026-08-03).
+
 Full details: [bench/BENCHMARK.md](bench/BENCHMARK.md).
 
 ## Customize the rules
@@ -135,10 +215,12 @@ Fork the repo, edit the file, and point your config at the local copy:
 
 ```json
 {
-  "plugin": ["file:///path/to/your/fork/.opencode/plugins/plain-style.mjs"]
+  "plugins": ["file:///path/to/your/fork/.opencode/plugins/plain-style.js"]
 }
 ```
 
+opencode v1 uses the `plugin` key instead.
+
 ## Development
 
 The `bench/` directory holds the full benchmark suite: harness, scorer, aggregator, raw results.

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@vasilvestre/opencode-plain-style",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "Plain-language writing rules for opencode agents, injected into every system prompt. Enforces ISO 24495-1 principles on commits, comments, docs, and chat prose.",
-  "keywords": ["opencode-plugin", "opencode", "plain-language", "writing", "style-guide"],
+  "keywords": [
+    "opencode-plugin",
+    "opencode",
+    "plain-language",
+    "writing",
+    "style-guide"
+  ],
   "license": "MIT",
   "author": {
     "name": "vasilvestre",
@@ -17,10 +23,13 @@
     "url": "https://github.com/vasilvestre/opencode-plain-style/issues"
   },
   "type": "module",
-  "main": "./.opencode/plugins/plain-style.mjs",
+  "main": "./.opencode/plugins/plain-style.js",
   "exports": {
-    ".": "./.opencode/plugins/plain-style.mjs",
-    "./plugin": "./.opencode/plugins/plain-style.mjs"
+    ".": "./.opencode/plugins/plain-style.js",
+    "./plugin": "./.opencode/plugins/plain-style.js"
+  },
+  "scripts": {
+    "test": "node scripts/check-plugin.mjs"
   },
   "files": [
     ".opencode/",

package/.opencode/plugins/plain-style.mjs

@@ -1,25 +0,0 @@
-// plain-style — OpenCode plugin.
-//
-// Injects the plain-language rulebook (plain-style.md, beside this file) into
-// every chat's system prompt on every LLM request — primary agent and
-// subagents alike — so the rules survive context compaction. Pattern cloned
-// from the ponytail plugin (experimental.chat.system.transform).
-//
-// Registered in opencode.jsonc: { "plugin": [..., "./plugins/plain-style.mjs"] }
-
-import fs from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-// Read once at load; a missing file throws here so startup fails loud instead
-// of silently injecting nothing.
-const rulebook = fs.readFileSync(
-  path.join(path.dirname(fileURLToPath(import.meta.url)), 'plain-style.md'),
-  'utf8',
-);
-
-export default async () => ({
-  'experimental.chat.system.transform': async (_input, output) => {
-    output.system.push(rulebook);
-  },
-});