@khanglvm/relay 0.2.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@khanglvm/relay",
+  "version": "0.2.0",
+  "description": "Browser-based question boards with rich blocks (markdown, charts, mermaid, tables, code, sandboxed HTML) and element-level annotations for AI coding agents (Claude Code, Codex, …): ask users structured questions, present interactive visuals, collect inline comments, wait for submit, read answers as JSON.",
+  "keywords": [
+    "ai-agents",
+    "claude-code",
+    "codex",
+    "cli",
+    "interactive-questions",
+    "human-in-the-loop",
+    "annotations",
+    "charts",
+    "prototype",
+    "visualization",
+    "agent-skill"
+  ],
+  "license": "MIT",
+  "author": "Le Vu Minh Khang (https://github.com/khanglvm)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/khanglvm/relay.git"
+  },
+  "homepage": "https://github.com/khanglvm/relay#readme",
+  "bugs": "https://github.com/khanglvm/relay/issues",
+  "type": "module",
+  "bin": {
+    "rly": "bin/rly.js",
+    "relay": "bin/rly.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "vendor",
+    "skills",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.3"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs"
+  }
+}

package/skills/relay/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: relay
+description: Ask the user interactive questions in a browser board (single/multi choice, yes-no, free text, scale) and/or present rich content blocks (markdown, mermaid diagrams, charts, interactive tables, code, sandboxed HTML), then wait for Submit and read JSON answers plus element-level annotations. PROACTIVELY use whenever you would otherwise (a) call a native ask-user/question tool with 2+ questions or options that need explanation, (b) describe a UI/design/plan/architecture in prose that a visual would show better — draft diagrams (mermaid), charts, and interactive tables as native blocks, or (c) hand-roll an HTML file or local server to demo an idea - relay replaces all three. Triggers - clarify requirements before ambiguous work, choose between approaches, plan approval, design/UX feedback, mockup or prototype review, compare alternatives, survey, metrics review, "ask the user", "show the user", "which do you prefer", "get feedback", diagram, chart, data table, architecture overview, metrics. Skip only for a single trivial yes/no confirmation.
+---
+
+# relay (`rly`)
+
+CLI that opens a local web board for the user, blocks until they click
+**Submit**, and prints their answers plus element-level annotations as JSON to
+stdout. Works for any agent (Claude Code, Codex, …). Answers autosave in real
+time; the tab auto-closes after submit.
+
+If `rly` is not installed: `npm i -g @khanglvm/relay` or invoke via
+`npx -y @khanglvm/relay <command …>`.
+
+**Full reference: run `rly agent` (complete guide) and `rly schema` (spec JSON
+Schema).** The essentials are below.
+
+## When to use rly vs your native question tool
+
+| Situation | Use |
+|---|---|
+| One trivial confirmation ("proceed?") | native tool |
+| 2+ questions, or options that need descriptions | **rly** |
+| Choice is easier to make visually (layouts, designs, diagrams) | **rly** (blocks per question) |
+| Show metrics / trends / data comparisons | **rly** (chart + table blocks) |
+| Present a prototype / demo an idea | **rly show** — never hand-roll an HTML file + server |
+| Gather requirements / plan approval / feedback round | **rly** |
+| Architecture or flow that benefits from a diagram | **rly** (mermaid block) |
+| Something you can decide yourself from context | neither — just decide |
+
+Once the user has answered one board in a session, prefer boards for later
+question rounds too — they've shown they engage with them. Batch related
+questions into ONE board rather than opening several in a row.
+
+## Choose a pattern
+
+1. **Blocking** — simple, but your shell tool must tolerate waiting:
+
+   ```sh
+   rly ask --file spec.json --timeout 1800   # prints result JSON when user submits
+   ```
+
+2. **Detached** — use when your shell tool has an execution time limit
+   (e.g. run it, then wait in a separate call):
+
+   ```sh
+   rly ask --file spec.json --detach    # → {"boardId":"b-…","url":…} immediately
+   rly wait b-xxxxx --timeout 3500      # blocks until submit, prints result JSON
+   rly result b-xxxxx                   # non-blocking peek (includes live draft)
+   ```
+
+Exit codes: 0 submitted · 2 timeout · 3 cancelled · 5 not found. On
+timeout/cancel the result still contains the autosaved `draft` of partial
+answers and any annotations written so far.
+
+## Minimal spec
+
+```json
+{
+  "title": "Pick the approach",
+  "intro": "Context for the user. Hover chart points or select text to leave comments.",
+  "questions": [
+    { "id": "approach", "type": "single", "label": "Which one?", "required": true,
+      "options": [{ "value": "a", "label": "A", "description": "fast" }, "B"], "other": true },
+    { "id": "parts", "type": "multi", "label": "Include?", "options": ["api", "ui"], "note": true },
+    { "id": "ship", "type": "yesno", "label": "Ship now?" },
+    { "id": "why", "type": "textarea", "label": "Reasoning?" },
+    { "id": "conf", "type": "scale", "label": "Confidence", "min": 1, "max": 5 }
+  ]
+}
+```
+
+Types: `single`, `multi`, `yesno`, `text`, `textarea`, `scale`. Users may
+submit with unanswered questions (returned in `skipped`) unless
+`"allowPartial": false` or per-question `"required": true`.
+
+Set `"note": true` on a question to add a small optional free-text field under
+it — use when the user may want to qualify their choice. Returned as
+`result.notes[questionId]`.
+
+Quick one-liners without a spec file:
+
+```sh
+rly ask -q "Deploy now?::yesno" -q "!Env::single::dev,staging,prod"   # "!" = required
+```
+
+## Blocks cheat-sheet
+
+Add `"blocks": [...]` to the root or to any question.
+
+```jsonc
+{ "type": "markdown", "md": "## Section\n**prose**" }
+{ "type": "mermaid",  "code": "graph TD; A-->B",     "height": 400 }
+{ "type": "chart",    "kind": "bar",  "title": "...",
+  "labels": ["Jan","Feb"], "series": [{"label":"x","data":[1,2]}], "height": 320 }
+{ "type": "chart",    "config": { /* full Chart.js v4 config */ }, "height": 300 }
+{ "type": "table",    "columns": ["A","B"], "rows": [["x","y"]], "sortable": true }
+{ "type": "code",     "lang": "js",  "code": "const x = 1;" }
+{ "type": "html",     "html": "<p>hi</p>",           "height": 360 }
+{ "type": "html",     "htmlFile": "viz.html",         "height": 400 }
+```
+
+Chart.js and Mermaid are **vendored and lazy-loaded** — the base board stays
+dependency-free. Legacy `"html"` / `"htmlFile"` / `"htmlHeight"` on root or
+questions are still accepted and normalised automatically.
+
+## Annotations
+
+Users can hover chart points, diagram nodes, table cells, or select text in
+markdown to leave inline comments. Always mention this in the board intro.
+
+`result.annotations` is an array of:
+
+```json
+{
+  "id": "a1",
+  "questionId": "q-id or null",
+  "blockId": "b2",
+  "target": {
+    "kind": "chart-element | mermaid-node | table-cell | text | html-element",
+    "..."
+  },
+  "text": "user comment",
+  "createdAt": "ISO"
+}
+```
+
+Read annotations before generating your next output — a comment on a specific
+data point often carries sharper signal than a checkbox answer.
+
+## Recipes
+
+**Plan approval** — board-level `markdown` block rendering the plan, one `yesno`
+"Approve this plan?", one `multi` "Which parts should change?" (`"note": true`),
+one `textarea` for concerns.
+
+**Requirements gathering** — one board with: `single` for the core approach
+(options with `description`s + `"other": true`), `multi` for scope, `scale` for
+urgency, `textarea` for constraints.
+
+**A/B design review** — `single` question with a `blocks` array containing an
+`html` block showing both options side by side; options `["A", "B"]`; `scale`
+for confidence; `textarea` for what's missing from both.
+
+**Metrics review** — board-level `chart` block (bar or line) showing the key
+numbers, followed by a `table` block for the raw data; at least one question
+asking what to act on. In the intro, tell the user they can click chart points
+and table cells to comment on specific values.
+
+## Reuse & management
+
+`rly history` (saved boards) · `rly spec <id>` (print spec to modify) ·
+`rly reuse <id>` (re-run blank) · `rly reopen <id>` (re-open with saved
+answers prefilled) · `rly list` / `rly open` / `rly stop <id>` · `rly rm <id>`.
+Multiple boards can run concurrently.

