docs: add AGENTS.md contributor and agent checklist - #57
Merged
Conversation
Collects what CI actually enforces on a pull request — branch pattern, conventional title, description minimum, issue reference, 50-file cap — in one place, alongside the repository conventions a change is expected to respect (hermetic builds, light-only, untrusted sub-app input, portability, contract stability, SHA-pinned actions). Calls out explicitly that the branch prefixes and the commit/PR title types are different sets: `perf` and `refactor` are valid titles but invalid branch prefixes, which is the easiest way to get a red PR on otherwise correct work. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QqFK6yffibtCBTF8xZ4hXW
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
AGENTS.md— a single mechanical checklist of what CI enforces on a pull request, plus the repository conventions a change is expected to respect. Written so a change lands green on the first CI run instead of the third.This is groundwork for the aggregated fix PRs that follow (#42–#56); every one of them will be held to this file.
Changes
AGENTS.md— new. Branch pattern, conventional title types, description minimum + issue reference, 50-file size cap, target branch. Then the three commands that must pass locally, and the conventions: hermetic-by-constructionapps.json, two modes / one document, light-only, sub-app HTML as untrusted input, portability (Node APIs over shelling out),contract/as a public API, SHA-pinned actions. Ends with rules for aggregated PRs, since the follow-up work groups issues by subsystem.CONTRIBUTING.md— points at it from the development-setup section.The one non-obvious thing it documents: the branch prefixes and the title types are different sets.
perf,refactor,style,buildandrevertpasstitle-typesbut are not inbranch-pattern, so aperf/…branch fails the check on otherwise correct work.Verification
Docs only — no code paths touched. Baseline confirmed green before branching:
npm run build:headless— 8 apps integratednpm test— 43 passed