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

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @ethlete/agent-rules
 
+## 0.1.0-next.32
+
+### Minor Changes
+
+- Add the `background-design-commands` hook: it denies a Bash call that runs a long design command (`design check`, `compare`, `ready`, `sketch ready`, `harness`, `studio:e2e`, `--visible-change`) without `run_in_background`.
+- Add the `git-safety` hook: it denies `git add -A`, `git stash`, `git commit --amend`, a `git commit` without a pathspec and any `go.json` in a commit.
+
+### Patch Changes
+
+- Add `--role builder` to the agent-sessions `run` command and a `builder-chat-words` Stop hook that logs the chat words of each builder turn.
+- `ethlete-agents sync` and `et` write their JSON files (`.mcp.json`, design and update state) in the checkout's Prettier format.
+- The git-commit skill asks for one commit per finished slice (code, specs, changeset and plan note together), one per sketch round or merge, and no history rewrites in a shared checkout.
+- The design-exploration skill tells parts to use `data-et-auto-surface` and `data-et-surface-interactive` instead of a picked `et-surface--<name>` class.
+- The design-exploration skill keeps its hard rules in SKILL.md and moves the command details into reference files, and the subagent rule says a job of under about 10 tool calls stays in the session.
+- The design-exploration skill tells parts to use `data-et-semantic-color="<type>"` instead of a picked `et-color--<name>` class.
+- The design-exploration skill tells an agent to take every colour from the SDK surface and colour theming, never from its own tokens.
+- The `handoff` skill spawns no sub-agent from 70 %, and a self-restart no longer waits for sub-agents that report into a result file.
+- Fix the nx-layout rule to describe inferred lint and test targets instead of the removed `@nx/eslint:lint` and `@nx/jest:jest` executors.
+- The context-warning hook tells an agent in a tmux pane with the agent-sessions skill to save the handoff and run `restart` on its own session, instead of asking the user to clear. The skill description names self-restart.
+- Let `git stash list` and `git stash show` through the git-safety hook. Every writing stash subcommand stays refused, and the refusal names it.
+- `sync` keeps the existing order of hook events and entries in `.claude/settings.json` and only updates, appends or removes its own entries, so a second run is a no-op.
+- The design skill now says visible UI is built only from a picked sketch, and the grilling skill says to decide technical questions yourself.
+- The agent-sessions skill notes that `yarn commit` runs the related specs before it takes the index lock.
+- `et design check` fails a frame-loaded design module that awaits at the top level (`TOP-LEVEL-AWAIT`), which can hang WebKit; a call variant may default-export a promise of its drawing instead.
+- `et design sketch report` refuses a ready sketch. Add `--reopen` to move it back to in progress when the user asks for a change.
+
 ## 0.1.0-next.31
 
 ### Minor Changes

package/README.md

@@ -312,7 +312,13 @@ per hook in the config:
 
 ```json
 {
-  "hooks": ["context-warning", "subagent-model-policy"]
+  "hooks": [
+    "context-warning",
+    "subagent-model-policy",
+    "background-design-commands",
+    "git-safety",
+    "builder-chat-words"
+  ]
 }
 ```
 