package/skills/relay/examples/blocks-showcase.json

@@ -0,0 +1,118 @@
+{
+  "title": "Q2 engineering review",
+  "intro": "Below you'll find the sprint metrics, architecture overview, and a data table. Hover chart bars, click diagram nodes, or click table cells to leave inline comments — they come back with your answers. Select any text in a markdown section to annotate it too.",
+  "blocks": [
+    {
+      "type": "markdown",
+      "md": "## Sprint velocity\nThe chart below shows shipped vs planned story points for each sprint this quarter. Click any bar to comment on a specific sprint."
+    },
+    {
+      "type": "chart",
+      "kind": "bar",
+      "title": "Q2 velocity — shipped vs planned",
+      "labels": ["S1", "S2", "S3", "S4", "S5", "S6"],
+      "series": [
+        { "label": "Shipped", "data": [34, 41, 29, 47, 38, 52], "color": "#4d8a66" },
+        { "label": "Planned", "data": [40, 40, 40, 40, 40, 40], "color": "#c2674b" }
+      ],
+      "height": 320
+    },
+    {
+      "type": "markdown",
+      "md": "## System architecture\nThe diagram below shows the current service topology. Click any node to comment on it."
+    },
+    {
+      "type": "mermaid",
+      "code": "graph LR\n  Client-->|HTTPS|Gateway\n  Gateway-->AuthService\n  Gateway-->APIService\n  APIService-->DB[(Postgres)]\n  APIService-->Cache[(Redis)]\n  APIService-->Queue[[Job queue]]\n  Queue-->Worker\n  Worker-->DB",
+      "height": 300
+    },
+    {
+      "type": "markdown",
+      "md": "## Service health snapshot\nCurrent status as of the last deployment. Click any cell to comment."
+    },
+    {
+      "type": "table",
+      "columns": [
+        { "key": "service",  "label": "Service" },
+        { "key": "status",   "label": "Status",      "align": "center" },
+        { "key": "p99ms",    "label": "p99 (ms)",     "align": "right" },
+        { "key": "errRate",  "label": "Error rate",   "align": "right" },
+        { "key": "owner",    "label": "Owner" }
+      ],
+      "rows": [
+        { "service": "Gateway",     "status": "healthy",  "p99ms": 42,  "errRate": "0.1%", "owner": "platform" },
+        { "service": "AuthService", "status": "healthy",  "p99ms": 98,  "errRate": "0.0%", "owner": "identity" },
+        { "service": "APIService",  "status": "degraded", "p99ms": 620, "errRate": "2.4%", "owner": "core" },
+        { "service": "Worker",      "status": "healthy",  "p99ms": 310, "errRate": "0.3%", "owner": "core" }
+      ],
+      "sortable": true
+    },
+    {
+      "type": "markdown",
+      "md": "## Config reference\nDeployment config in use this quarter:"
+    },
+    {
+      "type": "code",
+      "lang": "yaml",
+      "code": "api_service:\n  replicas: 4\n  memory_limit: 512Mi\n  cpu_limit: 500m\n  db_pool_size: 20\n  cache_ttl_s: 300"
+    }
+  ],
+  "questions": [
+    {
+      "id": "biggest_concern",
+      "type": "single",
+      "label": "Which area needs the most attention next quarter?",
+      "required": true,
+      "options": [
+        { "value": "api_perf",    "label": "API Service performance", "description": "p99 and error rate are high" },
+        { "value": "velocity",    "label": "Sprint predictability",   "description": "variance between sprints" },
+        { "value": "arch",        "label": "Architecture complexity", "description": "service sprawl, dependency depth" },
+        { "value": "on_call",     "label": "On-call burden",         "description": "toil from degraded services" }
+      ],
+      "other": true,
+      "note": true
+    },
+    {
+      "id": "api_degraded_cause",
+      "type": "single",
+      "label": "What is most likely causing the APIService degradation?",
+      "options": [
+        { "value": "db_pool",   "label": "DB connection pool exhaustion" },
+        { "value": "cache_miss","label": "Cache miss storm" },
+        { "value": "upstream",  "label": "Upstream traffic spike" },
+        { "value": "unknown",   "label": "Unknown — needs investigation" }
+      ],
+      "other": true
+    },
+    {
+      "id": "ship_reliability_work",
+      "type": "yesno",
+      "label": "Should we dedicate at least one sprint to reliability before adding features?"
+    },
+    {
+      "id": "velocity_target",
+      "type": "scale",
+      "label": "How ambitious should Q3's velocity target be?",
+      "min": 1,
+      "max": 5,
+      "minLabel": "conservative (≤40 pts)",
+      "maxLabel": "aggressive (60+ pts)",
+      "blocks": [
+        {
+          "type": "markdown",
+          "md": "Current average: **40 pts/sprint**. Improving reliability tooling could raise the ceiling, but also costs sprint capacity up front."
+        }
+      ]
+    },
+    {
+      "id": "other_notes",
+      "type": "textarea",
+      "label": "Anything else I should factor in for Q3 planning?",
+      "placeholder": "team changes, external deadlines, tech debt priorities…"
+    }
+  ],
+  "note": true,
+  "allowPartial": false,
+  "autoClose": true,
+  "submitLabel": "Submit review"
+}

