@sitar_fiercer4c/skills 0.1.0

package/skills/system-resource-triage/scripts/reap.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# Terminate detached, long-lived processes. Dry run unless --confirm is passed.
+#
+#   reap.sh --name claude                      list candidates (dry run)
+#   reap.sh --name claude --min-age-days 5     older than 5 days
+#   reap.sh --name claude --confirm            actually SIGTERM them
+#   reap.sh --name vscode-server --match-args  match the full command line, not the process name
+#   reap.sh --name claude --protect "123 456"  keep specific PIDs alive
+#
+# Only ever selects processes with NO controlling terminal: anything with a tty is attached to
+# something a human is using. The calling process and its entire ancestor chain are always
+# excluded, so this cannot kill the session running it.
+#
+# Runs under bash on purpose. In zsh `kill $PIDS` passes the whole list as a single argument and
+# silently fails, which is easy to misread as success.
+
+set -uo pipefail
+
+NAME=""
+MIN_AGE_DAYS=2
+CONFIRM=0
+MATCH_ARGS=0
+PROTECT=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --name)         NAME="${2:-}"; shift 2 ;;
+    --min-age-days) MIN_AGE_DAYS="${2:-2}"; shift 2 ;;
+    --protect)      PROTECT="${2:-}"; shift 2 ;;
+    --match-args)   MATCH_ARGS=1; shift ;;
+    --confirm)      CONFIRM=1; shift ;;
+    -h|--help)      sed -n '2,16p' "$0"; exit 0 ;;
+    *) printf 'unknown option: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+[ -z "$NAME" ] && { printf 'error: --name is required\n' >&2; exit 2; }
+
+# Walk up from this script's own PID so we can never select ourselves or whatever launched us.
+ancestors=" 1 "
+p=$$
+while [ -n "$p" ] && [ "$p" != "0" ] && [ "$p" != "1" ]; do
+  ancestors+="$p "
+  p=$(awk '/^PPid:/ { print $2 }' "/proc/$p/status" 2>/dev/null)
+done
+for x in $PROTECT; do ancestors+="$x "; done
+
+if [ "$MATCH_ARGS" -eq 1 ]; then
+  listing=$(ps -eo pid=,ppid=,stat=,euid=,tty=,etime=,rss=,args=)
+else
+  listing=$(ps -eo pid=,ppid=,stat=,euid=,tty=,etime=,rss=,comm=)
+fi
+
+candidates=$(printf '%s\n' "$listing" \
+  | awk -v want="$NAME" -v minage="$MIN_AGE_DAYS" -v prot="$ancestors" -v me="$(id -u)" '
+  BEGIN { n = split(prot, A, " "); for (i = 1; i <= n; i++) if (A[i] != "") P[A[i]] = 1 }
+  $1 <= 2 || $2 == 2 { next }                         # never touch init or kernel threads
+  $3 ~ /^Z/ { next }                                  # zombies hold no memory; TERM does nothing
+  $4 != me { next }                                   # only your own processes
+  $5 != "?" { next }                                  # has a terminal: someone is using it
+  {
+    split($6, a, "-")
+    days = (a[2] == "") ? 0 : a[1] + 0
+    if (days < minage) next
+    if ($1 in P) next
+    pid = $1; age = $6; rss = $7
+    $1 = $2 = $3 = $4 = $5 = $6 = $7 = ""
+    sub(/^ +/, "")
+    if ($0 !~ want) next
+    printf "%s|%s|%s|%s\n", pid, age, rss, $0
+  }')
+
+if [ -z "$candidates" ]; then
+  printf 'no candidates: nothing matching /%s/ is detached and older than %s day(s)\n' \
+    "$NAME" "$MIN_AGE_DAYS"
+  exit 0
+fi
+
+printf '%s\n' "$candidates" \
+  | awk -F'|' '{ printf "  pid=%-9s age=%-14s rss=%7.0f MB  %s\n", $1, $2, $3/1024, $4; n++; t += $3 }
+               END { printf "\n  %d processes, %.1f GB reclaimable\n", n, t/1048576 }'
+
+pids=$(printf '%s\n' "$candidates" | cut -d'|' -f1)
+
+# Belt and braces: abort rather than kill anything in the protected set.
+for pid in $pids; do
+  case "$ancestors" in
+    *" $pid "*) printf '\nABORT: protected pid %s appeared in the list\n' "$pid" >&2; exit 1 ;;
+  esac
+done
+
+if [ "$CONFIRM" -eq 0 ]; then
+  printf '\ndry run - nothing was killed. Re-run with --confirm to SIGTERM these.\n'
+  exit 0
+fi
+
+printf '\nsending SIGTERM...\n'
+sent=0
+for pid in $pids; do
+  if kill -TERM "$pid" 2>/dev/null; then sent=$((sent + 1)); else printf '  already gone: %s\n' "$pid"; fi
+done
+printf 'TERM delivered to %d processes, waiting 12s for clean exit...\n' "$sent"
+sleep 12
+
+survivors=""
+for pid in $pids; do kill -0 "$pid" 2>/dev/null && survivors+="$pid "; done
+
+if [ -n "$survivors" ]; then
+  printf '\nstill alive after SIGTERM: %s\n' "$survivors"
+  printf 'left running on purpose - SIGKILL loses unflushed state, so confirm before forcing.\n'
+else
+  printf '\nall terminated cleanly.\n'
+fi
+
+printf '\n== memory now ==\n'
+free -h