package/content/hooks/background-design-commands.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: long design commands must run in the background.
+
+`design check`, `design compare`, `design ready`, `design sketch ready`, `design harness`,
+the `studio:e2e` target and the `--visible-change` gate each take minutes. In the foreground
+they block the whole session, so a Bash call that runs one without `run_in_background: true`
+is denied and the agent repeats it in the background.
+
+Matches the `yarn design ...`, `node dist/libs/cli/src/index.js design ...` and
+`npx nx ... studio:e2e` forms. Quoted text is ignored, so a commit message that mentions a
+command does not trip the hook.
+
+Can be disabled per machine via a gitignored ethlete-agents.config.local.json at the repo
+root: {"disableHooks": true} or {"disableHooks": ["background-design-commands"]}.
+
+Fail-safe: any error exits 0 with no output.
+"""
+
+import json
+import os
+import re
+import sys
+
+HOOK_NAME = "background-design-commands"
+LOCAL_CONFIG_FILE = "ethlete-agents.config.local.json"
+
+LONG_COMMANDS = (
+    ("design check", re.compile(r"(?:^|[\s;&|])design\s+check(?=\s|$|[;&|])")),
+    ("design compare", re.compile(r"(?:^|[\s;&|])design\s+compare(?=\s|$|[;&|])")),
+    ("design ready", re.compile(r"(?:^|[\s;&|])design\s+ready(?=\s|$|[;&|])")),
+    ("design sketch ready", re.compile(r"(?:^|[\s;&|])design\s+sketch\s+ready(?=\s|$|[;&|])")),
+    ("design harness", re.compile(r"(?:^|[\s;&|])design\s+harness(?=\s|$|[;&|])")),
+    ("studio:e2e", re.compile(r"studio:e2e(?=\s|$|[;&|:])")),
+    ("--visible-change", re.compile(r"(?:^|\s)--visible-change(?=\s|=|$)")),
+)
+
+QUOTED = re.compile(r"\"(?:\\.|[^\"\\])*\"|'[^']*'")
+
+
+def agent_name(argv):
+    for index, arg in enumerate(argv):
+        if arg == "--agent" and index + 1 < len(argv):
+            return argv[index + 1]
+        if arg.startswith("--agent="):
+            return arg.split("=", 1)[1]
+    return "claude"
+
+
+def repo_root(data):
+    for variable in ("CLAUDE_PROJECT_DIR", "CODEX_PROJECT_DIR"):
+        value = os.environ.get(variable)
+        if value:
+            return value
+    here = os.path.abspath(__file__)
+    derived = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(here))))
+    if os.path.isfile(os.path.join(derived, LOCAL_CONFIG_FILE)):
+        return derived
+    cwd = data.get("cwd")
+    return cwd if isinstance(cwd, str) and cwd else derived
+
+
+def load_local_config(root):
+    if not root:
+        return {}
+    try:
+        with open(os.path.join(root, LOCAL_CONFIG_FILE), encoding="utf-8") as f:
+            config = json.load(f)
+    except (OSError, ValueError, AttributeError):
+        return {}
+    return config if isinstance(config, dict) else {}
+
+
+def disabled_locally(config):
+    disabled = config.get("disableHooks")
+    return disabled is True or (isinstance(disabled, list) and HOOK_NAME in disabled)
+
+
+def long_command_in(command):
+    """The name of the first long command the shell string runs, or None."""
+    unquoted = QUOTED.sub(" ", command)
+    for name, pattern in LONG_COMMANDS:
+        if pattern.search(unquoted):
+            return name
+    return None
+
+
+def reason_for(name):
+    return (
+        f"`{name}` takes minutes and blocks the session when it runs in the foreground. "
+        "Call Bash again with the same command and `run_in_background: true`, then read its output "
+        "when the completion notice arrives."
+    )
+
+
+def main():
+    if agent_name(sys.argv[1:]) != "claude":
+        return
+
+    data = json.load(sys.stdin)
+
+    if data.get("tool_name") != "Bash":
+        return
+
+    tool_input = data.get("tool_input")
+
+    if not isinstance(tool_input, dict) or tool_input.get("run_in_background") is True:
+        return
+
+    command = tool_input.get("command")
+
+    if not isinstance(command, str):
+        return
+
+    if disabled_locally(load_local_config(repo_root(data))):
+        return
+
+    name = long_command_in(command)
+
+    if not name:
+        return
+
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": reason_for(name),
+                }
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass
+    sys.exit(0)

package/content/hooks/builder-chat-words.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""Stop hook: logs how many chat words a builder session wrote in the turn that just ended.
+
+Only runs in a session started with `--role builder` (ETHLETE_AGENT_ROLE=builder). Appends one
+JSON line to .claude/builder-chat-words.jsonl: timestamp, session_id, words. It never blocks,
+never prints and always exits 0.
+"""
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+LOG_FILE = os.path.join(".claude", "builder-chat-words.jsonl")
+
+
+def is_prompt(entry):
+    if entry.get("type") != "user":
+        return False
+    content = (entry.get("message") or {}).get("content")
+    if isinstance(content, str):
+        return True
+    return isinstance(content, list) and not any(
+        isinstance(block, dict) and block.get("type") == "tool_result" for block in content
+    )
+
+
+def count_words(path):
+    words = 0
+    with open(path, encoding="utf-8") as handle:
+        for line in handle:
+            try:
+                entry = json.loads(line)
+            except ValueError:
+                continue
+            if not isinstance(entry, dict):
+                continue
+            if is_prompt(entry):
+                words = 0
+            elif entry.get("type") == "assistant":
+                content = (entry.get("message") or {}).get("content")
+                if isinstance(content, str):
+                    words += len(content.split())
+                elif isinstance(content, list):
+                    for block in content:
+                        if isinstance(block, dict) and block.get("type") == "text":
+                            words += len(str(block.get("text", "")).split())
+    return words
+
+
+def main():
+    if os.environ.get("ETHLETE_AGENT_ROLE") != "builder":
+        return
+    payload = json.load(sys.stdin)
+    path = payload.get("transcript_path")
+    if not path or not os.path.isfile(path):
+        return
+    root = os.environ.get("CLAUDE_PROJECT_DIR") or payload.get("cwd") or os.getcwd()
+    log = os.path.join(root, LOG_FILE)
+    os.makedirs(os.path.dirname(log), exist_ok=True)
+    record = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "session_id": payload.get("session_id"),
+        "words": count_words(path),
+    }
+    with open(log, "a", encoding="utf-8") as handle:
+        handle.write(json.dumps(record) + "\n")
+
+
+try:
+    main()
+except Exception:
+    pass
+sys.exit(0)

