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..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. 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.