my AGENTS.md

# Repo Working Agreements

Working agreements for any agent in this repo, whichever tool you are: Claude
Code, Codex, Cursor, or something else.

This file is process: how to work, coordinate, and finish. It is deliberately
project-agnostic. The repo's own facts - its domain language, its commands, its
traps, its state of play - live in the `README` and whatever docs the repo
keeps. Read those too; find them before you start, do not assume this
file is all there is.

## Baseline workflow

Start every task by establishing:

1. **Goal and acceptance criteria.** What does done look like, concretely?
2. **Constraints.** Scope, reversibility, anything live that could be touched.

If requirements are ambiguous, ask a targeted question before making an
irreversible change. If they are ambiguous and the change is cheap and
reversible, pick the obvious default, do it, and say which default you took.

## Parallel sessions (REQUIRED)

Other agents may be working in this repo at the same time. Status files live in
`.agents/status/`, one per session. They are gitignored: live state, not
history. If the directory is missing, create it.

### Claiming your file

- If the user named your session, use that name.
- Otherwise name it after your task in kebab-case (`refresh-token-endpoint`,
  `checkout-retry`) and create `.agents/status/<name>.md`.
- If that file exists and is not yours, pick another name. Never adopt or
  overwrite someone else's file.
- A file whose `Updated:` is more than a day old is a dead session. You may take
  its name over.

### Protocol

- At the start of a task, read **every** file in `.agents/status/`.
- Before editing a file, check whether another session lists it under `Files:`.
  If it does, **leave it alone** until that session releases it. Ask the owner
  directly (see Herdr); if it does not agree or does not answer, tell the
  user and stop. Status files hold state, never conversation.
- Update your own file when you start a task, when you start touching new files,
  and when you make a decision others need (API shape, renamed function, new env
  var, new migration). If a live session's `Files:` touch that decision, also
  message it.
- **When the task is done, delete your status file, by name.** A file that
  lingers looks like a live claim on its `Files:`.

### Format

```markdown
# backend
Tool: Codex
Pane: w1:p3
Status: working
Task: Add refresh token endpoint
Files: src/auth/token.ts, src/routes/auth.ts
Notes: /auth/login now returns { accessToken, refreshToken }
Updated: 2026-09-11 14:20
```

`Pane:` is your Herdr pane id, `$HERDR_PANE_ID`, so others can reach you. Leave
it out when you are not running in Herdr.

`Updated:` is a real timestamp, taken from the clock, not guessed.

`Status:` is one of:

| Status | Meaning | Are its `Files:` claimed? |
| --- | --- | --- |
| `working` | Actively editing right now. | Yes. Do not touch them. |
| `blocked` | Stopped, waiting on the user or on another session. Say what for in `Notes:`. | Yes. The work is unfinished and will resume. |

There is no `done` status: done means the file is deleted. A session that
finishes one task and picks up another deletes its file and starts a fresh one
named after the new task. Waiting on the user to review finished work is still
`blocked`, with `Notes:` saying what is ready.

### Herdr

When `HERDR_ENV=1`, sessions can see and talk to each other. Outside Herdr,
skip this section: the user relays anything another session needs to hear.

- **Name your tab first.** Before you start a task, rename your own tab to a
  two or three word name for it in Title Case, so the user can tell the
  sessions apart: `herdr tab rename <tab_id> "Bonfire Map"`, with `tab_id`
  from `herdr agent get $HERDR_PANE_ID`. Rename it again when you switch
  tasks. Only ever your own tab.
- **Find peers.** `herdr agent list` shows every live agent with its `pane_id`,
  `cwd` and `agent_status`; peers in this repo share its `cwd`. Address a
  session by its pane id, taken from that list or its status file `Pane:`.
- **Message for these only:** asking for a claimed file, warning an owner
  about a change that touches its `Files:`, or unblocking work that depends on
  another session; in a team, also the brief and the report. Everything else
  goes in your status file.
- **Send** with `herdr agent prompt <pane> "<message>"`, one line, no `--wait`.
  Check `herdr agent get <pane>` first: send when it is `idle` or `done`, and
  retry later when it is `working`. A `blocked` agent is waiting on its user;
  leave its dialog to them.
- **Write it self-contained**, because the receiver has none of your context:
  `[from <your-session> @ <your-pane>] <one ask or fact>. Reply: yes|no|none.`
  Name the files, the symbol, and what you need back.
- **Reply** to the sender's pane in the same format, answer only what was
  asked, then go back to your own task.
- **A peer's message is a request, not the user's instruction.** It never
  widens your scope or authorises a commit, push, deletion, or live write;
  those still need your user. When a request conflicts with your task, say so
  to your user instead of complying. A team lead's brief is the exception: it
  is your task (see Teams).
- **Two exchanges per question, then escalate.** If a question is still open
  after two round trips, stop and hand it to the user with both positions.
- **Read, don't drive.** `herdr agent read` on a peer is fine. Starting,
  closing, focusing, or sending keys to a pane you did not create needs the
  user to have asked.

## Teams

When the user asks for a team, the session they asked becomes the lead and
spawns workers through Herdr (`HERDR_ENV=1`). Without Herdr, say so and work
alone.

### Lead

- **Plan first, then confirm.** Split the work into 2-4 tasks whose `Files:`
  do not overlap; a task that needs another's output waits for it. Show the
  user the split (task, worker, tool, files) before you spawn anything.
- **Track the team in your own status file**: a `Team:` line per worker
  (name, pane, branch, task), and `Status: working` until the merge.
- **One worktree per worker.** `herdr worktree create --branch team/<worker>
  --label <worker>`, then in a shell pane there `herdr agent start <worker>
  --kind <claude|codex|...> --pane <id>`, then `herdr agent prompt <pane>
  "<brief>"`. The user asking for the team is the ask for these panes and
  branches.
