@tamng0905/builder-essential-skills 0.1.0

package/skills/lead/status.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# Read-only status tree for a techlead-loop run. Reads run artifacts plus `gh`;
+# never a new state store. Piped output is plain text; color follows isatty and
+# NO_COLOR. Callers print it verbatim instead of hand-composing status.
+set -u
+
+root=$(pwd)
+while [ "$#" -gt 0 ]; do
+  case "$1" in --repo-root) root=$2; shift 2;; *) shift;; esac
+done
+case "$root" in /*) ;; *) root="$(pwd)/$root";; esac
+[ -d "$root" ] || { printf 'unreadable repo: %s\n' "$root"; exit 1; }
+
+color_glyph(){ if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then printf '\033[%sm%s\033[0m' "$2" "$1"; else printf '%s' "$1"; fi; }
+g_merged=$(color_glyph '✓' 32); g_review=$(color_glyph '◐' 36); g_blocked=$(color_glyph '!' 31)
+g_reported=$(color_glyph '▣' 35); g_building=$(color_glyph '●' 34); g_queued=$(color_glyph '⊘' 33); g_ready=$(color_glyph '○' 37)
+
+newest_spec(){
+  spec_dir="$root/docs/spec"
+  newest=; newest_mtime=
+  [ -d "$spec_dir" ] || { printf unknown; return; }
+  for spec in "$spec_dir"/*.md; do
+    [ -f "$spec" ] || continue
+    mtime=$(stat -c %Y "$spec" 2>/dev/null || stat -f %m "$spec" 2>/dev/null || printf 0)
+    case "$mtime" in ''|*[!0-9]*) mtime=0;; esac
+    if [ -z "$newest" ] || [ "$mtime" -gt "$newest_mtime" ]; then newest=$spec; newest_mtime=$mtime; fi
+  done
+  [ -n "$newest" ] && basename "$newest" || printf unknown
+}
+tail_text(){ [ -f "$1" ] && tail -c 4096 "$1" | tr -d '\000'; }
+status_line(){ tail_text "$1" | sed 's/^\xEF\xBB\xBF//' | awk '/^STATUS:/{sub(/^STATUS:[[:space:]]*/,""); s=$0} END{print s}'; }
+last_command(){
+  ev="$root/.lead/wt/$1-01.events.jsonl"
+  cmd=$(tail_text "$ev" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | tail -n 1)
+  [ -n "$cmd" ] && printf '    last: %s age: unknown\n' "$cmd"
+}
+report_path(){
+  in_wt="$root/.lead/wt/$1-01/docs/jobs/$1-01.md"
+  in_repo="$root/docs/jobs/$1-01.md"
+  [ -f "$in_wt" ] && { printf '%s' "$in_wt"; return; }
+  printf '%s' "$in_repo"
+}
+slugify(){ printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g;s/--*/-/g;s/^-//;s/-$//'; }
+artifact_slugs(){ find "$root/.lead/wt" -maxdepth 1 -type d -name '*-01' 2>/dev/null | sed 's|.*/||;s/-01$//' | sort -u; }
+phase(){
+  slug=$1; state=${2:-}; blockers=${3:-}
+  [ "$state" = CLOSED ] && { printf '%s MERGED' "$g_merged"; return; }
+  [ "$state" = OPEN ] && [ -n "$blockers" ] && { printf '%s QUEUED' "$g_queued"; return; }
+  rep=$(report_path "$slug")
+  review=$(find "$root/.lead/wt" -maxdepth 1 -type f -name "$slug-01.review*.md" 2>/dev/null | head -n 1)
+  [ -f "$rep" ] && [ -n "$review" ] && { printf '%s REVIEWING' "$g_review"; return; }
+  st=$(status_line "$rep")
+  case "$st" in BLOCKED*) printf '%s BLOCKED' "$g_blocked"; return;; esac
+  [ -f "$rep" ] && { printf '%s REPORTED' "$g_reported"; return; }
+  [ -d "$root/.lead/wt/$slug-01" ] && { printf '%s BUILDING' "$g_building"; return; }
+  printf '%s READY' "$g_ready"
+}
+tracker_lines(){
+  jq_expr='. as $all | ([ $all[] | select(.parent != null) | .parent.number ] | unique) as $pnums | ([ $all[] | select(.state == "OPEN") | select(.number as $n | $pnums | index($n)) ] | map(.number) | max) as $t | if $t == null then "NOOPENRUN" else ("TRACK\t\($t)", ($all[] | select(.parent != null and .parent.number == $t) | [ "SUB", (.number|tostring), .state, ((.blockedBy.nodes // []) | map(select(.state == "OPEN") | (.number|tostring)) | join(",")), .title ] | @tsv)) end'
+  if [ -n "${STATUS_GH_STUB:-}" ] && [ -r "$STATUS_GH_STUB" ]; then cat "$STATUS_GH_STUB"; return 0; fi
+  command -v gh >/dev/null 2>&1 || return 1
+  (cd "$root" && gh issue list --state all --limit 200 --json number,title,state,parent,blockedBy --jq "$jq_expr")
+}
+
+branch=
+[ -e "$root/.git" ] && branch=$(git -C "$root" branch --show-current 2>/dev/null || true)
+[ -n "$branch" ] || branch=unknown
+tracker=0; tracker_tsv=
+if tracker_tsv=$(tracker_lines 2>/dev/null); then tracker=1; fi
+tracking=
+if [ "$tracker" -eq 1 ]; then
+  # Tab is IFS whitespace to bash: empty TSV fields shift columns. Use unit separators.
+  while IFS="$(printf '\037')" read -r kind num state blockers title; do
+    [ "$kind" = TRACK ] && tracking=$num
+  done <<< "$(printf '%s\n' "$tracker_tsv" | tr '\t' '\037')"
+fi
+slugs=$(artifact_slugs)
+if { [ "$tracker" -eq 0 ] || [ -z "$tracking" ]; } && [ -z "$slugs" ]; then
+  printf 'NO ACTIVE FACTORY RUN\nspec: %s\n' "$(newest_spec)"
+  exit 0
+fi
+printf 'STATUS TREE spec: %s branch: %s\n' "$(newest_spec)" "$branch"
+if [ "$tracker" -eq 1 ] && [ -n "$tracking" ]; then
+  printf 'tracker: #%s\n' "$tracking"
+elif [ "$tracker" -eq 1 ]; then
+  printf 'tracker: no open run\n'
+else
+  printf 'tracker: unavailable (local view)\n'
+fi
+printf 'LEAD: local view\n'
+cfg=$(find "$root/.lead/tmp" -maxdepth 1 -type f -name 'wd-*.json' 2>/dev/null | wc -l | tr -d ' ')
+ps -eo args= 2>/dev/null | grep 'watchdog\.\(ps1\|sh\)' >/dev/null && proc=True || proc=False
+printf 'WATCHDOG: process=%s config=%s\n' "$proc" "$cfg"
+if [ "$tracker" -eq 1 ] && [ -n "$tracking" ]; then
+  while IFS="$(printf '\037')" read -r kind num state blockers title; do
+    [ "$kind" = SUB ] || continue
+    slug=$(slugify "$title"); set -- $(phase "$slug" "$state" "$blockers")
+    extra=; [ "$2" = QUEUED ] && extra=" blocked-by: $blockers"
+    printf '%s #%s %s .lead/wt/%s-01%s\n' "$1" "$num" "$title" "$slug" "$extra"
+    [ "$2" = BUILDING ] && last_command "$slug"
+  done <<< "$(printf '%s\n' "$tracker_tsv" | tr '\t' '\037')"
+else
+  for slug in $slugs; do
+    set -- $(phase "$slug")
+    case "$2" in BUILDING|BLOCKED|REVIEWING|REPORTED)
+      printf '%s %s .lead/wt/%s-01\n' "$1" "$slug" "$slug"
+      [ "$2" = BUILDING ] && last_command "$slug"
+    esac
+  done
+fi

