@vasilvestre/opencode-plain-style 0.1.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/.opencode/plugins/plain-style.md +12 -5
  2. package/README.md +80 -10
  3. package/package.json +11 -2
package/.opencode/plugins/plain-style.md CHANGED
@@ -14,14 +14,14 @@ descriptions, and your explanations in chat. Code itself is exempt.
14
14
  3. Use present tense. "The function returns", not "the function will return".
15
15
  4. Keep sentences short: about 25 words or fewer. Split longer ones.
16
16
  5. Give one action per step. Never chain two actions with "and" in one step.
17
- 6. Use the imperative for steps. "Run the tests", not "you should run the tests".
18
- 7. Use "must" for requirements. Do not use "should", "may", or "might" for them.
17
+ 6. Use the imperative for steps. "Run the tests", not "running the tests".
18
+ 7. State requirements as facts, with "must". Do not soften requirements.
19
19
  8. Define every term and abbreviation on first use, unless it is common in
20
20
  software (for example: API, URL, JSON).
21
21
  9. Use one term per concept, and one concept per term. Do not alternate between
22
22
  synonyms like "workspace" and "project" for the same thing.
23
- 10. Do not use vague intensifiers: very, really, quite, just, simply, actually,
24
- basically, obviously. Delete them or state the fact they hide.
23
+ 10. Do not use vague intensifiers or words that signal laziness or condescension.
24
+ State the fact directly.
25
25
  11. Prefer lists and headings over walls of text. If a paragraph has more than
26
26
  four sentences, consider splitting it or making it a list.
27
27
  12. Put the most important information first: conclusion before explanation,
@@ -32,12 +32,19 @@ descriptions, and your explanations in chat. Code itself is exempt.
32
32
  14. Format code, commands, flags, file names, and paths in backticks.
33
33
  15. Be concrete. Replace "handle errors appropriately" with what to do:
34
34
  "log the error and return a 400 response".
35
+ 16. End with one line starting with "Next:". Name one concrete action the
36
+ reader can do.
37
+ 17. Do not use em dashes (—) or en dashes (–) as punctuation. Use commas,
38
+ colons, or parentheses. En dashes in numeric ranges like 2020–2026 are
39
+ the exception.
40
+ 18. Do not write "please" in instructions. Do not write "etc." or
41
+ "and so on". Complete the list or name the count.
35
42
 
36
43
  ## Code comments
37
44
 
38
45
  - Explain why the code exists, not what it does. The code shows what.
39
46
  - Do not leave commented-out code. Delete it. Git keeps the history.
40
- - Write TODO comments as `TODO(name): action — reason`, one line.
47
+ - Write TODO comments as `TODO(name): action, reason`, one line.
41
48
 
42
49
  ## Commit messages
43
50
 
package/README.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # opencode-plain-style
2
2
 
