AGENTS.md · git:20261114.65a1da1 · 2026-11-14 · sha256 8414adc5bfd2e7da

AGENTS.md git:20261114.65a1da1A

Immutable. This exact content never changes and is served at /api/v1/blob/8414adc5bfd2e7da.

# Rules for agents working on stampede

To run a job with stampede, read [USING.md](USING.md); the rules below are for changing this repo.

These rules apply to every agent that edits this repo: Claude, Codex, Cursor, Hermes, Grok Bot or any other.

The current contract is the [README](README.md) and [docs/CORE-NATIVE.md](docs/CORE-NATIVE.md). The original design, kept as history, is [docs/superpowers/specs/2026-10-21-stampede-lean-design.md](docs/superpowers/specs/2026-10-21-stampede-lean-design.md).

## 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, 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).
- **This repo is the one source.** `skills/stampede`, `skills/herdr-fleet`, `skills/grokbot-herdr` and `skills/share-plan` are changed here first, and every machine runs their code from a checkout through `install.sh` (`--replace` takes over an older install). What one owner wants and others do not is a setting with a default in [config.example](config.example), never a private edit; that owner's values live in their own config.
- **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.