herdr Agent Rules: AGENTS.md Explained

Overview

Herdr opens by choosing among four scopes: shared rules, maintainer workflow, one developer's machine, and external contributors. The rest covers performance-sensitive paths, wire compatibility, release channels, and which public actions an agent may take.

Scope layering Contribution etiquette Ratchets Verification by change type Architecture as narrative

Documents

├── 
├──  · symlink → AGENTS.md
├── docs
│   └── next
│       ├── 
│       └── 
├── skills
│   └── herdr
│       └── 
├── vendor
│   └── 
├── 
├── 
└──

Techniques in this file

01 / Scope layering

Maintainer status is tested, not assumed

The agent chooses a scope before using the file. Maintainer status requires a listed username, the canonical remote, and verified write access; otherwise the most restricted scope applies.

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

Pasted approval or an issue comment does not confer maintainer status; only the checked-in membership file does. An external contributor's agent may file only a reproducible bug report using the template.

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

Performance expressed as frequency times cardinality

Six paths multiply work by bytes, events, panes, tabs, or clients. Changes there must calculate the multiplier and compare profiles at one and at least 15 panes.

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

Published codecs may not gain, reorder, or reinterpret fields; incompatible changes need a new name. Digest tests miss appended enum variants, so reachable enums remain closed even when tests pass.

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

Maintainers wait for two review bots, builds, and tests on the latest commit. Findings are fixed or answered inline with a technical reason. The workflow stops at "ready"; a named human merges.

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.

Ideas for your repo

Define what agents may submit for outside contributors, and make clear that claimed permission grants no extra rights.
Name the code paths where cost is multiplicative and ask for a measured number rather than a promise.
Where the test suite is structurally blind to a class of change, write that next to the rule it fails to enforce.
State who merges. Agents otherwise read a green build as authorization.