@iceinvein/agent-skills 0.5.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Install agent skills into AI coding tools",
   "author": "iceinvein",
   "license": "MIT",

package/skills/index.json

@@ -283,7 +283,7 @@
     "name": "sluice",
     "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.",
     "type": "prompt",
-    "version": "0.2.1"
+    "version": "0.3.0"
   },
   {
     "name": "temporal-coupling-detector",

package/skills/sluice/SKILL.md

@@ -20,10 +20,13 @@ announcement is how your partner redirects you without being asked.
 | `main` | Adds an interface, or crosses subsystems | + agree intent, review before merge | "Main channel, new interface. Agreeing the shape first." |
 | `deep` | Several subsystems, or a plan was asked for | + written design and plan | "Deep channel, several subsystems. Design before code." |
 
+Two subsystems is `main`; the third is what makes it `deep`.
+
 `bypass`, `fast`, and `main` proceed without stopping for approval; only
-`deep` stops. It stops for design sign-off before code, again for the plan
-when agents rather than you will carry it out, and once more at pre-flight
-before Task 1, to settle review and workspace.
+`deep` stops: once for design sign-off before code, once for the plan and
+pre-flight together before Task 1. A stop ends your turn. Asking a question
+with a tool is not one, however many options it carried: the answer comes
+back to you and the run never left your hands.
 
 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
@@ -36,6 +39,9 @@ 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.
+A question that turns on how something looks is triggered the same way and in
+any channel: `references/show-or-say.md` decides whether to show it or say it,
+and `bypass` is where it comes up most.
 
 ## The rules
 
@@ -79,18 +85,23 @@ 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.
+The plan gets a stop of its own, whoever executes it. Dispatched agents each
+see only their own task, so nobody reads it whole; executing it yourself is
+the weaker case rather than the exempt one, because then nobody reads it but
+its author.
 
 Order the plan so the tasks that change nothing come first, and mark the one
 task that turns the new behaviour on. Then a late re-baseline, re-blessed
 snapshots, regenerated fixtures, attributes to that one point instead of to
 the branch at large.
 
-Before Task 1, stop once and ask which flagged tasks get a reviewer and
-whether the work runs in a worktree. Ask it as a choice with the counts in
-it, never as a paragraph. Review that turns out to be missing is only
+Pre-flight rides in the plan's stop: which flagged tasks get a reviewer, and
+whether the work runs in a worktree. Ask them as choices with the counts in
+them, never as a paragraph, then end the turn on the answers rather than
+opening Task 1 with them. A session that dispatches only when asked has not
+ruled dispatch out, it has made this question the place to ask. Genuine
+unavailability is the tool not being there at all, which is a different case
+and a different paragraph. Review that turns out to be missing is only
 actionable while the plan can still change.
 
 Read the plan as a graph rather than a list. `Needs` and `Offers` are
@@ -98,7 +109,7 @@ dependency edges and `Touches` says what cannot overlap, so which tasks may
 run at once is derivable rather than guessed. Fan out wherever that graph
 allows; serial is the fallback for where it doesn't, not the default.
 
-Then read `references/deep-channel.md` for the plan format, that checkpoint,
+Then read `references/deep-channel.md` for the plan format, that stop,
 the dispatch rules, and when a task actually needs a reviewer. Three that
 catch people out: concurrent implementers need a worktree each and the flip
 runs alone, review is tiered rather than automatic, and a `deep` run that
@@ -107,7 +118,12 @@ ship without one.
 
 ## Conflicts
 
-Sluice cannot run alongside the superpowers plugin. Superpowers requires its
-own fixed pipeline up front for anything that adds to or changes what the
-software does, not just code edits, and that pipeline overrides this router
-outright, so the two cannot be installed together.
+Sluice cannot run alongside the superpowers pipeline. Superpowers requires its
+own fixed sequence up front for anything that adds to or changes what the
+software does, not just code edits, and that sequence overrides this router
+outright.
+
+The test is whether that pipeline governs the work in front of you, not whether
+a plugin is installed. A repo whose own instructions mandate the sequence rules
+this router out exactly as the plugin does, with the plugin disabled or absent.
+Stand down and say so once, in the same breath you would have named a channel.

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

@@ -60,11 +60,20 @@ Split it. A plan with none is not a `deep` plan: nothing in it does anything.
 
 ## Pre-flight
 
-Design signed off, plan written, nothing built yet. Before Task 1, stop once
-and settle two things with your partner. Ask them as questions with options,
-not as a paragraph they have to reply to in prose: what you are after is a
-decision, and a wall of considerations asks them to extract the decision from
-it first.
+Design signed off, plan written, nothing built yet. Before Task 1, hand back
+once and settle two things with your partner. Ask them as questions with
+options, not as a paragraph they have to reply to in prose: what you are after
+is a decision, and a wall of considerations asks them to extract the decision
+from it first.
+
+This handback is the plan's sign-off as well, so it ends your turn, and a
+question tool does not end it for you. That tool returns an answer without
+returning control: two options came back, the plan itself did not, and your
+partner reads the summary of it in the same message as Task 1's first edit,
+by which point their only remaining move is to interrupt. Ask the questions,
+then end the turn on the answers and let the next instruction start the
+build. If the answers arrive with that instruction already attached, you have
+your sign-off and Task 1 begins.
 
 **Review.** Name the tasks the table below sends to a reviewer, each with the
 trigger that qualified it, and say how many of the rest skip with a ledger
@@ -159,8 +168,9 @@ unavailable, where there is nothing to ask.
 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
+Three things change. The plan stops being a brief for strangers and becomes
+your own worklist, which makes its handback the only outside read it will ever
+get rather than a formality on the way to dispatch. 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.

package/skills/sluice/references/meter.md

@@ -33,12 +33,24 @@ chain and a finding for one whose graph was not, so read it against the plan
 rather than on its own. Nine agents at 1.0× on a plan with four independent
 tasks in it is a run that took four times longer than it needed to.
 
+An agent dispatched into the background is handed back before it runs, so the
+result the session sees carries no cost at all. The ledger reads that agent's
+own transcript instead, which is why a plan run entirely on dispatched agents
+still prices. Agent rows count output tokens, the same unit the run reports for
+itself, so they can be read against each other and against the run.
+
+Where that log has been cleaned up the row reads "cost not reported", the
+totals leave it out, and the agent line carries the count. That is a gap in
+what could be measured rather than a cheap run, and it needs a sentence from
+you: a smaller total must not be allowed to stand for the whole.
+
 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.
+Exit 2 means neither an announcement nor an invocation of this skill was found,
+so 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

package/skills/sluice/references/review.md

@@ -47,18 +47,23 @@ reviews, and it spends context the plan still needs.
 
 ## When you cannot dispatch
 
-A session may withhold subagents, or grant them only on request. The review is
-owed either way. `deep` has its own treatment in `references/deep-channel.md`,
-where there is a plan to shrink and a tier table to argue from; this is the
-`main` case, which has neither.
+Separate the two cases before you say anything. A session that grants subagents
+only on request has not withheld them: asking is the whole procedure, and a
+claim that you cannot dispatch is false there. A session that withholds them
+outright is the one this section is about. The review is owed either way.
+`deep` has its own treatment in `references/deep-channel.md`, where there is a
+plan to shrink and a tier table to argue from; this is the `main` case, which
+has neither.
 
 Say it twice, and only twice.
 
-The first time is the routing announcement, in the same breath as the channel:
-"Main channel, new interface. I cannot dispatch a reviewer in this session, so
-this merges unreviewed unless you want one." That is the moment it is still a
-decision. Your partner can authorise the dispatch, split the change, or accept
-the gap knowingly. The same words at the end are a disclaimer.
+The first time is the routing announcement, in the same breath as the channel.
+Withheld: "Main channel, new interface. I cannot dispatch a reviewer in this
+session, so this merges unreviewed unless you want one." On request: "Main
+channel, new interface. A reviewer is one dispatch away if you want one, and
+without it this merges unreviewed." Either way, that is the moment it is still
+a decision. Your partner can authorise the dispatch, split the change, or
+accept the gap knowingly. The same words at the end are a disclaimer.
 
 The second is the integration event, where `references/finish.md` puts the
 three options. Review status belongs beside them, because it is part of what

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

@@ -46,7 +46,32 @@ if [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ]; then
   exit 1
 fi
 
-SUMMARY="$(jq -s '
+# An agent handed back before it ran leaves no cost on its tool result, but it
+# keeps a transcript of its own beside the session. That file is the only place
+# a backgrounded agent's cost is ever written down, so read it rather than
+# reporting the work as free.
+SUBS="$(dirname "$TRANSCRIPT")/$(basename "$TRANSCRIPT" .jsonl)/subagents"
+COSTS='{}'
+if [ -d "$SUBS" ]; then
+  COSTS="$(
+    for f in "$SUBS"/agent-*.jsonl; do
+      [ -e "$f" ] || continue
+      id="$(basename "$f" .jsonl)"; id="${id#agent-}"
+      jq -s --arg id "$id" '
+        def ts: sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601;
+        [ .[] | select(.timestamp) ] as $t
+        | { ($id): {
+            tokens: ([ .[] | .message.usage.output_tokens // 0 ] | add // 0),
+            tools: ([ .[] | .message.content[]? | select(.type == "tool_use") ] | length),
+            model: ([ .[] | .message.model // empty ] | last // "?"),
+            starts: (if ($t | length) > 0 then ($t[0].timestamp | ts) else 0 end),
+            ends: (if ($t | length) > 0 then ($t[-1].timestamp | ts) else 0 end) } }' "$f"
+    done | jq -s 'add // {}'
+  )"
+fi
+[ -n "$COSTS" ] || COSTS='{}'
+
+SUMMARY="$(jq -s --argjson costs "$COSTS" '
   # ---- what counts as a real turn ----------------------------------------
   # Transcript stamps carry milliseconds, which fromdateiso8601 will not take.
   def ts: sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601;
@@ -56,9 +81,20 @@ SUMMARY="$(jq -s '
   # 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";
+  # Real announcements carry a lead-in the anchor above misses: "Sluice: **deep
+  # channel**", "Tier 2 (new contract surface) = **deep channel**". Emphasis is
+  # what still separates one from prose naming a channel, and holding it to the
+  # opening line keeps a session reviewing sluice from starting a run per quote.
+  def emph: "\\*\\*[[:space:]]*(?<c>fast|main|deep)[[:space:]]+channel";
+  def head_line: texts | split("\n") | (.[0] // "");
   def announces: (.type == "assistant") and (is_meta | not)
-    and (texts | test(marker; "i"));
-  def chan: texts | capture(marker; "i") | .c | ascii_downcase;
+    and ((texts | test(marker; "i")) or (head_line | test(emph; "i")));
+  def chan: (if (texts | test(marker; "i")) then (texts | capture(marker; "i"))
+             else (head_line | capture(emph; "i")) end) | .c | ascii_downcase;
+  def invokes_sluice: (.type == "assistant") and (is_meta | not) and ([
+      .message.content[]? | select(.type == "tool_use" and .name == "Skill")
+      | select((.input.skill // "") == "sluice")
+    ] | length > 0);
   def is_stats_call: (.type == "assistant") and ([
       .message.content[]? | select(.type == "tool_use" and .name == "Bash")
       | select((.input.command // "") | test("run-stats\\.sh"))
@@ -74,7 +110,11 @@ SUMMARY="$(jq -s '
 
   . as $all
   | [ range(0; $all | length) ] as $ix
-  | [ $ix[] | select($all[.] | announces) ] as $ann
+  | [ $ix[] | select($all[.] | announces) ] as $said
+  # A run whose announcement never matched is still a run when the skill was
+  # invoked by name. Anchoring there beats reporting the work as nothing.
+  | [ $ix[] | select($all[.] | invokes_sluice) ] as $called
+  | (if ($said | length) > 0 then $said else $called end) as $ann
   | if ($ann | length) == 0 then { empty: true } else
 
   # A previous ledger closes the run before it. The call running right now has
@@ -87,7 +127,7 @@ SUMMARY="$(jq -s '
   | [ $all[$from:][] | select(.timestamp) ] as $run
 
   # ---- channel, and the trail if it escalated ----------------------------
-  | ([ $ann[] | $all[.] | chan ]
+  | ([ $said[] | select(. >= $from) | $all[.] | chan ]
      | reduce .[] as $c ([]; if (. | last) == $c then . else . + [$c] end)) as $trail
 
   # ---- clocks ------------------------------------------------------------
@@ -114,20 +154,39 @@ SUMMARY="$(jq -s '
      | 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),
-          # The transcript timestamps when an agent returned, not when it began,
-          # so the start is back-derived from its own duration.
-          ends: (.timestamp | ts),
-          starts: ((.timestamp | ts) - ((.toolUseResult.totalDurationMs // 0) / 1000)),
-          tools: (.toolUseResult.totalToolUseCount // 0) } ] as $agents
+      | . as $e
+      # Inline cost when the agent ran to completion here, its own transcript
+      # when it was handed back before it ran, and neither only when the file
+      # has been cleaned up. Priced at zero it would understate the run and drag
+      # the concurrency factor to a number the ledger has no meaning for.
+      | ($costs[$e.toolUseResult.agentId] // null) as $c
+      # The log wins where there is one. The two sources count different things,
+      # the inline total being the harness accounting and the log being output
+      # tokens, and rows drawn from different bases cannot be read against each
+      # other. Output tokens is also the unit the run reports for itself.
+      | (if $c == null then $e.toolUseResult.totalDurationMs
+         else (($c.ends - $c.starts) * 1000) end) as $ms
+      | ($c.tokens // $e.toolUseResult.totalTokens) as $tokens
+      | { label: ($labels[[ $e.message.content[]? | select(.type == "tool_result") | .tool_use_id ][0]]
+                  // $e.toolUseResult.commandName // "agent"),
+          model: ($c.model // $e.toolUseResult.resolvedModel // "?"),
+          status: ($e.toolUseResult.status // "?"),
+          measured: (($ms != null) or ($tokens != null)),
+          tokens: ($tokens // 0),
+          ms: ($ms // 0),
+          # The session transcript timestamps when an agent returned, not when
+          # it began, so that start is back-derived from its own duration. An
+          # agent log of its own carries both ends directly.
+          ends: (if $c != null then $c.ends else ($e.timestamp | ts) end),
+          starts: (if $c != null then $c.starts
+                   else (($e.timestamp | ts) - (($ms // 0) / 1000)) end),
+          tools: ($c.tools // $e.toolUseResult.totalToolUseCount // 0) } ] as $agents
+
+  | [ $agents[] | select(.measured) ] as $priced
 
   # Union of the agent intervals: sum the merged runs rather than the raw ones,
   # so overlapping agents are counted once against the clock they shared.
-  | ([ $agents[] | { s: .starts, e: .ends } ] | sort_by(.s)
+  | ([ $priced[] | { s: .starts, e: .ends } ] | sort_by(.s)
      | reduce .[] as $i ([];
          if (length == 0) or (.[-1].e < $i.s)
          then . + [$i]
@@ -135,17 +194,18 @@ SUMMARY="$(jq -s '
      | map(.e - .s) | add // 0) as $agent_span
 
   | { empty: false,
-      trail: ($trail | join(" → ")),
+      trail: (if ($trail | length) == 0 then "not announced" else ($trail | join(" → ")) end),
       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),
+      unmeasured: (($agents | length) - ($priced | length)),
+      agent_tokens: ([ $priced[].tokens ] | add // 0),
+      agent_ms: ([ $priced[].ms ] | add // 0),
       concurrency: (if $agent_span > 0
-                    then (([ $agents[].ms ] | add // 0) / 1000) / $agent_span
+                    then (([ $priced[].ms ] | add // 0) / 1000) / $agent_span
                     else 0 end) }
   end
 ' "$TRANSCRIPT" 2>/dev/null)"
@@ -229,24 +289,38 @@ if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
 fi
 
 count=$(g '.agents | length')
+unmeasured=$(g '.unmeasured')
 if [ "$count" -eq 0 ]; then
   printf 'agents    none dispatched\n'
 else
-  # 1.0× means every agent had the clock to itself. On a plan whose graph had
-  # independent tasks in it, that number is the finding.
-  printf 'agents    %s dispatched · %s tok · %s wall · %s× concurrent\n' \
-    "$count" "$(tok "$(g '.agent_tokens')")" "$(dur "$(( $(g '.agent_ms') / 1000 ))")" \
-    "$(printf '%.1f' "$(g '.concurrency')")"
+  if [ "$count" -eq "$unmeasured" ]; then
+    # Every agent was handed back before it ran, so there is no cost to report
+    # and none to invent. Saying so beats a row of zeroes that reads as a total.
+    printf 'agents    %s dispatched · cost not reported\n' "$count"
+  else
+    # 1.0× means every agent had the clock to itself. On a plan whose graph had
+    # independent tasks in it, that number is the finding.
+    printf 'agents    %s dispatched · %s tok · %s wall · %s× concurrent' \
+      "$count" "$(tok "$(g '.agent_tokens')")" "$(dur "$(( $(g '.agent_ms') / 1000 ))")" \
+      "$(printf '%.1f' "$(g '.concurrency')")"
+    [ "$unmeasured" -gt 0 ] && printf ' · %s unmeasured' "$unmeasured"
+    printf '\n'
+  fi
 
   # 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
+  while IFS=$'\t' read -r label model status tokens ms tools measured; 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 [ "$measured" = "true" ]; then
+      printf '  %-22.22s %-10s %6s  %7s  %s tools%s\n' \
+        "$label" "$model" "$(tok "$tokens")" "$(dur "$((ms / 1000))")" "$tools" "$status"
+    else
+      printf '  %-22.22s %-10s %6s  %7s  %s%s\n' \
+        "$label" "$model" "-" "-" "cost not reported" "$status"
+    fi
+  done < <(g "$rows | [.label, .model, .status, .tokens, .ms, .tools, .measured] | @tsv")
 
   if [ "$count" -gt 12 ]; then
     printf '  +%s more · %s tok (dearest 10 shown)\n' \

package/skills/sluice/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "sluice",
-  "version": "0.2.1",
+  "version": "0.3.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 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",