agent-simple-english 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "agent-simple-english",
+  "owner": {
+    "name": "JIA YI"
+  },
+  "metadata": {
+    "description": "Local install source for the Simple English Claude Code plugin."
+  },
+  "plugins": [
+    {
+      "name": "simple-english",
+      "description": "Apply Simplified Technical English rules to writes, edits, and git commit messages.",
+      "version": "0.1.0",
+      "author": {
+        "name": "JIA YI"
+      },
+      "source": "./",
+      "category": "development",
+      "homepage": "https://github.com/jyooi/agent-simple-english"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
+  "name": "simple-english",
+  "version": "0.1.0",
+  "description": "Apply Simplified Technical English rules to writes, edits, and git commit messages.",
+  "repository": "https://github.com/jyooi/agent-simple-english",
+  "license": "MIT",
+  "keywords": ["simplified-technical-english", "lint", "hooks"],
+  "author": {
+    "name": "JIA YI"
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JIA YI
+
+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,435 @@
+# agent-simple-english
+
+`agent-simple-english` checks ASD-STE100 Simplified Technical English (STE).
+It supplies one Engine, one CLI, a pi Adapter, and a Claude Code Adapter.
+The Claude Code plugin uses CLI Hook mode to enforce the same rules.
+
+This package reports deterministic writing problems.
+It does not rewrite text because an automatic rewrite can change its meaning.
+
+## What the pi Adapter does
+
+The pi Adapter adds its active STE rules to the model prompt before each agent turn.
+It then applies the rules at three layers.
+
+1. **Write and edit gate.**
+   The extension checks prose before the `write` or `edit` tool changes a file.
+   A hard violation blocks the tool.
+   A soft violation gives the model a warning but lets the tool change the file.
+   An edit reports only new violations, so an old violation does not block an unrelated edit.
+
+2. **Commit-message gate.**
+   The extension checks static messages in detected `git commit -m` and `git commit --message` commands.
+   A hard violation blocks the command before the shell starts.
+   Conventional Commit prefixes and final trailer lines do not form part of the check.
+   A detected commit without an available static message fails closed.
+
+3. **Reply check.**
+   Normal mode checks each final assistant reply and shows the hard and soft counts in a widget.
+   The model receives hard violation details before its next call.
+   Normal mode does not hide or change the reply.
+   Strict mode makes the model send each reply through the `say` tool.
+   A strict reply stays hidden until it has no hard violations.
+
+The pi Adapter checks Markdown prose and source comments according to the [content kinds](#content-kinds).
+It gives the line, column, rule ID, and suggested correction for a blocked tool call.
+A config or dictionary load error makes enabled write, edit, and commit gates fail closed.
+
+## Install the Claude Code Adapter
+
+Install [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [Bun](https://bun.sh) first.
+Then use the standard local plugin flow:
+
+```sh
+claude plugin marketplace add jyooi/agent-simple-english
+claude plugin install simple-english@agent-simple-english
+```
+
+Start a new Claude Code session after installation.
+Bun installs the plugin dependencies when the first hook starts.
+You do not need a global `simple-english` package or manual hook settings.
+The repository supplies the local marketplace manifest.
+Marketplace publication is outside this package release.
+
+At `SessionStart`, the Adapter loads the merged config for an enabled session.
+It reads the config from the session working directory and adds the active STE rule summary to context.
+The summary honors `hard`, `soft`, and `off` rule settings plus `maxSentenceWords`.
+
+The `PreToolUse` gate checks `Write`, `Edit`, and `Bash` events.
+A hard write or edit violation blocks the tool and returns its location, rule ID, and suggested correction.
+The Adapter checks only new edit violations, so old prose does not block an unrelated edit.
+Correct the text and retry the tool.
+A clean retry succeeds.
+
+For `Bash`, the gate checks static messages in detected `git commit` commands.
+It blocks a hard violation before Git starts.
+It also blocks a detected commit without a static `-m` or `--message` argument.
+A compliant static message passes.
+Soft violations allow the event and add warning text.
+
+### Session controls
+
+The `/ste` command controls the current Claude Code session.
+New sessions start in enabled mode without a strict reply gate.
+A change in one session does not change a parallel session.
+
+| Command | Result |
+| --- | --- |
+| `/ste on` | Enable write, edit, commit, and reply checks. |
+| `/ste off` | Disable all checks and leave strict mode. |
+| `/ste status` | Show the mode, rule counts, and dictionary state. |
+| `/ste strict` | Enable the strict reply gate and all other checks. |
+| `/ste strict off` | Disable the strict reply gate and use reply feedback. |
+
+Strict mode blocks a `Stop` event when the reply has a hard violation.
+Claude Code then uses the violation details to write the reply again.
+The `stop_hook_active` check stops a second block in the same rewrite loop.
+
+Claude Code shows streamed reply text before the `Stop` hook runs.
+Thus, strict mode can reject the completed reply, but it cannot redact text that Claude Code already showed.
+The pi Adapter does not have this gap because its `say` tool hides strict reply text before approval.
+
+### Reply feedback loop
+
+In enabled non-strict mode, the `Stop` hook checks each finished assistant reply after Claude Code shows it.
+It records only hard violation details in a state file for that Claude Code session.
+The `Stop` hook does not block or change the reply in this mode.
+
+At the next `UserPromptSubmit` event, the Adapter adds the pending feedback to the model context.
+The feedback gives the line, column, rule ID, and suggested fix for each hard violation.
+The Adapter then clears the pending feedback, so it adds each report only one time.
+The session state retains the processed reply identity and ignores duplicate `Stop` events.
+Clean and soft-only replies leave no pending feedback.
+
+Each session has a separate state file under `$XDG_STATE_HOME/simple-english/sessions`.
+The default state directory is `~/.local/state/simple-english/sessions`.
+The file stores the session mode, reply identity, and pending feedback.
+Concurrent sessions in one project do not read or clear state from another session.
+
+## Install the pi Adapter
+
+Install [pi](https://pi.dev) first.
+Then use the pi package mechanism:
+
+```sh
+pi install npm:agent-simple-english
+```
+
+Pi records the package in its user settings and loads the extension in each session.
+Pi packages run with your user permissions, so inspect third-party package code before installation.
+
+Use the checkout without a persistent installation during development:
+
+```sh
+git clone https://github.com/jyooi/agent-simple-english.git
+cd agent-simple-english
+bun install
+pi -e .
+```
+
+## Extension commands
+
+The mode applies to the current pi session.
+The extension starts in enabled mode without strict reply gating.
+Type `/ste ` to see autocomplete suggestions for `on`, `off`, `status`, and `strict`.
+The list changes to match the text that you type.
+
+| Command | Result |
+| --- | --- |
+| `/ste` | Toggle all enforcement. |
+| `/ste on` | Enable write, edit, commit, and reply checks. |
+| `/ste off` | Disable all checks and leave strict mode. |
+| `/ste status` | Show the mode, severity counts, and dictionary state. |
+| `/ste strict` | Enable strict reply gating and the other checks. |
+| `/ste strict on` | Enable strict reply gating and the other checks. |
+| `/ste strict off` | Disable strict reply gating without changing the other checks. |
+
+## Install and use the CLI
+
+The standalone command needs [Bun](https://bun.sh).
+Install it from the same npm package.
+The package is `agent-simple-english` and the command it installs is `simple-english`:
+
+```sh
+bun add --global agent-simple-english
+```
+
+### Claude Code Hook mode
+
+The `hook` subcommand reads one Claude Code hook event from standard input.
+It writes one hook result as JSON.
+A `SessionStart` event returns the active rule summary as added context.
+A `PreToolUse` event applies the write, edit, and commit gates that the plugin registers.
+A `Stop` event records hard reply feedback in enabled non-strict mode.
+In strict mode, it blocks a reply that has hard violations.
+
+A `UserPromptSubmit` event adds pending feedback to context and clears that feedback.
+Every hook reads the current session mode before it applies a gate.
+Malformed JSON returns a non-blocking error so Claude Code can continue.
+The hook also allows the event when configuration, dictionary, tagger, transcript, state, or file processing fails.
+It adds warning text.
+
+### Lint files and standard input
+
+Lint one or more files:
+
+```sh
+simple-english README.md
+simple-english README.md src/cli/main.ts
+```
+
+Lint standard input when no file path is present:
+
+```sh
+printf 'Open the valve.\n' | simple-english
+```
+
+Lint a commit message with an explicit content kind:
+
+```sh
+git log -1 --format=%B | simple-english --kind commit-message
+```
+
+Request JSON output:
+
+```sh
+simple-english --json README.md
+```
+
+Use one explicit config file instead of discovered config files:
+
+```sh
+config_file="$(mktemp)"
+printf '%s\n' '{"maxSentenceWords":25}' > "$config_file"
+simple-english --config "$config_file" README.md
+rm "$config_file"
+```
+
+The command prints each violation with its file, line, column, severity, rule ID, and message.
+Exit code 0 means that no hard violation exists.
+Exit code 1 means that at least one hard violation exists.
+Exit code 2 means that an argument, input, or config error occurred.
+Soft violations can appear with exit code 0.
+
+### CLI flags
+
+- `--json` writes one JSON report with `violations` and `summary` fields.
+
+- `--config <path>` uses only that config file and disables config discovery.
+
+- `--kind <kind>` sets one content kind for all inputs.
+  Valid values are `prose-file`, `slash-source`, `hash-source`, and `commit-message`.
+  The form `--kind=<kind>` also works.
+
+- A path of `-` reads standard input.
+  With no paths, the command also reads standard input.
+
+### Content kinds
+
+`prose-file` checks all prose in a file.
+It is the default for standard input, extensionless paths, and file types that have no source mapping.
+
+`slash-source` checks comments in these file types:
+`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.go`, `.rs`, `.java`, `.c`, `.h`, `.cpp`, `.hpp`, `.cc`, `.cs`, `.swift`, `.kt`, and `.scala`.
+
+`hash-source` checks comments in these file types:
+`.sh`, `.bash`, `.zsh`, `.py`, `.rb`, `.yaml`, `.yml`, `.toml`, and `.pl`.
+
+`commit-message` checks the complete input as a commit message.
+
+File extension matching does not depend on letter case.
+Source kinds ignore comment markers inside string literals.
+All kinds preserve the original line and column.
+They ignore identifiers plus fenced and indented Markdown code.
+Inline Markdown code is outside every rule except `semicolon`.
+
+## Configuration
+
+Configuration is an optional JSON object.
+The project file is `.simple-english.json` at the repository root.
+The global file is `$XDG_CONFIG_HOME/simple-english/config.json`.
+If `XDG_CONFIG_HOME` is unset or not absolute, the global path is `~/.config/simple-english/config.json`.
+
+Global and project files are deep-merged.
+Global values load first, and project values have precedence.
+The pi Adapter reads the project file only when pi trusts the project.
+The `--config` flag uses only its named file.
+
+Existing pi config paths remain as fallbacks.
+The project fallback is `.pi/simple-english.json`.
+The global fallback is `simple-english.json` in the pi agent config directory.
+The default pi agent config directory is `~/.pi/agent`.
+`PI_CODING_AGENT_DIR` can change that directory.
+
+The loader resolves a relative value from the working directory that requested the config.
+The loader reads a fallback file only when the new file at the same level is absent.
+
+This example contains every config key and every rule:
+
+```json
+{
+  "maxSentenceWords": 25,
+  "rules": {
+    "contraction": "hard",
+    "dictionary-not-approved-word": "hard",
+    "hedging": "soft",
+    "marketing": "soft",
+    "paragraph-length": "hard",
+    "phrasal-verb": "hard",
+    "semicolon": "hard",
+    "sentence-length": "hard",
+    "verb-progressive": "hard",
+    "verb-passive": "soft",
+    "verb-perfect": "hard"
+  }
+}
+```
+
+Each rule setting accepts `hard`, `soft`, or `off`.
+A hard violation fails the CLI and blocks a gated extension action.
+A soft violation produces a report or warning but does not block the action.
+The `off` value disables that rule.
+
+`maxSentenceWords` must be a positive integer and has a default value of 25.
+Unknown keys, unknown rule IDs, and invalid values cause a config error.
+
+## Rule reference
+
+### `contraction`
+
+Default: hard.
+Reports apostrophe contractions such as forms that end in `n't`, `'re`, `'ve`, `'ll`, `'d`, or `'m`.
+It also reports unambiguous forms that end in `'s`.
+
+### `dictionary-not-approved-word`
+
+Default: hard.
+Reports an unapproved word or phrase from the bundled dictionary and supplies approved alternatives.
+Part-of-speech data limits applicable entries when that data exists.
+Matching does not depend on letter case.
+
+### `hedging`
+
+Default: soft.
+Reports these phrases: `it is important to note`, `it should be noted`, `it is worth noting`, `please note that`, `as mentioned`, `as noted above`.
+A phrase match stays on one source line.
+
+### `marketing`
+
+Default: soft.
+Reports the first listed term in each token.
+Matching does not depend on letter case, and it also examines components of hyphenated tokens.
+
+- `seamless`.
+- `seamlessly`.
+- `robust`.
+- `powerful`.
+- `cutting-edge`.
+- `effortless`.
+- `effortlessly`.
+- `world-class`.
+- `next-generation`.
+- `revolutionary`.
+- `blazing`.
+- `lightning-fast`.
+- `elegant`.
+- `delightful`.
+- `turnkey`.
+- `best-in-class`.
+- `state-of-the-art`.
+- `game-changing`.
+- `battle-tested`.
+- `enterprise-grade`.
+- `supercharge`.
+- `unleash`.
+- `empower`.
+- `empowers`.
+
+### `paragraph-length`
+
+Default: hard.
+Reports a prose paragraph that has more than six sentences.
+Markdown block boundaries and list items start separate paragraphs.
+
+### `phrasal-verb`
+
+Default: hard.
+Reports these forms and supplies the listed suggestion:
+
+| Forms | Suggestion |
+| --- | --- |
+| `carry out`, `carries out`, `carried out`, `carrying out` | `do`. |
+| `spin up`, `spins up`, `spun up`, `spinning up` | `start`. |
+| `spin down`, `spins down`, `spun down`, `spinning down` | `stop`. |
+| `tear down`, `tears down`, `tore down`, `torn down`, `tearing down` | `remove`. |
+| `reach out`, `reaches out`, `reached out`, `reaching out` | `ask`. |
+| `dive into`, `dives into`, `dived into`, `dove into`, `diving into` | `examine`. |
+| `kick off`, `kicks off`, `kicked off`, `kicking off` | `start`. |
+| `roll out`, `rolls out`, `rolled out`, `rolling out` | `release`. |
+| `ramp up`, `ramps up`, `ramped up`, `ramping up` | `increase`. |
+| `circle back`, `circles back`, `circled back`, `circling back` | `return`. |
+| `drill down`, `drills down`, `drilled down`, `drilling down` | `examine`. |
+
+Matching does not depend on letter case.
+A phrase match stays on one source line.
+
+### `semicolon`
+
+Default: hard.
+Reports each semicolon and asks for two sentences.
+This rule also checks semicolons inside inline Markdown code.
+
+### `sentence-length`
+
+Default: hard.
+Reports a sentence above `maxSentenceWords`.
+The default maximum is 25 words.
+
+### `verb-progressive`
+
+Default: hard.
+Reports a form of `be` followed by an `-ing` verb, with optional adverbs or `not` between them.
+
+### `verb-passive`
+
+Default: soft.
+Reports a form of `be` followed by a past participle, with optional adverbs or `not` between them.
+
+### `verb-perfect`
+
+Default: hard.
+Reports auxiliary `have` followed by a past participle, with optional adverbs or `not` between them.
+
+The three verb rules and applicable dictionary entries use the bundled English part-of-speech tagger.
+
+## Dictionary and attribution
+
+The package vendors dictionary data converted from Cameron Moore's MIT-licensed [`ctotheameron/pi-ste`](https://github.com/ctotheameron/pi-ste).
+[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) records the pinned source, conversion scope, and license details.
+
+ASD owns ASD-STE100 and limits redistribution of the official specification and dictionary.
+This package does not include the official specification or the complete ASD dictionary.
+Get the current official specification from the [ASD-STE100 site](https://www.asd-ste100.org/).
+This project has no affiliation with or endorsement from ASD.
+
+The package dictionary format and match rules are in [`src/dictionary/README.md`](src/dictionary/README.md).
+Set `SIMPLE_ENGLISH_DICTIONARY` to a replacement dictionary file if necessary.
+Hook mode resolves a relative replacement path from the session working directory.
+A lint command reports a replacement dictionary load error and continues with all other rules.
+The enabled pi Adapter fails closed after that error.
+
+## Development
+
+```sh
+bun install
+bun run test
+bun run lint
+bun run typecheck
+npm publish --dry-run
+```
+
+Actual npm publishing is a separate release action.
+
+## License
+
+[MIT](LICENSE)

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,13 @@
+# Third-party notices
+
+## Vendored STE dictionary data
+
+`src/dictionary/data/pi-ste.json` is a data-only conversion of the entries returned by `word_entries()` and `phrase_entries()` with the `dictionary/not-approved-word` rule ID in [`ctotheameron/pi-ste`](https://github.com/ctotheameron/pi-ste), `src/ste/dictionary.gleam`, at commit `18a8cc686be2cc0e680705daf2327fb0d1ef93ce`.
+The `package.json` at that commit declares the package to be MIT licensed, and its README also states that the license is MIT.
+No other pi-ste lists or upstream implementation code are included.
+
+The conversion expands the upstream spelling generators into explicit forms.
+Forms produced by upstream verb helpers have `VERB` metadata.
+Entries without source POS metadata use word-level matching.
+
+The pinned source states that ASD owns ASD-STE100, limits redistribution of the full dictionary, and describes these entries as widely cited pairs.

package/commands/ste.md

@@ -0,0 +1,13 @@
+---
+description: Control STE for this Claude Code session
+argument-hint: on|off|status|strict|strict off
+allowed-tools: Bash
+disable-model-invocation: true
+---
+
+Session state:
+
+!`cd "${CLAUDE_PLUGIN_ROOT}" && bun "src/cli/main.ts" session "${CLAUDE_SESSION_ID}" "${CLAUDE_PROJECT_DIR}" "$ARGUMENTS"`
+
+Show the session state exactly.
+Do not add text.

package/hooks/hooks.json

@@ -0,0 +1,58 @@
+{
+  "description": "Inject active STE rules, gate changes, and return reply feedback on the next prompt.",
+
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun \"src/cli/main.ts\" hook",
+            "timeout": 120
+          }
+        ]
+      }
+    ],
+
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun \"src/cli/main.ts\" hook",
+            "timeout": 120
+          }
+        ]
+      }
+    ],
+
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun \"src/cli/main.ts\" hook",
+            "timeout": 120
+          }
+        ]
+      }
+    ],
+
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+
+            "command": "cd \"${CLAUDE_PLUGIN_ROOT}\" && bun \"src/cli/main.ts\" hook",
+            "timeout": 120
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "agent-simple-english",
+  "version": "0.1.0",
+  "description": "ASD-STE100 Simplified Technical English lint engine, CLI, and host adapters",
+  "license": "MIT",
+  "type": "module",
+  "author": {
+    "name": "JIA YI"
+  },
+  "homepage": "https://github.com/jyooi/agent-simple-english#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jyooi/agent-simple-english.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jyooi/agent-simple-english/issues"
+  },
+  "keywords": ["pi-package", "simplified-technical-english", "linter"],
+  "pi": {
+    "extensions": ["./src/extension/index.ts"]
+  },
+  "files": [
+    ".claude-plugin",
+    "commands",
+    "hooks",
+    "src",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "bin": {
+    "simple-english": "src/cli/main.ts"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "lint": "biome check .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "effect": "^3.14.0",
+    "wink-eng-lite-web-model": "^1.8.1",
+    "wink-nlp": "^2.4.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@earendil-works/pi-coding-agent": "0.83.0",
+    "@types/node": "^22.0.0",
+    "typebox": "1.3.7",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  }
+}