@ethlete/agent-rules 0.1.0-next.26 → 0.1.0-next.28

package/AGENTS.md

@@ -0,0 +1,28 @@
+# agent-rules
+
+`libs/agent-rules` publishes `@ethlete/agent-rules`: the portable slice of this repo's
+guidance, compiled into Claude Code, Codex, Cursor and Copilot formats. Content lives in
+`libs/agent-rules/content/`; what this repo itself consumes is configured in
+`ethlete-agents.config.json` (`profile: sdk`, so only `scope: both` content is emitted
+here). Never hand-edit the generated marker block at the end of the root `AGENTS.md` or a generated
+`ethlete-*` skill - edit the content file in `libs/agent-rules/content/`, then:
+
+```bash
+npx prettier --write libs/agent-rules/content/<file>   # format first
+yarn agents:sync                                       # then regenerate
+```
+
+A few content files are vendored from another repository. Keep them as written upstream,
+apart from the generator's link syntax - `libs/agent-rules/THIRD-PARTY-LICENSES.md` names
+each one, its upstream commit and its license.
+
+`content/output-styles/` is the exception: a Claude Code output style is a machine-level
+file, so `sync` never emits it and `agents:check` never diffs it. It is installed on
+demand instead - `node dist/libs/agent-rules/src/index.js output-style` after a build here,
+`npx ethlete-agents output-style` in a consumer repo.
+
+Format **before** syncing. The generated copies under `.claude/` and `.agents/` are
+Prettier-ignored, so formatting the content afterwards silently leaves them stale, and
+`yarn agents:check` (which CI runs) fails. The `npx ethlete-agents sync` in the published
+README works in consumer repos only - here the package is the source, not a dependency,
+so `npx` would look it up on the registry and 404.

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # @ethlete/agent-rules
 
