AGENTS.md ยท diff

git:20261030.83e7861 to git:20261030.d6b324d

1 added, 1 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

# Rules for agents working on stampede
These rules apply to every agent that edits this repo: Claude, Codex, Cursor, Hermes, Grok Bot or any other. The rules for *running* a job with stampede are not here: they live in [SKILL.md](SKILL.md) and the skills it names.
The design is in [docs/superpowers/specs/2026-10-21-stampede-lean-design.md](docs/superpowers/specs/2026-10-21-stampede-lean-design.md). Read it before your first change.
## 1. The README is the product's front page. Keep it current at every step
- **Same commit:** any change to behaviour, commands, scripts, skills, front doors, the layout or the status updates README.md in that commit. It also updates every doc under `docs/` and `remote/` that the change affects.
- **Incomplete otherwise:** a change without its README update is not done.
- **True today:**
- Every claim, command and number in the README is true of the current code.
- Every command in it was run, against a scratch job folder with a fake Herdr when it would otherwise touch real panes.
- Anything not built yet goes under the roadmap, marked as planned.
- **Roadmap and status:** update them at every milestone: what works, what was tested, what is next.
- - **The cross-client suite:** any change to behaviour, a front door, a client or a worker kind updates, in that same commit, the suite (`tests/test_clients.py`, `tests/clients_run.py`) and [docs/CLIENTS.md](docs/CLIENTS.md) (its matrix, what differs, and the live runbook). A front door or a client is a row in `CLIENTS` and in that doc; a worker kind is an entry in `WORKERS` under each backend that takes it, with its refusal in `REFUSED` for one that does not. A client that does worse gets a finding there and a test marked as an expected failure.
+ - **The cross-client suite:** any change to behaviour, a front door, a client or a worker kind updates, in that same commit, the suite (`tests/test_clients.py`, `tests/clients_run.py`) and [docs/CLIENTS.md](docs/CLIENTS.md) (its matrix, what differs, and the live runbook). A front door or a client is a row in `CLIENTS` and in that doc; a worker kind is an entry in `WORKERS` under each backend that takes it, with its refusal in `REFUSED` for one that does not, and in `HANDED` when a Core job hands it to a Herdr TUI pane. A client that does worse gets a finding there and a test marked as an expected failure.
- **Standard:** short, true and complete. A stranger can understand, install, use, configure, troubleshoot and extend stampede from the README and its docs alone, with no questions to anyone.
### What the README and docs must cover
Shape the sections to fit the content; no template is fixed. Together, the README, `docs/`, `remote/` and the skills answer all of these:
- **What and why:** what stampede is, the problem it solves, and who it is for.
- **See it:** real screenshots of a run, with captions.
- **How it works:** the flow from ask to report and reopen, the roles (owner, front door, lead, workers, reviewer), and what lives where.
- **Every option:**
- Every front door: a Herdr chat, Claude, Codex or Cursor, Grok Bot (preferred bot), Moshi with any of them, or others.
- Every agent CLI the lead can start: Claude, Codex, Cursor.
- **Install:**
- Prerequisites, with versions.
- A copy-paste quick start.
- A full setup, and the setup per front door.
- **Use:** a walkthrough of one job, start to finish, with the actual commands and their output.
- **Configure:** every key in [config.example](config.example), with its default.
- **Safety:** every gate that needs the owner's yes, what never happens without asking, and how to reopen.
- **Troubleshoot:** known failures with their fixes, and an FAQ.
- **Reference:** every script, its flags and its exit codes. Also the repo layout.
- **Contribute:** how to add a front door or an agent CLI, and how to run the tests.
- **Roadmap, status and license.**
The README is the front door. It covers every point at least briefly, then links to the doc with the depth.
### Imagery and video
- **Images** go in `docs/images/`, 1800 px wide.
- Each is either a real screenshot or rendered from an HTML source in `docs/images/src/`, using `system.css` and `render.sh`, so it can be re-rendered.
- Each has alt text that says what it shows.
- Each caption says what is real, what is a mock-up, and the date.
- Keep only images a doc uses.
- Product marks go in `docs/images/logos/` as the owner's own SVG, each credited in its `SOURCES.md`.
- **Screenshots:** take them from real runs. Crop out personal details first.
- **Video:** the film assets stay as they are for now. The owner decides when to re-cut them, after significant progress.
- The poster and the teaser go in `assets/`.
- The master goes in a GitHub release, never in git.
### Before each commit that touches the README or docs
- `python3 -m unittest discover tests` passes. This includes `test_shape.py`: links, anchors, line limits, frontmatter, no em or en dashes, and no personal details (home paths, private paths, private names), in `docs/superpowers` too.
- Render the README the way GitHub does (`gh api markdown -F text=@README.md`) and look at it. Fix overflow, stacked badges and broken images.
## 2. The skills and the playbooks
- **Where they live:** the playbooks are `skills/` (the four skills) and `remote/` (the front-door guides).
- **The four skills are copies.** `skills/stampede`, `skills/herdr-fleet`, `skills/grokbot-herdr` and `skills/share-plan` come from the owner's own skills, which are their source. Change a skill there first, then copy it here and scrub it (section 3); never edit it here first. Only what makes the copy public (a scrubbed name or path, a setting with a default) differs from the source.
- **One context per agent:** every skill, guide and brief stands on its own. An agent gets only its own file plus its brief, never the whole repo.
- **Line limits:** a skill's `SKILL.md` at most 140 lines, every other playbook file at most 160 (`test_shape.py`).
- **Credit:** a linked role or skill from someone else names its owner, its license and a pinned commit.
- **No history or reasoning** in playbooks. Git keeps it.
- **One place per rule:** each rule lives in one file. Others link to it.
## 3. Open source hygiene
- **Nothing personal or secret:**
- No secrets, `.env` files, keys or tokens.
- No personal paths, names, hostnames, owner tags or private repo or skill names.
- The three skills herdr-fleet, grokbot-herdr and share-plan may be named (the owner's call, 21 Oct 2026).
- **Machine-specific settings** are environment variables listed in [config.example](config.example). Each has a default.
- **Scan before every push** for keys and personal details.
- **The repo is private until the owner says yes** to making it public.
## 4. Git
- Work on a branch and open a draft PR. Merging to main is the owner's call.
- Commit only your own change. Never commit caches, scratch files or media over 10 MB.
- Do not touch the owner's private skills repo from here; it is changed only in its own checkout, by the owner's own jobs.