package/skills/relay/examples/feature-feedback.json

@@ -0,0 +1,27 @@
+{
+  "title": "Auth feature — decisions needed",
+  "intro": "I'm about to implement authentication. Three decisions before I start. Hover chart points or select text to leave comments.",
+  "questions": [
+    {
+      "id": "provider",
+      "type": "single",
+      "label": "Which auth approach?",
+      "required": true,
+      "options": [
+        { "value": "oauth", "label": "OAuth (GitHub + Google)", "description": "no password storage, needs provider setup" },
+        { "value": "magic-link", "label": "Magic links", "description": "email-based, no passwords" },
+        { "value": "password", "label": "Classic email + password", "description": "full control, more security surface" }
+      ],
+      "other": true
+    },
+    {
+      "id": "scope",
+      "type": "multi",
+      "label": "Which surfaces need auth in this iteration?",
+      "options": ["web app", "REST API", "admin panel", "CLI"]
+    },
+    { "id": "mfa", "type": "yesno", "label": "Include 2FA now (vs. a later iteration)?" },
+    { "id": "priority", "type": "scale", "label": "How urgent is this feature?", "min": 1, "max": 5, "minLabel": "whenever", "maxLabel": "blocking" },
+    { "id": "constraints", "type": "textarea", "label": "Any constraints I should know about?", "placeholder": "compliance, existing user table, …" }
+  ]
+}

