@vasilvestre/opencode-plain-style 0.1.0

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

@@ -0,0 +1,51 @@
+# PLAIN STYLE
+
+Write all prose in plain language. Goal, from ISO 24495-1: the reader gets what
+they need (relevant), finds it easily (findable), understands it easily
+(understandable), and uses it easily (usable).
+
+This applies to commit messages, code comments, READMEs and docs, PR
+descriptions, and your explanations in chat. Code itself is exempt.
+
+## Rules
+
+1. Use active voice. "The parser rejects the file", not "the file is rejected".
+2. Address the reader as "you" in instructions and docs.
+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.
+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.
+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,
+    warning before the step it applies to.
+12. State prerequisites before the steps that need them.
+13. Give an example for every concept that is not trivial. Show input and
+    output when you explain a command or function.
+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".
+
+## 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.
+
+## Commit messages
+
+- Subject line: imperative mood, 72 characters or fewer, no trailing period.
+- Say what changed and why, not how. The diff shows how.
+
+## What not to do
+
+- Do not pad. If one sentence says it, write one sentence.
+- Do not hedge instructions. "This usually works" is a bug report, not a step.
+- Do not simplify away precision: keep error codes, names, and numbers exact.

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

@@ -0,0 +1,25 @@
+// 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);
+  },
+});

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vasilvestre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# opencode-plain-style
+
+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).**
+See the [benchmark](bench/BENCHMARK.md) for method, raw data, and reproduction steps.
+
+## What it does
+
+The plugin adds one rulebook to the system prompt on every LLM call.
+The rulebook derives from ISO 24495-1 (plain language) and the Google developer documentation style guide.
+It governs commit messages, code comments, READMEs, docs, PR descriptions, and chat explanations.
+Code itself is exempt.
+
+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.
+- Lists and headings over walls of text, conclusion first.
+
+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.
+Full rulebook: [.opencode/plugins/plain-style.md](.opencode/plugins/plain-style.md).
+
+```text
+Rule: imperative mood for steps
+  Before: You should run the tests before merging.
+  After:  Run the tests.
+
+Rule: must for requirements, no hedging
+  Before: The token may need a refresh during long sessions.
+  After:  Refresh the token. Sessions over 1 hour must use a fresh token.
+
+Rule: no vague intensifiers
+  Before: A very simple, basically automatic setup.
+  After:  A setup with two commands.
+
+Rule: active voice
+  Before: The file is rejected by the parser.
+  After:  The parser rejects the file.
+
+Rule: one action per step
+  Before: Install the dependencies and then start the dev server.
+  After:  1. Install the dependencies. 2. Start the dev server.
+```
+
+The pattern: every "before" hides a fact or an action. Every "after" states it.
+
+## Install
+
+Add the package to the `plugin` array in `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "plugin": ["@vasilvestre/opencode-plain-style"]
+}
+```
+
+Restart opencode. The plugin loads at startup and works for the primary agent and every subagent.
+
+## 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 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.
+
+Note: the hook is marked experimental in opencode.
+If opencode renames it, the plugin fails loudly at startup rather than injecting nothing.
+
+## Example output
+
+Same blind prompt, same model, same agent: "Describe what happens when an HTTP request reaches an Express server."
+
+Without the plugin (control), the agent writes dense prose with vague intensifiers:
+
+```text
+Express is really just a callback you handed to http.createServer() —
+app.listen(port) is sugar for http.createServer(app).listen(port).
+It's middleware all the way down: routes are just middleware that
+happens to match on path + method.
+```
+
+With the plugin (treatment), the same agent writes numbered steps and adds an example:
+
+```text
+1. Node's HTTP server receives it. Node parses the raw bytes into req
+   (request) and res (response) objects, then calls your Express app
+   as a handler function.
+2. Express wraps the request. Express extends req and res with its own
+   helpers (like req.query, res.json()), then starts walking the
+   middleware stack.
+
+Example:
+
+const express = require('express');
+const app = express();
+app.use(express.json());          // parses JSON body
+app.get('/users/:id', (req, res) => {
+  res.json({ id: req.params.id });
+});
+```
+
+Both excerpts are real benchmark outputs, unedited.
+Full transcripts: [bench/runs/20260729-105827/](bench/runs/20260729-105827/).
+
+## Benchmark
+
+A/B design: same agent, same pinned model, two config replicas identical except this plugin.
+
+| Rule                    | Control | Treatment | Delta  |
+| ----------------------- | ------: | --------: | -----: |
+| Banned-intensifier-free |   80.0% |      100% | +20.0  |
+| Hedge-free              |   93.3% |      100% |  +6.7  |
+| Sentences ≤25 words     |   73.3% |     93.3% | +20.0  |
+| Fully compliant         |   66.7% |     93.3% | +26.6  |
+
+30 runs total: 5 blind probes × 3 repetitions × 2 arms, deterministic scoring, zero LLM judging.
+Injection shifts probability; it does not guarantee compliance.
+For a hard guarantee, add deterministic linting (for example Vale) to CI.
+
+Full details: [bench/BENCHMARK.md](bench/BENCHMARK.md).
+
+## Customize the rules
+
+The rulebook is plain markdown at `.opencode/plugins/plain-style.md`.
+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"]
+}
+```
+
+## Development
+
+The `bench/` directory holds the full benchmark suite: harness, scorer, aggregator, raw results.
+
+```bash
+cd bench
+./harness.sh 3 --jobs 2
+node aggregate.mjs runs/<timestamp>
+```
+
+The harness measures the machine's live opencode config, control arm versus treatment arm.
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@vasilvestre/opencode-plain-style",
+  "version": "0.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"],
+  "license": "MIT",
+  "author": {
+    "name": "vasilvestre",
+    "url": "https://github.com/vasilvestre"
+  },
+  "homepage": "https://github.com/vasilvestre/opencode-plain-style",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vasilvestre/opencode-plain-style.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vasilvestre/opencode-plain-style/issues"
+  },
+  "type": "module",
+  "main": "./.opencode/plugins/plain-style.mjs",
+  "exports": {
+    ".": "./.opencode/plugins/plain-style.mjs",
+    "./plugin": "./.opencode/plugins/plain-style.mjs"
+  },
+  "files": [
+    ".opencode/",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}