package/skills/system-resource-triage/scripts/triage.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# Read-only system resource triage. Gathers everything needed for a diagnosis in one pass.
+#
+#   triage.sh                        group memory by process name
+#   triage.sh claude vscode-server   group by regex against the full command line
+#   triage.sh --snapshot /tmp/before.txt [patterns...]
+#
+# Deliberately avoids spawning a subprocess per PID: on a box with ~1500 processes that generates
+# enough context switches and run-queue depth to show up in the very numbers being measured.
+
+set -uo pipefail
+
+SNAPSHOT=""
+PATTERNS=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --snapshot) SNAPSHOT="${2:-}"; shift 2 ;;
+    -h|--help) sed -n '2,10p' "$0"; exit 0 ;;
+    *) PATTERNS+=("$1"); shift ;;
+  esac
+done
+
+hr() { printf '\n== %s ==\n' "$1"; }
+
+main() {
+  printf 'triage @ %s\n' "$(date '+%Y-%m-%d %H:%M:%S')"
+
+  hr "load / uptime"
+  uptime
+  printf 'cores: %s\n' "$(nproc)"
+
+  hr "memory"
+  free -h
+
+  hr "cpu (instantaneous - second sample, first is a since-boot average)"
+  top -bn2 -d 1 2>/dev/null | grep '^%Cpu' | tail -1
+
+  hr "vmstat (header row dropped: it is a since-boot average, not now)"
+  vmstat 1 3 2>/dev/null | tail -2
+
+  hr "processes in D state (uninterruptible IO)"
+  local dcount
+  dcount=$(ps -eo stat= | awk '$1 ~ /^D/' | wc -l)
+  printf 'count: %s\n' "$dcount"
+  [ "$dcount" -gt 0 ] && ps -eo pid=,stat=,comm= | awk '$2 ~ /^D/' | head -10
+
+  hr "memory by group (the aggregate view - small processes hide here)"
+  if [ ${#PATTERNS[@]} -gt 0 ]; then
+    local joined
+    joined=$(printf '%s\001' "${PATTERNS[@]}")
+    ps -eo rss=,args= | awk -v pats="$joined" '
+      BEGIN { np = split(pats, P, "\001") }
+      {
+        rss = $1; $1 = ""; key = "other"
+        for (i = 1; i <= np; i++) if (P[i] != "" && $0 ~ P[i]) { key = P[i]; break }
+        n[key]++; s[key] += rss
+      }
+      END { for (k in n) printf "%.0f|%d|%s\n", s[k]/1024, n[k], k }'
+  else
+    ps -eo rss=,comm= | awk '{ n[$2]++; s[$2] += $1 }
+      END { for (k in n) printf "%.0f|%d|%s\n", s[k]/1024, n[k], k }'
+  fi | sort -t'|' -k1 -rn | head -12 \
+     | awk -F'|' '{ printf "%9s MB  %5s procs  %s\n", $1, $2, $3 }'
+
+  hr "top single processes by RSS"
+  ps -eo rss=,pid=,comm= --sort=-rss | head -8 \
+    | awk '{ printf "%9.0f MB  pid=%-8s %s\n", $1/1024, $2, $3 }'
+
+  hr "top swap consumers (single awk pass over /proc)"
+  awk '/^Name:/ { n = $2 }
+       /^VmSwap:/ { if ($2+0 > 0) { split(FILENAME, a, "/"); printf "%9.0f MB  pid=%-8s %s\n", $2/1024, a[3], n } }' \
+      /proc/[0-9]*/status 2>/dev/null | sort -rn | head -10
+
+  hr "zombies (no RAM/CPU cost, but they leak PID slots)"
+  local zcount
+  zcount=$(ps -eo stat= | awk '$1 ~ /^Z/' | wc -l)
+  printf 'total: %s\n' "$zcount"
+  if [ "$zcount" -gt 0 ]; then
+    printf 'by parent (a parent that is not reaping - often PID 1 = "sleep infinity" in a container):\n'
+    ps -eo stat=,ppid= | awk '$1 ~ /^Z/ { c[$2]++ } END { for (p in c) print c[p], p }' \
+      | sort -rn | head -5 \
+      | while read -r n pp; do
+          printf '  %6s zombies <- ppid=%-8s %s\n' "$n" "$pp" \
+            "$(ps -o comm=,etime= -p "$pp" 2>/dev/null | tr -s ' ')"
+        done
+  fi
+
+  hr "process count by name"
+  ps -eo comm= | sort | uniq -c | sort -rn | head -10
+
+  hr "your detached long-lived processes (no terminal, age >= 1 day) - cleanup candidates"
+  printf 'system daemons and zombies are excluded: killing them reclaims nothing.\n\n'
+  ps -eo pid=,ppid=,stat=,euid=,tty=,etime=,rss=,comm= | awk -v me="$(id -u)" '
+    $1 <= 2 || $2 == 2 { next }                       # init and kernel threads
+    $3 ~ /^Z/ { next }                                # zombies already hold no memory
+    $4 != me { next }                                 # someone else s daemon, not yours to reap
+    $5 == "?" {
+      split($6, a, "-")
+      if (a[2] == "") next
+      n++; tot += $7
+      if (n <= 15) printf "  pid=%-8s age=%-14s rss=%7.0f MB  %s\n", $1, $6, $7/1024, $8
+    }
+    END { printf "\n  %d processes, %.1f GB reclaimable\n", n+0, tot/1048576 }'
+}
+
+if [ -n "$SNAPSHOT" ]; then
+  main 2>&1 | tee "$SNAPSHOT"
+  printf '\nsnapshot saved to %s\n' "$SNAPSHOT"
+else
+  main
+fi

package/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: using-git-worktrees
+description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
+---
+
+# Using Git Worktrees
+
+## Overview
+
+Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.
+
+**Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
+
+## Step 0: Detect Existing Isolation
+
+**Before creating anything, check if you are already in an isolated workspace.**
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+**Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:
+
+```bash
+# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
+git rev-parse --show-superproject-working-tree 2>/dev/null
+```
+
+**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 2 (Project Setup). Do NOT create another worktree.
+
+Report with branch state:
+- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
+- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
+
+**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.
+
+Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
+
+> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
+
+Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 2.
+
+## Step 1: Create Isolated Workspace
+
+**You have two mechanisms. Try them in this order.**
+
+### 1a. Native Worktree Tools (preferred)
+
+The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 2.
+
+Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
+
+Only proceed to Step 1b if you have no native worktree tool available.
+
+### 1b. Git Worktree Fallback
+
+**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
+
+#### Directory Selection
+
+Follow this priority order. Explicit user preference always beats observed filesystem state.
+
+1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
+
+2. **Check for an existing project-local worktree directory:**
+   ```bash
+   ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+   ls -d worktrees 2>/dev/null      # Alternative
+   ```
+   If found, use it. If both exist, `.worktrees` wins.
+
+3. **If there is no other guidance available**, default to `.worktrees/` at the project root.
+
+#### Safety Verification (project-local directories only)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```bash
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**If NOT ignored:** Add to .gitignore, commit the change, then proceed.
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+#### Create the Worktree
+
+```bash
+# Determine path based on chosen location
+path="$LOCATION/$BRANCH_NAME"
+
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.
+
+## Step 2: Project Setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+## Step 3: Verify Clean Baseline
+
+Run tests to ensure workspace starts clean:
+
+```bash
+# Use project-appropriate command
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### Report
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| Already in linked worktree | Skip creation (Step 0) |
+| In a submodule | Treat as normal repo (Step 0 guard) |
+| Native worktree tool available | Use it (Step 1a) |
+| No native tool | Git worktree fallback (Step 1b) |
+| `.worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify ignored) |
+| Both exist | Use `.worktrees/` |
+| Neither exists | Check instruction file, then default `.worktrees/` |
+| Directory not ignored | Add to .gitignore + commit |
+| Permission error on create | Sandbox fallback, work in place |
+| Tests fail during baseline | Report failures + ask |
+| No package.json/Cargo.toml | Skip dependency install |
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "I'm obviously not in a worktree — no need to check" | Run Step 0. Harness-created isolation and submodules both fool eyeballing; the detection commands settle it. |
+| "`git worktree add` is quicker than hunting for a native tool" | A native tool (e.g. `EnterWorktree`) owns placement, branching, and cleanup. Bypassing it is the #1 mistake — it creates phantom state your harness can't see or manage. |
+| "The worktree directory is surely ignored already" | Run `git check-ignore`. An unignored worktree directory commits the whole tree into the repo. |
+| "Any directory name works" | Explicit instructions beat an existing project-local directory, which beats the `.worktrees/` default. |
+| "The workspace is fresh — baseline tests can wait" | A dirty baseline makes every later failure ambiguous. Run the tests now; proceeding past failures is your human partner's call. |