package/content/hooks/context-warning.py

@@ -258,37 +258,65 @@ def handoff_skill(root):
 
 
 SELF_RESTART = (
-    "you run in an agent-sessions tmux session, so do not hand this step to the user: apply the {handoff} skill's save "
-    "test, save if it calls for a file, then follow its 'Clear and resume on your own' section "
-    "and restart this session yourself with the agent-sessions `restart` command - with no file, "
+    "you run in an agent-sessions tmux session, so do not hand this step to the user and never ask them to clear: "
+    "apply the {handoff} skill's save test and save the handoff if it calls for a file, then run "
+    '`node {script} restart {name} "/{handoff} resume"` yourself and end the turn - with no file, '
     "restart with a prompt that names the next step"
 )
+SELF_RESTART_ACT_NOW = (
+    "Save the handoff, then run `node {script} restart {name} \"/{handoff} resume\"` yourself and end the turn. "
+    "Never ask the user to clear."
+)
 USER_DIRECTED_KEYS = ("recommend", "suggest", "save_now", "save_at_stop")
 
 
-def can_self_restart(root):
-    """True only in a tmux session the agent-sessions `restart` command can find and drive."""
-    if not os.environ.get("TMUX") or not root:
-        return False
-    if not any(
-        os.path.isfile(os.path.join(root, ".agents/skills", name, "agent-sessions.mjs"))
-        for name in ("ethlete-agent-sessions", "agent-sessions")
-    ):
-        return False
+def self_restart_target(root):
+    """The agent-sessions script path and own session name, or None outside a tmux session `restart` can drive."""
+    pane = os.environ.get("TMUX_PANE")
+    if not pane or not root:
+        return None
+    script = next(
+        (
+            path
+            for path in (
+                os.path.join(".agents/skills", name, "agent-sessions.mjs")
+                for name in ("ethlete-agent-sessions", "agent-sessions")
+            )
+            if os.path.isfile(os.path.join(root, path))
+        ),
+        None,
+    )
+    if not script:
+        return None
     try:
         session = subprocess.run(
-            ["tmux", "display-message", "-p", "#S"], capture_output=True, text=True, timeout=2
+            ["tmux", "display-message", "-p", "-t", pane, "#{session_name}"],
+            capture_output=True,
+            text=True,
+            timeout=2,
         ).stdout.strip()
     except (OSError, subprocess.SubprocessError):
-        return False
-    return session.endswith("@" + re.sub(r"[.:]", "-", os.path.basename(os.path.normpath(root))))
+        return None
+    if not session:
+        return None
+    slug = re.sub(r"[.:]", "-", os.path.basename(os.path.normpath(root)))
+    return {"script": script, "name": session.removesuffix("@" + slug)}
 
 
-def resolve_profile(profile, skill, self_restart=False):
+def resolve_profile(profile, skill, self_restart=None):
     """Fills the installed handoff skill's name into a profile's message fragments."""
-    resolved = {**profile, **{key: SELF_RESTART for key in USER_DIRECTED_KEYS}} if self_restart else profile
+    resolved = profile
+    if self_restart:
+        resolved = {
+            **profile,
+            **{key: SELF_RESTART for key in USER_DIRECTED_KEYS},
+            "act_now": SELF_RESTART_ACT_NOW,
+        }
+    values = {"handoff": skill, **(self_restart or {})}
     return {
-        key: value.replace("{handoff}", skill) if isinstance(value, str) else value
+        key: re.sub(r"\{(handoff|script|name)\}", lambda m: values.get(m.group(1), m.group(0)), value)
+        if isinstance(value, str)
+        else value
         for key, value in resolved.items()
     }
 
@@ -851,7 +879,7 @@ def main():
     if disabled_locally(local_config):
         return
 
