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

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-commit/SKILL.md

@@ -1,23 +1,22 @@
 ---
 name: git-commit
-description: How to write git commits in this repo - commitlint format (type(scope): Subject), lean messages, no trailers. Read before committing anything (e.g. the user says "commit this").
+description: How to write git commits in this repo - conventional format (type(scope): Subject), lean messages, no trailers. Read before committing anything (e.g. the user says "commit this").
 kind: skill
 scope: both
-vars: [commitScopes]
+vars: [commitScopes, commitRuleSource, commitValidation]
 ---
 
 # Git commits
 
-Commits are **lean** and follow the **commitlint rules** in `commitlint.config.js`
-(conventional commits with a required scope):
+Commits are **lean** and follow {%commitRuleSource%}:
 
-- **Format: `type(scope): Subject`** - one line. All three parts are enforced:
+- **Format: `type(scope): Subject`** - one line, all three parts required:
   - `type` ∈ `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`,
     `build`, `ci`, `chore`, `revert`
-  - `scope` is **required**, ∈ {%commitScopes%}
+  - `scope` ∈ {%commitScopes%}
   - Subject is **sentence-case** ("Add the search filter", not
     "add the search filter")
-- When unsure a message passes, check it: `echo "<msg>" | npx commitlint`.
+- {%commitValidation%}
 - Add a short body only when the change genuinely needs context that the diff
   can't convey.
 - **No trailers.** Never append `Co-Authored-By`, `Claude-Session`, or similar
@@ -26,4 +25,9 @@ Commits are **lean** and follow the **commitlint rules** in `commitlint.config.j
 - **Stage only what belongs to the change.** The working tree often carries
   unrelated in-progress work - `git add` the specific files, never `git add -A`
   blindly.
+- **In a checkout that other sessions share**, commit with
+  `git commit -- <paths>`, so their staged files stay out. `git commit -- <path>`
+  refuses an untracked file: run `git add -N <that file>` for that one path
+  first. Pass a formatter or `eslint --fix` the exact paths you changed, never a
+  list from `git diff` or `git status` - that list holds other sessions' files.
 - Don't push unless asked.

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

@@ -0,0 +1,87 @@
+---
+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
+{%packageRunner%} ethlete-agents git-flow start FIP-2178        # reads the issue, names it, branches off the right base
+{%packageRunner%} ethlete-agents git-flow check                 # is the current branch conforming?
+{%packageRunner%} ethlete-agents git-flow explain <branch>      # what the parser sees, and what it expects
+{%packageRunner%} 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.
+
+It reads the issue through the running Timetrack app, which holds this machine's only Jira
+credentials. If it reports that the app is not running, ask the
+user to start it. `--subject <text>` names a branch without reading Jira at all.
+
+## 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. Follow the repository's commit-message guidance.

package/content/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: grill-with-docs
+description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
+kind: skill
+scope: both
+modelInvocation: false
+---
+
+Call the Skill tool twice, for {%skill:grilling%} and {%skill:domain-modeling%}.
+
+---
+
+Vendored from [mattpocock/skills](https://github.com/mattpocock/skills) at `3cca18b`, MIT (Copyright (c) 2026 Matt Pocock).

package/content/skills/grilling/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: grilling
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
+kind: skill
+scope: both
+---
+
+Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
+
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
+
+Format a round like so:
+
+```
+❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+```
+
+Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
+
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.
+
+---
+
+Vendored from [mattpocock/skills](https://github.com/mattpocock/skills) at `3cca18b`, MIT (Copyright (c) 2026 Matt Pocock).
+
+## Local addition: write each question so it reads alone
+
+This section is ours, not upstream.
+
+- **One question, one situation.** Say what the thing is and why the decision matters, in plain
+  words, before the choices. The user must understand it without the earlier rounds.
+- **No reference chains.** Never lean on other question numbers, ADR numbers, slice numbers or
+  plan shorthand ("as Q6 settled", "per ADR 07"). Name the actual thing instead.
+- **Remind the user of a concept** when a round starts a new topic: one or two sentences, with a
+  concrete example ("a sketch is a draft with several variants of one part, for example three
+  headers").
+- **Check the facts before you recommend.** A recommendation built on an assumed file format or
+  an assumed existing tool is worse than none. Look it up first, and say in the round when a
+  look-up proved an earlier recommendation wrong.
+- **Close with the shared state.** When the frontier is empty, list every decision in one short
+  summary and ask the user to confirm it before you write it anywhere.