Repository navigation
feat: tell agents to write in Simple English, with hooks - #833
Conversation
Copy the Simple English skill into .agents/skills/simple-english. Cursor and Codex load project skills from .agents/skills. The files come from commit 79b590fc8596523d92c26b1ea7e33236606ef069 with no changes. The project uses the MIT license, and LICENSE holds the license text. Co-authored-by: Ramon Niebla <nieblara@users.noreply.github.com>
The upstream strip_code function replaced each code block and some table rows with one space. It removed their newlines, so each line number after a code block or a table was too small. In this repository, 34 hits went to the wrong line. strip_code now keeps the newlines that it removes. The violation counts do not change. Co-authored-by: Ramon Niebla <nieblara@users.noreply.github.com>
Add hooks that load the Simple English rules at session start and lint the Markdown files that an agent writes. The hooks are advisory, so they never block an action. One script, scripts/hook.py, serves the three tools. The lint reports only the lines that differ from the last commit, so an agent does not rewrite old text. Cursor also runs the hooks in .claude/settings.json. The script finds this case and runs only the Cursor hooks. Co-authored-by: Ramon Niebla <nieblara@users.noreply.github.com>
Add a Writing Style section to AGENTS.md. CLAUDE.md is a link to this file. The section gives the rules that agents break most often, the text that the rules cover, and the hooks for each tool. Co-authored-by: Ramon Niebla <nieblara@users.noreply.github.com>
The upstream file ends with a blank line. The end-of-file-fixer pre-commit hook requires one newline at the end of each file, so the build failed. UPSTREAM.md now records this change. Co-authored-by: Ramon Niebla <nieblara@users.noreply.github.com>
|
🤔 Approving because it looks fine, but I'm actually not 100% on this one... I think we can try the simple english, but I'll say that I tried it out on cursor for a bit and was distinctly displeased with the experience I was getting using ASD-STE100, it sort of annoyed me haha. To be clear, this is customer-facing right? Like a customer's agents will see and absorb these skills - not just ours as internal developers of the ldcli? If so, wonder if we could run an experiment or something to see if this noticeably affects usage trends. |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit e8c770a. Configure here.
| print(json.dumps({"additional_context": context})) | ||
| else: | ||
| sys.stdout.write(context) | ||
| return 0 |
There was a problem hiding this comment.
Codex session hook emits invalid output
High Severity
session_start writes raw text for the codex harness, but Codex parses SessionStart stdout as JSON and requires a hookSpecificOutput.additionalContext envelope. Non-JSON output fails with an invalid session-start error, so the rules never load.
Reviewed by Cursor Bugbot for commit e8c770a. Configure here.
| "command": "python3 .agents/skills/simple-english/scripts/hook.py post-edit --harness cursor", | ||
| "matcher": "Write", | ||
| "timeout": 10 | ||
| } |
There was a problem hiding this comment.
Cursor lint skips file edits
Medium Severity
The Cursor postToolUse matcher is only Write, so Markdown lint does not run after StrReplace. Cursor agents use StrReplace for in-place edits, so changed-line lint never runs for the common edit path.
Reviewed by Cursor Bugbot for commit e8c770a. Configure here.
Requirements
Related issues
None. The rules come from the Simple English skill, which uses the MIT license.
Describe the solution you've provided
Summary
This PR tells AI agents to write in Simple English in this repository. Simple English is plain English that follows the rules of ASD-STE100 Simplified Technical English. The rules give short sentences, active voice, one word for one meaning, and no filler words.
The PR has three parts:
.agents/skills/simple-english/AGENTS.mdthat tells agents to use the skillThe guidance
The new "Writing Style: Simple English" section in
AGENTS.mdapplies to replies, Markdown files, pull request descriptions, commit messages, and new code comments. It lists the rules that agents break most often. It also tells agents not to change code, generated files, or text that their task does not touch.CLAUDE.mdis a link toAGENTS.md, so Claude Code gets the same section.The hooks
A hook is a command that an agent tool runs at a fixed point, for example at the start of a session. All the hooks run one script,
.agents/skills/simple-english/scripts/hook.py. The hooks are advisory, so they never block an action..cursor/hooks.json.claude/settings.json.codex/hooks.jsonThe lint reports only the lines that differ from the last commit. For example,
README.mdhas 20 old violations today. If an agent adds one bad line, the hook reports that line only. A new file gets a full lint.Cursor also runs the hooks in
.claude/settings.json. For this case, the script finds the Cursor input and runs only the Cursor hooks. Cursor Cloud Agents do not run session start hooks, so they get the rules fromAGENTS.md.To turn off the hooks, set
SIMPLE_ENGLISH_HOOKS=off.A fix in the linter
The skill includes a linter,
scripts/ste_lint.py. In the upstream version, each line number after a code block or a table is too small. In this repository, the upstream linter put 34 hits on the wrong line, in 26 of the 33 Markdown files. The copy in this PR keeps the newlines, so all hits go to the correct line. The violation counts do not change.UPSTREAM.mdrecords this change and the steps to update the copy.Tests
scripts/test_hook.pyhas 15 tests. The tests cover these areas:CHANGELOG.mdTo run the tests, run
python3 .agents/skills/simple-english/scripts/test_hook.py. I also ran the hook on real files in this repository. I did not run the hooks in a live Cursor, Claude Code, or Codex session, because this environment has no credentials for those tools.Describe alternatives you've considered
We did not use the upstream hook scripts. The upstream scripts need the layout of a Claude Code or Codex plugin, and they do not support Cursor.
We did not add a Cursor stop hook for the reply report. A Cursor stop hook can only start a new agent turn, and that can cause a loop.
We did not lint the full file after each edit. The full lint told agents to correct old text that their task did not touch.
Additional context
The hooks need
python3. Codex runs project hooks only in a trusted project, and Codex asks you to approve each hook. Open/hooksin Codex to approve it.