@iceinvein/agent-skills 0.2.0 → 0.4.0

package/skills/sluice/SKILL.md

@@ -21,17 +21,20 @@ announcement is how your partner redirects you without being asked.
 | `deep` | Several subsystems, or a plan was asked for | + written design and plan | "Deep channel, several subsystems. Design before code." |
 
 `bypass`, `fast`, and `main` proceed without stopping for approval; only
-`deep` stops, for design sign-off before code.
+`deep` stops, for design sign-off before code, and again for the plan when
+agents rather than you will carry it out.
 
 Name the channel and the signal that actually routed you there. The strings above
 are examples, not fixed copy, and a channel with a two-part signal should say
 which part applied. `bypass` says nothing at all, because a question that gets
 announced stops being a question.
 
-**`root-cause` and `finish` are not channel-assigned.** The code misbehaving
-triggers the first: a bug report, a red test, behaviour you cannot account
-for. An integration event, merging, pushing, or opening a PR, triggers the
-second. Both fire in every channel, `bypass` included.
+**`root-cause`, `finish` and `meter` are not channel-assigned.** The code
+misbehaving triggers the first: a bug report, a red test, behaviour you cannot
+account for. An integration event, merging, pushing, or opening a PR, triggers
+the second. Handing the work back triggers the third, whether or not it ever
+reaches an integration event. The first two fire in every channel, `bypass`
+included; `meter` cannot, because `bypass` announces nothing to measure from.
 
 ## The rules
 
@@ -56,6 +59,10 @@ yourself wanting to skip the rule, or arguing that this one is the exception.
   yours. `references/review.md`
 - **Finish** deliberately. Green suite first, then let your partner pick
   merge, PR, or leave it. Never pick for them. `references/finish.md`
+- **Meter the run** as you hand it back. `scripts/run-stats.sh` reads the
+  ledger out of the session transcript: elapsed, tools, tokens, and what each
+  dispatched agent cost. A summary you assemble from memory is the one that
+  flatters you. `references/meter.md`
 
 ## Changing channel
 
@@ -70,9 +77,15 @@ Design to `docs/specs/YYYY-MM-DD-<topic>.md`, plan to
 `docs/plans/YYYY-MM-DD-<topic>.md`, unless the repo has a convention or
 your partner states a preference. Get the design signed off before code.
 
+The plan needs sign-off as well whenever agents will execute it, because each
+one sees only its own task and so nobody ever reads the plan whole. Executing
+it yourself makes it a worklist instead: write it and carry on.
+
 Then read `references/deep-channel.md` for the plan format, the dispatch rules,
-and when a task actually needs a reviewer. Two that catch people out: never run
-two implementers at once, and review is tiered, not automatic.
+and when a task actually needs a reviewer. Three that catch people out: never
+run two implementers at once, review is tiered rather than automatic, and a
+`deep` run that cannot dispatch has to replace the review tier with something,
+not quietly ship without one.
 
 ## Conflicts
 

package/skills/sluice/references/deep-channel.md

@@ -50,6 +50,26 @@
 - Match model to task: cheap for mechanical work, stronger for judgment
   and final review.
 
+## When dispatch is unavailable
+
+A session may forbid subagents outright. `deep` then loses most of the
+machinery this file describes, and the place to say so is the routing
+announcement, where your partner can still act on it, not the summary at the
+end where it reads as an excuse.
+
+Three things change. The plan becomes your own worklist and needs no sign-off,
+since you are the only one who will ever read it. Task isolation is gone, so
+`TaskCreate` now carries all of the state that outlives compaction and matters
+more, not less. And fresh context is unavailable, which was the entire thing
+review was buying.
+
+One thing does not change: the work still owes a review. Reading your own diff
+is not one, and the table below still names which tasks needed the stronger
+tier. List those tasks when you hand back, as review outstanding rather than
+review passed. A `deep` run that ships with nobody having read it has become a
+`fast` run with a design document attached, and your partner is entitled to
+know that before they decide anything.
+
 ## Review policy
 
 A review costs about what the implementation cost, so reviewing every task

