From facc0935048a4f89e300bf23f8bda028eef7adf7 Mon Sep 17 00:00:00 2001 From: esko Date: Wed, 21 Oct 2026 13:19:36 +0300 Subject: [PATCH 1/2] docs: add an STE pass to the README rule After readme-generator writes a README.md, the simple-english skill makes one Simplified Technical English (STE) pass over its prose, in its default mode. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 5 +++-- CONTRIBUTING.md | 12 +++++++++--- DECISIONS.md | 1 + src/agents-block.md | 5 +++-- 4 files changed, 16 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 212f20d..e464343 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,8 +46,9 @@ the reasons, is CONTRIBUTING.md in the BuildexLabsAI/.github repository. - **Decisions** that the code and git log cannot show go in DECISIONS.md, one dated line each. - **README.md** is written with the readme-generator skill: its sections for the project type, plus the template's Run it locally, Deploy, Media and large files, First-time setup and Owner. - Run every command before it goes in and keep only the ones that work. Codex reviews it at high - reasoning effort before it reaches main. + Then the simple-english skill makes one Simplified Technical English (STE) pass over all prose, + in its default mode. Run every command before it goes in and keep only the ones that work. + Codex reviews it at high reasoning effort before it reaches main. - **Check before you push:** `bash .github/scripts/check-standard.sh`. CI runs the same check on every pull request. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8e151b0..1dcf5e4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -88,10 +88,12 @@ one, goes into DECISIONS.md the day it is made, as one dated line. ## README Every README.md is written with the -[readme-generator](https://github.com/b1rdmania/readme-generator) skill for Claude Code: +[readme-generator](https://github.com/b1rdmania/readme-generator) skill for Claude Code, then +checked with the [simple-english](https://github.com/AminBlg/SimpleEnglish) skill: ```bash git clone https://github.com/b1rdmania/readme-generator ~/.claude/skills/readme-generator +npx skills add AminBlg/SimpleEnglish -g -a claude-code -y ``` 1. **Sections.** The skill picks the sections for the project type: a Claude Code skill, a CLI @@ -100,9 +102,13 @@ git clone https://github.com/b1rdmania/readme-generator ~/.claude/skills/readme- First-time setup and Owner. The last four close the README in that order. Write "Not deployed." or "None." rather than drop one. A section the project needs beyond these, such as how to test or release it, stays. -2. **Every command runs first.** The skill does not run the README's commands. Run each command +2. **STE pass.** Run the simple-english skill once over all prose, in its default mode. It + applies the rules of ASD-STE100 Simplified Technical English (STE): short sentences, one + instruction per sentence, the condition before the command, active voice and one name for + one thing. Code, commands, paths and quoted output stay as they are. +3. **Every command runs first.** The skill does not run the README's commands. Run each command before it goes into the README and keep only the ones that work. -3. **Independent review.** Before the README reaches main, Codex reviews it at high reasoning +4. **Independent review.** Before the README reaches main, Codex reviews it at high reasoning effort against the code: every command, path, number and claim. Fix what blocks and review again until nothing blocking is left. diff --git a/DECISIONS.md b/DECISIONS.md index 7ec941a..f3bbc79 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -14,3 +14,4 @@ Choices that neither the code nor the git log shows, newest first. One line each - 2026-10-07: Branches that agent tools create (claude/, codex/) are accepted, because Claude Code names its worktree branches that way. - 2026-10-07: Folder and file names may contain the route symbols frameworks use ([slug], (group), @slot, $param, {-$optional}); UAE-SponSlot's TanStack Router routes need $. - 2026-10-16: Video, audio, PDF, Office files, design sources, archives and files of any size may be committed; the check rejects files by type only for secrets and operating system junk (images still stay out of the top level), and has no size limit, so GitHub's own 100 MiB block is the only ceiling. Esko lifted the 2026-10-07 ban because project repositories must hold their deliverables, such as a 9.6 MB client proposal PDF: PDFs and files over 5 MB "may and must be there". +- 2026-10-21: After readme-generator writes a README.md, the simple-english skill makes one Simplified Technical English (STE) pass over its prose, in the skill's default mode. Esko made this an organization rule, so the README reads the same whoever or whatever writes it. The default mode keeps domain words; the strict mode's dictionary rules make a README stiff for no gain. diff --git a/src/agents-block.md b/src/agents-block.md index 1544e32..7ac6eb8 100644 --- a/src/agents-block.md +++ b/src/agents-block.md @@ -26,8 +26,9 @@ the reasons, is CONTRIBUTING.md in the BuildexLabsAI/.github repository. - **Decisions** that the code and git log cannot show go in DECISIONS.md, one dated line each. - **README.md** is written with the readme-generator skill: its sections for the project type, plus the template's Run it locally, Deploy, Media and large files, First-time setup and Owner. - Run every command before it goes in and keep only the ones that work. Codex reviews it at high - reasoning effort before it reaches main. + Then the simple-english skill makes one Simplified Technical English (STE) pass over all prose, + in its default mode. Run every command before it goes in and keep only the ones that work. + Codex reviews it at high reasoning effort before it reaches main. - **Check before you push:** `bash .github/scripts/check-standard.sh`. CI runs the same check on every pull request. From 4f99c4e605d90babae229adb92100b0816a0ec93 Mon Sep 17 00:00:00 2001 From: esko Date: Thu, 22 Oct 2026 00:29:18 +0300 Subject: [PATCH 2/2] docs: list the STE decision first, as DECISIONS.md asks Co-Authored-By: Claude Opus 5.5 --- DECISIONS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DECISIONS.md b/DECISIONS.md index f3bbc79..738fdd9 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -2,6 +2,7 @@ Choices that neither the code nor the git log shows, newest first. One line each. +- 2026-10-21: After readme-generator writes a README.md, the simple-english skill makes one Simplified Technical English (STE) pass over its prose, in the skill's default mode. Esko made this an organization rule, so the README reads the same whoever or whatever writes it. The default mode keeps domain words; the strict mode's dictionary rules make a README stiff for no gain. - 2026-10-13: README.md is written with the readme-generator skill, in its sections for the project type plus the template's five, with every command run first and a Codex review before main. The skill gives every repository the same shape; running the commands and an independent review catch the false claims a confident author misses. - 2026-10-07: This repository is public, because GitHub only reads organization-wide default files from a public `.github` repository. - 2026-10-07: Hard enforcement waits for GitHub Team. GitHub Free has no rulesets or branch protection for private repositories, so the standard relies on agent instructions, local hooks and a CI check that warns; docs/enforcement.md holds the ruleset ready to switch on. @@ -14,4 +15,3 @@ Choices that neither the code nor the git log shows, newest first. One line each - 2026-10-07: Branches that agent tools create (claude/, codex/) are accepted, because Claude Code names its worktree branches that way. - 2026-10-07: Folder and file names may contain the route symbols frameworks use ([slug], (group), @slot, $param, {-$optional}); UAE-SponSlot's TanStack Router routes need $. - 2026-10-16: Video, audio, PDF, Office files, design sources, archives and files of any size may be committed; the check rejects files by type only for secrets and operating system junk (images still stay out of the top level), and has no size limit, so GitHub's own 100 MiB block is the only ceiling. Esko lifted the 2026-10-07 ban because project repositories must hold their deliverables, such as a 9.6 MB client proposal PDF: PDFs and files over 5 MB "may and must be there". -- 2026-10-21: After readme-generator writes a README.md, the simple-english skill makes one Simplified Technical English (STE) pass over its prose, in the skill's default mode. Esko made this an organization rule, so the README reads the same whoever or whatever writes it. The default mode keeps domain words; the strict mode's dictionary rules make a README stiff for no gain.