squadrant 0.16.3 → 0.16.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "squadrant",
   "packageManager": "pnpm@10.30.3",
-  "version": "0.16.3",
+  "version": "0.16.5",
   "description": "Multi-project orchestration for your coding agents (Claude, Codex, opencode, Gemini)",
   "type": "module",
   "bin": {

package/plugin/skills/captain-ops/SKILL.md

@@ -228,6 +228,23 @@ This is the captain-side backstop: even if the completion-protocol imperative is
 
 When a crew sends you a status message via `squadrant runtime send <project> "<message>"`, it lands in your captain pane. Acknowledge, then update your handoff if a meaningful decision was made.
 
+### Handling CREW REVIEW (#599 review gate)
+
+CREW REVIEW is **unambiguous** — a crew ran `squadrant crew signal review` after committing its work to `crew/<name>`. Unlike CREW IDLE, this is never a stray heartbeat miss: the crew has explicitly paused and is waiting for your verdict. The task is **NOT terminal** — don't treat it like CREW DONE.
+
+On CREW REVIEW:
+
+1. **Open the diff** — `squadrant diff <project> <crew>` (branch-vs-base; the default is exactly the review surface). Use `--staged`/`--unstaged`/`--working` if you also want to peek at anything left uncommitted.
+2. **Classify:**
+
+| Diff looks | Captain action |
+|-----------|-----------------|
+| Good — matches the task, tests pass, no scope creep | `squadrant crew approve <project> <crew>` — pushes `crew/<name>` to origin, opens the PR, terminalizes DONE. |
+| Needs changes | `squadrant crew send <project> <crew> "<feedback>"` — the crew iterates, re-commits, and re-signals `review`. Loop until approved. |
+
+3. **Never auto-terminalize a CREW REVIEW yourself** by emitting `task.done` directly — always go through `squadrant crew approve` so the push+PR actually happens before the task closes.
+4. Do **not** re-send the original task or close the crew while it's awaiting review — `crew close` on a `review`-state task discards work that hasn't been pushed anywhere yet.
+
 ## When Crew Finishes
 
 After a crew task completes:

package/plugin/skills/explainer-reel/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: explainer-reel
+description: This skill should be used when the user asks to "animate a system diagram", "make a reel explaining X", "turn this architecture into a GIF", "explain this flow with motion", "make a JWT/auth/cache-style animated explainer", "map who calls whom across these systems", "make an interactive system-flow diagram with bands/swimlanes", or wants either a short looping GIF (dark-neon, monoline, terminal-panel style) or a clickable interactive HTML diagram that explains a structure, system, or flow — for embedding in or alongside HTML/markdown docs. Covers self-contained HTML scene authoring, a dark-neon component library, an HTML→Playwright→FFmpeg GIF pipeline, and a swimlane-band interactive preset that composes with `visual-explainer`. Optional MP4 export via Remotion.
+version: 0.2.0
+---
+
+# explainer-reel
+
+Two output modes for explaining a structure/system/flow with motion or interactivity, instead of
+a static diagram:
+
+| Mode | Output | Use when |
+|---|---|---|
+| **`reel`** (default) | a short, looping animated **GIF** — dark-neon, thin monoline, terminal-panel chrome | the ask is a passive, embeddable loop (e.g. "how JWT auth works" as a `<img>` in docs) |
+| **`interactive`** | a self-contained **interactive HTML** page — dark IBM Plex dev-console theme, horizontal system bands, click-node detail panel, tabs | the ask is to *explore* who-calls-whom across systems (e.g. "map this request across three services") |
+
+Both modes are **wrap-the-engine, build-the-style-pack** — see provenance below. Pick the mode
+from the user's ask; default to `reel` when the request is ambiguous (issue #598's original scope
+and golden reference are `reel` mode).
+
+**Provenance:**
+- `mode=reel` *wraps* `iart-ai/explainer-video-skills` (the engine — motion primitives + a
+  verify-loop toolkit) with a squadrant style-pack (design tokens + component library + a GIF
+  pipeline the engine doesn't ship).
+- `mode=interactive` *wraps* `visual-explainer`'s `generate-web-diagram` (the engine for
+  self-contained interactive HTML) with a named **swimlane preset** (bands/particles/detail-panel
+  layout grammar) so that command doesn't reinvent the layout each time.
+
+See `docs/specs/2026-07-23-animated-system-graph-skill.md` (issue #598, addendum for the two-mode
+scope) for the full build-vs-buy rationale. Don't rebuild either engine's techniques from
+scratch — reuse them; this skill only supplies the style/preset layer on top.
+
+## When to use this vs. plain `visual-explainer`
+
+- Plain `visual-explainer` — static or entrance-only diagrams (one-shot reveal on load), or an
+  interactive diagram with no particular bands/swimlane shape. Use for most architecture docs,
+  plans, and diagrams.
+- `explainer-reel` `mode=reel` — **continuous, looping motion** is the explicit ask: a packet
+  traveling a path, a counter climbing, a verify/reject beat.
+- `explainer-reel` `mode=interactive` — the ask specifically wants **bands = systems** with
+  network-hop edges and flow-particles (a "swimlane" system-flow map), not a general diagram.
+
+## Mode: `reel` (default)
+
+### Prerequisites
+
+1. **The engine.** If `diagram-animation`'s recipe table isn't already available in this session,
+   install it once per project:
+   ```bash
+   npx skills add iart-ai/explainer-video-skills -a claude-code -s diagram-animation -y
+   ```
+   This gives you the motion-primitive reference (`references/diagram-and-chart-recipes.md`) for
+   node/edge reveals, `offset-path` traveling dots, `stroke-dashoffset` edge-draw, and rAF
+   count-ups. This skill's own `assets/scene-kit.js` already implements the specific components you
+   need for the dark-neon look — read the engine's recipes when you need a primitive `scene-kit.js`
+   doesn't cover yet, rather than inventing new CSS/JS from scratch.
+2. **Tooling.** `npx` (Playwright auto-fetches Chromium on first use: `npx playwright install
+   chromium`) and `ffmpeg`/`ffprobe` on PATH.
+
+### The pipeline (zero-React default)
+
+```
+scene brief → self-contained .html (SVG + GSAP, dark-neon theme, ?t=N seek harness)
+            → verify: scripts/seek-shot.sh + scripts/contact-sheet.sh (freeze/tile/eyeball)
+            → scripts/render-gif.sh (Playwright frame capture → FFmpeg palettegen/paletteuse)
+            → looping .gif
+```
+
+MP4 is optional and secondary — only reach for Remotion (the engine's Heavy tier) if the user
+explicitly wants a social/video export; the GIF path has no React/build dependency.
+
+### 1. Author the scene
+
+Start from `examples/jwt-reel.html` — copy it, then swap the nodes/palette/beats for your topic.
+It's a fully worked, self-contained example: theme tokens inlined, `scene-kit.js`-style builders
+inlined, a GSAP master timeline, the `?t=N` seek harness, `prefers-reduced-motion` handling, and
+the `window.__ready` signal the verify scripts wait on. Don't build a scene from a blank file —
+adapt the working one.
+
+- Design tokens (colors, fonts, stroke, glow): `references/design-tokens.md` /
+  `assets/theme.css`.
+- Component builders (panels, packets, badges, highlight-step, counters, layer stacks, session
+  grids): `references/component-library.md` / `assets/scene-kit.js`.
+- Keep the reel-vocabulary shape: nodes have a fixed accent color that never changes meaning,
+  a traveling `packet` is the payload, `scenes`/beats are timed and captioned, everything loops.
+- Honor `prefers-reduced-motion`: freeze to the final composed frame, no looping motion (see the
+  example's harness code — this mirrors both the engine's and `visual-explainer`'s a11y rule).
+
+### 2. Verify fidelity before rendering
+
+```bash
+scripts/seek-shot.sh your-scene.html 0 <mid> <end>
+scripts/contact-sheet.sh /tmp/sheet.png frame-0.png frame-<mid>.png frame-<end>.png
+```
+Eyeball the contact sheet: reveal order correct, connectors land on the right nodes, no
+clipped/off-canvas text, color grammar consistent, badges land on the intended frame.
+
+### 3. Render the GIF
+
+```bash
+scripts/render-gif.sh your-scene.html <duration_s> <fps> out.gif [width] [viewport WxH]
+# e.g.
+scripts/render-gif.sh examples/jwt-reel.html 12 15 jwt-reel.gif 480 400,640
+```
+Pass `[viewport WxH]` matching your scene's stage pixel size for a tight crop (no black margin).
+Cap width ~480–720px and fps ~15–20 to keep GIF size sane; the script already loops seamlessly
+(`-loop 0`) and dithers (`paletteuse=dither=sierra2_4a`) so neon-on-black gradients don't band.
+
+### 4. (Optional) MP4 export
+
+Only if the user asks for a social/video export: build the scene as a Remotion composition per
+`diagram-animation`'s Heavy tier, then assert it with the engine's `scripts/probe-mp4.sh`. Not
+required for the GIF path — don't block on it.
+
+### Output contract (`reel`)
+
+- Primary: `<name>.gif` — looping, embed-friendly, drops into HTML/markdown.
+- Always also produce: `<name>.html` — the self-contained authoring/preview scene (so it can be
+  scrubbed and re-rendered later).
+- Optional: `<name>.mp4` — only on explicit request.
+
+### Golden reference (`reel`)
+
+`examples/jwt-reel.html` reproduces the *style/technique* of a JWT auth-flow reel (mint → travel
+client→server → verify badge → tamper → HACKER reject, "STATELESS · NO SESSION STORE" footer) —
+the acceptance demo for this skill (issue #598). It's a technique reproduction, not a copy of any
+specific creator's video: swap the placeholder `@your_handle` chrome for your own before
+publishing, and don't reuse anyone's exact copy/branding.
+
+## Mode: `interactive`
+
+A self-contained, clickable HTML page: horizontal **bands = systems**, nodes placed in time order
+within their band, edges that jump a band = a network hop (labeled), continuous flow-particles
+along each edge (CSS `offset-path`), a click-node → detail panel, and tabs for switching between
+flow variants. Full schema + composition instructions: `references/interactive-mode.md`.
+
+1. **Don't build this from scratch or from `visual-explainer`'s general guidance alone.** Start
+   from `assets/swimlane-preset.html` — copy it, then replace the `BANDS`/`FLOWS` data with your
+   own systems/nodes/edges. It already has the working mechanism (bands, SVG edges + particles,
+   detail panel, tabs, "Animate flow", `prefers-reduced-motion` handling).
+2. Fill in nodes per `references/interactive-mode.md`'s schema (`sys`, `lane`, `col`, title,
+   subtitle, and optional `detail`/`path`/`writes`/`flag`/`badge`/`ok`/`svc`).
+3. Open the result in a browser (or `visual-explainer`'s render step) — no GIF/render pipeline
+   needed; the interactive HTML *is* the deliverable.
+4. If the user also wants a static preview image, one `playwright screenshot` of the default tab
+   is enough — don't run the `reel` mode's GIF pipeline for this.
+
+### Output contract (`interactive`)
+
+- Primary: `<name>.html` — self-contained, interactive, opens directly in a browser.
+- No GIF/MP4 by default (there's no single "frame" to loop); add a screenshot only if asked.
+
+## Attribution
+
+Dark-neon monoline reel style (`mode=reel`) decoded from `@duchminh_nguyen`'s reel series
+(research handoff, `docs/specs/2026-07-23-animated-system-graph-skill.md` §0) — style/technique
+reproduction only. Engine (`diagram-animation`, `seek-shot.sh`, `contact-sheet.sh`) from
+`iart-ai/explainer-video-skills`, MIT license — see `scripts/README.md`. Swimlane preset
+(`mode=interactive`) generalizes the bands/particles/detail-panel mechanism first produced by the
+`visual-explainer` skill — see `references/interactive-mode.md`.

package/plugin/skills/explainer-reel/assets/scene-kit.js

@@ -0,0 +1,196 @@
+/*
+  explainer-reel scene-kit — reusable SVG component builders + a GSAP master-timeline helper.
+  Reference library: copy the functions you need inline into a scene's single <script> block.
+  Depends on GSAP (load from CDN in the scene HTML, matching diagram-animation's stack) and the
+  `.er-*` classes from theme.css. See ../references/component-library.md for usage + a full example.
+
+  Primitives map 1:1 onto the reel's shared vocabulary (spec §0):
+    createPanel   -> CLIENT/SERVER terminal node
+    createFunnel  -> "mint" node
+    createPacket  -> the traveling token/cookie/packet (edge payload)
+    travel        -> flow-particle: move a packet along an edge
+    morphPacket   -> content morph (text + accent color)
+    badgeCheck / badgeHacker -> pop-in state badges
+    magnifier     -> verify affordance
+    dimOthers     -> highlight-step (focus one element, dim the rest)
+    countUp       -> rAF count-up (Caching Layers style)
+    layerStack / sessionGrid -> bonus nodes for the Cookies / Caching Layers scenes
+*/
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+function el(tag, attrs = {}, parent) {
+  const n = document.createElementNS(SVG_NS, tag);
+  for (const [k, v] of Object.entries(attrs)) n.setAttribute(k, v);
+  if (parent) parent.appendChild(n);
+  return n;
+}
+
+/** Chrome: handle / title / footer above and below the SVG stage. Call once per scene. */
+function createChrome(root, { handle, title, footer }) {
+  root.insertAdjacentHTML('afterbegin', `
+    <div class="er-handle">@${handle}</div>
+    <div class="er-title">${title}</div>
+    <hr class="er-title-rule">
+  `);
+  root.insertAdjacentHTML('beforeend', `<div class="er-footer">${footer}</div>`);
+}
+
+/** Standard glow filter — call once, then apply class="er-glow" to any accent element. */
+function defineGlow(svg, blur = 4) {
+  const defs = el('defs', {}, svg);
+  const f = el('filter', { id: 'er-glow', x: '-60%', y: '-60%', width: '220%', height: '220%' }, defs);
+  el('feGaussianBlur', { stdDeviation: blur, result: 'blur' }, f);
+  const merge = el('feMerge', {}, f);
+  el('feMergeNode', { in: 'blur' }, merge);
+  el('feMergeNode', { in: 'SourceGraphic' }, merge);
+  return f;
+}
+
+/** The "mint" node — a thin V-funnel where a packet is spawned. */
+function createFunnel(svg, { x, y, w = 44, h = 40 }) {
+  return el('path', {
+    class: 'er-mono',
+    d: `M ${x - w / 2} ${y} L ${x} ${y + h} L ${x + w / 2} ${y}`,
+  }, svg);
+}
+
+/** A terminal-style panel node (CLIENT / SERVER): header dots + title + N fake code lines. */
+function createPanel(svg, { x, y, w = 150, h = 90, label, accent, lines = 4, activeLine = 0 }) {
+  const g = el('g', { class: 'er-panel', 'data-id': label }, svg);
+  el('rect', { class: 'er-panel-rect', x, y, width: w, height: h, stroke: accent }, g);
+  el('circle', { class: 'er-panel-dot', cx: x + 12, cy: y + 14, r: 2, fill: accent }, g);
+  el('circle', { class: 'er-panel-dot', cx: x + 20, cy: y + 14, r: 2, fill: accent }, g);
+  el('circle', { class: 'er-panel-dot', cx: x + 28, cy: y + 14, r: 2, fill: accent }, g);
+  el('text', { class: 'er-panel-title', x: x + 38, y: y + 18, fill: accent }, g).textContent = `>>> ${label}`;
+  const lineH = (h - 30) / lines;
+  for (let i = 0; i < lines; i++) {
+    const ly = y + 30 + i * lineH + lineH / 2;
+    el('line', { class: 'er-panel-line', x1: x + 12, y1: ly, x2: x + w - 24, y2: ly }, g);
+    el('circle', {
+      class: 'er-panel-dot', cx: x + w - 12, cy: ly, r: 2.5,
+      fill: i === activeLine ? accent : 'var(--er-line-dim)',
+    }, g);
+  }
+  return g;
+}
+
+/** The traveling packet: [icon cell | label cell | icon cell], a perforated-ticket pill. */
+function createPacket(svg, { x, y, label, sublabel = '', accent = 'var(--er-line)' }) {
+  const g = el('g', { class: 'er-packet', transform: `translate(${x},${y})` }, svg);
+  el('rect', { class: 'er-pill-rect', x: -14, y: -12, width: 28, height: 24, stroke: accent }, g);
+  for (const dy of [-6, 0, 6]) el('circle', { cx: -14, cy: dy, r: 1.2, fill: accent }, g);
+  const body = el('rect', { class: 'er-pill-rect', x: 16, y: -12, width: 64, height: 24, stroke: accent }, g);
+  const text = el('text', {
+    class: 'er-pill-text', x: 48, y: sublabel ? -1 : 4, 'text-anchor': 'middle', fill: accent,
+  }, g);
+  text.textContent = label;
+  let subEl = null;
+  if (sublabel) {
+    subEl = el('text', {
+      class: 'er-pill-text', x: 48, y: 9, 'text-anchor': 'middle', fill: 'var(--er-line-dim)',
+      style: 'font-size:6px',
+    }, g);
+    subEl.textContent = sublabel;
+  }
+  el('rect', { class: 'er-pill-rect', x: 84, y: -12, width: 20, height: 24, stroke: accent }, g);
+  for (let i = 0; i < 4; i++) {
+    el('rect', {
+      x: 88 + i * 4, y: 2 - i * 2, width: 2, height: 6 + i * 2, fill: accent,
+    }, g);
+  }
+  return { group: g, body, text, subEl };
+}
+
+/** Move a packet group along a straight edge (from -> to), added to the master timeline `tl`. */
+function travel(tl, packet, { from, to, duration = 2, at }) {
+  tl.fromTo(packet.group, { x: from.x, y: from.y }, {
+    x: to.x, y: to.y, duration, ease: 'power1.inOut',
+  }, at);
+}
+
+/** Morph a packet's label/sublabel text + accent color (content morph). */
+function morphPacket(tl, packet, { label, sublabel, color }, at) {
+  tl.call(() => {
+    packet.text.textContent = label;
+    if (sublabel && packet.subEl) packet.subEl.textContent = sublabel;
+    packet.body.setAttribute('stroke', color);
+    packet.text.setAttribute('fill', color);
+  }, null, at);
+}
+
+/** Verify affordance: a small magnifying-glass glyph pinned near a node. */
+function magnifier(svg, { x, y }) {
+  const g = el('g', { class: 'er-magnifier', transform: `translate(${x},${y})`, opacity: 0 }, svg);
+  el('circle', { class: 'er-mono', cx: -2, cy: -2, r: 6 }, g);
+  el('line', { class: 'er-mono', x1: 2, y1: 2, x2: 7, y2: 7 }, g);
+  return g;
+}
+
+/** Green check badge pop-in (verified / ok). */
+function badgeCheck(svg, { x, y }) {
+  const g = el('g', {
+    class: 'er-badge-check er-glow', transform: `translate(${x},${y}) scale(0.6)`, opacity: 0,
+  }, svg);
+  el('circle', { class: 'er-badge-hex', r: 9, stroke: 'var(--er-ok)' }, g);
+  el('path', { d: 'M -4 0 L -1 4 L 5 -5', class: 'er-mono', stroke: 'var(--er-ok)', 'stroke-width': 2 }, g);
+  return g;
+}
+
+/** Red HACKER hexagon badge pop-in (tamper detected / reject). */
+function badgeHacker(svg, { x, y }) {
+  const g = el('g', {
+    class: 'er-badge-hacker er-glow', transform: `translate(${x},${y}) scale(0.6)`, opacity: 0,
+  }, svg);
+  const pts = [0, -12, 10, -6, 10, 6, 0, 12, -10, 6, -10, -6].reduce((s, v, i) =>
+    s + (i % 2 === 0 ? `${v},` : `${v} `), '');
+  el('polygon', { points: pts, class: 'er-badge-hex', stroke: 'var(--er-danger)' }, g);
+  el('circle', { r: 6, class: 'er-badge-hex', stroke: 'var(--er-danger)' }, g);
+  el('line', { x1: -4, y1: -4, x2: 4, y2: 4, stroke: 'var(--er-danger)', 'stroke-width': 1.5 }, g);
+  el('text', {
+    class: 'er-badge-label', x: 0, y: 24, 'text-anchor': 'middle', fill: 'var(--er-danger)',
+  }, g).textContent = 'HACKER';
+  return g;
+}
+
+/** Highlight-step: fade every `.er-panel` except the active one (focus + context). */
+function dimOthers(tl, svg, activeId, at) {
+  tl.to(svg.querySelectorAll(`.er-panel:not([data-id="${activeId}"])`), { opacity: 0.35, duration: 0.3 }, at)
+    .to(svg.querySelector(`.er-panel[data-id="${activeId}"]`), { opacity: 1, duration: 0.3 }, at);
+}
+
+/** rAF-driven count-up for a <text> element (Caching Layers "DB queries" style counter). */
+function countUp(el, to, dur = 1200) {
+  const t0 = performance.now();
+  (function tick(now) {
+    const k = Math.min(1, (now - t0) / dur);
+    const e = 1 - Math.pow(1 - k, 3);
+    el.textContent = Math.round(to * e);
+    if (k < 1) requestAnimationFrame(tick);
+  })(t0);
+}
+
+/** Bonus node: vertical layer stack (Caching Layers scene) — client / cache / redis / db. */
+function layerStack(svg, { x, y, w = 140, layers }) {
+  const g = el('g', { class: 'er-layer-stack' }, svg);
+  layers.forEach((layer, i) => {
+    const ly = y + i * 56;
+    el('rect', { class: 'er-panel-rect', x, y: ly, width: w, height: 40, stroke: layer.accent }, g);
+    el('text', { class: 'er-panel-title', x: x + 10, y: ly + 24, fill: layer.accent }, g).textContent = layer.label;
+  });
+  return g;
+}
+
+/** Bonus node: session-store grid (Cookies scene) — a cell lights up green when a session lands. */
+function sessionGrid(svg, { x, y, cols = 5, rows = 2, cell = 18, gap = 4 }) {
+  const g = el('g', { class: 'er-session-grid' }, svg);
+  const cells = [];
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      cells.push(el('rect', {
+        class: 'er-mono', x: x + c * (cell + gap), y: y + r * (cell + gap), width: cell, height: cell, rx: 2,
+      }, g));
+    }
+  }
+  return { group: g, cells };
+}