@iceinvein/agent-skills 0.23.7 → 0.23.8

package/package.json

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

package/skills/index.json

@@ -295,7 +295,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 nine 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), lists every live deep run and routed fast or main session on the machine in one board.sh view (drawn once, watched, or as JSON), 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. Two Stop hooks hold a handback: one refuses a tree that moved since its last recorded check, the other refuses a changed existing test not proven to fail on the session's starting code (or recorded with a reason). Claude Code only; stands down where the superpowers pipeline governs the repo.",
     "type": "prompt",
-    "version": "0.26.1"
+    "version": "0.27.0"
   },
   {
     "name": "temporal-coupling-detector",

package/skills/sluice/SKILL.md

@@ -132,6 +132,14 @@ the design's shape turns on a fork only your partner can settle, ask that one
 question through `AskUserQuestion`, with your recommendation, before the design
 is written. `references/deep-channel.md` has the test for what counts.
 
+The design carries a `## Trace` section before it goes up for sign-off: the
+request's own example, quoted, walked through the data as it stands, with what
+each reused function requires and writes read from the code. Per-task reviews
+never run that example and the hunt runs it only once every task is built, so
+a design checked only against the shape of the code is wrong for a whole plan
+before anything catches it.
+`references/deep-channel.md` has what the section holds.
+
 Take the design stop through the harness's plan mode where there is one. Its
 gate is enforced rather than requested and it holds edits shut while it is open,
 so nothing gets built against a design nobody signed. It carries the first stop

package/skills/sluice/evals/README.md

@@ -1,6 +1,6 @@
 # sluice evals
 
-Twenty-one cases for `claude plugin eval`. Fourteen pin the routing decision: which
+Twenty-two cases for `claude plugin eval`. Fifteen pin the routing decision: which
 channel the run names, and whether the behaviour that channel owes actually
 happened. Seven pin what a deep run does after pre-flight, where the question is
 no longer which channel but whether the run keeps going.
@@ -12,6 +12,7 @@ no longer which channel but whether the run keeps going.
 | `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 |
 | `deep-plan-asks-the-fork` | The same plan with nothing saying where the counters can live | One question with a recommendation before any design; no spec yet |
+| `deep-plan-traces-the-example` | A ticket whose own example the obvious design fails: the lookup it says to reuse matches accepted slides, and the smoke deck has none | A `## Trace` section in the spec that walks the example through the smoke deck, a lookup designed around what it found, and no write under `src/` or `tests/` |
 | `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 |
 | `announcement-reaches-the-ledger` | A flag that a surface test turns into a new export | `status.sh route main` before any write under `src/` and before any fast or deep route |
@@ -36,7 +37,7 @@ Execution, where the run is already past both stops:
 
 ## Running
 
-Twenty cases scaffold a small Node repo and then change it, so they need the
+Twenty-one cases scaffold a small Node repo and then change it, so they need the
 scaffold flag and a tool grant. Pin the model, because the eval child does not
 inherit it, and pin the judge, because `--model` does not reach it and the
 `llm` graders otherwise run on Haiku. From the repo root:

package/skills/sluice/evals/deep-plan-traces-the-example/case.yaml

@@ -0,0 +1,4 @@
+schema_version: "1.1"
+name: deep-plan-traces-the-example
+context:
+  scaffold_script: fixture.sh

package/skills/sluice/evals/deep-plan-traces-the-example/fixture.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# A deck app where the ticket's own example fails the obvious design. The deck
+# store looks slides up by the title of their accepted version, and only the
+# canvas ever accepts one, so the smoke deck, built in chat, has no accepted
+# slides and the lookup the ticket says to reuse finds nothing. Nothing in the
+# code is wrong; the trap is in designing from which functions exist instead of
+# walking the example through the data. The README fixes where the design goes, so the graders can read it,
+# what an unaccepted slide is called, and what writes slide text, because
+# without them each is a fork the run rightly asks before writing any design.
+set -euo pipefail
+
+mkdir -p src/chat src/deck src/canvas data/decks tests docs/specs
+
+cat > package.json <<'JSON'
+{
+  "name": "decks",
+  "version": "0.9.0",
+  "type": "module",
+  "scripts": {
+    "test": "node --test \"tests/*.test.js\""
+  }
+}
+JSON
+
+cat > src/deck/store.js <<'JS'
+import { readFileSync, writeFileSync } from "node:fs";
+
+const path = (id) => new URL(`../../data/decks/${id}.json`, import.meta.url);
+
+export function loadDeck(id) {
+  return JSON.parse(readFileSync(path(id), "utf8"));
+}
+
+export function saveDeck(deck) {
+  writeFileSync(path(deck.id), JSON.stringify(deck, null, 2) + "\n");
+}
+
+// A slide's title is the title of the version the user accepted on the canvas.
+export function findSlideByTitle(deck, title) {
+  const wanted = title.trim().toLowerCase();
+  return deck.slides.find((slide) => {
+    const accepted = slide.versions[slide.accepted];
+    return accepted !== undefined && accepted.title.toLowerCase() === wanted;
+  });
+}
+JS
+
+cat > src/deck/redraft.js <<'JS'
+// Appends a new version; the canvas decides whether the user accepts it.
+export function redraftSlide(slide, draft) {
+  slide.versions.push({ title: draft.title, body: draft.body });
+  return slide.versions.length - 1;
+}
+JS
+
+cat > src/deck/draft.js <<'JS'
+// Slide text comes from the model; callers pass the completion so tests can stub it.
+export async function draftSlide(version, instruction, complete) {
+  const text = await complete(
+    `Rewrite this slide. ${instruction}\nTitle: ${version.title}\nBody: ${version.body}`,
+  );
+  const [title, ...body] = text.trim().split("\n");
+  return { title: title.replace(/^Title:\s*/, ""), body: body.join("\n").replace(/^Body:\s*/, "") };
+}
+JS
+
+cat > src/canvas/accept.js <<'JS'
+export function accept(slide, versionIndex) {
+  if (slide.versions[versionIndex] === undefined) {
+    throw new Error(`no version ${versionIndex} on slide ${slide.id}`);
+  }
+  slide.accepted = versionIndex;
+}
+JS
+
+cat > src/chat/build-deck.js <<'JS'
+export function buildDeck(id, outline) {
+  return {
+    id,
+    slides: outline.map((item, index) => ({
+      id: `s${index + 1}`,
+      accepted: null,
+      versions: [{ title: item.title, body: item.body }],
+    })),
+  };
+}
+JS
+
+cat > src/chat/router.js <<'JS'
+export function route(message) {
+  if (/^(prepare|build|make)\b.*\bslides?\b/i.test(message)) {
+    return { intent: "build-deck" };
+  }
+  return { intent: "chat" };
+}
+JS
+
+cat > data/decks/smoke.json <<'JSON'
+{
+  "id": "smoke",
+  "slides": [
+    {
+      "id": "s1",
+      "accepted": null,
+      "versions": [{ "title": "Why a pilot", "body": "Three sites asked for it." }]
+    },
+    {
+      "id": "s2",
+      "accepted": null,
+      "versions": [{ "title": "Pilot Stages", "body": "Recruit, run for six weeks, review." }]
+    },
+    {
+      "id": "s3",
+      "accepted": null,
+      "versions": [{ "title": "Next steps", "body": "Pick the sites by May." }]
+    }
+  ]
+}
+JSON
+
+cat > tests/store.test.js <<'JS'
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { findSlideByTitle } from "../src/deck/store.js";
+
+test("a slide is found by the title of its accepted version", () => {
+  const deck = { slides: [{ id: "s1", accepted: 0, versions: [{ title: "Pilot Stages" }] }] };
+  assert.equal(findSlideByTitle(deck, "pilot stages").id, "s1");
+});
+JS
+
+cat > README.md <<'MD'
+# decks
+
+Chat builds a deck (`src/chat/build-deck.js`), the canvas lets a user accept a
+slide version (`src/canvas/accept.js`), and the deck store reads and writes
+`data/decks/<id>.json`. Until a user accepts a version, a slide shows, and is
+called by, its latest one. Slide text, for a new deck or a redraft, comes from
+`draftSlide` in `src/deck/draft.js`. `data/decks/smoke.json` is the smoke deck QA runs
+tickets against. `npm test` runs the suite.
+
+## Designs
+
+A ticket's design goes in `docs/specs/<ticket>.md`, for example
+`docs/specs/DEK-12.md`, and its plan in `docs/plans/<ticket>.md`.
+MD
+touch docs/specs/.gitkeep
+
+git init --quiet
+git add -A
+git -c user.email=fixture@example.com -c user.name=fixture commit --quiet -m "decks 0.9.0"

package/skills/sluice/evals/deep-plan-traces-the-example/graders/announces-deep-channel.md

@@ -0,0 +1,12 @@
+---
+type: regex
+# The trace carries SKILL.md's own routing table, which names every channel, so
+# `contains` passes whenever the skill loads. Anchor on the two ways the agent
+# routes instead, the same ones run-stats.sh meters: a Bash call that invokes
+# `status.sh route deep` (a quoted mention, as in a grep, does not count), or the
+# words opening an assistant message or following a label such as "Sluice:".
+pattern: '"command":"(?:(?:[^"\\]|\\.)*?(?:[\s/]|\\[nt]))?status\.sh(?:\\"|'')?(?:\s|\\[nt])+route(?:\s|\\[nt])+deep(?:\s|\\[nt]|[;&|]|")|"text":"(?:[^.!?\n"]{0,100}[:=]\s*)?[\s*_#>\\]*deep channel'
+flags: i
+target: trace
+weight: 2
+---

package/skills/sluice/evals/deep-plan-traces-the-example/graders/design-written-to-docs.md

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

package/skills/sluice/evals/deep-plan-traces-the-example/graders/no-source-edit.md

@@ -0,0 +1,11 @@
+---
+type: tool_used
+# The run plans and stops for sign-off, so no Edit may land under src/ or
+# tests/. Bash is left out of the case's tools, so these two are the only ways
+# code could change.
+tool: Edit
+input_match: '"file_path"\s*:\s*"(?:[^"]*/)?(?:src|tests)/'
+min: 0
+max: 0
+weight: 2
+---

package/skills/sluice/evals/deep-plan-traces-the-example/graders/no-source-write.md

@@ -0,0 +1,11 @@
+---
+type: tool_used
+# The run plans and stops for sign-off, so no Write may land under src/ or
+# tests/. Bash is left out of the case's tools, so these two are the only ways
+# code could change.
+tool: Write
+input_match: '"file_path"\s*:\s*"(?:[^"]*/)?(?:src|tests)/'
+min: 0
+max: 0
+weight: 2
+---

package/skills/sluice/evals/deep-plan-traces-the-example/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-traces-the-example/graders/spec-has-a-trace.md

@@ -0,0 +1,7 @@
+---
+type: regex
+pattern: '^#{2,3}\s*Trace\b'
+flags: m
+target: { source: file, path: docs/specs/DEK-41.md }
+weight: 2
+---

package/skills/sluice/evals/deep-plan-traces-the-example/graders/stopped-for-signoff.md

@@ -0,0 +1,8 @@
+---
+type: llm
+---
+
+The agent was asked to plan a ticket that spans the chat router, the deck store and the redraft path.
+
+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-traces-the-example/graders/trace-finds-no-accepted-slide.md

@@ -0,0 +1,27 @@
+---
+type: llm
+focus: { source: file, path: docs/specs/DEK-41.md }
+weight: 3
+---
+
+This is the design for a ticket whose example is "Redraft the Pilot Stages
+slide to lead with the pilot outcome" on the smoke deck. In the repo,
+`findSlideByTitle` matches only on the title of a slide's accepted version,
+only the canvas ever sets `accepted`, and every slide in
+`data/decks/smoke.json` has `"accepted": null`. So the lookup the ticket says
+to reuse finds no slide for the ticket's own example.
+
+Judge the section under the design's Trace heading for the walk, and the rest
+of the design only for the lookup it settles on.
+
+PASS if the Trace section quotes the ticket's example, walks it through the
+smoke deck's actual data, and records there that its slides have no accepted
+version (so the existing lookup returns nothing), and the design builds the
+slide lookup around that, consistent with the
+README (an unaccepted slide is called by its latest version): for example,
+matching the accepted version's title when there is one and the latest
+version's otherwise.
+FAIL if there is no Trace section, if the accepted-slide finding appears only
+outside it, if the design reuses `findSlideByTitle` or the accepted version as
+it stands, or if the accepted state is mentioned only as a general risk
+without saying what the smoke deck holds.

package/skills/sluice/evals/deep-plan-traces-the-example/prompt.md

@@ -0,0 +1,17 @@
+---
+name: deep-plan-traces-the-example
+description: A deep plan whose ticket example contradicts the obvious design. Pins a Trace section in the spec that walks the example through the fixture's real data before sign-off.
+tags: [routing, deep, write]
+max_turns: 25
+timeout_seconds: 900
+allowed_tools: [Read, Glob, Grep, Skill, Write]
+expected_outcome: Announces the deep channel, writes docs/specs/DEK-41.md with a Trace section that runs the ticket's sentence against the smoke deck, finds its slides have no accepted version, designs around that, and stops for sign-off without code.
+---
+
+Plan DEK-41 for us.
+
+> Let people revise a single slide from chat. Example, on the smoke deck:
+> "Redraft the Pilot Stages slide to lead with the pilot outcome" should redraft
+> that slide and leave the rest alone. The chat router needs a revise intent;
+> finding the slide and saving the redraft should reuse what the deck store and
+> the redraft path already do.

package/skills/sluice/evals/rules.json

@@ -31,7 +31,8 @@
       "origin": "docs/specs/2026-08-07-sluice-design.md",
       "cases": [
         "deep-plan-across-subsystems",
-        "deep-plan-asks-the-fork"
+        "deep-plan-asks-the-fork",
+        "deep-plan-traces-the-example"
       ]
     },
     {
@@ -63,7 +64,8 @@
       "origin": "docs/specs/2026-08-07-sluice-design.md",
       "cases": [
         "deep-plan-across-subsystems",
-        "deep-plan-asks-the-fork"
+        "deep-plan-asks-the-fork",
+        "deep-plan-traces-the-example"
       ]
     },
     {
@@ -74,6 +76,14 @@
         "deep-plan-asks-the-fork"
       ]
     },
+    {
+      "id": "deep-design-traces-the-example",
+      "states": "SKILL.md: Deep channel",
+      "origin": "commit:7decf60",
+      "cases": [
+        "deep-plan-traces-the-example"
+      ]
+    },
     {
       "id": "deep-stops-for-plan-and-pre-flight",
       "states": "SKILL.md: Deep channel",

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

@@ -183,6 +183,44 @@ on it, and let the next instruction start the plan. Nothing else about this
 section changes, because the obligation was never the mode's, only the
 enforcement was.
 
+## The trace
+
+A design written from the shape of the code (which functions exist, which slots
+they fill) can be sound on paper and still fail the request's own example,
+and nothing after it notices: per-task reviews read each task against its own
+text, and the hunt runs once every task is done. So walk the request through
+the system as it stands before you draft, and give the design a `## Trace`
+section that records the walk (in the plan file under plan mode, carried into
+the spec on approval):
+
+1. **The example, verbatim.** Quote the sentence, command or scenario the
+   request gives. Where it gives none, write the acceptance criterion as one
+   concrete case and say that you did.
+2. **Through the real data.** Follow that case step by step through the rows,
+   files or fixtures it would touch, as they exist now rather than as the
+   design assumes them: read the record, run the query, open the fixture, and
+   cite what each step read. "A deck built in chat has no accepted slides" is
+   a fact one read away, and a design keyed on accepted slides is wrong without
+   it.
+3. **What each reused path requires and writes.** For every function the
+   design reuses, its preconditions and its side effects, read from the code
+   and not from its name. Run the example a second time where the request
+   implies a repeat (a redraft of a redraft, an edit after an edit), because
+   what the first pass wrote is what the second pass reads.
+4. **What the walk ruled out.** Each place it contradicted the obvious design
+   (the reuse the request suggests, the first shape that came to mind), and
+   what the design does instead. An empty list is a result, not a skipped
+   step.
+
+Walking first is also what puts a fork where **The design stop and plan mode**
+wants it: one the walk turns up only your partner can settle is asked before
+the design is written, and the trace goes into the design with the answer.
+
+The trace is what the sign-off is signing: a design without the section is
+incomplete, however good the rest reads. It is not a prototype and not a hunt;
+anything that only shows at runtime (routing, timing, a renderer) stays with
+the hunt after the flip.
+
 ## Pre-flight
 
 Design signed off, plan written, nothing built yet. Before Task 1, stop once

package/skills/sluice/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "sluice",
-  "version": "0.26.1",
+  "version": "0.27.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 nine 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), lists every live deep run and routed fast or main session on the machine in one board.sh view (drawn once, watched, or as JSON), 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. Two Stop hooks hold a handback: one refuses a tree that moved since its last recorded check, the other refuses a changed existing test not proven to fail on the session's starting code (or recorded with a reason). Claude Code only; stands down where the superpowers pipeline governs the repo.",
   "author": "iceinvein",
   "type": "prompt",