@ethlete/agent-rules 0.1.0-next.3 → 0.1.0-next.31

package/content/output-styles/ste-clarity.md

@@ -0,0 +1,131 @@
+---
+name: ste-clarity
+description: Write all prose in ASD-STE100 Simplified Technical English — approved words, simple verb forms, active voice, one idea per sentence.
+keep-coding-instructions: true
+---
+
+# ASD-STE100 output style
+
+Write every sentence you show the user in Simplified Technical English, as specified
+by ASD-STE100. Clarity comes first. Never sacrifice technical accuracy for brevity.
+
+## Scope
+
+Apply STE to your own prose: answers, explanations, plans, summaries, commit
+messages, and pull request text.
+
+Do not apply STE to:
+
+- Code, identifiers, file paths, and command names.
+- Quoted material: error messages, log lines, command output, and text from files.
+  Copy these exactly. Never rewrite a quote to make it simpler.
+- Text the user asks you to write in a different style.
+
+Markdown is still available. Use code blocks, and use `file.ts:42` references.
+
+## Words
+
+1. Use the most common, shortest word that has one clear meaning.
+2. Use one word for one meaning. Do not use synonyms for the same thing. If you
+   write "flag" for a variable, do not later call it a "switch" or an "option".
+3. Use one meaning for one word. Do not use "close" for both a state and an action
+   if this can confuse the reader.
+4. Technical names are permitted. Use the exact name from the code or the domain.
+5. Do not use slang, idioms, or figures of speech. "The build blew up" is wrong.
+   "The build failed" is correct.
+6. Do not use "etc." Complete the list, or write "for example" and give two items.
+7. Do not use a noun as a verb. Write "make a request", not "request it", when
+   "request" is a name in the code.
+
+Prefer the word on the right:
+
+| Not approved             | Use               |
+| ------------------------ | ----------------- |
+| utilize, employ          | use               |
+| initiate, commence       | start             |
+| terminate                | stop, end         |
+| perform, execute         | do, run           |
+| modify                   | change            |
+| indicate                 | show              |
+| ascertain, determine     | find, find out    |
+| assist, aid              | help              |
+| attempt                  | try               |
+| require                  | need              |
+| sufficient               | enough            |
+| additional               | more              |
+| numerous, multiple       | many              |
+| approximately            | about             |
+| currently, presently     | now               |
+| prior to                 | before            |
+| subsequent to, following | after             |
+| in order to              | to                |
+| due to the fact that     | because           |
+| via                      | with, by, through |
+| such as                  | for example       |
+| in the event that        | if                |
+| at this point in time    | now               |
+
+This table is a guide, not the full ASD-STE100 Dictionary. The Dictionary holds about
+900 approved words, each with one approved part of speech and one approved meaning.
+When you do not know if a word is approved, choose the shortest common word that has
+one clear meaning.
+
+## Verbs
+
+1. Use only these verb forms: the infinitive, the imperative, the simple present, the
+   simple past, the simple future, and the past participle as an adjective.
+2. Do not use complex tenses. Write "I changed the config", not "I have changed the
+   config".
+3. Do not use "-ing" forms, unless the form is part of a technical name, for example
+   "a logging module".
+4. Use the active voice. Write "the parser drops the field", not "the field is dropped
+   by the parser". Use the passive voice only when the actor is unknown or does not
+   matter.
+5. Do not leave out a verb to make a sentence shorter.
+
+## Noun phrases
+
+1. Do not build a cluster of more than three nouns. Break up "user account balance
+   sync failure" as "a failure in the sync of the user account balance".
+2. Add articles ("a", "the") where they help the reader.
+
+## Sentences
+
+1. Instructions: 20 words maximum.
+2. Descriptions: 25 words maximum.
+3. One idea per sentence. One instruction per sentence.
+4. A paragraph holds 6 sentences maximum, and covers one topic.
+5. Put a condition at the start of the sentence, before the instruction. Write "If the
+   sync fails, restart the server".
+6. Use connecting words such as "however", "therefore", and "then" to show the link
+   between sentences.
+7. Use a vertical list when the content has more than three parallel parts. Do not use
+   a list to give structure to a single idea.
+
+## Procedures
+
+1. Use the imperative for each step. Write "Open the file", not "You should open the
+   file" or "We can open the file".
+2. Number the steps in the order the user must do them.
+3. Give the result after the action, if the result is not obvious.
+
+## Warnings
+
+1. Put a warning or a caution before the step it applies to, never after.
+2. Start the warning with a clear command. Write "Do not run this on the production
+   database. The command deletes all rows."
+3. State the consequence in a separate, simple sentence.
+
+## Punctuation
+
+1. Do not use a slash to mean "and" or "or". Write "the date or the payee".
+2. Do not use parentheses for information the reader needs. Put it in its own sentence.
+3. Do not use a dash to join two thoughts. Use two sentences.
+4. Use a hyphen only to make a compound word clear.
+
+## When STE and accuracy conflict
+
+Accuracy wins. If a simple word would hide a real distinction, use the exact term and
+define it once in a short sentence. Never simplify a claim about what the code does.
+Keep the difference between what you verified and what you assume: write "I ran the
+tests and they passed" or "I did not run the tests", not a sentence that blurs the two.

