herdr-peers
AGENTS.md1 starsChanged 38 days agoMITView on GitHub
Entry point for AI agents working on this repository. A standalone agent skill for Herdr: any coding agent can ask any other agent, in any pane on any machine, and get the answer back — with an explicit reply grant, a loop guard, depth 1, and a record of every delegation. It builds on Herdr's official skill and never re-teaches its CLI. herdr-peers (skill + helper script) The protocol's interface version is metadata.protocol in SKILL.md; a wire change bumps it…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository3 other files it gives its agents.
- ai-diff-reviewerSkill
- deepworkplanSkill
- herdr-peersSkill
The file
We split this AGENTS.md into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 53
Never print, log or write the value of any *_API_KEY / *_TOKEN variable.
- Distinctive: line 54
Never spell a fetch-piped-to-shell install line in a skill file (marketplace rule E005).
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — herdr-peers
Entry point for AI agents working on this repository.
Purpose
A standalone agent skill for Herdr: any coding agent can ask any other agent, in any pane on any machine, and get the answer back — with an explicit reply grant, a loop guard, depth 1, and a record of every delegation. It builds on Herdr's official skill and never re-teaches its CLI.
Command / skill
herdr-peers (skill + helper script)
Layout
| Path | What |
skills/herdr-peers/ | The installable skill: SKILL.md, normative protocol.md, discipline.md, launcher.md, orchestra.md, the debate sub-skill debate.md, templates/ (incl. delegation-record.json schema and templates/debate/) |
skills/herdr-peers/scripts/ | The helper: herdr-peers (bash entry) + herdr_peers.py (python3 stdlib) + debate.py (the debate verb). It lives inside the skill so npx skills add installs it. |
bin/herdr-peers | Checkout shim that runs the skill's helper |
tests/ | run.sh (sandboxed runner), lib.sh, fakes/herdr, fakes/agentkit/ak, scopes/, fixtures/messages/, tools/ |
assets/ | README logos (logo-light.png, logo-dark.png) |
docs/ | TESTING_GUIDE.md, SECURITY.md (threat model) |
scripts/ | check-public-hygiene.sh (public-hygiene check; allow-list in .public-hygiene-allow), release-assets.sh (release notes + SHA256SUMS) |
.github/ | workflows/ci.yml (suite on Ubuntu + macOS, public hygiene job), workflows/release.yml (annotated tag → release), issue/PR templates, CODEOWNERS, dependabot.yml |
.agents/ | Working on this repo: agents/ (personas), commands/ (/dwp-* delegators), skills/ (vendored deepworkplan, ai-diff-reviewer — never hand-edit), docs/ (catalogs); .claude and .cursor link here |
.review/extension.md | Severity overrides for the local AI Diff Reviewer |
.dwp/config.json | Tracked DWP addon registry (the rest of .dwp/ is gitignored) |
| Root | README.md, CHANGELOG.md (Keep a Changelog), SECURITY.md (policy), CONTRIBUTING.md, CODE_OF_CONDUCT.md, CREDITS.md, LICENSE; CLAUDE.md is a symlink to this file |
The protocol's interface version is metadata.protocol in SKILL.md; a wire
change bumps it (and the major version, since 1.0.0). Keep protocol.md, the
helper constants and templates/ in step — the skill and templates test
scopes compare them.
Quick commands
| Scope | Command |
| Full | bash tests/run.sh |
| Scoped | bash tests/run.sh <scope> |
| Public hygiene | bash scripts/check-public-hygiene.sh |
| Release assets (local) | bash scripts/release-assets.sh vX.Y.Z <outdir> |
| DWP conformance | bash .agents/skills/deepworkplan/verify/conformance.sh |
Agents, commands and skills for working on this repo: .agents/docs/skills_agents_catalog.md. Local review: the vendored ai-diff-reviewer skill with .review/extension.md.
The test map lives in docs/TESTING_GUIDE.md.
Rules
- English for code, comments and docs; conventional commits.
- Runtime code depends on bash and the python3 standard library only.
- Never print, log or write the value of any
*_API_KEY/*_TOKENvariable; refer to variables by name. - Never spell a fetch-piped-to-shell install line in a skill file (marketplace rule E005); never inject a permission-bypass flag by default (E006); pin every cross-repo install to a tag (W012).
- Developing is not installing: tests run in a sandbox
HOME; nothing is installed into the real$HOMEwhile developing. - Pin every external tool by version.
- This repository is public: never commit personal absolute paths, private
organization or repository names, internal hostnames, or real credentials.
Secret-shaped test data says it is fake and is listed in
.public-hygiene-allowwith a reason. Never rewrite history; a leaked secret is rotated first. - Upgrading a vendored skill (
npx --yes skills add <repo>@<tag> --skill <name> --force -y) can also write copies intoagent/skills/and symlinks intoskills/; delete them —skills/ships onlyherdr-peers(therepotest scope checks it). - Changes land through a pull request with green CI; releases come from an
annotated
vX.Y.Ztag (.github/workflows/release.yml).
Deep Work Plans
Structured work runs through the installed deepworkplan skill (.agents/skills/deepworkplan/, pinned in skills-lock.json); the /dwp-* commands are thin delegators in .agents/commands/ (.claude and .cursor are symlinks to .agents/). Plans live in the gitignored .dwp/; only the addon registry .dwp/config.json is tracked (herdr enabled — this repository ships it; ai-diff-reviewer enabled for the local review).
DWP standard: 7.0.0 (onboarded 2026-10-08; upgraded 2026-10-09, 2026-10-11, 2026-10-12 and 2026-10-13; skill 7.8.1, vendored 2026-10-13)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

