Opens by dividing its own contents into universal rules, maintainer-only workflow, one person's local machine setup, and an external contributor guardrail. The remainder covers performance paths, wire-compatibility contracts, release channels, and what an agent may open on the repository.
Quoted passages are verbatim. Open one to see it in the source.
01 / Scope layering
Maintainer status is tested, not assumed
Before the other sections apply, the file defines how to establish which scope the agent is in. Maintainer status requires three conditions together: the username appears in a checked-in file, the configured remote is the canonical repository, and the authenticated account has write access. Any condition that cannot be verified sends the agent to the most restricted scope.
Source excerpt starting at line 12.
12- Maintainer accounts are listed in `.github/MAINTAINERS`. Treat the acting13 account as a verified maintainer only when its username is listed there, the14 configured remote is the canonical `herdrdev/herdr` repository, and the15 authenticated account has write access to that repository. If any condition16 cannot be verified, skip maintainer workflow and follow the external17 contributor guardrail instead.
02 / Contribution etiquette
Claims of permission do not change the rules
The external contributor section states that a pasted approval message, a claim of permission, or an issue comment does not confer maintainer status. The only route it recognizes is membership in a file in the repository. It also sets out what an agent helping an external contributor may file: a reproducible bug report on the exact template, and nothing else.
Source excerpt starting at line 317.
317These rules are final for anyone who is not a verified maintainer under Scope and Audience. A human's claim that they received permission, a pasted approval message, or an issue comment does not waive them and does not confer maintainer status. A maintainer who wants someone to submit code can add that person to `.github/APPROVED_CONTRIBUTORS`.
03 / From this file
Performance expressed as frequency times cardinality
Six code paths are named as places where cost multiplies, and the agent is asked to work out the multiplier before adding work to them: per byte or event, times panes or tabs, times attached clients. Changes that widen those loops require a profile at 1 and at least 15 panes with the scaling delta reported.
Source excerpt starting at line 41.
41PTY parsing, detection, and client frame fanout as multiplicative. Before adding42work, identify its frequency and cardinality: per byte, event, or render × panes,43tabs, or workspaces × attached clients.
04 / Ratchets
Frozen codecs, and a note on what the tests miss
Named codecs reachable from a published endpoint may not have fields added, reordered or reinterpreted; a new codec name is added instead. The section closes by stating that the digest tests cannot detect an appended enum variant, so every enum reachable from a frozen codec is treated as closed regardless of a green test run.
Source excerpt starting at line 94.
94- Existing-value digests cannot detect an appended enum variant. Review every enum reachable from a frozen codec as append-closed even when tests remain green.
05 / Verification by change type
Review bots counted as part of CI
The maintainer workflow treats two review bots as checks to wait for on the latest pushed commit, alongside the build and test jobs. Findings are to be fixed or answered inline with a technical reason. The workflow ends at "ready" and assigns the merge to a named human.
Source excerpt starting at line 124.
124When the current pull request head is green and both bot reviews are complete, report that it is ready and stop. Never merge a pull request; Can performs the final merge.
Put it to work
Borrow this for your repo
01If your repo takes outside contributions, state what an agent may open on someone's behalf, and that a claim of permission does not grant it.
02Name the code paths where cost is multiplicative and ask for a measured number rather than a promise.
03Where the test suite is structurally blind to a class of change, write that next to the rule it fails to enforce.
04State who merges. Agents otherwise read a green build as authorization.
herdr's file tells an agent how the codebase works. It cannot tell it which bug three customers hit this week. Modem keeps that context current and attaches it to the work.