package/content/rules/agent-sessions-wake-up.md

@@ -0,0 +1,11 @@
+---
+name: agent-sessions-wake-up
+description: A prompt that says "New mailbox message for <name>" means run the inbox command in it and act on the result; read the agent-sessions skill before you edit a file another agent may edit.
+kind: rule
+scope: both
+---
+
+## Agent sessions
+
+If a prompt says `New mailbox message for <name>`, run the `inbox` command in that prompt and act on
+the messages. Before you edit a file that another agent may edit, read {% skill:agent-sessions %}.

package/content/rules/app-styling.md

@@ -0,0 +1,66 @@
+---
+name: app-styling
+description: App components are styled with Tailwind utilities in their templates; app CSS stays out of @layer components; the SDK needs a 10px rem root; hardcoded colours are never primary values.
+kind: rule
+scope: consumer
+requires: ['@ethlete/core']
+---
+
+## Styling
+
+Every component in this workspace (views, pages, shells, shared UI in `libs/`) is laid out
+and styled with **Tailwind utility classes in its template**, including the colour utilities
+the app's theme provides: the generated SDK theme utilities (`bg-et-surface-bg`,
+`border-et-surface-border`, `text-et-<theme>`) where the app generates them, or the palette its
+Tailwind config defines. Do not
+invent a BEM class system, and do not write a `.css` file for layout, spacing or
+typography a utility expresses. Every app component sets `encapsulation: ViewEncapsulation.None`,
+as the `require-view-encapsulation-none` lint rule requires. Its CSS is then global, so give the
+component a host class (`host: { class: 'app-player-card' }`) and scope every selector under it,
+the way SDK components scope theirs under their `et-` classes. Never write a bare element or
+unprefixed class selector in a component stylesheet.
+
+In an existing repo, convert a component's styles whenever you change any of its files (class,
+template, template-bound logic or CSS), not only its styles; if the conversion is large, ask the
+user first. A legacy component that relies on emulated encapsulation keeps it until its CSS is
+scoped under a host class: without that scope, `ViewEncapsulation.None` leaks its CSS into every
+view.
+
+If the repo as a whole breaks this section (global classes in `styles.css`, hardcoded colours),
+tell the user once at first contact, with the size of the conversion (files, classes, hardcoded
+colours), and record it as owed work in the plan or handoff. Never skip it silently. This holds
+for a deviation from any rule here: report it once and record it.
+
+Write CSS only for what utilities cannot express. With Tailwind 4, keep that CSS **unlayered**
+or in `@layer utilities` — never in `@layer components`, and that includes the global
+stylesheet. SDK component styles are injected into `@layer components` at runtime, after your
+stylesheet, so an app rule in the same layer ties on layer and loses on source order. With
+Tailwind 3, `@layer` is a Tailwind directive that emits unlayered CSS, so app CSS already beats
+the SDK's layered styles.
+
+To change an SDK component's look, set its `--et-*` tokens first (documented per
+component), then use a utility class or unlayered CSS on the element — see "Overriding
+component styles" in the docs site's components overview.
+
+The SDK sizes everything in `rem` on a **10px root**: the app's global stylesheet must set
+`html { font-size: 62.5%; }`. Without it every SDK control renders 1.6× too large. With it,
+`1rem` is `10px`, so the app's own `rem` values stay easy to read.
+
+The 10px root also shrinks every rem-based Tailwind scale to 62.5% of its nominal size (1.6×
+smaller): `p-4` is 10px instead of 16px, and `max-w-3xl` is 480px instead of 768px. Keep the
+spacing scale on its 4px step: with Tailwind 4, set `--spacing: 0.4rem` in the app's `@theme`,
+as the SDK's own Storybook does; with Tailwind 3, redefine `theme.spacing` in
+`tailwind.config`. In an app that already uses utilities without it, the change rescales every
+view: tell the user rather than make it. Redefine any other rem scale the app uses (text,
+container, radius) the same way, or use px where a size matters. Breakpoints are not affected:
+a media query's `rem` ignores the root font size.
+
+**Never use a hardcoded colour as the primary value.** Backgrounds, text, borders and
+interaction states resolve from the app's theme: the SDK surface and colour tokens
+(`--et-surface-*-solid`, `--et-theme-color-*`) and their generated utilities, or the palette
+the app's Tailwind config defines. Never write an arbitrary colour value such as
+`bg-[#1a1a1a]` in a template. A static fallback inside `var(--token, <fallback>)` is
+permitted, but not required.
+
+Theme **names** (`brand`, `danger`, `dark-elevated`, …) are registered by this app; the SDK
+ships none. Semantic colours resolve by theme `type` (e.g. `injectSemanticColorTheme('error')`).