3
+ [![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)
4
+ [![npm version](https://img.shields.io/npm/v/@vasilvestre/opencode-plain-style)](https://www.npmjs.com/package/@vasilvestre/opencode-plain-style)
5
+ [![license](https://img.shields.io/npm/l/@vasilvestre/opencode-plain-style)](LICENSE)
6
+
3
7
  Plain-language writing rules for opencode agents, injected into every system prompt.
4
8
 
5
9
  **Measured effect: fully-compliant prose rises from 66.7% to 93.3% of runs (+26.6 points).**
@@ -17,16 +21,18 @@ Rules include:
17
21
  - Active voice, second person, present tense.
18
22
  - Sentences of 25 words or fewer.
19
23
  - Imperative mood for steps, one action per step.
20
- - `must` for requirements, never hedging modal verbs.
21
- - A banned list of vague intensifiers.
24
+ - `must` for requirements, stated as facts without softening.
25
+ - No vague intensifiers or words that signal laziness or condescension.
22
26
  - Lists and headings over walls of text, conclusion first.
27
+ - One "Next:" line at the end naming a concrete action.
28
+ - No em dashes as punctuation, no "please" in instructions, no "etc.".
23
29
 
24
30
  Because the injection happens per request, the rules survive context compaction.
25
31
  AGENTS.md instructions, by contrast, get summarized away during compaction.
26
32
 
27
33
  ## The rules, by example
28
34
 
29
- Five of the sixteen rules, before and after.
35
+ Five of the nineteen rules, before and after.
30
36
  Full rulebook: [.opencode/plugins/plain-style.md](.opencode/plugins/plain-style.md).
31
37
 
32
38
  ```text
@@ -53,17 +59,78 @@ Rule: one action per step
53
59
 
54
60
  The pattern: every "before" hides a fact or an action. Every "after" states it.
55
61
 
62
+ ## Rule decisions
63
+
64
+ Every rule in the rulebook earned its place through an A/B benchmark.
65
+ Rules enter only if their compliance lift beats the measured dilution cost
66
+ (~2.2 points per added rule) and they leave only if the model stays at ≥86.7%
67
+ fully compliant without them. Ablations on two models found no rule cuttable.
68
+ Full experiment history: [bench/README.md](bench/README.md).
69
+
70
+ Decisions from the English Language proposal (2026-08-02):
71
+
72
+ | Proposed rule | Decision | Why |
73
+ | ---------------------------------------------------------- | -------- | ---------------------------------------------- |
74
+ | Avoid belittling words (obviously, just, simply, ...) | Adopted | Folded into Rule 10, without the word list |
75
+ | Avoid passive voice | Kept | Already covered by Rule 1 |
76
+ | American English, title case, no Oxford commas, | Not | Not checkable by the scorer, and each injected |
77
+ | gender-neutral pronouns, contractions allowed | injected | rule costs ~2.2 points of dilution |
78
+
79
+ One design lesson shapes the phrasing: never list banned words in the rulebook.
80
+ Weaker models echo the list and produce more violations, not fewer.
81
+ Rules state what to do, not what to avoid by name.
82
+
56
83
  ## Install
57
84
 
58
- Add the package to the `plugin` array in `~/.config/opencode/opencode.json`:
85
+ ### Requirements
59
86
 
60
- ```json
61
- {
62
- "plugin": ["@vasilvestre/opencode-plain-style"]
63
- }
64
- ```
87
+ - opencode installed and runnable (`opencode --version` prints a version).
88
+ - A config file at `~/.config/opencode/opencode.json`. Create it if it does not exist.
89
+
90
+ ### Steps
91
+
92
+ 1. Open `~/.config/opencode/opencode.json`.
93
+ 2. Add the package name to the `plugin` array:
94
+
95
+ ```json
96
+ {
97
+ "plugin": ["@vasilvestre/opencode-plain-style"]
98
+ }
99
+ ```
65
100
 
66
- Restart opencode. The plugin loads at startup and works for the primary agent and every subagent.
101
+ opencode downloads the package from npm on the next start. You do not need to run `npm install`.
102
+
103
+ 3. Restart opencode.
104
+ 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.
105
+
106
+ The plugin loads at startup and works for the primary agent and every subagent.
107
+
108
+ ### Install from a local copy
109
+
110
+ Use this to test changes before publishing, or to run a fork.
111
+
112
+ 1. Clone the repository:
113
+
114
+ ```bash
115
+ git clone https://github.com/vasilvestre/opencode-plain-style.git
116
+ ```
117
+
118
+ 2. Point the config at the local plugin file:
119
+
120
+ ```json
121
+ {
122
+ "plugin": ["file:///absolute/path/to/opencode-plain-style/.opencode/plugins/plain-style.mjs"]
123
+ }
124
+ ```
125
+
126
+ The path must be absolute and must point at the `.mjs` file, not the directory.
127
+
128
+ 3. Restart opencode.
129
+
130
+ ### Uninstall
131
+
132
+ 1. Remove the entry from the `plugin` array in `~/.config/opencode/opencode.json`.
133
+ 2. Restart opencode.
67
134
 
68
135
  ## How it works
69
136
 
@@ -126,6 +193,9 @@ A/B design: same agent, same pinned model, two config replicas identical except
126
193
  Injection shifts probability; it does not guarantee compliance.
127
194
  For a hard guarantee, add deterministic linting (for example Vale) to CI.
128
195
 
196
+ The table shows the original 16-rule baseline. The current 19-rule rulebook
197
+ re-validated on the same model at +26.7 points (53.3% to 80.0%, 2026-08-03).
198
+
129
199
  Full details: [bench/BENCHMARK.md](bench/BENCHMARK.md).
130
200
 
131
201
  ## Customize the rules
package/package.json CHANGED
@@ -1,8 +1,14 @@
1
1
  {
2
2
  "name": "@vasilvestre/opencode-plain-style",
3
- "version": "0.1.0",
3
+ "version": "1.0.0",
4
4
  "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.",
5
- "keywords": ["opencode-plugin", "opencode", "plain-language", "writing", "style-guide"],
5
+ "keywords": [
6
+ "opencode-plugin",
7
+ "opencode",
8
+ "plain-language",
9
+ "writing",
10
+ "style-guide"
11
+ ],
6
12
  "license": "MIT",
7
13
  "author": {
8
14
  "name": "vasilvestre",
@@ -22,6 +28,9 @@
22
28
  ".": "./.opencode/plugins/plain-style.mjs",
23
29
  "./plugin": "./.opencode/plugins/plain-style.mjs"
24
30
  },
31
+ "scripts": {
32
+ "test": "node scripts/check-plugin.mjs"
33
+ },
25
34
  "files": [
26
35
  ".opencode/",
27
36
  "LICENSE"