package/skills/sluice/references/finish.md

@@ -14,8 +14,10 @@ Confirm the base branch instead of assuming it; untangling a wrong merge
 costs far more than asking would have.
 
 With the suite green and the base confirmed, put exactly three options to
-your partner: merge it locally, push it and open a PR, or leave the branch
-as it stands. Those three exhaust what you may offer. Your partner may still
+your partner, with the run ledger above them so the choice is made against
+what the work actually cost rather than against your account of it;
+`references/meter.md` owns that. The three: merge it locally, push it and
+open a PR, or leave the branch as it stands. Those three exhaust what you may offer. Your partner may still
 ask for something off the list, most notably scrapping the branch, but the
 request has to originate with them and be unmistakable. Then stop. Which of
 the three it is belongs to them, however obvious the choice looks from where

package/skills/sluice/references/meter.md

@@ -0,0 +1,38 @@
+# Meter the run
+
+Run `scripts/run-stats.sh` as part of the message that hands the work back,
+and paste its output into that message unedited:
+
+```
+bash <skill-dir>/scripts/run-stats.sh --tests "<what the suite actually printed>"
+```
+
+It reads the session transcript, so it needs no state of its own and cannot
+drift from what happened. `--tests` is the one field it cannot know: only you
+watched the suite run. Fill it from the output you read in this session, and
+leave it off entirely if no suite ran, which prints "not reported" rather
+than a number nobody checked. `--base <ref>` overrides the diff base when the
+merge-base with `main` or `master` is not where this branch actually began.
+
+The run starts at your channel announcement, not at the session, so three
+unrelated tasks in one session report as three runs. A previous ledger closes
+the run before it. `bypass` announces nothing, so there is nothing to meter
+and the script exits quietly.
+
+What the ledger is for: the cost of a channel is otherwise invisible, and a
+channel nobody can price is a channel nobody can choose between. Six agents
+and four hours of agent wall-clock on a two-file change is the sort of thing
+that only becomes obvious once it is written down next to the diff. Expect
+some runs to make the case for a shallower channel next time. That is the
+ledger working, not the ledger complaining.
+
+Read it before you paste it. A row showing an agent that errored, or an agent
+whose token count dwarfs every other row, is a finding about the run and
+belongs in your prose, not left for your partner to spot in a table.
+
+Exit 2 means there was no run to report. That is a fact about the work, not a
+failure: do not synthesise a ledger to fill the gap.
+
+The friction line: "I know roughly what this cost." Roughly is the problem.
+Every number here is already on disk, and the remembered version is reliably
+the flattering one.

package/skills/sluice/scripts/run-stats.sh