-    profile = resolve_profile(profile, handoff_skill(root), self_restart=can_self_restart(root))
+    profile = resolve_profile(profile, handoff_skill(root), self_restart=self_restart_target(root))
 
     claude_subagent = agent == "claude" and bool(data.get("agent_id"))
     if claude_subagent:

package/content/hooks/git-safety.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: git safety in a checkout several agents share.
+
+Denies, for a Bash call:
+- `git add -A`, `git add --all` and `git add .` (they stage other sessions' work)
+- every `git stash` that writes (bare, `push`, `save`, `pop`, `apply`, `drop`, `clear`, `branch`,
+  `create`, `store`); `git stash list` and `git stash show` stay allowed
+- `git commit --amend`
+- `git commit` without a ` -- <paths>` pathspec
+- any `git add` or `git commit` whose paths name an `.ethlete/**/go.json` (a go is granted
+  in Studio, never committed by an agent)
+
+`git commit-tree` and `git update-index` stay allowed, so a merge commit built on a temporary
+GIT_INDEX_FILE works. Commit messages (`-m`, `--message`) and other quoted text are ignored for
+the command checks, so a message that mentions `git stash` does not trip the hook.
+
+Can be disabled per machine via a gitignored ethlete-agents.config.local.json at the repo
+root: {"disableHooks": true} or {"disableHooks": ["git-safety"]}.
+
+Fail-safe: any error exits 0 with no output.
+"""
+
+import json
+import os
+import re
+import sys
+
+HOOK_NAME = "git-safety"
+LOCAL_CONFIG_FILE = "ethlete-agents.config.local.json"
+
+MESSAGE_ARG = re.compile(
+    r"""(?:^|(?<=\s))(?:-[a-zA-Z]*m|--message)(?:=|\s*)(?:"(?:\\.|[^"\\])*"|'[^']*'|[^\s;&|]*)"""
+)
+SEGMENT_SPLIT = re.compile(r"[;&|\n]+")
+GLOBAL_OPTS_WITH_VALUE = ("-C", "-c", "--git-dir", "--work-tree", "--namespace")
+ADD_ALL = ("-A", "--all", ".")
+GO_JSON = re.compile(r"(?:^|/)go\.json$")
+
+def agent_name(argv):
+    for index, arg in enumerate(argv):
+        if arg == "--agent" and index + 1 < len(argv):
+            return argv[index + 1]
+        if arg.startswith("--agent="):
+            return arg.split("=", 1)[1]
+    return "claude"
+
+
+def repo_root(data):
+    for variable in ("CLAUDE_PROJECT_DIR", "CODEX_PROJECT_DIR"):
+        value = os.environ.get(variable)
+        if value:
+            return value
+    here = os.path.abspath(__file__)
+    derived = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(here))))
+    if os.path.isfile(os.path.join(derived, LOCAL_CONFIG_FILE)):
+        return derived
+    cwd = data.get("cwd")
+    return cwd if isinstance(cwd, str) and cwd else derived
+
+
+def load_local_config(root):
+    if not root:
+        return {}
+    try:
+        with open(os.path.join(root, LOCAL_CONFIG_FILE), encoding="utf-8") as f:
+            config = json.load(f)
+    except (OSError, ValueError, AttributeError):
+        return {}
+    return config if isinstance(config, dict) else {}
+
+
+def disabled_locally(config):
+    disabled = config.get("disableHooks")
+    return disabled is True or (isinstance(disabled, list) and HOOK_NAME in disabled)
+
+
+def git_calls_in(command):
+    """Yield (subcommand, args) for every command-position git call in the shell string."""
+    stripped = MESSAGE_ARG.sub(" ", command)
+    unquoted = stripped.replace('"', " ").replace("'", " ")
+    for segment in SEGMENT_SPLIT.split(unquoted):
+        words = segment.split()
+        index = 0
+        while index < len(words) and re.match(r"^[A-Za-z_][A-Za-z0-9_]*=", words[index]):
+            index += 1
+        if index < len(words) and (words[index] == "git" or words[index].endswith("/git")):
+            rest = words[index + 1 :]
+            while rest and rest[0].startswith("-"):
+                skip = 2 if rest[0] in GLOBAL_OPTS_WITH_VALUE else 1
+                rest = rest[skip:]
+            if rest:
+                yield rest[0], rest[1:]
+
+
+STASH_READS = ("list", "show")
+
+
+def stash_subcommand_of(args):
+    """The stash subcommand `args` run; a bare `git stash` or one starting with an option is `push`."""
+    return args[0] if args and not args[0].startswith("-") else "push"
+
+
+def violation_in(command):
+    """(rule, allowed form) for the first forbidden git call, or None."""
+    for sub, args in git_calls_in(command):
+        if sub == "add":
+            if any(arg in ADD_ALL for arg in args):
+                return (
+                    "`git add -A`, `--all` and `.` stage other sessions' work",
+                    "stage named paths: `git add <path> ...`, or skip staging and use `git commit -m \"...\" -- <paths>`",
+                )
+        if sub == "stash" and stash_subcommand_of(args) not in STASH_READS:
+            return (
+                f"`git stash {stash_subcommand_of(args)}` hides or rewrites other sessions' uncommitted work",
+                "leave the working tree alone; commit your own paths with `git commit -m \"...\" -- <paths>`",
+            )
+        if sub == "commit":
+            if "--amend" in args:
+                return (
+                    "`git commit --amend` rewrites a commit another session may have built on",
+                    "make a new commit: `git commit -m \"...\" -- <paths>`",
+                )
+            if "--" not in args:
+                return (
+                    "`git commit` without a pathspec commits everything staged, including other sessions' work",
+                    "name the paths: `git commit -m \"...\" -- <paths>`",
+                )
+        if sub in ("add", "commit") and any(GO_JSON.search(arg) for arg in args):
+            return (
+                "an agent never stages or commits a `go.json`; a go is granted in Studio",
+                "leave `go.json` out of the paths",
+            )
+    return None
+
+
+def reason_for(rule, allowed):
+    return f"Denied: {rule}. Allowed form: {allowed}."
+
+
+def main():
+    if agent_name(sys.argv[1:]) != "claude":
+        return
+
+    data = json.load(sys.stdin)
+
+    if data.get("tool_name") != "Bash":
+        return
+
+    tool_input = data.get("tool_input")
+    command = tool_input.get("command") if isinstance(tool_input, dict) else None
+
+    if not isinstance(command, str):
+        return
+
+    if disabled_locally(load_local_config(repo_root(data))):
+        return
+
+    found = violation_in(command)
+
+    if not found:
+        return
+
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": reason_for(*found),
+                }
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass
+    sys.exit(0)