package/skills/relay/examples/prototype-review.json

@@ -0,0 +1,25 @@
+{
+  "title": "Dashboard layout — pick a direction",
+  "intro": "Two interactive mockups below. Click around, then answer. Select any text to leave inline comments.",
+  "questions": [
+    {
+      "id": "layout",
+      "type": "single",
+      "label": "Which layout direction?",
+      "required": true,
+      "blocks": [
+        {
+          "type": "html",
+          "html": "<!doctype html><html><body style=\"margin:0;font-family:system-ui;display:flex;gap:12px;padding:12px;background:#fff\"><div style=\"flex:1;border:2px solid #3b6ef6;border-radius:10px;padding:10px\"><b>A · sidebar</b><div style=\"display:flex;gap:6px;margin-top:8px\"><div style=\"width:60px;height:120px;background:#dbe4ff;border-radius:6px\"></div><div style=\"flex:1;height:120px;background:#f1f3f9;border-radius:6px\"></div></div></div><div style=\"flex:1;border:2px solid #999;border-radius:10px;padding:10px\"><b>B · topbar</b><div style=\"margin-top:8px\"><div style=\"height:24px;background:#dbe4ff;border-radius:6px\"></div><div style=\"height:90px;background:#f1f3f9;border-radius:6px;margin-top:6px\"></div></div></div></body></html>",
+          "height": 220
+        }
+      ],
+      "options": [
+        { "value": "sidebar", "label": "A — sidebar navigation" },
+        { "value": "topbar",  "label": "B — topbar navigation" }
+      ]
+    },
+    { "id": "density", "type": "scale", "label": "Information density?", "min": 1, "max": 5, "minLabel": "airy", "maxLabel": "dense" },
+    { "id": "missing", "type": "textarea", "label": "Anything missing from both?" }
+  ]
+}