@ethlete/agent-rules 0.1.0-next.4 → 0.1.0-next.6

package/content/skills/figma-export/dump-figma-layers.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Dump the properties of every layer in a Figma "copy as CSS" export, in document order.
+
+    python3 dump-figma-layers.py <export.css> ['<name regex>']
+
+Without a regex every layer is printed except obvious vector artwork. With one, only the
+layers whose name matches it.
+
+Figma emits sub-comments — `/* Auto layout */`, `/* Inside auto layout */`, `/* or 16px */`
+and design-token names like `/* Brand/Chalk White/500 (base) */` — that carry properties
+belonging to the layer named above them. They are folded into that layer rather than treated
+as new ones: a parser that splits on every comment reports frames with zero properties.
+"""
+
+import re
+import sys
+
+COMMENT = re.compile(r'^/\* (.+) \*/$')
+LAYOUT_NOTE = re.compile(r'^(Auto layout|Inside auto layout|or [\d.]+px|Hug|Fixed|Fill|Effect style)$')
+ARTWORK = re.compile(
+    r'^(Polygon|Vector|Ellipse|Rectangle \d|Star|Union|Subtract|Group|Mask|Clip'
+    r'|Texture|Frame \d{6,})'
+)
+
+
+def read_blocks(path):
+    """Yield ('comment', name) and ('prop', text), skipping Figma's multi-line prose notes."""
+    lines = [line.rstrip('\n') for line in open(path)]
+    index, total = 0, len(lines)
+
+    while index < total:
+        stripped = lines[index].strip()
+
+        if stripped.startswith('/*') and not stripped.endswith('*/'):
+            while index < total and not lines[index].rstrip().endswith('*/'):
+                index += 1
+            index += 1
+            continue
+
+        comment = COMMENT.match(stripped)
+
+        if comment:
+            following = lines[index + 1].strip() if index + 1 < total else ''
+            yield 'comment', comment.group(1), following
+        elif ':' in stripped and not stripped.startswith('/*'):
+            yield 'prop', stripped, ''
+
+        index += 1
+
+
+def main():
+    if len(sys.argv) < 2:
+        sys.exit(__doc__)
+
+    path = sys.argv[1]
+    match = re.compile(sys.argv[2]).search if len(sys.argv) > 2 else None
+    show, index = False, 0
+
+    for kind, text, following in read_blocks(path):
+        if kind == 'prop':
+            if show:
+                print(f'    {text}')
+            continue
+
+        # A layer name is followed by a blank line; a sub-comment sits directly on top of the
+        # declarations it annotates. The name list covers the few notes Figma writes before
+        # another comment, where that spacing rule cannot decide.
+        is_declaration = ':' in following and not following.startswith('/*')
+
+        if is_declaration or LAYOUT_NOTE.match(text):
+            if show:
+                print(f'    /* {text} */')
+            continue
+
+        index += 1
+        show = match(text) is not None if match else not ARTWORK.match(text)
+
+        if show:
+            print(f'\n--- [{index}] {text}')
+
+
+if __name__ == '__main__':
+    main()