+## 0.1.0-next.28
+
+### Minor Changes
+
+- New `mods` config key: `sync` turns on Claude Code mods that the package ships, starting with `e2e-progress`, a live Playwright run progress in the status line.
+- Add the consumer skill `e2e-triage`: read the failures file of the `@ethlete/cli` failure reporter, group the failures by error, fix the largest group first, and re-run only the failed spec files.
+- Add the `agent-sessions` skill and `ethlete-agents sessions`: agents in one checkout run in `tmux`, message each other, claim paths, and restart a session with a prompt. The `handoff` skill uses it to clear and resume.
+
+### Patch Changes
+
+- `agent-sessions restart` refuses a session the caller does not run in, and the handoff skill says how to read the own session name.
+- The `claude` and `codex` shell functions no longer switch your tmux client when a script or a one-shot flag such as `--version` calls them.
+- `agent-sessions run` starts `<name>-2`, `<name>-3` and so on when the session already has a terminal attached, so a second `claude` terminal gets its own agent.
+- The e2e-triage skill treats connection-refused groups on a local mock as infrastructure, and the e2e-progress mod shows the failure `detail`.
+- The handoff skill counts an open item as the next task, so an agent in tmux restarts itself with it instead of handing the prompt to the user.
+- A handoff self-restart now resumes with the installed skill name and keeps both the restart reason and the text after the slug.
+- In an agent-sessions tmux session, the context-warning hook tells the agent to save and restart itself, not to ask the user for `/clear`.
+- The `sdk-update` skill warns that after Angular 22, `a?.b` gives `undefined`, not `null`, which breaks pipes that treat the two differently.
+- Shorten the mailbox wake-up prompt: it runs `npx ethlete-agents sessions inbox <name>` or the `agents:sessions` script when one exists, and the full script path otherwise.
+- `et design shot --variants` takes `--round <key>` and `--variant <name>` to draw only the current round next to the merged row.
+- Reject and reopen single sketch variants with `et design sketch reject|reopen` or in Studio; a rejected variant keeps its reason, origin and history and can no longer be picked or merged.
+- The `agent-sessions` dispatcher waits when the prompt of an agent holds typed text or an open menu, and sends the wake-up line after the text is sent or cleared.
+
+## 0.1.0-next.27
+
+### Minor Changes
+
+- The design-exploration skill says every `et design` write takes `--by <model id>`, that `sketch report` names its variant with `--variant`, and that the coordinator writes the exact model id into each sub-agent prompt; an agent never guesses it.
+- The design-exploration skill says a flow may name a page that exists only as an open sketch, and Studio draws its first variant.
+- The design-exploration skill says elements may draw with the wireframe kit, and a rough shell is a kit element each page imports.
+- The design render check warns of grid rows that leave out interaction columns other rows fill (`GRID-COVERAGE`).
+- `design check` warns of a `.replace` on markup that neither the part nor a part it uses draws (`STALE-REPLACE`).
+- The design render check warns of a class with a product prefix that no stylesheet of the frame defines (`UNDEFINED-CLASS`).
+
+### Patch Changes
+
+- The design-exploration skill explains the open, addressed and resolved comment states, and that the agent never merges after a pick.
+- The design-exploration skill says when to pass `--question` to `et design comment reply`.
+- The design-exploration skill covers `et design comment reply` and the inbox group "waiting for the user".
+- The design-exploration skill says to call `node dist/libs/cli/src/index.js design` in a check-and-shot loop instead of `yarn design`, which builds the CLI first.
+- The design-exploration skill now forbids `vh`, `dvh` and `svh` in parts, and requires every flow line to carry a label naming an element visible in the frame before it.
+- Document product flows, the wireframe kit and the FLOW and WIREFRAME-KIT checks in the design-exploration skill.
+- The design exploration skill explains comments on an element variant inside a page.
+- The design-exploration skill says a product's own `presets` replace its base's, so a desktop-only app lists `desktop` alone.
+- Tell design agents that a Tailwind product registers its drawing folders in a stylesheet, so sketches use the app's utilities.
+- Explain a sketch's `shared/` folder, `sketch new --like` and `embedPage()` in the design-exploration skill.
+- Teach the design-exploration skill the product and sketch workflow of Ethlete Studio: `et design product new`, sketches, the inbox, and Studio-side merge.
+- The design exploration skill describes the product config `tokens` list.
+- The design-exploration skill says how a part imports the product's tokens through `@system/foundations/tokens.css?inline`.
+- The design and git-commit skills add rules for variants, pages and commits in a shared checkout.
+- The design-exploration skill draws wireframes first, then foundations, logo and CI, components, elements and pages.
+- The design-exploration skill says a part with `definePart({ styles })` may draw `drawing({ body })` without styles.
+- The design-exploration skill says `et design inbox done` needs `--note`, which replaces the part's note.
+- The design-exploration skill says a part may export named helpers, and that another part imports a piece instead of copying its markup.
+- The design-exploration skill says `sketch check` and `sketch ready` note a problem the product already had instead of failing on it.
+- The design-exploration skill says `sketch new` starts no report, so `report --done` follows only a report of your own.
+- The design-exploration skill says to start each `et design sketch report` message with `variant <name>`, so Studio can mark that variant as drawing.
+- The design-exploration skill names `sketch round` and says `sketch list` shows the rounds.
+- The design-exploration skill tells agents to answer a combine comment with `et design sketch variant --from` in a new round, noting why the old round lost.
+- The design-exploration skill makes wireframes strict: keep what the app already has, one sketch per screen, regions and names only, no polish, no subagent, and stop the stage early.
+- The design-exploration skill lists the wireframe kit's new controls (`select`, `tabs`, `segmented`, `checkbox`, `badge`, `dot`), an icon `glyph` and a box `fill`, and says to draw a control as its type.
+- The design-exploration skill teaches the wireframe kit's `heading`, `image` `ratio` and row `stackBelow` instead of fixed sizes.
+- The delegation rule says a subagent starts with the full start context, so a small lookup stays in the session. The format rule asks for one Prettier call over all edited files.
+- The design-exploration skill says the auto merge blocks only on problems it adds, and that `sketch ready` can be re-run on a ready sketch.
+- The design-exploration skill says that `design check` warns of a merged part changed outside a sketch.
+- Design parts and stylesheets load product assets as `@assets/<file>`.
+- `et design check --tsconfig` also typechecks each variant of an open sketch and prints the tsc output of a failing one.
+- `et design sketch new` takes `--note <text>`, the note of the first round.
+- `et design <command> [<subcommand>] --help` prints the usage of that one command and skips its checks.
+- `et design check` reports a `var(--token)` without a fallback that no part or stylesheet of the product or its base defines.
+- `et design shot --crop x,y,width,height` and `/__design/shot?clip=x,y,width,height` cut a picture to a box in CSS pixels, so a hairline can be judged with `--scale`.
+- `et design shot --variants --diff-props` compares each variant with the merged part drawn with the variant's state props, so changed props no longer paint the whole diff red.
+- `et design shot --interaction <hover|focus-visible|active|disabled>` forces an interaction on every cell, and `--help` names it. The design-exploration skill names it.
+- The diff row of `et design shot --variants` says "no pixel change, but the markup differs" when a variant draws other markup to the same pixels.
+- `et design shot --scale <1-4>` and `/__design/shot?scale=` draw a part at a device scale, so a small part is legible. The design-exploration skill names it.
+- `et design shot --state <a>,<b>` draws only the named states, side by side, and names the states of the part when one does not exist. The design-exploration skill names it.
+- `et design sketch check --fix` writes the variants in the checkout's Prettier format before it checks them; a FORMAT problem points to it.
+- `et design sketch check` warns of a variant that restyles a class of the sketch's `shared/` folder and of a variant file nothing imports.
+- `et design sketch new --round` requires `--note`, so `sketch ready` no longer stops on a round without a note.
+- `et design sketch new` takes `--variant-note`, `sketch variant` takes several variants, and sketch commands format their output, explain each flag and infer `--product`.
+- `et design sketch variant` refuses a sketch the user discarded and asks for a variant pick first; a pick is still cleared.
+- `design check` warns of an export in a part's `shared/` that nothing imports, and `sketch check` of a sketch `shared/` export a variant does not import.
+- `sketch new --variant-note` keeps each variant's note in `sketch.json` instead of overwriting the part's merged note; Studio shows it in the variant's head, and a merge gives it to a new part.
+- A sketch variant may hold its own copy of a shared file at `<variant>/shared/<path>`: `@shared/<path>` resolves to it first in rendering, typechecks and checks, and a merge of that variant carries it.
+- The context-warning hook now tells the agent to apply the handoff save test before it suggests a handoff. When nothing is left to hand off, the agent suggests a fresh session instead.
+- The design-exploration skill says when to run `design accept`.
+- `et design check` also type-checks each variant of an open sketch and fails with a `TYPE-ERROR` line per broken variant. A merge's own check still types only the product.
+- The design-exploration skill lists the render rules of `design check` and how a part opts out of one.
+- The design exploration skill documents component states per axis, and treats an icon set as a foundation asset.
+- The design exploration skill extracts a component only when two hosts draw the same case.
+- `forceInteraction` from `@design-system` forces an interaction on one element of a part's markup, not only its root.
+- The design-exploration skill says the frame loads a product's tokens, so parts stop importing them.
+- The render check reads each drawn part's `grid`: `sketch check` prints `grid <rows> x <columns> ok` or the states it leaves out, and a state in two cells or a cell naming no state fails as `GRID`.
+- `interactionRows` from `@design-system` builds a part's states and grid from one props object per row and a list of interactions.
+- `et design part remove <layer>/<name>` deletes a merged part with its `merged.json` entry and tsconfig path, and resolves its comments. It refuses a part another part imports, a base part, and a part with an open sketch.
+- `definePart({ styles })` exposes a part's stylesheet on its default export and adds it to every drawing of the part.
+- Tell the design-exploration skill to take its own check shots with `et design shot` instead of a scratch script.
+- The design exploration skill now sends every change to a merged part through a sketch. When there is nothing to choose, the sketch has one variant.
+- The design-exploration skill keeps a component's frame-only wrapper in `render` and out of the markup a host embeds.
+- The design-exploration skill mentions the duplicate-class warning of `sketch check`.
+- `svgAsset` sets a `class` and `attrs` on the root `<svg>` of an asset.
+- Add `svgAsset(raw, { size })` to `@design-system`, fail `design check` on an SVG asset without a root `<svg>` or the SVG namespace, print each variant's `assets/` folder, and add a pixel diff row to `design shot --variants`.
+- The design render check reports `UNKNOWN-THEME` when a drawing uses a colour theme that no stylesheet of its frame defines.
+- The grilling skill now asks for questions that read alone: plain words, no chains of question or ADR numbers, a short reminder when a new topic starts, facts checked before a recommendation, and a confirmed summary at the end.
+- When the handoff save test finds nothing to hand off, the handoff skill and the context-warning hook now ask the agent for a prompt the user can copy into the fresh session.
+- The design-exploration skill says the merge note is optional and which sketch commands record a variant's authors.
+- Document design notes in the design-exploration skill: the note file format, the size a pointed note needs, free flow notes, and when to write a note instead of a comment.
+- The design exploration skill says a closed comment thread is resolved, not deleted.
+- The design exploration skill says a merge, discard or new round closes the sketch's open comments.
+- `et design sketch check` and `sketch ready` fail when a variant drops a state the product's part has.
+- `et design sketch ready` merges a sketch by itself when no state of any variant differs by a pixel from the product, and logs it as `auto` in `accepted.json`.
+- `sketch report --variant <key> --done` ends the live "drawing" report of that variant, so Studio shows its frames before `sketch ready`. The design exploration skill names the command.
+- The design-exploration skill says that `sketch variant` without `--round` fails while the sketch has open comments.
+
 ## 0.1.0-next.26
 
 ### Patch Changes

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/THIRD-PARTY-LICENSES.md