package/content/rules/comments.md

@@ -20,6 +20,8 @@ smaller function, or a type; fix that instead of narrating it.
    limitation) and linking it where a link exists, so the next reader can tell when it may go.
 4. **Public API JSDoc** — what it does and how to call it, on something a lib actually
    exports. One or two sentences. Not internals, not history, not why it is shaped that way.
+   In an application nothing is public API unless it lives in a shared lib other projects
+   import, so this case rarely applies to app code.
 
 Nothing else qualifies. Not "this is subtle", not "worth noting", not a heading over a group
 of members, not a summary of the function underneath it.
@@ -43,7 +45,8 @@ years.
   annotation, a factory instead of a literal, a helper moved into its own file. The type, the
   annotation and the import already say what happens.
 - **Migration narration** — "moved here from X", "used to be a tuple", "so Y no longer pulls
-  Z", "renamed for clarity". Git knows; the next reader does not care.
+  Z", "renamed for clarity", "see ADR-0012". Git and the ADR index know; the next reader does
+  not care.
 - **The same explanation at every call site.** Explain a pattern once where it is defined (the
   helper's JSDoc, the lint rule's message, the guide) and let every use site stay silent.
 - **Commented-out code.**

package/content/rules/lint-and-format.md

@@ -1,6 +1,6 @@
 ---
 name: lint-and-format
-description: Run lint with --fix before fixing anything by hand, and format every edited file.
+description: Run lint with --fix before fixing anything by hand, and format every edited source file Prettier supports.
 kind: rule
 scope: both
 vars: [lintCommand, lintFixCommand, formatCommand]
@@ -12,14 +12,16 @@ Run lint with `--fix` — most styleguide rules in `@ethlete/eslint-plugin` ship
 so let them do the work before correcting anything by hand:
 
 ```bash
-{%lintFixCommand%}   # auto-fixes first (case, ordering, $ suffix, metadata, …)
+{%lintFixCommand%}   # auto-fixes first (case, ordering, metadata, …); rename to the $ suffix by hand
 {%lintCommand%}      # then re-run to see what needs a manual fix
 ```
 
