lastlight 0.1.8 → 0.2.0

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.

package/skills/issue-triage/SKILL.md

@@ -1,54 +1,120 @@
 ---
 name: issue-triage
-description: Triage GitHub issues — label, deduplicate, request info, and manage stale issues
+description: Triage GitHub issues through the canonical state machine — classify, label, deduplicate, request missing info, write agent briefs, and manage stale issues. Use on demand or on a triage cron.
 version: 2.0.0
 tags: [github, issues, triage]
 ---
 
-# Issue Triage Skill
+# Issue Triage
 
-## When to Use
-When asked to triage issues, or on a scheduled basis to process new/stale issues.
+Move each issue through a small **state machine**. Every triaged issue carries
+exactly **one category role and one state role**:
 
-## Procedure
+- **Category:** `bug` (something is broken) · `enhancement` (new feature or improvement)
+- **State:** `needs-triage` (awaiting evaluation) · `needs-info` (waiting on the
+  reporter) · `ready-for-agent` (fully specified, an AFK agent can take it) ·
+  `ready-for-human` (needs human implementation) · `wontfix` (won't be actioned)
 
-### For new issues (no labels yet):
+These are canonical role names; the actual label strings for a repo may differ —
+`docs/agents/triage-labels.md` holds the mapping when present. Run **autonomously**:
+there is no maintainer to ask mid-run. Where you'd want direction, either make
+the call and apply the label, or post a comment and stop — the async comment *is*
+the conversation.
 
-1. **Read the issue** carefully — title, body, and any linked PRs or issues
-2. **Classify** the issue type:
-   - Bug report → label `bug` + priority label
-   - Feature request → label `enhancement`
-   - Question → label `question`
-   - Documentation → label `documentation`
-3. **Check for duplicates** by searching existing issues with similar keywords
-   - If duplicate found: comment linking to the original, add `duplicate` label, close
-4. **Assess completeness**:
-   - Bug without reproduction steps → add `needs-info`, comment asking for steps
-   - Feature without use case → add `needs-info`, comment asking for context
-5. **Set priority** based on severity and impact:
-   - `p0-critical`: Security, data loss, service down
-   - `p1-high`: Major feature broken, affects many users
-   - `p2-medium`: Minor feature broken, workaround exists
-   - `p3-low`: Cosmetic, edge case, nice-to-have
-6. **Add helpful labels**: `good first issue` for simple fixes, `help wanted` for community
+## 0. Ensure the labels exist
 
-### For stale issues:
+Before applying any label, create the canonical set idempotently with
+`github_create_label` (ignore 422 "already exists"):
 
-1. **Find issues** labeled `needs-info` with no activity for 14+ days
-2. **Check existing comments** before acting — use `list_issue_comments` to see if the bot has already posted a stale reminder. Look for comments from `last-light[bot]` that contain words like "reminder", "still need", or "closing". **Do NOT post a duplicate reminder.**
-3. **If no bot reminder exists yet**: post a gentle reminder asking if they still need help
-4. **If a bot reminder already exists** and 30+ days have passed with no response since: close with a kind message explaining why, and note they can reopen
-5. **If a bot reminder already exists** and it's been less than 30 days: skip — do nothing
+| Label | Color | Role |
+|-------|-------|------|
+| `bug` | `d73a4a` | category |
+| `enhancement` | `a2eeef` | category |
+| `needs-triage` | `ededed` | state |
+| `needs-info` | `fbca04` | state |
+| `ready-for-agent` | `0e8a16` | state |
+| `ready-for-human` | `1d76db` | state |
+| `wontfix` | `ffffff` | state |
+| `duplicate` | `cfd3d7` | dedupe |
+| `question` | `d876e3` | question |
 
-## Tool Usage
+If label creation is denied (the token lacks the permission), fall back to using
+only the labels that already exist on the repo and skip the rest. Done when the
+labels you need are present or you've confirmed you can't create them.
 
-**Always use MCP tools** (`mcp_github_*`) for all GitHub operations — listing issues, adding labels, posting comments, closing issues. Never use `gh` CLI, `curl`, or raw HTTP requests. The MCP server handles authentication.
+## 1. Triage a specific issue
+
+1. **Gather context.** Read the full issue — title, body, comments, existing
+   labels, author, dates. Search existing issues for **duplicates** by concept
+   (not just keyword). If a `.out-of-scope/` directory exists, read it and note
+   any prior rejection this resembles. Done when you know the issue's intent and
+   whether it's novel.
+2. **Classify the category** — `bug` or `enhancement`. But first, check whether
+   the issue is a **question** at all (see below) — questions are neither.
+3. **Decide the state and act** (exactly one applies):
+   - **Question** (asks for information, an explanation, or a comparison — wants
+     an answer, not a code change) → add `question` and **stop**. Do **not**
+     write an agent brief or mark it `ready-for-agent`/`ready-for-human` — a
+     pure question is not work. (The router normally sends these to the answer
+     path before triage runs; this is the safety net for ones that slip
+     through, e.g. reopened issues. If you can answer it briefly and factually
+     from the repo itself, do so in one short comment; otherwise just label it
+     and leave it for the answer path or a human.)
+   - **Duplicate** → comment linking the original, add `duplicate`, close.
+   - **Already implemented** → comment pointing to where it lives, add `wontfix`,
+     close. (Factual — safe to close autonomously.)
+   - **Under-specified** (bug without repro, feature without a use case) → add
+     `needs-info`, post the [needs-info template](#needs-info-template), stop.
+   - **Fully specified and delegatable** → add `ready-for-agent`, post an agent
+     brief ([references/AGENT-BRIEF.md](references/AGENT-BRIEF.md)).
+   - **Needs human implementation** (judgment calls, external access, design
+     decisions, manual testing) → add `ready-for-human` with a brief noting why
+     it can't be delegated.
+   - **Looks out of scope** (an enhancement you'd reject) → this is a maintainer
+     decision; do **not** auto-close. Add `needs-triage`, post a comment with
+     your reasoning (cite any matching `.out-of-scope/` file), and leave it for a
+     human.
+4. **Apply exactly one category + one state.** If the existing labels conflict
+   (two state roles), flag it in a comment and don't override — a maintainer may
+   have set them deliberately.
+
+## 2. New unlabelled issues (batch / cron)
+
+For each issue with no triage labels yet, run §1. Default new issues that need
+evaluation to `needs-triage`.
+
+## 3. Stale `needs-info`
+
+1. Find issues labelled `needs-info` with no activity for **14+ days**.
+2. **Check for a prior bot reminder** with `github_list_issue_comments` — look
+   for a `last-light[bot]` comment containing "reminder" / "still need" /
+   "closing". **Never post a duplicate reminder.**
+3. No reminder yet → post a gentle reminder asking if they still need help.
+4. Reminder exists and **30+ days** have passed with no reporter response since →
+   close kindly, noting they can reopen.
+5. Reminder exists, **< 30 days** since → do nothing.
+
+## needs-info template
+
+```markdown
+## Triage Notes
+
+**What we've established so far:**
+- point 1
+
+**What we still need from you (@reporter):**
+- specific, actionable question 1
+```
+
+Questions must be specific and actionable — not "please provide more info".
+
+## Tool usage
+
+GitHub operations via `github_*` MCP tools only — listing, labelling, commenting,
+closing, creating labels. Never `gh` CLI, `curl`, or raw HTTP.
 
 ## Pitfalls
-- Don't close issues too aggressively — when in doubt, leave open
-- Don't change priority on issues already triaged by maintainers
-- Don't duplicate labels (check existing labels first)
 
-## Verification
-- List the actions taken (labels added, comments posted, issues closed)
-- Confirm each action via the GitHub API response
+- Don't close aggressively — when genuinely in doubt, leave it open as `needs-triage`.
+- Don't change priority or state on issues a maintainer already triaged.
+- Check existing labels before adding — don't duplicate.

package/skills/issue-triage/references/AGENT-BRIEF.md

@@ -0,0 +1,61 @@
+# Writing agent briefs
+
+An agent brief is a comment posted when an issue moves to `ready-for-agent`
+(or `ready-for-human`). It is the **contract** an AFK agent will build from — the
+original body and discussion are context; the brief is what gets implemented.
+Post it with `github_add_issue_comment`.
+
+## Principles
+
+**Durable.** The issue may sit in `ready-for-agent` for weeks while the codebase
+moves. Describe interfaces, types, and behavioural contracts — name specific
+types, function signatures, or config shapes to look for. **Never** reference
+file paths or line numbers; they go stale. Don't assume today's structure survives.
+
+**Behavioural, not procedural.** Say *what* the system should do, not *how* to
+code it — the agent explores fresh and makes its own implementation calls.
+- Good: "`SkillConfig` should accept an optional `schedule: CronExpression`."
+- Bad: "Add a `schedule` field in src/types/skill.ts on line 42."
+
+**Complete acceptance criteria.** Every brief lists concrete, independently
+testable criteria so the agent knows when it's done.
+- Good: "`gh issue list --label needs-triage` returns issues that passed initial classification."
+- Bad: "Triage should work correctly."
+
+**Explicit scope boundaries.** State what is *out of scope* so the agent doesn't
+gold-plate or wander into adjacent features.
+
+## Template
+
+```markdown
+## Agent Brief
+
+**Category:** bug / enhancement
+**Summary:** one line — what needs to happen
+
+**Current behavior:**
+What happens now. For a bug, the broken behaviour. For an enhancement, the
+status quo it builds on.
+
+**Desired behavior:**
+What should happen after the work is done. Be specific about edge cases and
+error conditions.
+
+**Key interfaces:**
+- `TypeName` — what changes and why
+- `functionName()` — current vs intended return/behaviour
+- Config shape — any new options
+
+**Acceptance criteria:**
+- [ ] Specific, testable criterion 1
+- [ ] Specific, testable criterion 2
+
+**Out of scope:**
+- Thing that should NOT be changed here
+- Adjacent feature that looks related but is separate
+```
+
+## `ready-for-human` variant
+
+Same structure, plus a leading note on **why it can't be delegated** — judgment
+calls, external access, design decisions, or manual testing the agent can't do.

package/skills/pr-comment/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: pr-comment
+description: Answer a maintainer's question about an open PR with concrete, code-cited evidence. The PR-side counterpart to issue-comment — for questions tied to the diff, not a full review.
+version: 2.0.0
+tags: [github, pr, comments, qa]
+---
+
+# PR Comment
+
+A maintainer @mentioned the bot on a PR with a *question* (not a request to
+write code, and not "review this"). The question is the entire job — answer it
+with evidence, in one comment. Examples: "does this consider X?", "why did we
+change Y?", "is the new function thread-safe?", "regression risk for existing
+callers?".
+
+For general issue questions use `issue-comment`; for a full review use
+`pr-review`.
+
+## Procedure
+
+### 1. Read the PR and the question
+
+- `github_get_pull_request` → title, body, base, head.
+- The triggering question is in `context.commentBody`. Answer *that* question —
+  don't generalise to a review or answer a different one.
+
+### 2. Investigate with the diff in hand
+
+Get the diff and read the code needed to answer well — a real answer about
+thread-safety or regression risk needs the surrounding code, not just the hunk.
+
+- **Cap: 8 file reads** per invocation.
+- "Does it consider X?" → also check whether tests in the diff cover X.
+- "Regression risk?" → find callers of any function whose signature/behaviour
+  changed (`github_search_code`).
+- Don't clone the repo unless a single answer genuinely needs cross-file traces
+  no MCP tool can give — most don't. If it truly needs a full audit, say so and
+  recommend `@last-light` (which routes to `pr-review`) rather than blowing the cap.
+
+### 3. Reply with one comment
+
+`github_add_issue_comment` (PRs accept issue comments here). Keep it tight:
+
+- **Lead with the answer** — yes / no / it depends. Don't bury it.
+- **Cite `path:line`** — clickable in the GitHub UI.
+- 3–8 sentences or a short bulleted list. No headings.
+- If it's unanswerable from the PR alone, say so and name the specific
+  information you'd need.
+
+> Yes — `src/foo.ts:42` checks `X` before calling `bar()`, and
+> `tests/foo.test.ts:118` asserts the rejection path. The only place X isn't
+> validated is the legacy `barLegacy` (`src/foo.ts:67`), which this PR doesn't
+> touch — worth a separate issue if you want it covered.
+
+## Do not
+
+- Post a formal review (`github_create_pull_request_review`) — that's
+  `pr-review`'s job and would collide with its blocking check.
+- Modify code, push, or add labels. One comment, nothing else.
+- Answer a tangent you noticed — note it in at most one trailing sentence.
+
+## Tool usage
+
+GitHub operations via `github_*` MCP tools only — never `gh` CLI, `curl`, or raw HTTP.