@@ -9,7 +9,7 @@ Commit `3cca18b` (2026-09-04). Vendored skills, kept as written upstream apart f
 generator's own link syntax:
 
 - `content/skills/grill-with-docs` - the entry point; calls the other two.
-- `content/skills/grilling`
+- `content/skills/grilling` - plus our own section "Local addition" after the upstream footer.
 - `content/skills/domain-modeling`
 
 MIT License

package/content/hooks/context-warning.py

@@ -93,6 +93,7 @@ a tool batch or the end of a turn.
 import json
 import os
 import re
+import subprocess
 import sys
 import tempfile
 
@@ -176,8 +177,16 @@ AGENT_PROFILES = {
         "emits_system_message": True,
         "act_now": "Run /{handoff} now and continue in a fresh session.",
         "act_later": "consider /{handoff} to continue in a fresh session",
-        "recommend": "recommend the user run /{handoff} to save state and start a fresh session",
-        "suggest": "suggest the user run /{handoff} to save state and start a fresh session",
+        "recommend": (
+            "first apply the handoff skill's save test yourself; if it calls for a file, "
+            "recommend the user run /{handoff} to save state and start a fresh session, "
+            "otherwise recommend /clear and say nothing is left to hand off, with a prompt to copy into the fresh session"
+        ),
+        "suggest": (
+            "first apply the handoff skill's save test yourself; if it calls for a file, "
+            "suggest the user run /{handoff} to save state and start a fresh session, "
+            "otherwise suggest /clear and say nothing is left to hand off, with a prompt to copy into the fresh session"
+        ),
         "save_now": (
             "run the handoff skill's save mode right now - finish only an in-flight atomic "
             "edit first, nothing new. Apply its own test: with every change committed, no "
@@ -209,11 +218,13 @@ AGENT_PROFILES = {
         "recommend": (
             "tell the user you are near the context limit, then follow "
             ".agents/skills/{handoff}/SKILL.md to save a handoff and have them start a "
+            "fresh session; when its save test calls for no file, only tell them to start a "
             "fresh session"
         ),
         "suggest": (
-            "suggest saving a handoff via .agents/skills/{handoff}/SKILL.md and "
-            "continuing in a fresh session"
+            "first apply the save test in .agents/skills/{handoff}/SKILL.md yourself; if it "
+            "calls for a file, suggest saving a handoff and continuing in a fresh session, "
+            "otherwise suggest a fresh session and say nothing is left to hand off, with a prompt to copy into the fresh session"
         ),
         "save_now": (
             "follow .agents/skills/{handoff}/SKILL.md and save a handoff right now - finish "
@@ -245,11 +256,39 @@ def handoff_skill(root):
     return "ethlete-handoff"
 
 
-def resolve_profile(profile, skill):
+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, "
+    "restart with a prompt that names the next step"
+)
+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
+    try:
+        session = subprocess.run(
+            ["tmux", "display-message", "-p", "#S"], 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))))
+
+
+def resolve_profile(profile, skill, self_restart=False):
     """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
     return {
         key: value.replace("{handoff}", skill) if isinstance(value, str) else value
-        for key, value in profile.items()
+        for key, value in resolved.items()
     }
 
 
@@ -811,7 +850,7 @@ def main():
     if disabled_locally(local_config):
         return
 
-    profile = resolve_profile(profile, handoff_skill(root))
+    profile = resolve_profile(profile, handoff_skill(root), self_restart=can_self_restart(root))
 
     claude_subagent = agent == "claude" and bool(data.get("agent_id"))
     if claude_subagent:

package/content/mods/.claude-plugin/marketplace.json

@@ -0,0 +1,11 @@
+{
+  "name": "ethlete",
+  "owner": { "name": "ethlete" },
+  "plugins": [
+    {
+      "name": "e2e-progress",
+      "source": "./plugins/e2e-progress",
+      "description": "Live Playwright e2e progress from a run log, as a status line entry and a pane"
+    }
+  ]
+}

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

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

package/content/mods/plugins/e2e-progress/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }