lastlight 0.1.15 → 0.2.1

package/skills/demo/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: demo
+description: Record a short demo VIDEO of a PR or feature — drive the repo's web UI in a real headless browser, capture the session, and composite a titled, size-capped mp4 with ffmpeg. Use on the docker QA image when the deliverable is a playable demo clip (single walkthrough or before/after comparison), not a text/screenshot report.
+version: 1.0.0
+tags: [demo, video, browser, ffmpeg, evidence]
+---
+
+# Demo
+
+Turn a PR or feature into a short, polished **demo video**: drive the repo's
+web UI in a real headless Chromium, screen-record the session, and composite a
+titled, size-capped **mp4** the maintainer can watch inline.
+
+This is the **video** sibling of `browser-qa` (screenshots) and `verify`/
+`qa-test` (text evidence). It only works on the `lastlight-sandbox-qa:latest`
+docker image, which bakes in Playwright + Chromium **and ffmpeg**. You have
+bash + file tools but **no vision** — you reason over the driver's JSON stdout
+and the ffprobe summary; you never "see" the video.
+
+Compositing is **ffmpeg only** — there is no Remotion / cinematic-effects
+pipeline. You get a title card, optional before/after side-by-side, trim/speed,
+and a size cap. That's the deliverable: a clear, honest walkthrough, not a
+marketing reel.
+
+This skill uses **browser-qa** (the headless driver) and **building** (install
++ start the dev-server).
+
+## When this applies
+
+A phase on the docker QA image whose target is a **web app** the repo serves on
+`localhost`, where a *moving* demonstration adds value over a screenshot. For a
+CLI, a curl-able API, or pure pass/fail evidence, use `qa-test`/`verify`. For
+static screenshot evidence, use `browser-qa`. Don't record a video you don't
+need.
+
+## FIRST — probe for a browser
+
+The browser driver lives in the **browser-qa** skill bundle at
+`<browser-qa-dir>/scripts/agent-browser.mjs`, and this skill's compositor at
+`<demo-dir>/scripts/compose-demo.sh`. Resolve both `<…-dir>` paths from the
+available-skills catalogue (it gives each skill's absolute staged path); do not
+assume a relative path from `$PWD` — your cwd is the checked-out repo, the
+bundles are siblings.
+
+Run the runtime probe before anything else:
+
+```bash
+node <browser-qa-dir>/scripts/agent-browser.mjs doctor
+```
+
+- Exit 0 with `{"ok":true,...}` → proceed.
+- Exit non-zero (lean image / gondolin / no Chromium) → **DO NOT attempt a demo.**
+  Report that the demo path was unavailable on this host and stop. (The workflow
+  gates this phase to the QA image, so this should be rare — but never fake a
+  recording.)
+
+## Understand what to prove
+
+Read the PR (description, diff, linked issue) from the context the prompt gives
+you. For each change, ask: *what could a viewer confuse this with?* Design the
+demo so the viewer sees something that **only happens if the feature works as
+claimed** — both states (before/after, input/result) must appear on screen.
+
+State your **commitments** up front, then honour them:
+
+- **Layout** — `single` (default: a new feature, a fix proof, a walkthrough) or
+  `side-by-side` (only when the story is fundamentally a comparison: regression
+  fixed, behaviour-preserving refactor). Never fabricate a "before" to justify
+  side-by-side.
+- **Speed** — target a watchable length; speed up dead time rather than leaving
+  it. 30–60s is a good single-feature target.
+
+## Build and run the app
+
+Follow the **building** skill to install dependencies, then start the repo's
+dev-server **in the background** and poll with `curl` until it answers on
+`localhost:PORT`. Note the port — you pass it as `--base-url`.
+
+## Capture the session
+
+Author a `flow.json` (same shape as **browser-qa**) that scripts the
+interaction as a *director*, not an operator:
+
+- **Record the baseline first** — the starting state is act one.
+- **Hold after state changes** — add a `waitFor`/short pause so text is readable.
+- **Verify between steps** — `waitFor` the expected element before the next
+  action; don't blindly fire keys into an unsettled page.
+
+Record the session by passing `--record-dir`:
+
+```bash
+node <browser-qa-dir>/scripts/agent-browser.mjs run flow.json \
+  --base-url http://localhost:PORT \
+  --record-dir /tmp/demo-cap
+# → writes /tmp/demo-cap/session.webm, reports {"video":"…/session.webm", …}
+```
+
+Pick the viewport to match the layout so the clip isn't letterboxed:
+`1280x720` for `single`; `~960x1000` per panel for `side-by-side` (set it in the
+flow's `viewport`).
+
+**Before/after comparison:** check out and run each branch in turn (the
+`building` skill), recording the **same** scripted interaction against each —
+`session-before.webm` (base branch) and `session-after.webm` (PR head). Only the
+behaviour should differ.
+
+## Compose the video
+
+Composite the raw recording(s) into the final mp4 with the bundled wrapper:
+
+```bash
+# Single walkthrough
+<demo-dir>/scripts/compose-demo.sh \
+  --output <artifact-dir>/demo.mp4 \
+  --title "PR #42 — Add dark mode toggle" \
+  --subtitle "Toggling persists the theme across reloads" \
+  --layout single --speed 1.5 --target-size-mb 5 \
+  /tmp/demo-cap/session.webm
+
+# Before/after comparison
+<demo-dir>/scripts/compose-demo.sh \
+  --output <artifact-dir>/demo.mp4 \
+  --title "PR #51 — Fix flicker on load" \
+  --layout side-by-side --labels "BEFORE (main)" "AFTER (PR)" \
+  --target-size-mb 5 \
+  /tmp/before/session-before.webm /tmp/after/session-after.webm
+```
+
+Flags: `--title` (required, on the card), `--subtitle`, `--layout
+single|side-by-side`, `--labels A B` (side-by-side), `--speed N`, `--trim
+START:END` (seconds, single layout), `--target-size-mb` (default 5),
+`--width/--height` (default 1280×720), `--title-secs`. The script normalizes,
+lays out, adds the title card, and does a **two-pass** encode to land under the
+size cap (`+faststart`, `yuv420p`). It prints a JSON summary line:
+`{"output":"…","resolution":"1280x720","duration":"38.4","size_mb":3.1}`.
+
+## Guardrails — self-check before reporting
+
+Confirm the output with `ffprobe` (the script's summary already reports these):
+
+- **Resolution** matches the requested size (default 1920-free 1280×720).
+- **Duration** is sane — not 0s, within a watchable band (~15–90s).
+- **Size ≤ 5 MB** so GitHub embeds it inline (25 MB hard limit). If over, re-run
+  with a lower `--target-size-mb` or a higher `--speed`.
+
+If the recording is too short to be meaningful (a couple of seconds), go back
+and add interaction steps — don't ship a clip that proves nothing.
+
+## Output location
+
+Write `demo.mp4` into the **artifact directory the prompt provides** (the run's
+`.lastlight/<issueKey>/` dir, referenced by the template variable the prompt
+passes). The harness harvests it into the dashboard Artifacts view, and the
+public artifact URL makes it playable inline on GitHub. Do **not** commit the
+mp4 into the repo, and do **not** post it yourself — the workflow embeds it.
+
+Video delivery requires **server-mode build-assets**. If the mp4 can't be
+persisted (no artifact dir provided, or repo-mode), say so in the report and
+describe what the demo showed instead.
+
+## Evidence rules
+
+Mirror `verify`/`browser-qa` — you are demonstrating real behaviour, not selling
+it:
+
+- **Never fake it.** Don't edit the code under test to force a nicer demo, and
+  don't stage a result the feature didn't actually produce.
+- **Show the disambiguating moment** — the thing that only happens if the change
+  works. Off-camera claims don't count.
+- If something doesn't work, the honest demo shows that — report it; don't trim
+  the failure out and call it a success.
+
+## Report
+
+Produce your report as your **final message** — the workflow posts it (don't
+comment yourself). Keep it short:
+
+```
+## Demo: <target>
+
+**Environment:** <branch / commit, package manager, how served, Chromium version>
+
+<one or two sentences: what the video demonstrates and the key moment to watch>
+
+- **Layout:** single | side-by-side
+- **Video:** demo.mp4 (<resolution>, <duration>s, <size>MB)
+
+### Not covered
+<one line: anything the demo doesn't show, and why>
+```
+
+The workflow embeds the playable video from the artifact store; reference it as
+`demo.mp4`. If the browser or compositor was unavailable, say so plainly instead
+of pretending a clip exists.

package/skills/demo/scripts/compose-demo.sh

@@ -0,0 +1,205 @@
+#!/usr/bin/env bash
+# compose-demo.sh — composite a raw browser screen recording into a titled,
+# size-capped demo mp4 using ffmpeg only (NO Remotion, NO headless render).
+#
+# Used by the `/demo` workflow: agent-browser records the session to a .webm,
+# this script turns it into a polished, GitHub-embeddable mp4.
+#
+# Usage:
+#   compose-demo.sh --output demo.mp4 --title "PR #42 — Add dark mode" \
+#     [--subtitle "..."] [--layout single|side-by-side] \
+#     [--labels "BEFORE (main)" "AFTER (PR)"] [--speed 1.5] \
+#     [--trim START:END] [--target-size-mb 5] [--width 1280] [--height 720] \
+#     [--title-secs 2.5] <clip1.webm> [clip2.webm]
+#
+# What it does:
+#   1. Normalizes each input clip (optional trim, speed-up, scale+pad to the
+#      panel size, fps/pixfmt/SAR normalize, optional per-panel label).
+#   2. Lays out the body: a single panel, or two panels side-by-side (hstack).
+#   3. Prepends a title/subtitle card (solid bg + drawtext).
+#   4. Two-pass H.264 encode targeting --target-size-mb so the mp4 lands under
+#      GitHub's inline-embed limit; yuv420p + +faststart for web streaming.
+#   5. Prints an ffprobe summary (resolution / duration / size).
+#
+# Prerequisites: ffmpeg, ffprobe (baked into lastlight-sandbox-qa:latest).
+# Runs fully offline.
+
+set -euo pipefail
+
+die() { echo "compose-demo.sh: error: $*" >&2; exit 1; }
+require_cmd() { command -v "$1" >/dev/null 2>&1 || die "required command not found: $1"; }
+require_cmd ffmpeg
+require_cmd ffprobe
+
+# ── Defaults ────────────────────────────────────────────────────────────────
+OUTPUT=""
+TITLE=""
+SUBTITLE=""
+LAYOUT="single"
+LABEL1=""
+LABEL2=""
+SPEED="1"
+TRIM=""
+TARGET_MB="5"
+WIDTH="1280"
+HEIGHT="720"
+TITLE_SECS="2.5"
+CLIPS=()
+
+# ── Parse args ──────────────────────────────────────────────────────────────
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --output) OUTPUT="$2"; shift 2;;
+    --title) TITLE="$2"; shift 2;;
+    --subtitle) SUBTITLE="$2"; shift 2;;
+    --layout) LAYOUT="$2"; shift 2;;
+    --labels) LABEL1="$2"; LABEL2="$3"; shift 3;;
+    --speed) SPEED="$2"; shift 2;;
+    --trim) TRIM="$2"; shift 2;;
+    --target-size-mb) TARGET_MB="$2"; shift 2;;
+    --width) WIDTH="$2"; shift 2;;
+    --height) HEIGHT="$2"; shift 2;;
+    --title-secs) TITLE_SECS="$2"; shift 2;;
+    -*) die "unknown flag: $1";;
+    *) CLIPS+=("$1"); shift;;
+  esac
+done
+
+[[ -n "$OUTPUT" ]] || die "--output is required"
+[[ ${#CLIPS[@]} -ge 1 ]] || die "at least one input clip is required"
+for c in "${CLIPS[@]}"; do [[ -f "$c" ]] || die "clip not found: $c"; done
+if [[ "$LAYOUT" == "side-by-side" ]]; then
+  [[ ${#CLIPS[@]} -ge 2 ]] || die "side-by-side layout needs two clips"
+fi
+
+WORK="$(mktemp -d "${TMPDIR:-/tmp}/compose-demo-XXXXXX")"
+cleanup() { rm -rf "$WORK"; }
+trap cleanup EXIT
+
+# ── Font for drawtext ────────────────────────────────────────────────────────
+# Prefer an explicit fontfile (Liberation ships in the QA image via
+# fonts-liberation); fall back to fontconfig's default Sans family.
+FONT="${DEMO_FONT:-}"
+if [[ -z "$FONT" ]]; then
+  for f in \
+    /usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf \
+    /usr/share/fonts/truetype/dejavu/DejaVuSans.ttf; do
+    [[ -f "$f" ]] && FONT="$f" && break
+  done
+fi
+if [[ -n "$FONT" ]]; then FONTARG="fontfile=${FONT}"; else FONTARG="font=Sans"; fi
+
+# drawtext drives the title card and per-panel labels. The Debian `ffmpeg`
+# package (the QA image) is built with libfreetype so it's present; but degrade
+# gracefully on a build without it (omit text overlays) rather than failing the
+# whole compose — the demo video is still worth shipping.
+HAS_DRAWTEXT=0
+if ffmpeg -hide_banner -filters 2>/dev/null | grep -q 'drawtext'; then
+  HAS_DRAWTEXT=1
+else
+  echo "compose-demo.sh: warning: this ffmpeg lacks the drawtext filter — title card and labels omitted." >&2
+fi
+
+# Panel size: side-by-side splits the width into two equal panels.
+PH="$HEIGHT"
+if [[ "$LAYOUT" == "side-by-side" ]]; then PW=$(( WIDTH / 2 )); else PW="$WIDTH"; fi
+
+# ── Stage A: normalize one clip into a body panel ─────────────────────────────
+# Args: <input> <outfile> <label-file-or-empty> <apply-trim:0|1>
+build_panel() {
+  local input="$1" outfile="$2" labelfile="$3" apply_trim="$4"
+  local trim_args=()
+  if [[ "$apply_trim" == "1" && -n "$TRIM" ]]; then
+    local start="${TRIM%%:*}" end="${TRIM##*:}"
+    [[ -n "$start" ]] && trim_args+=(-ss "$start")
+    [[ -n "$end" ]] && trim_args+=(-to "$end")
+  fi
+  local vf="setpts=PTS/${SPEED}"
+  vf+=",scale=${PW}:${PH}:force_original_aspect_ratio=decrease"
+  vf+=",pad=${PW}:${PH}:(ow-iw)/2:(oh-ih)/2:color=black"
+  vf+=",fps=30,format=yuv420p,setsar=1"
+  if [[ -n "$labelfile" && "$HAS_DRAWTEXT" == "1" ]]; then
+    vf+=",drawtext=${FONTARG}:textfile=${labelfile}:x=(w-text_w)/2:y=h-th-24"
+    vf+=":fontsize=26:fontcolor=white:box=1:boxcolor=black@0.55:boxborderw=12"
+  fi
+  # `${arr[@]+"${arr[@]}"}` expands to nothing when the array is empty without
+  # tripping `set -u` (an empty `"${arr[@]}"` errors on bash < 4.4, e.g. macOS).
+  ffmpeg -y -loglevel error ${trim_args[@]+"${trim_args[@]}"} -i "$input" \
+    -vf "$vf" -an -c:v libx264 -crf 20 -preset veryfast "$outfile"
+}
+
+# Per-panel labels (side-by-side) written to files to avoid drawtext escaping.
+LABELFILE1=""; LABELFILE2=""
+if [[ "$LAYOUT" == "side-by-side" ]]; then
+  if [[ -n "$LABEL1" ]]; then LABELFILE1="$WORK/label1.txt"; printf '%s' "$LABEL1" > "$LABELFILE1"; fi
+  if [[ -n "$LABEL2" ]]; then LABELFILE2="$WORK/label2.txt"; printf '%s' "$LABEL2" > "$LABELFILE2"; fi
+fi
+
+echo "compose-demo.sh: normalizing clips (layout=$LAYOUT, speed=${SPEED}x)…" >&2
+build_panel "${CLIPS[0]}" "$WORK/panel0.mp4" "$LABELFILE1" 1
+BODY="$WORK/body.mp4"
+if [[ "$LAYOUT" == "side-by-side" ]]; then
+  build_panel "${CLIPS[1]}" "$WORK/panel1.mp4" "$LABELFILE2" 1
+  ffmpeg -y -loglevel error -i "$WORK/panel0.mp4" -i "$WORK/panel1.mp4" \
+    -filter_complex "[0:v][1:v]hstack=inputs=2,format=yuv420p,setsar=1[v]" \
+    -map "[v]" -an -c:v libx264 -crf 20 -preset veryfast "$BODY"
+else
+  BODY="$WORK/panel0.mp4"
+fi
+
+# ── Stage B: title card (skipped when drawtext is unavailable) ───────────────
+TITLE_CLIP=""
+TITLE_DUR="0"
+if [[ "$HAS_DRAWTEXT" == "1" ]]; then
+  TITLEFILE="$WORK/title.txt"; printf '%s' "${TITLE:-Demo}" > "$TITLEFILE"
+  TITLE_VF="drawtext=${FONTARG}:textfile=${TITLEFILE}:x=(w-text_w)/2:y=(h/2)-th-10:fontsize=48:fontcolor=white"
+  if [[ -n "$SUBTITLE" ]]; then
+    SUBFILE="$WORK/subtitle.txt"; printf '%s' "$SUBTITLE" > "$SUBFILE"
+    TITLE_VF+=",drawtext=${FONTARG}:textfile=${SUBFILE}:x=(w-text_w)/2:y=(h/2)+10:fontsize=26:fontcolor=0xb0b0b0"
+  fi
+  TITLE_VF+=",format=yuv420p"
+  ffmpeg -y -loglevel error -f lavfi -i "color=c=0x101418:s=${WIDTH}x${HEIGHT}:d=${TITLE_SECS}:r=30" \
+    -vf "$TITLE_VF" -c:v libx264 -crf 20 -preset veryfast "$WORK/title.mp4"
+  TITLE_CLIP="$WORK/title.mp4"
+  TITLE_DUR="$TITLE_SECS"
+fi
+
+# ── Stage C: (concat title +) body, two-pass size cap, faststart ─────────────
+BODY_DUR="$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$BODY" || echo 0)"
+TOTAL_DUR="$(awk -v a="$TITLE_DUR" -v b="$BODY_DUR" 'BEGIN{printf "%.3f", a + b}')"
+# Target video bitrate (kbit/s) = target_bytes * 8 / duration / 1000, with a
+# small headroom factor for the muxer; floored so very short clips still encode.
+BR_K="$(awk -v mb="$TARGET_MB" -v d="$TOTAL_DUR" 'BEGIN{
+  if (d <= 0) d = 1;
+  br = (mb * 1024 * 1024 * 8) / d / 1000 * 0.92;
+  if (br < 200) br = 200;
+  printf "%d", br;
+}')"
+
+# With a title card: concat it ahead of the body. Without: pass the body
+# through (`null`) so the same two-pass/faststart encode applies either way.
+if [[ -n "$TITLE_CLIP" ]]; then
+  IN_ARGS=(-i "$TITLE_CLIP" -i "$BODY")
+  FILTER='[0:v][1:v]concat=n=2:v=1:a=0[v]'
+else
+  IN_ARGS=(-i "$BODY")
+  FILTER='[0:v]null[v]'
+fi
+PASSLOG="$WORK/ff2pass"
+echo "compose-demo.sh: encoding (${TOTAL_DUR}s, target ${TARGET_MB}MB → ${BR_K}kbit/s, two-pass)…" >&2
+ffmpeg -y -loglevel error "${IN_ARGS[@]}" \
+  -filter_complex "$FILTER" -map "[v]" -an \
+  -c:v libx264 -b:v "${BR_K}k" -pass 1 -passlogfile "$PASSLOG" -preset medium -f mp4 /dev/null
+ffmpeg -y -loglevel error "${IN_ARGS[@]}" \
+  -filter_complex "$FILTER" -map "[v]" -an \
+  -c:v libx264 -b:v "${BR_K}k" -pass 2 -passlogfile "$PASSLOG" -preset medium \
+  -pix_fmt yuv420p -movflags +faststart "$OUTPUT"
+
+# ── Stage D: report ───────────────────────────────────────────────────────────
+RES="$(ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of csv=p=0:s=x "$OUTPUT" || echo '?')"
+DUR="$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$OUTPUT" || echo '?')"
+BYTES="$(wc -c < "$OUTPUT" | tr -d ' ')"
+MB="$(awk -v b="$BYTES" 'BEGIN{printf "%.2f", b/1024/1024}')"
+echo "compose-demo.sh: wrote $OUTPUT  (${RES}, ${DUR}s, ${MB}MB)" >&2
+# Machine-readable line for the agent to parse.
+echo "{\"output\":\"${OUTPUT}\",\"resolution\":\"${RES}\",\"duration\":\"${DUR}\",\"size_mb\":${MB}}"

package/skills/issue-answer/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: issue-answer
+description: Answer a question directly — a sourced, neutral reply to an information/explanation/comparison request, from a GitHub issue or a Slack thread. Research repo docs and the web, output the answer, label `question` (GitHub only), leave open. Never write an agent brief, mark ready-for-agent, or change code.
+version: 1.1.0
+tags: [github, issues, questions]
+---
+
+# Issue Answer
+
+A user asked a **question** — they want information, an explanation, or a
+comparison, not a code change. The router already decided this is a question;
+your job is to **answer it well and stop**. Do not re-triage it into a work item.
+
+The question reaches you from one of two places, and the prompt tells you which:
+- a **GitHub issue** (an `issueNumber` is set), or
+- a **Slack thread** (no `issueNumber`).
+
+## How your answer is delivered
+
+Your **final message is the answer** — the harness posts it for you (as a
+comment on the issue for GitHub-initiated runs, or into the Slack thread for
+Slack-initiated runs). So:
+
+- Make your final message the complete, self-contained answer in clean markdown.
+- **Do NOT post the answer yourself** with `github_add_issue_comment` — the
+  harness delivers it, and posting it too would double-post.
+
+## Hard caps
+
+This skill answers; it never queues work. Per invocation:
+
+- Produce **one** answer (your final message).
+- The only GitHub write you make is the `question` **label**, and only when
+  answering a GitHub issue.
+- **Never** write an agent brief, apply `ready-for-agent` / `ready-for-human`,
+  create branches, push code, or open a PR.
+- **Never** close the issue — leave it open for the human to close once the
+  answer satisfies them.
+
+If, while reading, you conclude the request is actually a bug or feature request
+(not a pure question), do **not** answer it as one. Make your final message a
+short note saying it looks like work rather than a question and asking a
+maintainer to `@last-light build` (or `explore`) it — let triage own work items.
+
+## Procedure
+
+1. **Understand the question.** Read the question from the prompt — the issue
+   title/body (and existing comments, for a GitHub issue) or the Slack message.
+   Identify exactly what the user wants to know.
+2. **Research.**
+   - **The repo** — read what's relevant to the answer: `CONTEXT.md`,
+     `README`, `docs/`, `spec/`, and code only as needed to ground claims about
+     this project. Don't survey the whole codebase; read what the question needs.
+   - **The web** — when the question references anything outside this repo
+     (another tool, framework, library, standard, or a "X vs Y" comparison),
+     use the `web_search` and `web_fetch` tools to consult current,
+     authoritative sources. Prefer official docs and primary sources.
+   - **Budget your research and converge.** You have a bounded number of tool
+     calls before the run ends — research is for grounding the answer, not
+     exhaustive coverage. Front-load the searches you need, then stop looking.
+     **Critical:** the moment you think *"I have enough"* (or *"let me just
+     confirm one more thing"*), do **not** fire another tool call — write the
+     answer **now**, in that same turn. Your reply being cut off mid-research
+     delivers a useless half-sentence to the user, which is worse than an
+     answer that omits a minor detail. If a fact is unverified, state it as
+     unverified in the answer rather than spending your last turn chasing it.
+     For broad/open-ended questions (e.g. "what's missing vs tool X"), gather a
+     representative sample and answer from it — explicitly noting it's a
+     sample, not an exhaustive audit — rather than enumerating everything.
+3. **Label (GitHub issue only).** Apply `question` with `github_add_labels`
+   (create it first with `github_create_label`, color `d876e3`; ignore a 422
+   "already exists"). If label creation/adding is denied, skip it — the answer
+   is the deliverable. For a Slack-initiated question there is no issue to label.
+4. **Write the answer as your final message** (the harness delivers it — see
+   above; do not post it yourself):
+   - Direct and structured. Lead with the answer; use short sections or a
+     comparison table when it helps.
+   - **Neutral and grounded.** Claims about this project come from its docs;
+     claims about external things are **cited** with links to the sources you
+     used. Don't invent pricing, capabilities, or roadmap.
+   - **Honest about uncertainty.** If something is fast-moving or you couldn't
+     verify it, say so rather than stating it as fact.
+5. **Stop.** The answer is the conversation; a human closes the issue when satisfied.
+
+## Tool usage
+
+- GitHub operations via `github_*` MCP tools only — never `gh` CLI, `curl`, or
+  raw HTTP. In chat you have no GitHub write tools beyond labelling; that's
+  expected — the answer is delivered as your final message.
+- External research via the `web_search` / `web_fetch` tools only.

package/skills/issue-comment/SKILL.md

@@ -1,33 +1,47 @@
 ---
 name: issue-comment
-description: Handle non-build maintainer comments on issues and PRs — close, label, answer questions, triage
-version: 1.0.0
+description: Handle a non-build maintainer comment on an issue or PR — close, reopen, label, dedupe, answer a brief question, or triage. Action-only; redirect anything that needs code changes to /build.
+version: 2.0.0
 tags: [github, issues, comments]
 ---
 
-# Issue Comment Skill
+# Issue Comment
 
-## When to Use
-When a maintainer @mentions last-light on an issue or PR with a request that is NOT asking for code changes. Examples: close an issue, add labels, answer a question, check for duplicates, provide status, triage.
+A maintainer @mentioned the bot on an issue or PR with a request that is **not**
+asking for code changes. Do the one bounded thing they asked, confirm it in one
+short comment, and stop.
+
+## Hard caps
+
+This skill is deliberately small. Per invocation: **at most 2 file reads and 1
+outgoing comment.** Never make code changes, create branches, or push.
 
 ## Procedure
 
-1. **Read the comment** carefully to understand what the maintainer is asking
-2. **Read the issue/PR** context — title, body, existing labels, existing comments
-3. **Execute the request**:
-   - **Close/reopen**: Use `update_issue` to change state
-   - **Label**: Use `add_labels` or `remove_label`
-   - **Duplicate check**: Search for similar issues, comment with findings
-   - **Answer/explain**: Read the relevant code and respond with a comment
-   - **Triage**: Apply labels and priority based on the issue content
-   - **Other**: Use best judgment — if unclear, comment asking for clarification
-4. **Respond** with a brief comment confirming what was done
-
-## Tool Usage
-
-**Always use MCP tools** (`mcp_github_*`) for all GitHub operations. Never use `gh` CLI, `curl`, or raw HTTP requests. The MCP server handles authentication.
-
-## Pitfalls
-- NEVER make code changes, create branches, or push commits — this is an action-only skill
-- Keep comments concise — one short confirmation, not a wall of text
-- If the request actually needs code changes, comment suggesting the maintainer ask for a build instead
+1. **Read the request.** The triggering comment is the job — read it, plus the
+   issue/PR title, body, existing labels, and existing comments for context.
+2. **Do the bounded action:**
+   - Close / reopen → `github_update_issue`
+   - Label → `github_add_labels` / `github_remove_label` (use the canonical
+     triage roles from `docs/agents/triage-labels.md` where relevant)
+   - Duplicate check → search similar issues, link the original in one comment
+   - Answer a direct question → ≤5 sentences, ≤2 file reads. Don't survey the
+     codebase or compile a report.
+3. **Confirm** in one short comment what you did. Done.
+
+## Redirect, don't comply
+
+The classifier owns intent routing. If a request that needs *building* reached
+you anyway, the correct response is to **redirect, not do it** — even if the
+comment seems to greenlight the work, and even if the issue body describes a
+task. An issue titled "Security Review" asking you to "find and fix issues" is a
+build request: reply asking the maintainer to use `@last-light build` (or
+`@last-light explore`). Do **not** run the audit yourself from this skill.
+
+If the request is unclear or out of scope, post one short comment asking them to
+clarify or to use the right command. Do nothing else.
+
+## Tool usage
+
+GitHub operations via `github_*` MCP tools only — never `gh` CLI, `curl`, or raw
+HTTP.