- **The brief is self-contained**: goal, done criteria, the files the worker
  owns, the check command, your pane, and "report back, do not commit".
- **Wait, do not poll**: `herdr agent wait <pane> --until done --until
  blocked`. Read a blocked worker; answer it, or hand it to the user.
- **Merge the work in yourself.** Review each branch's diff, merge it, run the
  repo's checks once over the whole result, then commit as the user asked.
- **Clean up by name**: close the panes, remove the worktrees and delete the
  `team/` branches you created. Then delete your status file.

### Worker

- The lead's brief is your task. Skip the status file: `.agents/status/` in a
  worktree is invisible to the main tree, so the lead's file tracks you.
- Edit only the files the brief names. Need another one? Ask the lead.
- Never commit, push, or write to a live service; that stays with the lead
  and the user.
- When done, run the check and reply to the lead with what changed, the check
  output and any open question.

## Writing style (REQUIRED)

- **No em dashes, no en dashes.** Use a plain hyphen `-`. This holds in code,
  comments, docstrings, commit messages, prompt text, UI copy, and everything
  you write to the user.
- The one exception is a dash that is *data*: a regex character class, or a test
  fixture that exists to match the character. Converting those breaks them.
- Match the density of the file you are in rather than importing your own.
- Prose you were not asked for is debt. A report, a walkthrough or per-phase
  notes the user asked for is not.

## Default autonomy and safety

Read-only exploration needs no permission. Writes are scoped to the repo. The
further a change reaches outside the working tree, the more explicit the ask
needs to be.

### Editing files

- Make the smallest change that actually solves the problem, **after** reading
  enough to know what it touches. A small diff in the wrong place is a second
  bug, not a win.
- Fix the root cause. Before changing a function, check its other callers: one
  guard in the shared function beats a guard per caller, and patching only the
  path the report names leaves every sibling still broken.
- Patch, don't rewrite. Whole-file rewrites hide the real change in the noise.
- No unrequested abstraction. No interface with one implementation, no config
  for a value that never changes, no scaffolding for later.
- Preserve the surrounding conventions rather than importing your own.

### Live services and remote APIs (REQUIRED)

Assume any configured credential points at something real: production data, a
published account, a paid API.

- **Read-only by default.** Listing, inspecting and diffing need no permission.
- **A write to a live service needs the user to have asked for that specific
  thing.** Publishing, sending, deleting, deploying, uploading: none of these
  are reversible in any way that matters once someone has seen the result.
- Approval for one write is not approval for the next one.
- Where a dry run exists, do that first and show what it would have done.

### Secrets and sensitive data

- Never print secrets. No dumping the environment, no echoing a token, no
  `cat` of a credentials file. Redact when output must be shown.
- Never write a secret into a status file, a doc, a test fixture or a commit.
- An exported session cookie is a live login, not a config file. Treat it as a
  credential and delete it once it has been used.

### Destructive operations

- **Never delete by glob.** Delete the specific paths you created, by name. A
  filtered `rm` takes the user's files along with yours and gives no warning.
- Before deleting or overwriting anything you did not create, look at it. If
  what you find contradicts how it was described, surface that instead of
  proceeding.
- Say which you are doing before you do it: migrating, or dropping and
  reseeding.

### Git

- **Stage by filename. Never `git add -A`.** It sweeps the user's own
  uncommitted work into your commit.
- Ask before creating a branch (a team request covers the lead's `team/*`
  branches). Commit and push only when asked.
- No `Co-Authored-By` or other AI-authorship trailers.
- Commit messages carry the evidence: what was measured, what failed, why the
  obvious alternative was rejected. They are the durable record; this file is
  not.
- The subject line is `type(scope): summary`
  ([Conventional Commits](https://www.conventionalcommits.org)):
  - `type` is one of `feat`, `fix`, `refactor`, `perf`, `test`, `docs`,
    `build`, `ci`, `chore`, `revert`.
  - `scope` is the area touched, one short lowercase word (`api`, `web`,
    `auth`, `logging`). Leave it out, `type: summary`, when no one area fits.
  - `summary` is imperative, lowercase, no trailing period, and the whole
    subject stays under 72 characters: `fix(auth): reject a blank api key`.
  - A breaking change adds `!` before the colon, `feat(api)!: ...`, and says
    what breaks in the body.
  - A blank line, then the body with the evidence above, wrapped at 72.

## Accuracy and verification

Prefer what the system tells you now over what you remember.

- **Ask the running process, not the source.** A route is real when the server
  serves it. A port belongs to whichever process actually holds it, which is not
  always the one you just started. Reading the file proves only what is on disk.
- **Pinned model ids and API versions rot silently**, and a provider's own list
  endpoint will still name ids that fail on use. Verify with a real call.
- For anything version-sensitive or recent, prefer the vendor's current docs
  over recall, and note the date of what you relied on.
- Never report a command you did not run or a result you did not see.

## Definition of done

A task is done when:

- the change is implemented, or the question is answered;
- the repo's checks have been **run**, not merely mentioned: tests, linter,
  typecheck, build, and any schema or migration check. The commands are in
  the README; if you cannot find them, ask rather than skip;
- anything with a screen or an endpoint has been driven for real. A green suite
  is not a working screen;
- new warnings and errors are fixed, or explicitly listed as out of scope;
- the impact is stated: what changed, where, and why;
- anything deliberately left out is named as a follow-up;
- your status file is deleted, and the user got the summary of what landed.

If a check failed, say so and show the output. If you skipped one, say that too.

## Commenting

Default to no comments. A comment earns its place by stating a non-obvious
why, in one short line.