diff --git a/AGENTS.md b/AGENTS.md index 8c0bbef..f57443f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,6 +44,10 @@ the reasons, is CONTRIBUTING.md in the BuildexLabsAI/.github repository. `feat(api): add athlete height endpoint`. Pull requests are squash-merged, so the title becomes the commit on main. - **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. - **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 eff8b0a..b717acc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -83,6 +83,27 @@ prisma # Prisma reads its schema from a folder at the root A choice that the code and the git log cannot show, such as why this library and not that 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: + +```bash +git clone https://github.com/b1rdmania/readme-generator ~/.claude/skills/readme-generator +``` + +1. **Sections.** The skill picks the sections for the project type: a Claude Code skill, a CLI + tool, a package, a script collection or another kind of repository. Every README also keeps + the five sections of the repo-template README: Run it locally, Deploy, Media and large files, + 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 + 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 + effort against the code: every command, path, number and claim. Fix what blocks and review + again until nothing blocking is left. + ## New repositories 1. Create the repository from @@ -92,7 +113,8 @@ one, goes into DECISIONS.md the day it is made, as one dated line. ```bash gh api -X PATCH repos/BuildexLabsAI/ -F allow_squash_merge=true -F allow_merge_commit=false -F allow_rebase_merge=false -F delete_branch_on_merge=true -f squash_merge_commit_title=PR_TITLE -f squash_merge_commit_message=PR_BODY ``` -3. Fill in README.md and AGENTS.md: what it is, the commands, the sanity check. +3. Write README.md as [README](#readme) says, and fill in AGENTS.md: the commands and the + sanity check. 4. In every clone, once: `git config core.hooksPath .github/hooks` ## The check diff --git a/DECISIONS.md b/DECISIONS.md index 1b962a9..a940e87 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-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. - 2026-10-07: All code lives in src/ whatever the framework (Next.js src/app/, Vite src/, Python src//), so the top level is identical in every repository. diff --git a/README.md b/README.md index faa1cc3..28b863f 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,122 @@ # BuildexLabsAI/.github -The BuildexLabsAI organization's shared defaults and its repository standard. - -- **Defaults for every repository.** GitHub shows [CONTRIBUTING.md](CONTRIBUTING.md), - [SECURITY.md](SECURITY.md) and the [pull request template](.github/pull_request_template.md) - in every BuildexLabsAI repository that has none of its own. GitHub only reads these defaults - from a public `.github` repository, so this one is public. Nothing secret belongs here. -- **The standard.** CONTRIBUTING.md is the full rulebook. - [src/agents-block.md](src/agents-block.md) is the short version that every repository's - AGENTS.md carries for AI agents. -- **The check.** [src/check-standard.sh](src/check-standard.sh) enforces the rules. Every - repository runs it in three places: the Claude Code hook (when Claude creates a file), the git - pre-commit hook, and CI through the shared workflow - [.github/workflows/standard-check.yml](.github/workflows/standard-check.yml). -- **Enforcement.** [docs/enforcement.md](docs/enforcement.md) says what is enforced where, and - how to switch on hard enforcement when the organization moves to GitHub Team. +The BuildexLabsAI organization's default community files, its repository standard, and the +check that enforces the standard in every repository. -New repositories start from [BuildexLabsAI/repo-template](https://github.com/BuildexLabsAI/repo-template). +## What it does + +- GitHub shows [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md) and the + [pull request template](.github/pull_request_template.md) in every BuildexLabsAI repository + that has none of its own. GitHub reads these defaults only from a public `.github` repository, + so this one is public and holds nothing secret. +- [CONTRIBUTING.md](CONTRIBUTING.md) is the full standard. [src/agents-block.md](src/agents-block.md) + is the short version that every repository's AGENTS.md carries for AI agents. +- [src/check-standard.sh](src/check-standard.sh) enforces the standard in three places. The + Claude Code hook and the git pre-commit hook run each repository's copy at + `.github/scripts/check-standard.sh`. CI runs the current check from this repository's main: + +```mermaid +flowchart TD + S[src/check-standard.sh on main] -- copy --> R[Each repository] + R -- Claude Code creates a file --> H[Claude Code hook: blocks a name that breaks the rules] + R -- git commit --> P[pre-commit hook: blocks bad new names, media, files over 5 MB] + R -- pull request or push to main --> C[standard-check.yml: whole repository, pull request title, secret scan] + S -- current check --> C + C -- compares the repository's copies with src/ --> W[Warning when a copy is out of date] +``` + +## What it doesn't do + +- Does not block a merge on GitHub Free. CI shows a red X and merging still works. + [docs/enforcement.md](docs/enforcement.md) says how to switch on hard enforcement with GitHub + Team. +- Does not update the copies in other repositories. A rule merged here applies in every + repository's CI at once, while the hooks keep running the old copy until someone replaces it. +- Does not fix files. The check reports problems and changes nothing. + +## Run it locally + +```bash +git clone https://github.com/BuildexLabsAI/.github.git +cd .github +bash tests/check-standard.test.sh +bash .github/scripts/check-standard.sh +``` + +The tests build throwaway repositories and run the check against them. In this repository +`.github/scripts/check-standard.sh` is a link to `src/check-standard.sh`, so the hooks run the +file every other repository copies. + +CI runs the check with `--canonical`, which also compares this repository's AGENTS.md block with +`src/agents-block.md`, and lints the scripts with ShellCheck: + +```bash +bash src/check-standard.sh --canonical src +``` + +The tests and the Claude Code hook need `jq`. Without it, the hook skips the file-name check and says so. ## Changing the standard 1. Open a pull request here. Change the rule in `src/check-standard.sh` and add a test to - `tests/check-standard.test.sh` that fails without the change. If agents need to know the - rule, update `src/agents-block.md` and CONTRIBUTING.md in the same pull request. -2. After the merge, CI warns every repository whose copies are out of date. Update - BuildexLabsAI/repo-template first: copy `src/check-standard.sh` to - `.github/scripts/check-standard.sh` and the new block into AGENTS.md. + `tests/check-standard.test.sh` that fails without the change. If agents need to know the rule, + update `src/agents-block.md`, the block in this repository's AGENTS.md and CONTRIBUTING.md in + the same pull request. +2. After the merge, update BuildexLabsAI/repo-template first, so new repositories start current. + With both repositories cloned side by side, run this from this one: + + ```bash + cp src/check-standard.sh ../repo-template/.github/scripts/check-standard.sh + awk 'NR == FNR { block = block $0 "\n"; next } + /buildexlabs-standard:start/ { printf "%s", block; skip = 1 } + !skip { print } + /buildexlabs-standard:end/ { skip = 0 }' src/agents-block.md ../repo-template/AGENTS.md > AGENTS.md.new + mv AGENTS.md.new ../repo-template/AGENTS.md + ``` + +3. Check the copies from repo-template. The run must end with 0 warnings: + + ```bash + cd ../repo-template + bash .github/scripts/check-standard.sh --canonical ../.github/src + ``` + +A new rule applies in every repository's CI as soon as it is merged. CI also warns in each +repository until someone updates its copies the same way. + +## Project structure + +``` +CONTRIBUTING.md the full standard; GitHub shows it in every repository without its own +SECURITY.md how to report a security problem; shown the same way +src/check-standard.sh the canonical check +src/agents-block.md the rules block every repository's AGENTS.md copies +tests/ tests for the check +.github/workflows/ standard-check.yml, the shared CI workflow; standard.yml, this repository's CI +.github/hooks/pre-commit runs the check on the files you commit +docs/ what is enforced where, and the ruleset to switch on with GitHub Team +``` + +New repositories start from [BuildexLabsAI/repo-template](https://github.com/BuildexLabsAI/repo-template). + +## Deploy + +Not deployed to a server. Merging to main is the release: GitHub shows the new default files at +once, and every repository's CI runs `standard-check.yml` and the check from this repository's +main branch. + +## Media and large files + +None. + +## First-time setup + +Once per clone, switch on the check that runs before every commit: + +```bash +git config core.hooksPath .github/hooks +``` + +## Owner -Run the tests with `bash tests/check-standard.test.sh`. +@eskokoivula diff --git a/src/agents-block.md b/src/agents-block.md index 530d613..5dc30ca 100644 --- a/src/agents-block.md +++ b/src/agents-block.md @@ -24,6 +24,10 @@ the reasons, is CONTRIBUTING.md in the BuildexLabsAI/.github repository. `feat(api): add athlete height endpoint`. Pull requests are squash-merged, so the title becomes the commit on main. - **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. - **Check before you push:** `bash .github/scripts/check-standard.sh`. CI runs the same check on every pull request.