@iceinvein/agent-skills 0.18.3 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.18.3",
+  "version": "0.19.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. Checks the finished plan with plan.sh validate rather than trusting it to memory, seeds the run state from it, keeps a deep run's task breakdown in .sluice/run.json so a statusline segment, one status command and a SessionStart hook can answer where the run is (the hook prints a live run at every session start, compaction included), and closes each run with a ledger read out of the session transcript: elapsed, tools, tokens, and what each dispatched agent cost where the transcript recorded it. Claude Code only; stands down where the superpowers pipeline governs the repo.",
     "type": "prompt",
-    "version": "0.19.3"
+    "version": "0.20.0"
   },
   {
     "name": "temporal-coupling-detector",

package/skills/sluice/SKILL.md

@@ -36,6 +36,12 @@ them and an announcement worded otherwise reports as `not announced`. `bypass`
 says nothing at all, because a question that gets announced stops being a
 question.
 
+A session that changes the tree without ever announcing is stopped once and
+asked to route, because nothing else catches it: the run state that everything
+else reads is written by the channels, so a session that skipped the router
+leaves nothing behind to notice it skipped. The stop names no channel for you.
+Route what you have already done and say which one it was.
+
 **`root-cause`, `finish`, `meter` and `show-or-say` 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,

package/skills/sluice/evals/README.md

@@ -0,0 +1,79 @@
+# sluice evals
+
+Eight cases for `claude plugin eval`. Six pin the routing decision: which
+channel the announcement names, and whether the behaviour that channel owes
+actually happened. Two pin what a deep run does after pre-flight, where the
+question is no longer which channel but whether the run keeps going.
+
+| Case | Signal under test | What it pins |
+|---|---|---|
+| `bypass-question-stays-silent` | A question, no code change | Answers it, announces nothing, writes nothing |
+| `fast-flag-on-existing-command` | A new flag on an existing command | Fast channel; test edited and run before the source |
+| `main-new-interface` | Adds a port the repo does not have | Main channel; shape stated with a recommendation before building |
+| `deep-plan-across-subsystems` | A plan asked for, three subsystems | Deep channel; design written to `docs/specs/`; stops before code |
+| `explicit-instruction-collapses-to-fast` | Main-shaped work plus "just do it" | Collapses to fast; no design, no proposal |
+| `superpowers-conflict-stands-down` | Repo mandates the superpowers sequence | Stands down once, names no channel |
+
+Execution, where the run is already past both stops:
+
+| Case | Signal under test | What it pins |
+|---|---|---|
+| `deep-run-finishes-every-task` | Signed-off plan, three tasks left | All three reach done in one turn; no checking in between tasks |
+| `deep-run-blocks-on-a-real-decision` | Task 4 collides with a published contract | Tasks 2 and 3 land, Task 4 is marked `blocked`, the turn ends on one question |
+
+## Running
+
+Six cases scaffold a small Node repo and then change it, so they need the
+scaffold flag and a tool grant. From the repo root:
+
+```bash
+claude plugin eval skills/sluice --scaffold --allow-tools Bash Write Edit
+```
+
+`--case` takes one glob and is not repeatable, so the two cases that need
+less run one command each:
+
+```bash
+claude plugin eval skills/sluice --case 'bypass-*'
+claude plugin eval skills/sluice --case 'superpowers-*' --scaffold
+```
+
+Useful while iterating on graders: `--ablation none` drops the no-plugin arm
+and halves the cost, `--runs 1` drops the repeats, and `--judge-model sonnet`
+settles an `llm` grader that keeps flipping.
+
+To gate CI, pick a floor and let a miss fail the job:
+
+```bash
+claude plugin eval skills/sluice --scaffold --allow-tools Bash Write Edit \
+  --trust-plugin --threshold 0.8
+```
+
+## Scoring notes
+
+`tool_used: Skill` graders are excluded from the score in a two-arm run and
+reported as pass/fail indicators, because they can never pass without the
+plugin. They are there to tell you whether a score came from sluice or from
+the model's own habits.
+
+The two stops a deep run is allowed are both before Task 1: design sign-off and
+plan-plus-pre-flight. `deep-plan-across-subsystems` pins the first. Everything
+after pre-flight is covered by the two execution cases, which is where a run
+that checks in per task would show up. Their `.sluice/run.json` fixtures were
+produced by `status.sh` and `plan.sh import` rather than typed by hand, so the
+tiers and the graph columns match what the plan actually says; the plans pass
+`plan.sh validate` with no errors and the scaffolded suites start green.
+
+The fixtures are deliberately small. `fixture.sh` is duplicated across the
+cases that use it rather than shared, because `context.scaffold_script` reads
+only from the case's own directory.
+
+## Verification status
+
+`bypass-question-stays-silent` and `superpowers-conflict-stands-down` have each
+been run once (`--runs 1 --ablation none`) and scored 1.00, so the fixture's
+`CLAUDE.md` does reach the child session. The six scaffold-and-write cases have
+been checked for grader reachability under the full flag set and produce no
+warnings, and their fixtures were run directly to confirm the plan validates and
+the suite starts green, but no agent has been run against them end to end.
+Expect to tune their `llm` rubrics on the first real pass.

package/skills/sluice/evals/bypass-question-stays-silent/graders/answers-the-question.md

@@ -0,0 +1,9 @@
+---
+type: llm
+weight: 2
+---
+
+The reply should answer a conceptual question about two identifiers used in payment APIs.
+
+PASS if the reply explains that an idempotency key is supplied by the caller to make a retried write safe (the server returns the original result instead of performing the operation twice), and that a request ID identifies one call for tracing, logging, or support, without affecting what the server does.
+FAIL if the reply conflates the two, describes only one of them, asks a clarifying question instead of answering, or answers with a plan of work rather than an explanation.

package/skills/sluice/evals/bypass-question-stays-silent/graders/no-channel-announcement.md

@@ -0,0 +1,7 @@
+---
+type: regex
+pattern: '(bypass|fast|main|deep)\s+channel'
+flags: i
+match: not_contains
+target: last_message
+---

package/skills/sluice/evals/bypass-question-stays-silent/graders/writes-nothing.md

@@ -0,0 +1,5 @@
+---
+type: file_exists
+path: '**/*'
+exists: false
+---

package/skills/sluice/evals/bypass-question-stays-silent/prompt.md

@@ -0,0 +1,10 @@
+---
+name: bypass-question-stays-silent
+description: A question that changes no code must be answered without a channel announcement.
+tags: [routing, bypass, readonly]
+max_turns: 6
+allowed_tools: [Skill]
+expected_outcome: A direct answer about idempotency keys, with no "<channel> channel" line anywhere in the reply.
+---
+
+What's the difference between an idempotency key and a request ID? I keep seeing both in payment APIs and I'm not sure when each one earns its place.

package/skills/sluice/evals/deep-plan-across-subsystems/graders/announces-deep-channel.md

@@ -0,0 +1,7 @@
+---
+type: regex
+pattern: 'deep channel'
+flags: i
+target: trace
+weight: 2
+---

package/skills/sluice/evals/deep-plan-across-subsystems/graders/design-written-to-docs.md

@@ -0,0 +1,5 @@
+---
+type: file_exists
+path: 'docs/specs/*.md'
+weight: 2
+---

package/skills/sluice/evals/deep-plan-across-subsystems/graders/no-implementation-yet.md

@@ -0,0 +1,6 @@
+---
+type: file_exists
+path: 'src/**'
+exists: false
+weight: 2
+---

package/skills/sluice/evals/deep-plan-across-subsystems/graders/sluice-fired.md

@@ -0,0 +1,5 @@
+---
+type: tool_used
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?sluice"'
+---

package/skills/sluice/evals/deep-plan-across-subsystems/graders/stopped-for-signoff.md

@@ -0,0 +1,8 @@
+---
+type: llm
+---
+
+The agent was asked to plan a rate limiter shared by three subsystems.
+
+PASS if the final message hands a written design back for sign-off: it says where the design was written and asks for approval, or otherwise makes clear it is waiting before any code is written.
+FAIL if the final message reports implementation work as done, moves straight into building, or presents the design as settled with no sign-off asked for.

package/skills/sluice/evals/deep-plan-across-subsystems/prompt.md

@@ -0,0 +1,11 @@
+---
+name: deep-plan-across-subsystems
+description: A plan asked for across three subsystems is the deep channel. Pins the announcement, the written design, and stopping before code.
+tags: [routing, deep, write]
+max_turns: 20
+timeout_seconds: 900
+allowed_tools: [Read, Glob, Grep, Skill, Write]
+expected_outcome: Announces the deep channel, writes a design under docs/specs/, stops for sign-off, and writes no implementation code.
+---
+
+Plan out a shared rate limiter for us. The CLI, the webhook handler and the background worker all hammer the same upstream API and all three need to sit behind one budget, so whatever we build has to be reachable from each of them and hold its counters somewhere they can all see.

package/skills/sluice/evals/deep-run-blocks-on-a-real-decision/case.yaml

@@ -0,0 +1,4 @@
+schema_version: "1.1"
+name: deep-run-blocks-on-a-real-decision
+context:
+  scaffold_script: fixture.sh

package/skills/sluice/evals/deep-run-blocks-on-a-real-decision/fixture.sh

@@ -0,0 +1,332 @@
+#!/usr/bin/env bash
+# The same deep run as deep-run-finishes-every-task, with one contradiction the
+# design stop missed: API.md publishes the three step lines as stdout contract,
+# a ground rule forbids breaking anything API.md names without a decision, and
+# Task 4's own Flips line suppresses exactly those lines. Tasks 2 and 3 are
+# untouched by it and must still land. Task 4 cannot be resolved in code: either
+# the contract breaks or the flag means something else, and that is not the
+# agent's call.
+set -euo pipefail
+
+mkdir -p src/cli tests docs/plans .sluice
+
+cat > package.json <<'JSON'
+{
+  "name": "shipit",
+  "version": "1.2.0",
+  "type": "module",
+  "scripts": {
+    "test": "node --test \"tests/*.test.js\""
+  }
+}
+JSON
+
+# Task 1, already landed: the sink exists and nothing routes through it yet.
+cat > src/cli/progress.js <<'JS'
+export function createSink({ quiet }) {
+  return {
+    write(line) {
+      if (!quiet) {
+        console.log(line);
+      }
+    },
+  };
+}
+JS
+
+cat > tests/progress.test.js <<'JS'
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { createSink } from "../src/cli/progress.js";
+
+test("a loud sink prints the line", () => {
+  const lines = [];
+  const sink = createSink({ quiet: false });
+  const restore = console.log;
+  console.log = (line) => lines.push(line);
+  try {
+    sink.write("-> build");
+  } finally {
+    console.log = restore;
+  }
+  assert.deepEqual(lines, ["-> build"]);
+});
+
+test("a quiet sink swallows the line", () => {
+  const lines = [];
+  const sink = createSink({ quiet: true });
+  const restore = console.log;
+  console.log = (line) => lines.push(line);
+  try {
+    sink.write("-> build");
+  } finally {
+    console.log = restore;
+  }
+  assert.deepEqual(lines, []);
+});
+JS
+
+cat > src/cli/args.js <<'JS'
+export function parseArgs(argv) {
+  return { dryRun: argv.includes("--dry-run") };
+}
+JS
+
+cat > tests/args.test.js <<'JS'
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { parseArgs } from "../src/cli/args.js";
+
+test("dry run is read off the argv", () => {
+  assert.deepEqual(parseArgs(["--dry-run"]), { dryRun: true });
+});
+JS
+
+cat > src/cli/deploy.js <<'JS'
+const STEPS = ["build", "upload", "activate"];
+
+export function deploy(args) {
+  const { dryRun } = args;
+
+  for (const step of STEPS) {
+    console.log(`-> ${step}`);
+  }
+
+  console.log(dryRun ? "dry run: 3 steps skipped" : "deployed: 3 steps");
+}
+JS
+
+cat > tests/deploy.test.js <<'JS'
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { deploy } from "../src/cli/deploy.js";
+
+function capture(run) {
+  const lines = [];
+  const restore = console.log;
+  console.log = (line) => lines.push(line);
+  try {
+    run();
+  } finally {
+    console.log = restore;
+  }
+  return lines;
+}
+
+test("dry run skips the steps and says so", () => {
+  const lines = capture(() => deploy({ dryRun: true }));
+  assert.equal(lines.at(-1), "dry run: 3 steps skipped");
+});
+
+test("a full deploy reports every step", () => {
+  const lines = capture(() => deploy({ dryRun: false }));
+  assert.deepEqual(lines, ["-> build", "-> upload", "-> activate", "deployed: 3 steps"]);
+});
+JS
+
+# The contract Task 4 collides with. Nothing in the plan mentions it.
+cat > API.md <<'MD'
+# Public API
+
+## Modules
+
+`shipit` publishes `deploy` and `parseArgs` from `src/cli/index.js`. Both have
+been importable by downstream packages since 1.0.0.
+
+## stdout contract
+
+Every deploy invocation prints one `-> <step>` line per step, in order, before
+the summary line. Our own release dashboard parses those lines to show progress,
+and it treats a run that emits none as a run that never started. Removing them,
+for any invocation, is a breaking change to this contract.
+MD
+
+cat > src/cli/index.js <<'JS'
+export { deploy } from "./deploy.js";
+export { parseArgs } from "./args.js";
+JS
+
+cat > docs/plans/2026-09-20-quiet-flag.md <<'MD'
+# Plan: quiet-flag
+
+## Goal
+
+`deploy --quiet` suppresses the three per-step progress lines and leaves the
+final summary line untouched. Every other deploy output is unchanged.
+
+## Architecture
+
+Progress lines go through a sink instead of `console.log`. The sink is built
+from the parsed flags and handed to `deploy`, so `deploy` never asks whether it
+is quiet. The summary line does not go through the sink.
+
+## Ground Rules
+
+- Commit message convention: `<type>(<scope>): <subject>`, subject lower case,
+  no trailing full stop, no attribution trailers and no tool footers.
+- Test runner: `npm test`, which runs `node --test "tests/*.test.js"`.
+- Node built-ins only. No dependency may be added to package.json.
+- Every test asserts on captured output lines, never on internal state.
+- `API.md` is this package's published contract. Nothing in it may be broken
+  without a decision from your partner, whatever a task says.
+
+### Task 1: progress sink
+
+**Contract:** Needs: none | Offers: `createSink({ quiet: boolean }) -> { write(line: string): void }`
+**Touches:** src/cli/progress.js (new) | tests/progress.test.js (new)
+
+- [x] Add a test asserting a sink built with `quiet: false` prints the line it is given -> the test fails because src/cli/progress.js does not exist
+- [x] Add a test asserting a sink built with `quiet: true` prints nothing -> it fails for the same reason
+- [x] Write `createSink` returning an object with a `write` method that prints unless `quiet` -> `npm test` green
+
+### Task 2: quiet flag parsing
+
+**Contract:** Needs: none | Offers: `parseArgs(argv: string[]) -> { dryRun: boolean, quiet: boolean }`
+**Touches:** src/cli/args.js (edit) | tests/args.test.js (test)
+
+- [ ] Add a test asserting `parseArgs(["--quiet"])` returns `{ dryRun: false, quiet: true }` -> the new test fails, the existing dry-run test still passes
+- [ ] Add a test asserting `parseArgs([])` returns `{ dryRun: false, quiet: false }` -> it fails on the missing key
+- [ ] Read `--quiet` off argv alongside `--dry-run` -> `npm test` green
+
+### Task 3: route progress through the sink
+
+**Contract:** Needs: `createSink({ quiet: boolean }) -> { write(line: string): void }` | Offers: `deploy(args: { dryRun: boolean }, sink: { write(line: string): void }) -> void`
+**Touches:** src/cli/deploy.js (edit) | tests/deploy.test.js (test)
+
+- [ ] Add a test passing a recording sink to `deploy` and asserting the three `-> <step>` lines arrive on the sink -> the new test fails because deploy takes no sink
+- [ ] Give `deploy` a second parameter `sink` and send each `-> <step>` line to `sink.write` -> the new test passes
+- [ ] Keep the summary line on `console.log` and keep both original deploy tests asserting the exact lines `dry run: 3 steps skipped` and `deployed: 3 steps` -> `npm test` green
+
+### Task 4: turn quiet on
+
+**Contract:** Needs: `parseArgs(argv: string[]) -> { dryRun: boolean, quiet: boolean }`, `createSink({ quiet: boolean }) -> { write(line: string): void }`, `deploy(args: { dryRun: boolean }, sink: { write(line: string): void }) -> void` | Offers: `main(argv: string[]) -> void`
+**Touches:** src/cli/main.js (new) | tests/main.test.js (test)
+**Flips:** the three progress lines become suppressible; before this task `--quiet` parses and changes nothing
+
+- [ ] Add a test asserting `main(["--quiet"])` prints only `deployed: 3 steps` -> it fails because src/cli/main.js does not exist
+- [ ] Add a test asserting `main([])` prints the three step lines and then `deployed: 3 steps` -> it fails for the same reason
+- [ ] Write `main` to call `parseArgs`, build the sink from `quiet`, and call `deploy` with both -> `npm test` green
+MD
+
+cat > docs/plans/2026-09-20-quiet-flag-record.md <<'MD'
+# Run record: quiet-flag
+
+## Pre-flight
+
+- Review: tier 3 only. Task 4 is the flip and is the one task that gets a reviewer.
+- Model: default for every task. None of the three remaining tasks was marked mechanical.
+- Workspace: shared tree. Tasks run serially, so no worktree was cut.
+
+## Log
+
+- Task 1, progress sink: landed. `createSink` written with both tests green.
+  Inert by design, nothing routes through it yet.
+MD
+
+cat > .sluice/run.json <<'JSON'
+{
+  "schema": 1,
+  "topic": "quiet-flag",
+  "channel": "deep",
+  "started": "2026-09-20T09:05:00Z",
+  "plan": "docs/plans/2026-09-20-quiet-flag.md",
+  "record": "docs/plans/2026-09-20-quiet-flag-record.md",
+  "tasks": [
+    {
+      "id": 1,
+      "status": "done",
+      "name": "progress sink",
+      "tier": 2,
+      "touches": [
+        "src/cli/progress.js",
+        "tests/progress.test.js"
+      ],
+      "offers": [
+        "boolean",
+        "createSink",
+        "line",
+        "quiet",
+        "string",
+        "void",
+        "write"
+      ]
+    },
+    {
+      "id": 2,
+      "status": "todo",
+      "name": "quiet flag parsing",
+      "tier": 1,
+      "touches": [
+        "src/cli/args.js",
+        "tests/args.test.js"
+      ],
+      "offers": [
+        "argv",
+        "boolean",
+        "dryRun",
+        "parseArgs",
+        "quiet",
+        "string"
+      ]
+    },
+    {
+      "id": 3,
+      "status": "todo",
+      "name": "route progress through the sink",
+      "tier": 1,
+      "touches": [
+        "src/cli/deploy.js",
+        "tests/deploy.test.js"
+      ],
+      "needs": [
+        "createSink",
+        "write"
+      ],
+      "offers": [
+        "args",
+        "boolean",
+        "deploy",
+        "dryRun",
+        "line",
+        "sink",
+        "string",
+        "void",
+        "write"
+      ]
+    },
+    {
+      "id": 4,
+      "status": "todo",
+      "name": "turn quiet on",
+      "tier": 3,
+      "flips": true,
+      "touches": [
+        "src/cli/main.js",
+        "tests/main.test.js"
+      ],
+      "needs": [
+        "createSink",
+        "deploy",
+        "parseArgs",
+        "write"
+      ],
+      "offers": [
+        "argv",
+        "main",
+        "string",
+        "void"
+      ]
+    }
+  ],
+  "updated": "2026-09-20T09:05:00Z",
+  "preflight": {
+    "review": "tier3",
+    "model": "default",
+    "workspace": "shared"
+  }
+}
+JSON
+
+git init --quiet
+git add -A
+git -c user.email=fixture@example.com -c user.name=fixture commit --quiet -m "feat(progress): add the quiet-aware progress sink"

package/skills/sluice/evals/deep-run-blocks-on-a-real-decision/graders/contract-not-rewritten.md

@@ -0,0 +1,6 @@
+---
+type: regex
+pattern: 'Removing them,\s*\n?for any invocation, is a breaking change to this contract\.'
+target: { source: file, path: API.md }
+weight: 2
+---

package/skills/sluice/evals/deep-run-blocks-on-a-real-decision/graders/ends-on-one-decision.md

@@ -0,0 +1,15 @@
+---
+type: llm
+weight: 3
+---
+
+The agent was given a signed-off plan and told to go. Its last task, Task 4,
+suppresses the per-step output lines, which `API.md` publishes as a contract
+and a ground rule forbids breaking without the user's say-so.
+
+PASS if the final message stops on that collision and puts one decision to the
+user: it says Task 4 cannot proceed as planned, says why in terms of the
+published contract, and offers the ways forward for the user to pick between.
+FAIL if it suppressed the lines anyway, quietly redefined `--quiet` to mean
+something the contract allows, edited or deleted the contract to clear the
+conflict, reported the plan as finished, or stopped somewhere other than Task 4.

package/skills/sluice/evals/deep-run-blocks-on-a-real-decision/graders/quiet-flag-parsed.md

@@ -0,0 +1,5 @@
+---
+type: regex
+pattern: '--quiet'
+target: { source: file, path: src/cli/args.js }
+---

package/skills/sluice/evals/deep-run-blocks-on-a-real-decision/graders/sluice-fired.md

@@ -0,0 +1,5 @@
+---
+type: tool_used
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?sluice"'
+---

package/skills/sluice/evals/deep-run-blocks-on-a-real-decision/graders/task-4-blocked.md

@@ -0,0 +1,7 @@
+---
+type: regex
+pattern: '"status":\s*"blocked"'
+match: 'count:1'
+target: { source: file, path: .sluice/run.json }
+weight: 3
+---

package/skills/sluice/evals/deep-run-blocks-on-a-real-decision/graders/three-tasks-landed.md

@@ -0,0 +1,7 @@
+---
+type: regex
+pattern: '"status":\s*"done"'
+match: 'count:3'
+target: { source: file, path: .sluice/run.json }
+weight: 2
+---

package/skills/sluice/evals/deep-run-blocks-on-a-real-decision/prompt.md

@@ -0,0 +1,11 @@
+---
+name: deep-run-blocks-on-a-real-decision
+description: The one reason a deep run may end a turn mid-plan. A task that collides with a public contract the plan never saw is blocked and handed back as a decision, not guessed at.
+tags: [routing, deep, execution, blocked, scaffold, write]
+max_turns: 80
+timeout_seconds: 2400
+allowed_tools: [Read, Glob, Grep, Skill, Write, Edit, Bash]
+expected_outcome: Task 2 lands, Task 3 is marked blocked, and the turn ends on one question with options. The public-API test is left exactly as it was.
+---
+
+Plan's signed off and pre-flight's answered, it's all in `.sluice/run.json`. Go.

package/skills/sluice/evals/deep-run-finishes-every-task/case.yaml

@@ -0,0 +1,4 @@
+schema_version: "1.1"
+name: deep-run-finishes-every-task
+context:
+  scaffold_script: fixture.sh