package/content/skills/figma-export/dump-figma-svg.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""Dump the box tree of a Figma SVG export: every shape with absolute coordinates.
+
+    python3 dump-figma-svg.py <export.svg>
+
+Prints one line per drawn element in document order, indented by group nesting, then a
+summary of repeated shapes and of the gaps between shapes that share a row.
+
+An SVG export has no layer names and — because Figma outlines text on export — no strings
+or font metrics. What it does have is exact geometry: every rect carries its own x/y/
+width/height/rx, so padding and gaps are differences you can read off rather than numbers
+you have to trust a label for. Outlined text is measured by the bounding box of its path
+coordinates, which runs a fraction of a pixel wide because Bezier control points sit
+outside the curve — enough to place a text run, not to size a glyph.
+"""
+
+import re
+import sys
+import xml.etree.ElementTree as ET
+
+SVG_NS = '{http://www.w3.org/2000/svg}'
+TRANSLATE = re.compile(r'translate\(\s*([-\d.]+)[\s,]+([-\d.]+)\s*\)')
+TOKEN = re.compile(r'([MmLlHhVvCcSsQqTtAaZz])|(-?\d*\.?\d+(?:e[-+]?\d+)?)', re.IGNORECASE)
+ARITY = {'m': 2, 'l': 2, 'h': 1, 'v': 1, 'c': 6, 's': 4, 'q': 4, 't': 2, 'a': 7, 'z': 0}
+SKIP = {'defs', 'clipPath', 'mask', 'filter', 'linearGradient', 'radialGradient', 'pattern'}
+
+
+def tag_of(element):
+    return element.tag[len(SVG_NS) :] if element.tag.startswith(SVG_NS) else element.tag
+
+
+def number(element, name, fallback=0.0):
+    try:
+        return float(element.get(name, fallback))
+    except ValueError:
+        return fallback
+
+
+def translation(element):
+    match = TRANSLATE.search(element.get('transform') or '')
+
+    return (float(match.group(1)), float(match.group(2))) if match else (0.0, 0.0)
+
+
+def path_points(data):
+    """Every point a path visits, control points included. `H`/`V`/`A` take counts of their
+    own, so pairing the numbers off two at a time reports a box the shape never occupies."""
+    tokens = TOKEN.findall(data)
+    index, command, x, y = 0, 'm', 0.0, 0.0
+
+    while index < len(tokens):
+        letter, value = tokens[index]
+
+        if letter:
+            command = letter
+            index += 1
+
+            if command.lower() == 'z':
+                continue
+
+        arity = ARITY[command.lower()]
+        args = [float(tokens[index + step][1]) for step in range(arity) if index + step < len(tokens)]
+
+        if len(args) < arity:
+            return
+
+        index += arity
+        relative = command.islower()
+
+        if command.lower() == 'h':
+            x = x + args[0] if relative else args[0]
+        elif command.lower() == 'v':
+            y = y + args[0] if relative else args[0]
+        else:
+            pairs = [(args[5], args[6])] if command.lower() == 'a' else list(zip(args[0::2], args[1::2]))
+
+            for point_x, point_y in pairs:
+                yield (x + point_x, y + point_y) if relative else (point_x, point_y)
+
+            x, y = (x + pairs[-1][0], y + pairs[-1][1]) if relative else pairs[-1]
+
+        yield x, y
+
+        if command == 'M':
+            command = 'L'
+        elif command == 'm':
+            command = 'l'
+
+
+def path_box(data):
+    points = list(path_points(data))
+    xs, ys = [point[0] for point in points], [point[1] for point in points]
+
+    if not xs:
+        return None
+
+    return min(xs), min(ys), max(xs) - min(xs), max(ys) - min(ys)
+
+
+def box_of(element):
+    name = tag_of(element)
+
+    if name in ('rect', 'image'):
+        return number(element, 'x'), number(element, 'y'), number(element, 'width'), number(element, 'height')
+
+    if name == 'path':
+        return path_box(element.get('d') or '')
+
+    if name in ('polygon', 'polyline'):
+        return path_box('M' + (element.get('points') or ''))
+
+    if name == 'circle':
+        radius = number(element, 'r')
+
+        return number(element, 'cx') - radius, number(element, 'cy') - radius, radius * 2, radius * 2
+
+    if name == 'ellipse':
+        rx, ry = number(element, 'rx'), number(element, 'ry')
+
+        return number(element, 'cx') - rx, number(element, 'cy') - ry, rx * 2, ry * 2
+
+    if name == 'line':
+        x1, y1 = number(element, 'x1'), number(element, 'y1')
+
+        return x1, y1, number(element, 'x2') - x1, number(element, 'y2') - y1
+
+    return None
+
+
+def trim(value):
+    return f'{value:.3f}'.rstrip('0').rstrip('.')
+
+
+def walk(element, offset, depth, boxes):
+    for child in element:
+        name = tag_of(child)
+
+        if name in SKIP:
+            continue
+
+        dx, dy = translation(child)
+        origin = (offset[0] + dx, offset[1] + dy)
+
+        if name in ('g', 'svg'):
+            print(f'{"  " * depth}<{name}>' + (f' translate({trim(dx)} {trim(dy)})' if (dx or dy) else ''))
+            walk(child, origin, depth + 1, boxes)
+            continue
+
+        if name == 'text':
+            content = ' '.join(''.join(child.itertext()).split())
+            metrics = ' '.join(
+                f'{key}={child.get(key)}'
+                for key in ('font-family', 'font-size', 'font-weight', 'letter-spacing')
+                if child.get(key)
+            )
+            x, y = number(child, 'x') + origin[0], number(child, 'y') + origin[1]
+            print(f'{"  " * depth}{"text":<6} {trim(x):>9} {trim(y):>8}  {metrics}  "{content}"')
+            continue
+
+        box = box_of(child)
+
+        if box is None:
+            continue
+
+        x, y, width, height = box[0] + origin[0], box[1] + origin[1], box[2], box[3]
+        radius = child.get('rx') if name == 'rect' else None
+        paint = child.get('fill') or child.get('stroke') or ''
+        detail = f' r={radius}' if radius else ''
+        detail += f' {"stroke" if child.get("stroke") else "fill"}={paint}' if paint and paint != 'none' else ''
+        label = 'text?' if name == 'path' and width >= height * 3 else name
+
+        print(f'{"  " * depth}{label:<6} {trim(x):>9} {trim(y):>8}  {trim(width):>8} × {trim(height):<8}{detail}'.rstrip())
+        boxes.append((x, y, width, height, name, radius, paint))
+
+
+def summarise(boxes):
+    shapes = {}
+
+    for x, y, width, height, name, radius, paint in boxes:
+        if name != 'rect':
+            continue
+
+        shapes.setdefault((round(width, 2), round(height, 2), radius), []).append((x, y, paint))
+
+    repeats = {key: hits for key, hits in shapes.items() if len(hits) > 1}
+
+    if repeats:
+        print('\nRepeated rects — one component rendered N times, not N designs:')
+
+        for (width, height, radius), hits in sorted(repeats.items(), key=lambda item: -len(item[1])):
+            fills = {paint for _, _, paint in hits}
+            varies = f', {len(fills)} fills' if len(fills) > 1 else ''
+            print(f'  {len(hits)}× {trim(width)} × {trim(height)}' + (f' r={radius}' if radius else '') + varies)
+
+    rows = {}
+
+    for x, y, width, height, name, _, _ in boxes:
+        if name == 'rect':
+            rows.setdefault(round(y, 2), set()).add((x, width))
+
+    printed = False
+
+    for y, hits in sorted(rows.items()):
+        spans, edge = [], None
+
+        for x, width in sorted(hits):
+            if edge is not None and x >= edge:
+                spans.append(round(x - edge, 2))
+
+            edge = max(edge or 0, x + width)
+
+        if not spans:
+            continue
+
+        if not printed:
+            print('\nGaps between rects sharing a top edge — the auto-layout gap, measured:')
+            printed = True
+
+        print(f'  y={trim(y):<8} {len(spans) + 1} columns, gaps: {", ".join(trim(span) for span in spans)}')
+
+
+def main():
+    if len(sys.argv) < 2:
+        sys.exit(__doc__)
+
+    root = ET.parse(sys.argv[1]).getroot()
+    boxes = []
+
+    print(f'canvas {root.get("width")} × {root.get("height")}  viewBox={root.get("viewBox")}\n')
+    walk(root, (0.0, 0.0), 0, boxes)
+    summarise(boxes)
+
+
+if __name__ == '__main__':
+    main()

package/content/skills/figma-export/measure-template.mjs

@@ -0,0 +1,87 @@
+/**
+ * Measure real rendered geometry against the numbers in a Figma export.
+ *
+ * Copy into a scratch directory next to a `styles.css` copied out of a production build,
+ * replace MARKUP / WIDTHS / DESIGN / probe(), then `node measure-template.mjs`.
+ */
+import { createRequire } from 'node:module';
+import { writeFileSync } from 'node:fs';
+
+// This runs from a scratch directory, so Playwright cannot be resolved by name — point
+// createRequire at the repo root. Playwright is CommonJS; a named import fails.
+const REPO_ROOT = '/absolute/path/to/repo'; // <-- change me
+const { chromium } = createRequire(`${REPO_ROOT}/`)('playwright');
+
+/** One instance of the thing under test. Keep the real component classes verbatim. */
+const MARKUP = (id) => `
+  <div id="${id}-card" class="…">
+    <h4 id="${id}-title" class="…">Some realistically long label</h4>
+  </div>`;
+
+/** Container widths to probe, taken from the export's frames — not from viewport breakpoints. */
+const WIDTHS = [956, 640];
+
+/** What the export says each width should produce. */
+const DESIGN = {
+  956: { cols: 4, cardW: 219, cardH: 60 },
+  640: { cols: 3, cardW: 192, cardH: 60 },
+};
+
+// Column, never row: in a flex row the harness items shrink, and container queries then
+// report results for a width the component would never actually see.
+const page = (blocks) => `<!doctype html><html class="et-surface--dark"><head><meta charset="utf-8">
+<link rel="stylesheet" href="./styles.css"></head>
+<body class="et-surface--dark" style="margin:0;padding:24px;display:flex;flex-direction:column;gap:24px;align-items:flex-start">
+${blocks}
+</body></html>`;
+
+const block = (width) => `<div id="w${width}" class="@container" style="width:${width}px">
+  <div class="…">${MARKUP(`w${width}`)}</div>
+</div>`;
+
+// page.setContent() renders on about:blank, which blocks file:// subresources — the
+// stylesheet would silently never load. Write a real file and navigate to it.
+writeFileSync('harness.html', page(WIDTHS.map(block).join('\n')));
+
+const browser = await chromium.launch();
+const tab = await browser.newPage({ viewport: { width: 1200, height: 900 }, deviceScaleFactor: 2 });
+
+await tab.goto(`file://${process.cwd()}/harness.html`);
+await tab.waitForTimeout(300);
+
+const measured = await tab.evaluate((widths) => {
+  const round = (value) => Math.round(value * 100) / 100;
+  const box = (id) => document.getElementById(id).getBoundingClientRect();
+  const font = (id) => getComputedStyle(document.getElementById(id));
+
+  return widths.map((width) => {
+    const card = box(`w${width}-card`);
+    const title = font(`w${width}-title`);
+
+    return {
+      width,
+      cardW: round(card.width),
+      cardH: round(card.height),
+      titleInset: round(box(`w${width}-title`).left - card.left),
+      fontSize: title.fontSize,
+      lineHeight: title.lineHeight,
+      letterSpacing: title.letterSpacing,
+    };
+  });
+}, WIDTHS);
+
+let failures = 0;
+
+for (const row of measured) {
+  const want = DESIGN[row.width];
+  const ok = Math.abs(row.cardW - want.cardW) < 1 && Math.abs(row.cardH - want.cardH) < 0.5;
+
+  if (!ok) failures++;
+
+  console.log(`${String(row.width).padStart(4)}px | ${ok ? 'OK ' : 'BAD'} |`, row);
+}
+
+console.log(failures === 0 ? '\nALL GEOMETRY MATCHES' : `\n${failures} MISMATCHES`);
+
+await tab.screenshot({ path: 'verify.png', fullPage: true });
+await browser.close();

package/content/skills/git-flow/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: git-flow
+description: How to name and base a branch in this repo, and what its merge request must target - feature, sub-feature, release, release fix and hotfix. Read BEFORE creating a branch, opening a merge request, or choosing what to branch from (e.g. the user says "start work on FIP-2177" or "open an MR").
+kind: skill
+scope: both
+vars: [gitFlowDevelopmentBranch, gitFlowProductionBranch, gitFlowTypes, gitFlowEnforcement, gitFlowSubPrefix]
+---
+
+# Git flow
+
+Work is organised in two levels: a **main feature branch** per Jira Story, into which
+**sub-feature branches** (one per Task) are merged after review. The main feature branch is
+what gets deployed to a test environment and, once accepted, merged into
+`{%gitFlowDevelopmentBranch%}`.
+
+**Never name a branch by hand - `start` does it from the grammar:**
+
+```bash
+npx ethlete-agents git-flow start FIP-2178        # reads the issue, names it, branches off the right base
+npx ethlete-agents git-flow check                 # is the current branch conforming?
+npx ethlete-agents git-flow explain <branch>      # what the parser sees, and what it expects
+npx ethlete-agents git-flow repair <branch>       # rename a non-conforming one, retarget its MRs
+```
+
+`start` prints its plan (branch, base, MR target) and asks before writing anything; add
+`--dry-run` to see the plan alone. It refuses on a dirty working tree, and a Task nests under
+its parent Story's branch, so that branch has to exist first.
+
+## The five shapes
+
+| Shape                                                                             | Issue | Branch from                    | MR targets                                                       |
+| --------------------------------------------------------------------------------- | ----- | ------------------------------ | ---------------------------------------------------------------- |
+| `feat/FIP-2177-user-management`                                                   | Story | `{%gitFlowDevelopmentBranch%}` | `{%gitFlowDevelopmentBranch%}`                                   |
+| `{%gitFlowSubPrefix%}/feat/FIP-2177-user-management/FIP-2178-user-password-reset` | Task  | the main feature branch        | the main feature branch                                          |
+| `release/2026.04.28`                                                              | -     | `{%gitFlowDevelopmentBranch%}` | `{%gitFlowDevelopmentBranch%}` and `{%gitFlowProductionBranch%}` |
+| `{%gitFlowSubPrefix%}/release/2026.04.28/FIP-2222-button-not-visible`             | Bug   | the release branch             | the release branch                                               |
+| `hotfix/FIP-2799-password-recovery-broken`                                        | Bug   | `{%gitFlowProductionBranch%}`  | `{%gitFlowProductionBranch%}`                                    |
+
+- The **type** is one of {%gitFlowTypes%}, and a nested branch carries its parent's **full**
+  name - that path is what makes the parent machine-readable.
+- The **key** is the Jira issue, uppercase, immediately after the type. The **subject** is the
+  Story's subject meta field in kebab-case, not a paraphrase of the summary.
+- A branch with no key still works, but nothing can attribute it to an issue. Add the key.
+
+### Why a nested branch starts with `{%gitFlowSubPrefix%}/`
+
+Git refuses a ref that is both a branch and a directory of branches. So
+`feat/FIP-2177-user-management/FIP-2178-user-password-reset` **cannot exist** while
+`feat/FIP-2177-user-management` does - git rejects it locally and the push comes back as
+`refname conflict`. The prefix moves the nested tree out of the way and keeps the parent's
+full path inside the child's name, so the MR target is still readable off the name.
+
+Do not "fix" a name by dropping the prefix; the branch it produces cannot be created.
+
+## Rules that are not about naming
+
+- **Never rebase a shared branch.** A main feature branch is published and other people's
+  sub-features are based on it - bring it up to date by **merging**
+  `{%gitFlowDevelopmentBranch%}` into it. Rebase only a local branch you have not pushed.
+- **A sub-feature merges into its parent, never straight into
+  `{%gitFlowDevelopmentBranch%}`** - that is the whole point of the two levels, since the
+  parent is what gets tested as a unit.
+- **Delete the source branch on merge** (the checkbox in the merge request) for sub-features,
+  release fixes and merged main features.
+- **A hotfix branches off `{%gitFlowProductionBranch%}`** and, after rollout, that branch is
+  merged back into `{%gitFlowDevelopmentBranch%}` so the two do not drift.
+- **Never push directly to `{%gitFlowDevelopmentBranch%}` or
+  `{%gitFlowProductionBranch%}`.** Open a merge request; it needs another developer's review.
+
+## Enforcement is `{%gitFlowEnforcement%}`
+
+In `advisory` mode every rule reports and nothing blocks - the older naming shapes (`feature/`
+instead of `feat/`, a lowercase key, no key at all, a `dev-*` integration branch) are accepted
+on purpose while the team adapts. Report the suggestion, do not "fix" someone's existing
+branch unasked - `repair` is how a rename happens, and only when asked for.
+
+`dev-*` is the **old spelling of a main feature branch**, not a stray name: sub-features
+legitimately target it. Leave a live one alone.
+
+## Commit messages are a separate thing
+
+Commits stay conventional (`feat(platform): Prefer a player's common name`) and carry **no
+issue key** - the branch already has it. See {%skill:git-commit%}.

package/content/skills/handoff/SKILL.md

@@ -15,6 +15,10 @@ continue in a fresh session. Two modes:
 - **save** ("handoff", "wrap up") - write a handoff file.
 - **resume** ("continue from the handoff") - read one and continue the work.
 
+This skill is installed as `ethlete-handoff`, so under Claude Code the commands
+are `/ethlete-handoff` and `/ethlete-handoff resume [name]` - there is no
+`/handoff`. Name them that way whenever you tell the user what to run.
+
 Handoff files live in `{%handoffDir%}/` (gitignored - they are personal,
 ephemeral working state, not team docs).
 

package/content/skills/query/SKILL.md

@@ -16,17 +16,17 @@ paged queries, bearer auth, GraphQL, and a socket.io realtime client.
 non-trivial query work.** This guide is the index plus the load-bearing facts, so you
 don't re-derive them from source.
 
-| Page                                                                   | Covers                                                                              |
-| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| {%docsBaseUrl%}/query/                                                 | Overview + the two-generations note                                                 |
-| {%docsBaseUrl%}/query/queries                                          | **Start here** - client, creators, the query object's signals, auto-execution       |
-| {%docsBaseUrl%}/query/features                                         | `withArgs`, `withPolling`, `withAutoRefresh`, side-effect handlers                  |
-| {%docsBaseUrl%}/query/http                                             | REST creators, typing requests, response transforms, upload progress                |
-| {%docsBaseUrl%}/query/auth                                             | Bearer auth: login/refresh, auto token refresh, multi-tab sync                      |
-| {%docsBaseUrl%}/query/caching · `/stacks` · `/errors` · `/gql` · `/ws` | Caching/dedup, pagination, error/retry, GraphQL, WebSockets                         |
-| {%docsBaseUrl%}/query/multi-tab                                        | Opt-in cross-tab sync: shared responses, per-key polling election, mutation fan-out |
-| {%docsBaseUrl%}/query/query-forms                                      | Router-synced filter/search forms                                                   |
-| {%docsBaseUrl%}/query/legacy                                           | The maintenance-mode `V2QueryClient`                                                |
+| Page                                                                   | Covers                                                                                |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| {%docsBaseUrl%}/query/                                                 | Overview + the two-generations note                                                   |
+| {%docsBaseUrl%}/query/queries                                          | **Start here** - client, creators, the query object's signals, auto-execution         |
+| {%docsBaseUrl%}/query/features                                         | `withArgs`, `withPolling`, `withLongPolling`, `withAutoRefresh`, side-effect handlers |
+| {%docsBaseUrl%}/query/http                                             | REST creators, typing requests, response transforms, upload progress                  |
+| {%docsBaseUrl%}/query/auth                                             | Bearer auth: login/refresh, auto token refresh, multi-tab sync                        |
+| {%docsBaseUrl%}/query/caching · `/stacks` · `/errors` · `/gql` · `/ws` | Caching/dedup, pagination, error/retry, GraphQL, WebSockets                           |
+| {%docsBaseUrl%}/query/multi-tab                                        | Opt-in cross-tab sync: shared responses, per-key polling election, mutation fan-out   |
+| {%docsBaseUrl%}/query/query-forms                                      | Router-synced filter/search forms                                                     |
+| {%docsBaseUrl%}/query/legacy                                           | The maintenance-mode `V2QueryClient`                                                  |
 
 ## Two generations - use the current one
 
@@ -77,9 +77,19 @@ raw `toObservable`). It emits `null` first - `pipe(filter(r => r !== null))`.
 - **`withArgs(() => ({ pathParams, queryParams, body }))`** - runs like a `computed`;
   re-runs when a signal it reads changes and re-executes the query. This is how you
   drive **search-as-you-type**: back it with a search signal
-  (`withArgs(() => ({ queryParams: { search: this.search() } }))`). Return
-  `CLEAR_QUERY_ARGS` to reset args to `null` (pauses polling/auto-refresh).
+  (`withArgs(() => ({ queryParams: { search: this.search() } }))`). Return `null`
+  to park the query - args reset to `null`, pausing polling/auto-refresh.
+- **Prefer `withArgs` over passing `args` to `execute()`.** Args declared on the query
+  stay reactive: a `GET` re-executes itself when they change, and `withPolling` /
+  `withAutoRefresh` restart off the same signal - none of which happens for args handed
+  to `execute()`. A function route additionally throws without it. With `withArgs` in
+  place a mutation is just `.execute()`, which reuses the current `args()`. Reserve
+  `execute({ args })` for a one-off payload no signal holds (a form submit).
 - `withPolling({ interval })`, `withAutoRefresh({ onSignalChanges: [...] })`.
+- **`withLongPolling({ nextArgs })`** for a completion-driven chain instead of an interval: each
+  round starts once the previous settled, with args (a cursor) derived from its response. `nextArgs`
+  returning `null` ends the chain. Not `withPolling` with a small interval - and the two throw when
+  combined.
 - Side-effects: `withSuccessHandling`, `withErrorHandling`, `withLogging`.
 
 There is no built-in debounce operator - dedup/caching handles repeated identical

package/package.json

@@ -1,8 +1,19 @@
 {
   "name": "@ethlete/agent-rules",
-  "version": "0.1.0-next.4",
+  "version": "0.1.0-next.6",
   "license": "MIT",
   "type": "commonjs",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./git-flow": {
+      "types": "./src/lib/git-flow/index.d.ts",
+      "default": "./src/lib/git-flow/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "main": "./src/index.js",
   "typings": "./src/index.d.ts",
   "bin": {

package/src/index.js

@@ -5,6 +5,7 @@ const tslib_1 = require("tslib");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const config_1 = require("./lib/config");
+const git_flow_command_1 = require("./lib/git-flow-command");
 const migrate_1 = require("./lib/migrate");
 const sync_1 = require("./lib/sync");
 const USAGE = `ethlete-agents — compile @ethlete agent rules and skills into your repo
@@ -12,6 +13,8 @@ const USAGE = `ethlete-agents — compile @ethlete agent rules and skills into y
   ethlete-agents sync      Write the generated rules/skills for every detected agent
   ethlete-agents check     Exit non-zero when the generated files are out of date (for CI)
   ethlete-agents init      Write a starter ${config_1.CONFIG_FILE_NAME}
+  ethlete-agents git-flow  Name, check and repair branches against the repo's git flow
+                           (start, check, repair, explain)
   ethlete-agents migrate   Convert the repo to the AGENTS.md + .agents/skills layout:
                            CLAUDE.md content moves into AGENTS.md (CLAUDE.md becomes an
                            @AGENTS.md import), hand-written .claude/skills move to
@@ -66,6 +69,8 @@ const run = (argv) => {
             return (0, sync_1.check)(options);
         case 'init':
             return init(root);
+        case 'git-flow':
+            return (0, git_flow_command_1.gitFlowCommand)({ root, argv: argv.slice(1) });
         case 'migrate':
             return (0, migrate_1.migrate)(Object.assign(Object.assign({}, options), { dryRun: argv.includes('--dry-run') }));
         default:
@@ -76,12 +81,12 @@ const run = (argv) => {
 tslib_1.__exportStar(require("./lib"), exports);
 // Guarded so the package can also be imported as a library without running the CLI.
 if (require.main === module) {
-    try {
-        process.exit(run(process.argv.slice(2)));
-    }
-    catch (error) {
+    Promise.resolve()
+        .then(() => run(process.argv.slice(2)))
+        .then((code) => process.exit(code))
+        .catch((error) => {
         console.error(error instanceof Error ? error.message : error);
         process.exit(1);
-    }
+    });
 }
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/agent-rules/src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/agent-rules/src/index.ts"],"names":[],"mappings":"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"}