@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+# Print the run ledger: what this piece of work actually cost.
+#
+# The run starts at the channel announcement, not at the session, so a session
+# holding three unrelated tasks reports each one separately. A previous ledger
+# ends the run before it. `bypass` announces nothing and so prints nothing.
+#
+# Usage: run-stats.sh [--tests "<what the suite reported>"] [--base <git-ref>]
+#                     [--transcript <path>]
+#
+# Exit 0 printed a ledger, 1 could not read a transcript, 2 no run to report.
+
+set -uo pipefail
+
+TESTS=""
+BASE=""
+TRANSCRIPT=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --tests) TESTS="${2-}"; shift 2 ;;
+    --base) BASE="${2-}"; shift 2 ;;
+    --transcript) TRANSCRIPT="${2-}"; shift 2 ;;
+    -h|--help) sed -n '2,11p' "$0" | cut -c3-; exit 0 ;;
+    *) echo "run-stats: unknown argument '$1'" >&2; exit 1 ;;
+  esac
+done
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "run-stats: jq is required and was not found on PATH" >&2
+  exit 1
+fi
+
+if [ -z "$TRANSCRIPT" ]; then
+  sid="${CLAUDE_CODE_SESSION_ID:-}"
+  if [ -z "$sid" ]; then
+    echo "run-stats: no --transcript given and CLAUDE_CODE_SESSION_ID is unset" >&2
+    exit 1
+  fi
+  # The session id is unique across projects, so glob rather than guess the slug.
+  TRANSCRIPT="$(ls "$HOME"/.claude/projects/*/"$sid".jsonl 2>/dev/null | head -1)"
+fi
+
+if [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ]; then
+  echo "run-stats: transcript not found (looked for '${TRANSCRIPT:-<unresolved>}')" >&2
+  exit 1
+fi
+
+SUMMARY="$(jq -s '
+  # ---- what counts as a real turn ----------------------------------------
+  # Transcript stamps carry milliseconds, which fromdateiso8601 will not take.
+  def ts: sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601;
+  def is_meta: (.isMeta == true) or (.isSidechain == true);
+  def texts: [ .message.content[]? | select(.type == "text") | .text ] | join("\n");
+  # The channel is stated in one line before proceeding, so the announcement
+  # opens the message. Anchoring there is what separates it from prose that
+  # merely discusses a channel, which a session about sluice is full of.
+  def marker: "^[*_#>[:space:]]*(?<c>fast|main|deep)[[:space:]]+channel";
+  def announces: (.type == "assistant") and (is_meta | not)
+    and (texts | test(marker; "i"));
+  def chan: texts | capture(marker; "i") | .c | ascii_downcase;
+  def is_stats_call: (.type == "assistant") and ([
+      .message.content[]? | select(.type == "tool_use" and .name == "Bash")
+      | select((.input.command // "") | test("run-stats\\.sh"))
+    ] | length > 0);
+  # Waiting is any turn the partner had to take: a prompt, or an answer to a
+  # question you put to them. Leaving the latter out understates the wait on
+  # exactly the runs that stopped to ask, which are the ones worth pricing.
+  def is_prompt: (.type == "user") and (is_meta | not)
+    and (((.message.content | type) == "string"
+          or ((.message.content | type) == "array"
+              and ([ .message.content[]? | select(.type == "tool_result") ] | length == 0)))
+         or ((.toolUseResult | type) == "object" and (.toolUseResult | has("answers"))));
+
+  . as $all
+  | [ range(0; $all | length) ] as $ix
+  | [ $ix[] | select($all[.] | announces) ] as $ann
+  | if ($ann | length) == 0 then { empty: true } else
+
+  # A previous ledger closes the run before it. The call running right now has
+  # no announcement after it, so it is skipped rather than closing this run.
+  ([ $ix[] | select($all[.] | is_stats_call) ]
+    | map(select(. < ($ann | max)))
+    | if length == 0 then -1 else max end) as $boundary
+  | [ $ann[] | select(. > $boundary) ] as $ann
+  | ($ann | min) as $from
+  | [ $all[$from:][] | select(.timestamp) ] as $run
+
+  # ---- channel, and the trail if it escalated ----------------------------
+  | ([ $ann[] | $all[.] | chan ]
+     | reduce .[] as $c ([]; if (. | last) == $c then . else . + [$c] end)) as $trail
+
+  # ---- clocks ------------------------------------------------------------
+  | ($run | map(.timestamp) | min) as $start
+  | ($run | map(.timestamp) | max) as $end
+  | (($end | ts) - ($start | ts)) as $elapsed
+  | ([ range(1; $run | length)
+       | select($run[.] | is_prompt)
+       | ($run[.].timestamp | ts) - ($run[. - 1].timestamp | ts) ]
+     | add // 0) as $waiting
+
+  # ---- tools and tokens, main loop only ----------------------------------
+  | [ $run[] | select((.type == "assistant") and (is_meta | not))
+      | .message.content[]? | select(.type == "tool_use") | .name ] as $tools
+  | ([ $run[] | select((.type == "assistant") and (is_meta | not))
+       | .message.usage.output_tokens // 0 ] | add // 0) as $out_tok
+  | ([ $run[] | select((.type == "assistant") and (is_meta | not))
+       | .message.usage.cache_read_input_tokens // 0 ] | add // 0) as $cache_tok
+
+  # ---- dispatched agents -------------------------------------------------
+  | ([ $run[] | select(.type == "assistant") | .message.content[]?
+       | select(.type == "tool_use" and (.name == "Agent" or .name == "Task"))
+       | { key: .id, value: (.input.description // .input.subagent_type // "agent") } ]
+     | from_entries) as $labels
+  # toolUseResult is whatever the tool returned: object, array or string.
+  | [ $run[] | select((.toolUseResult | type) == "object") | select(.toolUseResult.agentId)
+      | { label: ($labels[[ .message.content[]? | select(.type == "tool_result") | .tool_use_id ][0]] // "agent"),
+          model: (.toolUseResult.resolvedModel // "?"),
+          status: (.toolUseResult.status // "?"),
+          tokens: (.toolUseResult.totalTokens // 0),
+          ms: (.toolUseResult.totalDurationMs // 0),
+          tools: (.toolUseResult.totalToolUseCount // 0) } ] as $agents
+
+  | { empty: false,
+      trail: ($trail | join(" → ")),
+      elapsed: $elapsed, waiting: $waiting,
+      tool_total: ($tools | length),
+      tool_top: ([ $tools | group_by(.)[] | { n: length, name: (.[0] | ascii_downcase | split("__") | last) } ]
+                 | sort_by(-.n) | .[0:3]),
+      out_tok: $out_tok, cache_tok: $cache_tok,
+      agents: $agents,
+      agent_tokens: ([ $agents[].tokens ] | add // 0),
+      agent_ms: ([ $agents[].ms ] | add // 0) }
+  end
+' "$TRANSCRIPT" 2>/dev/null)"
+
+if [ -z "$SUMMARY" ]; then
+  echo "run-stats: could not parse '$TRANSCRIPT'" >&2
+  exit 1
+fi
+
+if [ "$(jq -r '.empty' <<<"$SUMMARY")" = "true" ]; then
+  exit 2
+fi
+
+# ---- formatting -------------------------------------------------------------
+
+dur() { # seconds -> 1h05m | 3m11s | 42s
+  local s=${1%.*} h m
+  h=$((s / 3600)); m=$(((s % 3600) / 60)); s=$((s % 60))
+  if [ "$h" -gt 0 ]; then printf '%dh%02dm' "$h" "$m"
+  elif [ "$m" -gt 0 ]; then printf '%dm%ds' "$m" "$s"
+  else printf '%ds' "$s"; fi
+}
+
+tok() { # tokens -> 1.2M | 313k | 51.0k | 350
+  local n=$1
+  if [ "$n" -ge 1000000 ]; then awk -v n="$n" 'BEGIN{printf "%.1fM", n/1000000}'
+  elif [ "$n" -ge 100000 ]; then awk -v n="$n" 'BEGIN{printf "%dk", n/1000}'
+  elif [ "$n" -ge 1000 ]; then awk -v n="$n" 'BEGIN{printf "%.1fk", n/1000}'
+  else printf '%d' "$n"; fi
+}
+
+g() { jq -r "$1" <<<"$SUMMARY"; }
+
+printf '─── run %s\n' "$(printf '─%.0s' $(seq 1 36))"
+printf 'channel   %s\n' "$(g '.trail')"
+
+elapsed=$(g '.elapsed'); waiting=$(g '.waiting')
+if [ "${waiting%.*}" -gt 0 ]; then
+  printf 'elapsed   %s · %s of that waiting on you\n' "$(dur "$elapsed")" "$(dur "$waiting")"
+else
+  printf 'elapsed   %s\n' "$(dur "$elapsed")"
+fi
+
+top="$(g '[.tool_top[] | "\(.n) \(.name)"] | join(" · ")')"
+if [ -n "$top" ]; then
+  printf 'tools     %s · %s\n' "$(g '.tool_total')" "$top"
+else
+  printf 'tools     %s\n' "$(g '.tool_total')"
+fi
+
+printf 'tokens    %s out · %s cache read\n' "$(tok "$(g '.out_tok')")" "$(tok "$(g '.cache_tok')")"
+printf 'tests     %s\n' "${TESTS:-not reported}"
+
+# The diff is the branch as a whole against where it left the base, working
+# tree included, because uncommitted work is still work this run produced.
+if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  if [ -z "$BASE" ]; then
+    for cand in main master; do
+      if git rev-parse --verify --quiet "$cand" >/dev/null 2>&1; then
+        BASE="$(git merge-base HEAD "$cand" 2>/dev/null)" && break
+      fi
+    done
+    [ -z "$BASE" ] && BASE="HEAD"
+  fi
+  stat="$(git diff --shortstat "$BASE" 2>/dev/null | sed 's/^ *//')"
+  files="$(git diff --name-only "$BASE" 2>/dev/null | wc -l | tr -d ' ')"
+  # awk, not sed: BSD sed has no \+ and silently matches nothing.
+  ins="$(awk '{for(i=1;i<=NF;i++) if($i ~ /^insertion/) print $(i-1)}' <<<"$stat")"
+  del="$(awk '{for(i=1;i<=NF;i++) if($i ~ /^deletion/) print $(i-1)}' <<<"$stat")"
+  ins=${ins:-0}; del=${del:-0}
+
+  # A file the run created is not in the diff until it is staged, and staging
+  # it here would be a side effect on someone else's index. Count it instead.
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    files=$((files + 1))
+    ins=$((ins + $(wc -l <"$f" 2>/dev/null || echo 0)))
+  done < <(git ls-files --others --exclude-standard 2>/dev/null)
+
+  [ "$files" -gt 0 ] && printf 'diff      +%s −%s across %s files\n' "$ins" "$del" "$files"
+fi
+
+count=$(g '.agents | length')
+if [ "$count" -eq 0 ]; then
+  printf 'agents    none dispatched\n'
+else
+  printf 'agents    %s dispatched · %s tok · %s wall\n' \
+    "$count" "$(tok "$(g '.agent_tokens')")" "$(dur "$(( $(g '.agent_ms') / 1000 ))")"
+
+  # Up to a dozen rows read as the narrative of the plan. Past that the order
+  # stops helping, so show what the run actually spent on and say what is cut.
+  if [ "$count" -le 12 ]; then rows='.agents[]'; else rows='(.agents | sort_by(-.tokens) | .[0:10][])'; fi
+  while IFS=$'\t' read -r label model status tokens ms tools; do
+    model="${model#claude-}"; model="$(sed 's/-[0-9]\{8\}$//' <<<"$model")"
+    [ "$status" = "completed" ] && status="" || status="  ($status)"
+    printf '  %-22.22s %-10s %6s  %7s  %s tools%s\n' \
+      "$label" "$model" "$(tok "$tokens")" "$(dur "$((ms / 1000))")" "$tools" "$status"
+  done < <(g "$rows | [.label, .model, .status, .tokens, .ms, .tools] | @tsv")
+
+  if [ "$count" -gt 12 ]; then
+    printf '  +%s more · %s tok (dearest 10 shown)\n' \
+      "$((count - 10))" "$(tok "$(g '(.agents | sort_by(-.tokens) | .[10:] | map(.tokens) | add) // 0')")"
+  fi
+fi

package/skills/sluice/skill.json

@@ -1,7 +1,7 @@
 {
   "name": "sluice",
-  "version": "1.0.0",
-  "description": "Routes work by change shape into four channels (bypass, fast, main, deep) and applies only the rules each channel needs, so a one-line fix does not pay the cost of a multi-subsystem build. Carries six rules as one-liners in the router and the full treatment in references read only on friction. Claude Code only; conflicts with the superpowers plugin.",
+  "version": "0.1.1",
+  "description": "Routes work by change shape into four channels (bypass, fast, main, deep) and applies only the rules each channel needs, so a one-line fix does not pay the cost of a multi-subsystem build. Carries seven rules as one-liners in the router and the full treatment in references read only on friction, and closes each run with a ledger read out of the session transcript: elapsed, tools, tokens, and what every dispatched agent cost. Claude Code only; conflicts with the superpowers plugin.",
   "author": "iceinvein",
   "type": "prompt",
   "tools": [
@@ -12,7 +12,8 @@
   },
   "bundle": {
     "include": [
-      "references"
+      "references",
+      "scripts"
     ]
   },
   "install": {