-For the judgment calls lint cannot enforce — signals vs RxJS, templates, lifecycle and DI
-patterns — see {%skill:styleguide%}.
+For judgment calls lint cannot enforce, load the repository's focused guidance for the
+code you are changing.
 
-After editing any file, format it before wrapping up:
+Format every edited Prettier-supported source file before wrapping up, in one call over all of
+them, not one call per file. Do not send binary,
+generated, or unsupported files to this command:
 
 ```bash
 {%formatCommand%}

package/content/rules/nx-layout.md

@@ -0,0 +1,50 @@
+---
+name: nx-layout
+description: Nx workspace layout - thin apps, feature code in libs grouped by kind, path-mirroring aliases, scope tags.
+kind: rule
+scope: consumer
+requires: ['nx']
+---
+
+## Nx workspace layout
+
+Apps are thin shells. All feature code lives in libs, grouped by kind, not by Nx type:
+
+```text
+apps/<app>/src/app/        app.component.ts, app.config.ts, app.routes.ts only
+libs/
+  domain/<app>/            one lib per app
+    src/lib/<feature>/     views, components, services, <feature>.routes.ts
+    src/lib/shared/        code shared by the app's features (optional)
+  queries/                 query clients and creators, one folder per backend
+  types/                   API models and shared types
+  uikit/                   app-agnostic presentational components
+  theme/                   surface and colour themes
+  env/                     environment.ts, environment.production.ts
+  assets/                  fonts, icons, images
+```
+
+- Each feature folder exports its own `<FEATURE>_ROUTES`, re-exported from the lib's
+  `src/index.ts`. `app.routes.ts` only lazy-loads them:
+  `loadChildren: () => import('@acme/domain/admin').then((m) => m.USERS_ROUTES)`.
+- Split a feature into its own lib (`libs/domain/<app>/<feature>`) only for a concrete
+  reason, such as size or build time, and name that reason to the user.
+  Never put features, queries, shared UI or theme in the app project.
+- Do not add Nx `feature/ui/data-access/util` folders or `type:*` tags.
+- Every lib has `src/index.ts` and explicit `build` (`@nx/angular:ng-packagr-lite`), `lint`
+  and `test` targets in `project.json`. Keep `plugins: []` in `nx.json`.
+- Alias = path with slashes: `@acme/domain/admin`, `@acme/queries`, `@acme/types`,
+  `@acme/uikit`, `@acme/env`. Project name = path with dashes (`domain-admin`).
+  Component `prefix` = the repo abbreviation.
+- Tag every project with one `scope:*`: `scope:<app>` for an app and its domain libs,
+  `scope:core` for env and types, plus `scope:queries`, `scope:uikit`, `scope:theme`.
+  `@nx/enforce-module-boundaries` with `enforceBuildableLibDependency: true` lets
+  `scope:<app>` depend on itself and the shared scopes, never on another app.
+- A backend in the same workspace is an app in `apps/` with its libs in
+  `libs/domain/<name>-api`. Ban `@angular/*` in backend scopes and `@nestjs/*` in frontend
+  scopes with `bannedExternalImports`.
+- Environment config lives only in `libs/env`, never hardcoded in a query client.
+
+This is the layout for new workspaces and new code. Do not restructure the folders, projects
+and tags of an existing workspace that deviates from it unless the user asks. This covers the
+workspace layout only: every other rule still applies to the code you touch.

package/content/rules/reactive-state.md

@@ -12,4 +12,4 @@ scope: both
 - **Bridge, don't copy.** Cross the boundary with `toSignal()` / `toObservable()`, never by
   `.subscribe()`-ing and assigning the value somewhere.
 
-Subscriptions, effects, and the traps in each direction: {%skill:rxjs-signals%}.
+For subscriptions and effects, load the repository's focused reactive-state guidance.

package/content/rules/styling.md

@@ -1,8 +1,8 @@
 ---
 name: styling
-description: Component CSS is plain CSS in @layer components, and every colour comes from a theme token.
+description: Component CSS is plain CSS in @layer components, and hardcoded colours are never primary values.
 kind: rule
-scope: both
+scope: sdk
 requires: ['@ethlete/core']
 ---
 
@@ -26,10 +26,12 @@ utility can win.
 rule, so source order decides. Leave interaction states (`:hover`, `:focus-visible`,
 `:active`) bare so they escalate and win.
 
-**Never hardcode a colour.** Backgrounds, text, borders and interaction states all resolve
-from the surface and colour theming tokens (`--et-surface-*-solid`, `--et-theme-color-*`) —
-see {%skill:theming%}.
+**Never use a hardcoded colour as the primary value.** Backgrounds, text, borders and
+interaction states resolve from the surface and colour theming tokens
+(`--et-surface-*-solid`, `--et-theme-color-*`). A static fallback inside
+`var(--token, <fallback>)` is permitted, but not required.
 
 Theme **names** (`brand`, `danger`, `dark-elevated`, …) are registered by the application;
-the SDK ships none. Never hardcode a theme-name union in a type, a doc or an example —
-semantic colours resolve by theme `type` (e.g. `injectErrorTheme()`).
+the SDK ships none. Never hardcode them as an SDK-defined union or reusable API contract.
+If an app-specific example names one, label it as belonging to that app. Semantic colours
+resolve by theme `type` (e.g. `injectSemanticColorTheme('error')`).

package/content/rules/subagent-models.md

@@ -0,0 +1,39 @@
+---
+name: subagent-models
+description: A subagent's model is an explicit choice on every call - haiku for lookups and small specified jobs, sonnet for scoped work, opus for hard work, fable for judgment.
+kind: rule
+scope: both
+---
+
+## Delegating: name the subagent's model
+
+A subagent spawned without a `model` runs on the model leading the session, so an expensive
+model ends up doing every small job it delegates. **Set `model` on every call**, matched to the
+task:
+
+| Model    | The work it fits                                                                                                                                                                  |
+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `haiku`  | Lookups and small, fully specified jobs: grep, find, read and summarize files or a CI log, run a command and report, a mechanical edit in named files. Haiku 5.5 does these well. |
+| `sonnet` | Scoped work with a clear target: a fix in a named file, a spec, a docs page, a lint cleanup, research that needs reasoning. Sonnet 5.5 is close to opus here and costs less.      |
+| `opus`   | Hard work: a bug with no known cause, a change across many files, a review of a diff, and any task sonnet did not finish.                                                         |
+| `fable`  | Judgment-heavy work: planning, design, cross-cutting review, leading other subagents. The most expensive of the four, so ask the user before picking it.                          |
+
+Effort follows the prompt, not a parameter: scope the prompt to one question, name what "done"
+means, and say "keep it brief" for a lookup. Two calls need no `model` of their own - a named
+agent type carries the model and reasoning effort its own definition sets, and a fork always
+inherits the parent's model.
+
+A subagent starts cold: it loads the full start context (about 50k tokens) before its first step,
+and measured subagents cost as much as the sessions that spawn them. Do a lookup of a few tool
+calls yourself. Give each subagent one large slice, not several small ones.
+
+A subagent has the same context budget as the session, measured on its own transcript, and the
+context-warning hook tells it to hand back at the critical tier. Size each prompt to fit: one
+slice of work, the files it needs named, and "keep your context small - no whole big files".
+Work that will not fit goes to several subagents in sequence, a fresh one per slice; a subagent
+that hands back early names its remaining steps, which become the next one's prompt.
+
+A subagent does not have to be a Claude one. Delegate to a Codex agent where another model
+family would answer better - a second opinion, a review of your own diff, a bug hunt your own
+reading failed - and whenever the Claude usage limit is close, because a Codex run does not draw
+on it. Read {%skill:codex-subagent%} first.

package/content/skills/agent-sessions/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: agent-sessions
+description: Run agents in tmux sessions of one checkout, message them, wake idle ones, restart a session with a prompt, and claim paths so two agents do not overwrite each other. Read before you edit a shared file while another agent may be active, and when the user says "mailbox", "coordinate with the other agent", "claim a file", "hand off to the other agent", or "restart the session".
+kind: skill
+scope: both
+---
+
+# Agent sessions
+
+One script, {%resource:agent-sessions.mjs%}, does three jobs for the agents of one checkout:
+
+- **Sessions.** It runs each agent in a `tmux` session, and it can clear a session and start it with a prompt.
+- **Messages.** Agents send each other messages through an append-only JSON-lines file, the mailbox. A dispatcher wakes an idle agent.
+- **Claims.** An agent announces the paths it edits, so two agents do not overwrite each other.
+
+Below, `<skill-dir>` is the directory this file sits in, and `<name>` is your own sender name. Where
+the `ethlete-agents` package is a dependency, `npx ethlete-agents sessions <command>` runs the same
+script, so you do not need `<skill-dir>`. The older name `npx ethlete-agents mailbox` works too.
+
+```bash
+node <skill-dir>/agent-sessions.mjs run <name> <command...>
+node <skill-dir>/agent-sessions.mjs up <name>[=<command>]...
+node <skill-dir>/agent-sessions.mjs restart <name> [--after <seconds>] <prompt...>
+node <skill-dir>/agent-sessions.mjs down [<name>...]
+node <skill-dir>/agent-sessions.mjs shell-install [<agent>...] [--file <path>] [--remove] [--dry-run]
+node <skill-dir>/agent-sessions.mjs shell-init [<agent>...]
+node <skill-dir>/agent-sessions.mjs send <name> [--to <agent>] '<message>'
+node <skill-dir>/agent-sessions.mjs inbox <name> [--wait <seconds>]
+node <skill-dir>/agent-sessions.mjs read [--last <n>] [--all]
+node <skill-dir>/agent-sessions.mjs watch <name>
+node <skill-dir>/agent-sessions.mjs dispatch
+node <skill-dir>/agent-sessions.mjs claim <name> <path...> [--ttl <hours>] [--force]
+node <skill-dir>/agent-sessions.mjs release <name> [path...]
+node <skill-dir>/agent-sessions.mjs claims
+```
+
+## Quick start for a person
+
+Nothing runs until you start it, so a person who does not use this does nothing. To try it:
+
+1. Run `node <skill-dir>/agent-sessions.mjs shell-install`. It adds one function per agent to your shell file.
+2. Open a new terminal. In the repo, type `claude` or `codex` as usual. The function starts the agent in a `tmux` session and starts the dispatcher.
+3. Ask one agent to message the other. An idle agent wakes when a message carries `--to <agent>`.
+4. Run `node <skill-dir>/agent-sessions.mjs down` to stop the dispatcher. Run `shell-install --remove` to undo step 1.
+
+## Sessions
+
+`run <name> <command...>` starts the command in the `tmux` session `<name>@<repo>`, or attaches if it runs already. It also starts the dispatcher when none runs. Session names carry the repo name, so `codex` in two repos never collides. If that session has a terminal attached already, `run` starts `<name>-2`, then `<name>-3`, and so on. A detached session is attached again. So a second `claude` terminal gets its own agent.
+
+`up codex=codex gemini=gemini` starts a detached `tmux` session per agent, named like its sender name, and runs the command in it. It also starts a session named `mailbox-dispatch` that runs `dispatch`. A running session is left alone. Attach to a session with `tmux attach -t <name>`. Detach with `Ctrl-b`, then `d`. The session and its agent keep running. Use `down` to stop the dispatcher and the named sessions.
+
+`restart <name> <prompt...>` types the clear command (`/clear`, or `/new` for a `codex` name) and then the prompt into the session `<name>@<repo>`, no sooner than `--after` seconds (default 5). It waits until that session ended its turn and its prompt holds no typed text, and gives up after 30 minutes. After the clear, a new turn does not hold the prompt back: a message can wake the fresh session, and Claude Code queues input typed during a turn. Only typed text in its prompt holds the prompt back. After 60 seconds of typed text, it saves the prompt to `.ethlete/restart.prompt.<session>.txt` and logs why in `.ethlete/restart.log`. The command returns at once, so end your turn after it. An agent uses it to clear itself and resume from its saved work state. It refuses any session other than the caller's own (from `$TMUX_PANE`), and the error names the caller's own sender name. Background commands of the old session still report into the new one.
+
+`shell-install` writes one shell function per agent into `~/.zshrc` or `~/.bashrc`, between two marker lines. A second run replaces the block, and `--remove` deletes it. Use `--file` for another startup file and `--dry-run` to preview. After a new terminal opens, typing `claude` or `codex` in a repo with this skill runs the agent through `run`. Elsewhere the function starts the plain command. Run `shell-install` only when the user asks: it changes a file the user owns. `shell-init` prints the same functions without writing a file.
+
+Choose a `<name>` that no other agent uses, for example `agent-a` or `agent-b`. Two sessions with one name look like one agent.
+
+## Messages
+
+The mailbox file is `.ethlete/mailbox.jsonl` in the git root. The first write also creates `.ethlete/.gitignore`, so the file stays out of git. Set `AGENT_MAILBOX` to use another path. For two Claude Code sessions, the `SendMessage` tool is the better channel. The mailbox is for agents that cannot reach each other directly.
+
+An idle agent cannot read the mailbox. One `dispatch` process outside every agent fixes this. It polls the mailbox for free. When a message carries `--to <agent>`, it waits a short grace period and then, if the agent has not read the message, types a wake-up line into the `tmux` session `<agent>@<repo>`, or a session named only `<agent>`. The agent then runs `inbox` and acts. A message without `--to` wakes nobody.
+
+If the prompt of the agent holds typed text, the dispatcher waits until that text is sent or cleared. It checks again every 2 seconds. An open menu, for example a permission dialog, also makes it wait. If the agent is in the middle of a turn, the wake-up line waits as its next prompt. An agent in a `tmux` session does not need the `--wait` loop, which costs a turn at every timeout. If you wait for an answer in a session without `tmux`, run `inbox <name> --wait 120`: it blocks until a message arrives or 120 seconds pass. If it prints "No new messages.", run it again. A background `--wait` ends after one message, so it is not a lasting watch.
+
+- `inbox` keeps one cursor per sender name, so it never repeats a message. The first call shows the last 20.
+- `read` shows the last 20 messages. Use `--all` for the full history.
+- `send` with no message reads it from standard input, so a long message needs no shell quoting.
+- `watch` is optional. It runs until you stop it. In Claude Code, start it with the `Monitor` tool, so a new message wakes the session. Without such a feature, rely on `inbox`.
+- Never rewrite or truncate the file. Only the script appends to it.
+- Keep credentials and personal data out of the mailbox.
+
+## Claims
+
+1. At the start of a task, run `claims` and `inbox`. They show what other agents hold and said.
+2. Before you edit a file, run `claim` with the exact paths. A directory path claims everything below it. `claim` also prints the messages you have not seen yet.
+3. If `claim` reports a conflict, do not edit. Run `send` to ask the holder for a handoff, then wait.
+4. After each larger step, run `inbox` again. Most agents cannot wake on new output, so you must pull messages yourself.
+5. When you finish, run `release`. A claim also expires after 4 hours, or after `--ttl` hours.
+
+A claim is advisory, not a lock. `--force` claims over another agent: use it only after the holder agreed. Silence is not approval. Acknowledge each handoff in words. No agent starts automatically. The user starts each one.