package/skills/lead/watchdog.ps1

@@ -0,0 +1,90 @@
+param([Parameter(Mandatory=$true)][string]$Config)
+
+# Deterministic stall watchdog for techlead-loop (Windows). Detects mechanically
+# and exits with typed evidence; never kills, nudges, or judges. A job is done
+# only when its report's last non-blank line starts with STATUS:.
+
+function DecodeBytes($Buf) {
+    if ($Buf.Length -ge 2 -and $Buf[0] -eq 255 -and $Buf[1] -eq 254) { return [System.Text.Encoding]::Unicode.GetString($Buf) }
+    if ($Buf.Length -ge 2 -and $Buf[0] -eq 254 -and $Buf[1] -eq 255) { return [System.Text.Encoding]::BigEndianUnicode.GetString($Buf) }
+    $utf8 = New-Object System.Text.UTF8Encoding($false, $true)
+    try { return $utf8.GetString($Buf) } catch { return [System.Text.Encoding]::Unicode.GetString($Buf) }
+}
+
+function TailText($Path) {
+    if (-not (Test-Path -LiteralPath $Path)) { return "" }
+    $fs = [System.IO.File]::Open($Path, [System.IO.FileMode]::Open, [System.IO.FileAccess]::Read, [System.IO.FileShare]::ReadWrite)
+    try { $len = [Math]::Min([int64]4096, $fs.Length); [void]$fs.Seek(-$len, [System.IO.SeekOrigin]::End); $buf = New-Object byte[] $len; [void]$fs.Read($buf, 0, $len) }
+    finally { $fs.Close() }
+    return DecodeBytes $buf
+}
+
+function HasTerminalStatus($Path) {
+    $lines = (TailText $Path) -split "`r?`n"
+    for ($i = $lines.Count - 1; $i -ge 0; $i--) {
+        $t = $lines[$i].Trim()
+        if ($t.Length -gt 0) { return $t.StartsWith("STATUS:", [StringComparison]::Ordinal) }
+    }
+    return $false
+}
+
+function FileSize($Path) { if (Test-Path -LiteralPath $Path) { return (Get-Item -LiteralPath $Path).Length }; return 0 }
+
+function CpuTotal($Needle) {
+    $sum = [int64]0
+    foreach ($p in (Get-CimInstance Win32_Process -ErrorAction SilentlyContinue)) {
+        if ($p.CommandLine -and $p.CommandLine.IndexOf($Needle, [StringComparison]::OrdinalIgnoreCase) -ge 0) {
+            $sum += [int64]$p.KernelModeTime + [int64]$p.UserModeTime
+        }
+    }
+    return $sum
+}
+
+$cfg = Get-Content -LiteralPath $Config -Raw | ConvertFrom-Json
+$sweep = if ($cfg.sweep_sec) { [int]$cfg.sweep_sec } else { 120 }
+$stall = if ($cfg.stall_after_min) { [double]$cfg.stall_after_min } else { 10 }
+$state = @{}
+foreach ($j in $cfg.jobs) {
+    $state[$j.id] = @{ Done = $false; Size = ((FileSize $j.events_file) + (FileSize $j.report_path)); Growth = (Get-Date); Cpu = (CpuTotal $j.worktree) }
+}
+
+while ($true) {
+    foreach ($j in $cfg.jobs) {
+        $id = [string]$j.id
+        $s = $state[$id]
+        if ($s.Done) { continue }
+        if (HasTerminalStatus $j.report_path) { $s.Done = $true; continue }
+        if ((-not (Test-Path -LiteralPath $j.events_file)) -and (-not (Test-Path -LiteralPath $j.worktree))) {
+            Write-Output "WATCHDOG: INTEGRATED $id"
+            exit 2
+        }
+        $size = (FileSize $j.events_file) + (FileSize $j.report_path)
+        $cpu = CpuTotal $j.worktree
+        if ($size -gt $s.Size) { $s.Size = $size; $s.Growth = Get-Date }
+        $mins = ((Get-Date) - $s.Growth).TotalMinutes
+        $cpuDelta = $cpu - $s.Cpu
+        $s.Cpu = $cpu
+        $grace = $stall + [double]$j.duration_hint_min
+        if ($mins -gt $grace -and $cpuDelta -eq 0) {
+            Write-Output "WATCHDOG: STALL $id minutes_since_growth=$([Math]::Round($mins, 3)) cpu_delta=$cpuDelta"
+            foreach ($line in ((TailText $j.events_file) -split "`r?`n" | Select-Object -Last 5)) { Write-Output $line }
+            exit 3
+        }
+        $cmds = @()
+        foreach ($m in [regex]::Matches((TailText $j.events_file), '"command"\s*:\s*"((?:\\.|[^"\\])*)"')) { $cmds += $m.Groups[1].Value }
+        if ($cmds.Count -ge 4) {
+            $last = $cmds | Select-Object -Last 4
+            if (($last | Select-Object -Unique).Count -eq 1) {
+                Write-Output "WATCHDOG: REPEAT $id command=$($last[0]) count=4"
+                exit 4
+            }
+        }
+    }
+    $open = @($state.Values | Where-Object { -not $_.Done })
+    if ($open.Count -eq 0) {
+        Write-Output "WATCHDOG: ALL_DONE"
+        foreach ($j in $cfg.jobs) { Write-Output "$($j.id) $($j.report_path) $(FileSize $j.report_path) bytes" }
+        exit 0
+    }
+    Start-Sleep -Seconds $sweep
+}