package/content/mods/plugins/e2e-progress/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "e2e-progress",
-  "version": "0.1.0-next.31",
+  "version": "0.1.0-next.32",
   "description": "Live Playwright e2e progress from a run log, as a status line entry and a pane",
   "types": "./types/index.d.ts"
 }

package/content/rules/nx-layout.md

@@ -31,8 +31,11 @@ libs/
   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`.
+- Every lib has `src/index.ts` and an explicit `build` target in `project.json`
+  (`@nx/angular:ng-packagr-lite`). `lint` and `test` are inferred by the plugins in `nx.json`
+  (`@nx/eslint/plugin`, and `@nx/vite/plugin` or `@nx/jest/plugin` for the test runner), so
+  do not write `@nx/eslint:lint` or `@nx/jest:jest` executor targets by hand. Nx 24 has no
+  such executors. Run `npx nx show project <name>` to see the inferred targets.
 - 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.

package/content/rules/subagent-models.md

@@ -24,8 +24,8 @@ agent type carries the model and reasoning effort its own definition sets, and a
 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.
+and measured subagents cost as much as the sessions that spawn them. A lookup or job of under about 10 tool
+calls stays in the session. 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

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

@@ -1,6 +1,6 @@
 ---
 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".
+description: Run agents in tmux sessions of one checkout, message them, wake idle ones, restart a session with a prompt (also your own, to clear yourself and resume after a handoff), 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
 ---
@@ -18,7 +18,7 @@ the `ethlete-agents` package is a dependency, `npx ethlete-agents sessions <comm
 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 run <name> <command...> [--role builder] [--dry-run]
 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>...]
@@ -45,7 +45,7 @@ Nothing runs until you start it, so a person who does not use this does nothing.
 
 ## 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.
+`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. `--role builder` sets `ETHLETE_AGENT_ROLE=builder` and, for `claude`, appends a system prompt that keeps the chat silent and sends reports to the grill session. `--dry-run` prints the command instead of starting it. 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.
 
@@ -78,4 +78,6 @@ If the prompt of the agent holds typed text, the dispatcher waits until that tex
 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.
 
+In this repo commit with `yarn commit -m "..." -- <paths>`: it runs the related specs first in a throwaway worktree of HEAD plus those paths, before it takes `.git/index.lock`, and the pre-commit hook then skips them for that exact tree (a plain `git commit` still runs them in the hook).
+
 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.