package/skills/lead/watchdog.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Deterministic stall watchdog for techlead-loop. It detects mechanically and
+# never kills, nudges, or judges - it exits with typed evidence and the Lead
+# rules on it. A job is done only when its report's last non-blank line starts
+# with STATUS:.
+set -u
+
+cfg=
+while [ "$#" -gt 0 ]; do
+  case "$1" in --config) cfg=$2; shift 2;; *) shift;; esac
+done
+[ -n "$cfg" ] || { printf 'usage: watchdog.sh --config <wd.json>\n' >&2; exit 1; }
+
+json=$(tr -d '\r\n' < "$cfg")
+sweep=$(printf '%s' "$json" | sed -n 's/.*"sweep_sec"[[:space:]]*:[[:space:]]*\([0-9.]*\).*/\1/p')
+stall=$(printf '%s' "$json" | sed -n 's/.*"stall_after_min"[[:space:]]*:[[:space:]]*\([0-9.]*\).*/\1/p')
+[ -n "$sweep" ] || sweep=120
+[ -n "$stall" ] || stall=10
+jobs=$(printf '%s' "$json" | sed 's/.*"jobs"[[:space:]]*:[[:space:]]*\[//;s/\][^]]*$//;s/}[[:space:]]*,[[:space:]]*{/\}\n\{/g')
+
+field(){ printf '%s' "$1" | sed -n "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p"; }
+numfield(){ printf '%s' "$1" | sed -n "s/.*\"$2\"[[:space:]]*:[[:space:]]*\([0-9.]*\).*/\1/p"; }
+fsize(){ stat -c %s "$1" 2>/dev/null || stat -f %z "$1" 2>/dev/null || printf 0; }
+now(){ date +%s; }
+tail_text(){ [ -f "$1" ] && tail -c 4096 "$1" | tr -d '\000\377\376'; }
+report_done(){
+  [ -f "$1" ] || return 1
+  last=$(tail_text "$1" | awk 'NF{line=$0} END{gsub(/^[[:space:]]+|[[:space:]]+$/,"",line); print line}')
+  case "$last" in STATUS:*) return 0;; *) return 1;; esac
+}
+cpu_sum(){
+  w=$1
+  if [ -d /proc ]; then
+    total=0
+    for p in /proc/[0-9]*; do
+      [ -r "$p/cmdline" ] || continue
+      cmd=$(tr '\000' ' ' < "$p/cmdline")
+      case "$cmd" in *"$w"*) v=$(awk '{print $14+$15}' "$p/stat" 2>/dev/null); total=$((total+${v:-0}));; esac
+    done
+    printf '%s' "$total"
+  else
+    ps -eo time=,args= | awk -v w="$w" 'index($0,w){split($1,a,"-"); n=split($1,b,"-"); t=(n==2?b[2]:$1); split(t,c,":"); if(length(c)==3)s+=c[1]*3600+c[2]*60+c[3]; else s+=c[1]*60+c[2]} END{print s+0}'
+  fi
+}
+
+declare -a ids events reports trees hints done_ sizes growth cpus
+i=0
+while IFS= read -r job; do
+  [ -n "$job" ] || continue
+  ids[$i]=$(field "$job" id); events[$i]=$(field "$job" events_file)
+  reports[$i]=$(field "$job" report_path); trees[$i]=$(field "$job" worktree)
+  hints[$i]=$(numfield "$job" duration_hint_min); done_[$i]=0
+  ev=$(fsize "${events[$i]}"); rp=$(fsize "${reports[$i]}"); sizes[$i]=$((ev+rp)); growth[$i]=$(now); cpus[$i]=$(cpu_sum "${trees[$i]}")
+  i=$((i+1))
+done <<EOF
+$jobs
+EOF
+
+while :; do
+  all=1
+  for i in "${!ids[@]}"; do
+    [ "${done_[$i]}" = 1 ] && continue
+    report_done "${reports[$i]}" && { done_[$i]=1; continue; }
+    all=0
+    if [ ! -e "${events[$i]}" ] && [ ! -e "${trees[$i]}" ]; then
+      printf 'WATCHDOG: INTEGRATED %s\n' "${ids[$i]}"; exit 2
+    fi
+    ev=$(fsize "${events[$i]}"); rp=$(fsize "${reports[$i]}"); sz=$((ev+rp)); cpu=$(cpu_sum "${trees[$i]}")
+    [ "$sz" -gt "${sizes[$i]}" ] && { sizes[$i]=$sz; growth[$i]=$(now); }
+    mins=$(awk -v a="$(now)" -v b="${growth[$i]}" 'BEGIN{printf "%.3f",(a-b)/60}')
+    delta=$((cpu-cpus[$i])); cpus[$i]=$cpu
+    grace=$(awk -v a="$stall" -v b="${hints[$i]:-0}" 'BEGIN{print a+b}')
+    if awk -v m="$mins" -v g="$grace" 'BEGIN{exit !(m>g)}' && [ "$delta" -eq 0 ]; then
+      printf 'WATCHDOG: STALL %s minutes_since_growth=%s cpu_delta=%s\n' "${ids[$i]}" "$mins" "$delta"
+      tail_text "${events[$i]}" | tail -n 5; exit 3
+    fi
+    last4=$(tail_text "${events[$i]}" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' | tail -n 4)
+    if [ "$(printf '%s\n' "$last4" | sed '/^$/d' | wc -l)" -eq 4 ] && [ "$(printf '%s\n' "$last4" | sort -u | wc -l)" -eq 1 ]; then
+      printf 'WATCHDOG: REPEAT %s command=%s count=4\n' "${ids[$i]}" "$(printf '%s\n' "$last4" | sed -n '1p')"; exit 4
+    fi
+  done
+  if [ "$all" -eq 1 ]; then
+    printf 'WATCHDOG: ALL_DONE\n'
+    for i in "${!ids[@]}"; do printf '%s %s %s bytes\n' "${ids[$i]}" "${reports[$i]}" "$(fsize "${reports[$i]}")"; done
+    exit 0
+  fi
+  sleep "$sweep"
+done

package/skills/lead-research/README.md

@@ -0,0 +1,27 @@
+# Lead Research
+
+<p align="center">
+  <img src="../../assets/skill-cards/lead-research.svg" alt="lead-research skill card" width="100%">
+</p>
+
+Map a topic cheaply, design parallel research assignments, verify claims
+against sources, and produce a decision-oriented report.
+
+## Install
+
+Install this skill for your user account:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill lead-research
+```
+
+Install it into the current repository instead:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill lead-research --project
+```
+
+Restart Claude Code or Codex, then ask it to research a topic, compare
+technology choices, or investigate the state of the art.
+
+See the full workflow in [SKILL.md](SKILL.md).

package/skills/lead-research/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: lead-research
+description: >
+  Discovery-scale research harness. A cheap scout maps the topic, the Lead designs
+  topic-specific parallel researcher assignments from the scout's map (drawing on a
+  source-class tactics library — academic, repos, production patterns, web,
+  experts), then verifies claims against sources and writes a decision-oriented
+  report. Use when brainstorming a project or feature, choosing a technology, or
+  asked to "research X", "state of the art", "deep research". For narrow
+  slice-level fact checks inside the build loop, /lead handles those inline.
+effort: high
+---
+
+# Lead Research
+
+You are the research Lead. Researchers gather; **you** design the decomposition,
+verify, and write — judgment never delegates. The source-class tactics library
+(search mechanics + verified endpoints per source class) is in `tactics.md`; read
+it when you design researcher assignments. Resolve the `researcher` and `scout`
+models with `python ../lead/config.py` (or the shipped defaults) exactly as the
+build loop does — repo `.lead/config`, then `~/.lead/config`, then defaults.
+
+## Scale before anything
+
+A tool call is one search OR one page fetch.
+
+- **Simple fact-find** → answer directly or 1 researcher, 3–10 tool calls. Don't
+  run a harness on a question one search answers.
+- **Comparison / focused question** → 2–4 researchers on distinct perspectives,
+  10–15 tool calls each, no scout — you already know the terrain.
+- **Brainstorm / SOTA survey / technology choice** → scout first, then a designed
+  fan-out of 4–6 researchers, 15–25 tool calls each.
+
+## Procedure
+
+### 1. Scope → brief
+
+If the question is ambiguous, ask at most 2–3 clarifying questions, then compress
+everything into a **research brief**: the question, the decision it informs,
+constraints, and what "answered" looks like. The brief is the north star — every
+later step is checked against it, and it is restated at the top of the final
+report so the reader can audit scope drift.
+
+### 2. Scout, then design the researchers
+
+Production deep-research systems use LLM-designed, topic-specific decomposition
+rather than a fixed taxonomy. Researcher assignments are designed per topic.
+
+**Scout (brainstorm scale only):** dispatch ONE cheap researcher (the `scout`
+role, ~10 searches) to map the terrain — canonical terminology; the 5–10
+load-bearing systems/papers/repos; the named people; which source classes look
+rich vs empty; the topic's natural fault lines. The scout returns a map, not
+findings. Skip the scout when you already know the terrain (comparisons,
+fact-finds) — an upfront pass that tells you nothing is pure latency.
+
+**Design (you, from the scout map):** decompose into 3–6 sub-questions along the
+topic's own fault lines — distinct perspectives, never keyword variants of one
+query. For each researcher pick the source-class tactics it needs from
+`tactics.md` (academic snowballing, dependents-not-stars repo evidence,
+production-pattern mining, general web, expert tracking) — one researcher may mix
+tactics; most topics do not need every class. Scope each researcher to ≤5
+subjects and give it an explicit search budget. Reserve **expert opinion** for a
+second-wave researcher, its roster seeded from the first wave. Review the set for
+overlap AND gaps against the brief before dispatch.
+
+### 3. Fan out
+
+One fresh researcher per assignment, all parallel, in the background. Take the
+command from `python ../lead/config.py --role researcher`; for Codex it is:
+
+```bash
+codex exec --sandbox read-only -c web_search="live" \
+  -m <model-id> -c model_reasoning_effort="<effort>" \
+  -o .lead/research/<NN>-<researcher>.md \
+  - < .lead/research/<NN>-<researcher>.prompt.md
+```
+
+Write each researcher block to a `.prompt.md` file and pass it via stdin (`-`) —
+never as a shell argument; quote-mangling shells make the CLI hang. Launch ONE
+canary and confirm it starts cleanly before fanning out. If the resolved
+researcher is a Claude row or Codex is unavailable, run researchers as read-only
+Claude subagents with web search — the blocks work verbatim.
+
+Every researcher block carries the full contract (objective, output format,
+source guidance, boundaries) plus:
+
+- **Search budget** by tier: simple 5, standard 15, deep 25 searches.
+- **Saturation rule**: two consecutive searches yielding no new load-bearing
+  facts → return what you have.
+- **Findings discipline**: every finding has a source tag + date + exact figure
+  or short quote + confidence tag (high = primary / med = reputable secondary /
+  low = single blog or forum). NOT FOUND beats inference. Disagreements between
+  sources are reported, never resolved. No recommendations — judgment is yours.
+  The findings file is capped at ≤ ~2,500 tokens; every source URL appears
+  EXACTLY ONCE in a numbered list at the end, and findings cite by tag ([S3]).
+
+### 4. Gap round (max 2 extra rounds, usually 1)
+
+After reading wave-1 findings, write (or update) a skeleton draft at
+`.lead/research/<topic>.draft.md` (gitignored working state) — an answer-first
+outline where every section carries **SUPPORTED / THIN / EMPTY** against the
+brief. Gap researchers are designed from the THIN/EMPTY sections. Every NOT FOUND
+carries forward into a **do-not-rechase list** that every gap block includes. The
+**expert-opinion researcher** dispatches here, seeded by the names wave one
+surfaced. Hard stop after two refinement rounds.
+
+### 5. Verify (your work, against raw sources)
+
+- Extract the **load-bearing claims** — the facts the decision depends on.
+- Require **≥2 independent-origin sources** per load-bearing claim (two articles
+  rewriting one press release are one source).
+- Tag each: VERIFIED (≥2 independent agree) / UNVERIFIED (<2, no contradiction) /
+  DISPUTED (sources disagree — report both and why) / SUSPICIOUS (contradicts
+  available evidence).
+- **Adversarial pass** on the top claims: search "<claim> criticism", "<X>
+  problems", "<X> vs <alternative>".
+- **Citations are only URLs fetched this session.** Never cite from memory — even
+  search-grounded agents fabricate a nontrivial fraction of URLs. Spot-check the
+  load-bearing ones by fetching them yourself.
+- **Recency discipline**: every quantitative or current-state claim carries a
+  source date; prefer the most recent authoritative treatment.
+- **Source hierarchy**: primary (papers, official docs, changelogs, first-party
+  engineering blogs) > reputable secondary > SEO listicles (pointers, never
+  citations).
+- **Opinion ≠ fact.** Expert opinions are positions — quoted, dated,
+  conflict-of-interest flagged — and never count toward the ≥2-source rule.
+  Expert *disagreements* are first-class findings: they mark the open questions.
+
+### 6. Synthesize (one pass, one author — you)
+
+Parallelize gathering, never synthesis. Write `docs/research/<topic>.md`:
+
+- **Answer first** (BLUF), then evidence, then method.
+- The brief, restated.
+- Per major finding: the claim + confidence tag + what it implies for the
+  decision + what evidence would change this conclusion.
+- Disputes surfaced with both positions — never silently averaged.
+- **Expert positions map**: who believes what (quoted, dated, COI-flagged), and
+  where credible experts disagree.
+- **Open questions**: each UNVERIFIED/DISPUTED item with the specific search or
+  experiment that would resolve it (this doubles as the next round's input).
+- Citations dated and tier-labeled: `[primary, 2026-04]`.
+
+Commit the report — this is the **research handoff**: its Open-questions section
+is the next round's input, and the repo is the memory. Raw findings stay in
+`.lead/research/` (gitignored).
+
+### 7. Hand off
+
+A later session resumes by reading the committed report and dispatching gap
+researchers against its Open-questions section instead of restarting the harness.
+If this feeds the build loop, distill the report into `docs/spec/<slice>.md` per
+`/lead` and continue there. The builder's PHASE 0 will challenge the spec's
+claims — that is a feature.
+
+Research is a separate skill on purpose: fan-out costs many times chat-level
+tokens, so it should be a deliberate act, not a side effect of building.

package/skills/lead-research/tactics.md

@@ -0,0 +1,150 @@
+# Source-class tactics library
+
+Researcher assignments are DESIGNED per topic by the Lead (SKILL.md step 2); the
+sections below are search tactics and verified endpoints per source class — draw
+on whichever a designed researcher needs, mix freely. Every researcher block
+starts with this preamble, then the researcher-specific objective:
+
+```text
+You are a web research agent. Answer ONE assigned objective. Do not write code,
+do not make recommendations - judgment belongs to the Lead reading your output.
+Budget: <N> searches; if two consecutive searches yield no new load-bearing
+facts, stop and return. HARD CONTEXT RULES: never open a full page when the
+search snippet answers the question; quote at most 2 sentences per source; the
+moment you can answer, STOP and write your findings - partial findings beat
+context exhaustion (a researcher that fills its window dies without writing
+anything). OUTPUT: markdown findings, <= ~2,500 tokens - every finding carries a
+source tag (e.g. [S3]), source date, the exact figure or a short direct quote,
+and a confidence tag (high = primary / med = reputable secondary / low = single
+blog or forum). Prefer primary sources. Record exact version numbers and dates.
+When sources disagree, report the disagreement - do not resolve it. If you cannot
+find evidence, write NOT FOUND - never fill gaps from prior knowledge without
+flagging it. End with a numbered source list - every source URL appears EXACTLY
+ONCE, numbered [S1], [S2], ... - then the 2-3 findings most likely to change a
+design decision.
+```
+
+**Researcher scoping rule:** cap each researcher at ~5 subjects (repos, vendors,
+people). Doc-heavy assignments burn the context window on fetched pages. A
+researcher that dies returns NOTHING (the `-o` output only materializes on a
+clean finish). If a researcher dies this way, bisect the assignment into narrower
+researchers and re-dispatch; do not re-run it as-is.
+
+## Researcher 0 — Scout (brainstorm scale; runs before assignment design)
+
+Objective template: map the terrain of <topic> — do NOT gather findings. Return:
+(1) canonical terminology and the names the field itself uses; (2) the 5–10
+load-bearing systems/papers/repos/vendors, one line each on why they matter;
+(3) the named people whose positions recur; (4) which source classes look rich vs
+empty (papers? repos? vendor blogs? forums?); (5) the topic's natural fault lines
+— the 3–6 sub-questions an expert would split it into. Budget ~10 searches;
+breadth over depth; snippet over page. Output is a MAP for the Lead to design
+researchers from — structure matters more than completeness.
+
+## Researcher 1 — Academic (latest papers)
+
+Objective: the current academic state of <topic> — most recent survey, the latest
+preprints, and which papers the field treats as load-bearing.
+
+Pipeline: **survey first → latest sweep → snowball → score.**
+
+- Recent survey: Semantic Scholar `publicationTypes=Review`, or arXiv
+  `ti:survey AND abs:<topic>` (last ~18 months). The survey supplies canonical
+  terminology and the seed bibliography.
+- Latest sweep (newest first): the arXiv Atom API
+  `https://export.arxiv.org/api/query?search_query=cat:<cs.XX>+AND+abs:%22<topic>%22&sortBy=submittedDate&sortOrder=descending&max_results=25`
+  (uppercase AND/OR; wait ~3s between calls) and Semantic Scholar
+  `https://api.semanticscholar.org/graph/v1/paper/search?query=<topic>&fields=title,year,citationCount,tldr,venue&limit=20`
+  (expect 429s — back off and retry; the `tldr` field is gold for triage).
+- Snowball from the 2–3 most relevant seeds — forward citations and semantic
+  neighbours via the Semantic Scholar graph API; fall back to OpenAlex
+  `https://api.openalex.org/works?search=<topic>&sort=publication_date:desc&per-page=25`
+  when S2 throttles.
+- Score candidates by citations-per-month (not raw count — meaningless for 2026
+  papers), venue/review decision, code availability. Red flags: preprint-only
+  after 18+ months, self-citation-heavy.
+
+## Researcher 2 — Popular repos (what the ecosystem actually uses)
+
+Objective: the 5–10 repos/libraries the ecosystem has actually adopted for
+<topic>, with adoption evidence beyond stars.
+
+- Discovery: GitHub search — `topic:<topic> stars:>1000 archived:false sort:stars`,
+  `"<topic>" in:name,description,readme stars:>2000`, plus awesome-lists as recall
+  boosters — re-check `pushed:` on every list entry; lists go stale.
+- **Adoption evidence beats stars**: dependents via `https://api.deps.dev` or
+  `https://packages.ecosyste.ms` (keyless); registry download trends
+  (`https://pypistats.org`, `https://api.npmjs.org/downloads`).
+- **Fake-star check**: stars without proportional forks/issues/dependents = flag
+  it. Report stars AND dependents AND last release for every repo.
+
+## Researcher 3 — Cutting-edge repos (emerging, not hype)
+
+Objective: what's emerging in <topic> in the last ~6 months that practitioners are
+actually adopting — and which hyped repos are already abandoned.
+
+- Where bleeding-edge surfaces first: Hacker News via Algolia
+  `https://hn.algolia.com/api/v1/search_by_date?query=<topic>&tags=story&numericFilters=points>50`;
+  `https://lobste.rs/t/<tag>.json`; GitHub
+  `topic:<topic> created:>{90d ago} stars:>100 pushed:>{14d ago} sort:stars`.
+- **Emerging-vs-hype test** (report which side each repo lands on): EMERGING =
+  created recently AND pushed <14d AND sustained star velocity AND maintainer
+  responses AND forks/issues growing in proportion to stars. HYPE = week-one
+  spike then stalled pushes, unanswered issues, README >> code, single
+  contributor, no tests/releases. Any single signal is gameable; the conjunction
+  is not.
+
+## Researcher 4 — Production-grade design patterns
+
+Objective: how 2–3 production libraries adjacent to <topic> design the thing we're
+about to build — API ergonomics, error handling, extension points, testing
+patterns — and where they differ.
+
+- Select subjects with the production-grade test: pushed <6mo (or explicitly
+  stable + responsive issues), tagged releases + changelog in the last 12mo,
+  dependents >100 (ecosystem-adjusted), ≥2 active maintainers, CI runs tests on
+  PRs, OSI license. Ignore raw stars and commit counts.
+- Reading order — never start at file #1: README + manifest (the deliberate
+  public surface) → trace ONE canonical happy-path call end to end → tests for the
+  relevant feature → 3 closed issues + 2 merged PRs in the area (the "why not").
+- Extract four categories per library: API ergonomics, error handling, extension
+  points (grep for hook/adapter/middleware/plugin/register/Protocol), testing
+  patterns. Then the cross-library diff: shared patterns are load-bearing; where
+  they differ is a trade-off to document.
+- Tools: GitHub code search (`symbol:`, `/regex/`, `repo:`, `path:`),
+  `https://grep.app`, `https://sourcegraph.com/search`.
+
+## Researcher 5 — General web
+
+Objective: everything the other researchers structurally miss on <topic> — expert
+blog posts, postmortems and failure reports, comparisons, official vendor
+docs/changelogs, pricing/operational constraints.
+
+- Standard multi-angle sweep: official docs/changelogs; named-expert posts;
+  "<X> postmortem" / "<X> at scale" / "<X> problems"; "<X> vs <Y>". Date-restrict
+  queries on fast-moving topics.
+- Source hierarchy applies hardest here: SEO listicles and AI-generated
+  aggregators are pointers, never citations — chase them to the primary source or
+  drop the claim.
+
+## Researcher 6 — Expert opinion (second wave)
+
+Objective: what the named experts in <topic> are saying right now — positions,
+warnings, predictions, and especially disagreements — from their blogs, talks,
+and social posts.
+
+- **Build the roster first** (why this runs second): survey and top-paper authors
+  (researcher 1), maintainers of the leading repos (researchers 2–3), and names
+  that recur across researcher 5. Pick 5–8; record each expert's affiliation for
+  conflict-of-interest tagging.
+- Where to find their voice, in reliability order: personal blogs / newsletters
+  (`"<name>" <topic>`, `site:<their-domain> <topic>`); HN comments
+  (`https://hn.algolia.com/api/v1/search?tags=comment,author_<username>&query=<topic>`);
+  conference talks / podcasts (prefer transcripts or the speaker's own writeup);
+  indexed social (`site:x.com "<name>" <topic>`); Reddit / lobste.rs threads.
+- **Opinion is its own evidence class.** For every position report: the exact
+  quote or close paraphrase, where and when stated, and any conflict of interest.
+  An opinion NEVER counts toward the ≥2-source rule for factual claims.
+- **The highest-value output is disagreement**: where credible experts contradict
+  each other is exactly where the genuinely open questions are. Map who stands
+  where and what evidence each side cites.

package/skills/orwell-writing/README.md

@@ -0,0 +1,27 @@
+# Orwell Writing
+
+<p align="center">
+  <img src="../../assets/skill-cards/orwell-writing.svg" alt="orwell-writing skill card" width="100%">
+</p>
+
+Draft, revise, and polish prose in plain English while preserving the intended
+meaning, voice, audience, and genre.
+
+## Install
+
+Install this skill for your user account:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill orwell-writing
+```
+
+Install it into the current repository instead:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill orwell-writing --project
+```
+
+Restart Claude Code or Codex, then ask it to draft, edit, simplify, or
+humanize a piece of writing.
+
+See the full workflow in [SKILL.md](SKILL.md).