@iceinvein/agent-skills 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.4.0",
+  "version": "0.5.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.1.1"
+    "version": "0.2.0"
   },
   {
     "name": "temporal-coupling-detector",

package/skills/sluice/SKILL.md

@@ -21,8 +21,9 @@ 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, and again for the plan when
-agents rather than you will carry it out.
+`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.
 
 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
@@ -81,11 +82,27 @@ 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. 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.
+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
+actionable while the plan can still change.
+
+Read the plan as a graph rather than a list. `Needs` and `Offers` are
+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,
+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
+cannot dispatch has to replace the review tier with something, not quietly
+ship without one.
 
 ## Conflicts
 

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

@@ -4,15 +4,28 @@
 
 - A plan opens with **Goal**, **Architecture** and **Ground Rules**. The ground
   rules are the limits the whole plan answers to, each recorded at its literal
-  value, and each one binds every task without being repeated in it.
+  value, and each one binds every task without being repeated in it. The commit
+  message convention is one of them, written out at literal value along with
+  anything the repo forbids a message from carrying. An implementer arrives
+  with its own defaults and will use them on anything you left unsaid.
 - No implementer sees a neighbouring task, so each task carries a
   **Contract**, not optional: a symbol absent from it does not exist for
   whoever builds the task. `Needs` names what this task calls but another
   task defines; `Offers` names what later tasks will call. Both sides are
-  spelled out whole, argument lists and return shapes.
+  spelled out whole, argument lists and return shapes. They are also the
+  plan's dependency edges, which is what dispatch order gets derived from.
 - A **Touches** line lists the exact paths the task creates, edits and tests.
+  Complete, not indicative: it decides which tasks may run at the same time,
+  so a path left off it has stopped being an untidy diff stat and become a
+  corrupted concurrent run.
 - A **Review** field may name why the task needs the stronger tier (auth,
   data, money, concurrency); the table below decides otherwise.
+- **Order the plan so the inert tasks come first.** A task is inert when it
+  adds capability, config, a schema or a code path that nothing reads yet:
+  landing it changes no observable behaviour, so it is safe to land alone and
+  safe to leave landed. Exactly one task turns the new behaviour on, and it
+  carries a **Flips** line saying what changes and what it changes from.
+  Tasks after it build on the new behaviour and are no longer inert.
 - Steps are checkboxes: an action, and the proof it worked. Skip the
   test-first ritual per step; `references/test-first.md` owns it.
 - Code goes in only where exact characters matter and paraphrase breaks
@@ -30,32 +43,121 @@
 ### Task N: <name>
 **Contract:** Needs: <sig> | Offers: <sig>
 **Touches:** <path> (new) | <path> (edit) | <path> (test)
+**Flips:** <what changes, from what, or omit>
 **Review:** <reason, or omit>
 - [ ] <action> -> <proof>
 ```
 
+One `Flips` line pays for itself at the far end of the plan. When a late task
+re-baselines something, regenerated fixtures, re-blessed snapshots, a golden
+file that now reads differently, the flip is what the new baseline is
+attributable to, a single point rather than a diffuse property of the branch.
+Without it, whoever reads the branch later has to derive that ordering from
+the diff, and they will derive it wrong.
+
+Two tasks carrying `Flips` means the plan holds two branches' worth of work.
+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.
+
+**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
+line. Then offer the choice: dispatch a reviewer at each of them, dispatch
+only at the stronger-model tier, or hand back with those tasks listed as
+review outstanding. The options are what makes the cost legible.
+"Four of nine need a reviewer" is a decision your partner can price; "I will
+review where appropriate" is not.
+
+**Workspace, commits and concurrency.** One worktree for the plan, one per
+concurrent implementer, or straight onto the current branch; and with it who
+commits, each agent committing its own task as it finishes or agents leaving
+the tree dirty for you to read and commit yourself. One question rather than
+three, because isolation is what gates the other two: a shared tree means
+serial implementers, and the current branch means serial and your commits.
+Say how many tasks the graph says could actually overlap, because a worktree
+per implementer is only worth buying if the plan has parallelism to spend it
+on. Agents committing into a worktree is cheap and easy to
+discard; the same on master is a different proposition, and that is the pairing
+your partner needs in front of them. Implementing onto main or master needs
+their say-so and this is where you get it. Known friction in a worktree for this
+repo, a lint target that resolves through a symlink, a build that needs its own
+install, belongs in the option text where it can affect the answer, not in a
+footnote after they have chosen.
+
+If one of the two has only one live answer, say which and ask the other. A
+checkpoint down to a single question is still a checkpoint.
+
+A session that forbids subagents does not skip this; it changes what the
+review options are. Skipping it is how "review outstanding" first appears in
+the closing summary, at the one moment your partner can no longer do anything
+about it.
+
 ## Dispatch rules
 
+Read the plan as a graph before you read it as a list. `Needs` and `Offers`
+are dependency edges, not only blindness insurance: a task is ready when every
+`Needs` it names is offered by a task already done, and any two ready tasks
+with disjoint `Touches` can go at the same time. Do that read once, before
+Task 1. A plan run in the order it happened to be written is a plan whose
+graph nobody looked at, and inert-first ordering tends to put the independent
+tasks at the front, so the opportunity is usually real.
+
+Derive the sets at dispatch rather than writing wave numbers into the plan. A
+declared schedule is wrong the moment one task lands late or comes back with a
+blocking finding. A derived one just recomputes.
+
 - One `TaskCreate` per task, marked in progress then complete. That state
   outlives compaction; your memory doesn't.
 - Each task goes to a fresh agent with that task's text and nothing else.
   What this session accumulated is yours to hold, not theirs.
-- **Never run two implementers at once.** They collide in the same files.
-- Fan out for work that doesn't write: investigations or searches, one
-  agent per question, all dispatched in one message so they run at once.
-  The test: could two agents touch the same file?
+- **Fan out wherever the graph allows.** Work that does not write is always
+  safe and always parallel: investigations, searches and reviewers, one agent
+  per question, all in one message so they run at once.
+- **Concurrent implementers need a worktree each.** Disjoint `Touches` is
+  necessary and no longer sufficient: agents commit their own tasks, so two
+  in one tree contend on the git index and on `HEAD` even when their files
+  never meet. One worktree per concurrent implementer, or run them serially.
+  Those worktrees cost something, which is why pre-flight asks rather than
+  assumes.
+- **The flip runs alone.** Nothing goes concurrent with the task carrying
+  `Flips`. The invariant it establishes is what later tasks are checked
+  against, and whatever landed beside it was checked against nothing.
 - Isolate the workspace before a multi-task plan: the harness's worktree
   tool, not `git worktree` yourself. Implementing straight onto main or
-  master needs your partner's say-so.
+  master needs your partner's say-so, which pre-flight is where you got, and
+  it forecloses concurrent implementers for the whole run.
+- **The agent that built the task commits it**, once its own tests pass, and
+  only the paths in its `Touches`. Never `git add -A`: the tree is shared, and
+  on a branch you did not isolate it holds work that is not this task's. The
+  agent committing is the default rather than you committing, because
+  authoring a message for a diff you did not write means reading that diff,
+  which is the context dispatch exists to keep out of this session. Pre-flight
+  can overturn it for a given run.
 - Match model to task: cheap for mechanical work, stronger for judgment
   and final review.
 
+A per-task commit is not an integration event. `references/finish.md` owns
+push, PR and merge, none of which happen here, and a standing instruction to
+commit only when asked is about that outward-facing act. The plan's sign-off
+is the asking. Nothing a task commits reaches anywhere your partner has not
+already agreed to, so the instruction is satisfied rather than excepted.
+
 ## 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.
+Separate two cases first. A session where dispatch is off unless your partner
+asks for it is not this section: it is the pre-flight review question, and
+answering it is theirs to do. This section is dispatch being genuinely
+unavailable, where there is nothing to ask.
+
+`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
@@ -65,35 +167,57 @@ 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.
+tier. Name those tasks at pre-flight, not at handback, so the choice of what
+to do about them is still open: shrink the plan, take the flip on its own, or
+accept the gap knowingly. Whatever is left then gets listed 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 while it can still change the plan.
 
 ## Review policy
 
+`references/review.md` owns the mechanics every review shares: what to send,
+the two destinations and the grade that sorts them, findings going back to
+whoever wrote the code, and the three-round cap. This section is only what
+`deep` adds on top, which is the tiering. It does not restate the rest, and
+where it once did, the two copies had already drifted apart.
+
 A review costs about what the implementation cost, so reviewing every task
-doubles the plan. Confirming Offers landed and nothing outside Touches moved
-is free, one `git diff --stat`; only quality judgment needs a dispatch.
+doubles the plan. Confirming `Offers` landed and nothing outside `Touches`
+moved is free, one `git show --stat` over the task's commits; only quality
+judgment needs a dispatch. `git diff --stat` is the wrong reach now that the
+agent commits its own task: it reports a clean tree and confirms nothing,
+and it fails by printing success rather than by erroring.
+
+| Tier | Task shape | Review |
+|------|------------|--------|
+| 0 | Created files only, executable tests exist and pass, Contract matches | No dispatch. Read the commit stat yourself. |
+| 1 | Modified existing code, or later tasks build on it | One reviewer dispatch |
+| 2 | No executable test covers it: prose, config, docs | One reviewer dispatch; a stat cannot confirm the words are right |
+| 3 | Auth, data, money, concurrency, or the plan flags it | One reviewer dispatch, stronger model |
+| 3 | Carries the `Flips` line | One reviewer dispatch, stronger model |
 
-| Task shape | Review |
-|------------|--------|
-| Created files only, executable tests exist and pass, Contract matches | No dispatch. Read the diff stat yourself. |
-| Modified existing code, or later tasks build on it | One reviewer dispatch |
-| Auth, data, money, concurrency, or the plan flags it | One reviewer dispatch, stronger model |
-| No executable test covers it: prose, config, docs | One reviewer dispatch; a diff stat can't confirm the words are right |
+A task matching more than one row takes the highest tier of them. Tier is the
+number, not the row order and not which shape sounds more serious. A task that
+only creates files but ships prose is tier 2, and a suite re-bless paired with
+an ADR is tier 2 rather than the free row it resembles.
 
-A task that matches more than one row takes the strongest review of them.
+Ordering inert tasks first is what keeps this affordable. An inert task that
+only creates files takes tier 0, so a nine-task plan usually buys three
+or four dispatches rather than nine. If most of your plan qualifies for a
+dispatch, the tasks are interleaved rather than ordered, and reordering them
+is cheaper than reviewing them.
 
-The diff goes to disk and the reviewer gets its path: `git diff <base>
-<head> > <file>`. Base means where that task began, which is why `HEAD~1` is
-wrong: on a five-commit task it shows the fifth and buries the rest.
-Findings return to whoever wrote the code.
+Reviews are reads, so they are always parallel. Every review a wave earned
+goes out in one message, and they run while the next wave's implementers work:
+a reviewer writes nothing, so it collides with nothing. The final review is
+the only one that waits, because it is the only one that needs everything to
+have landed.
 
-**Most fixes are too small to earn a second review.** Read the fix diff
-yourself and check the test it names ran; dispatch again only for
-substantial logic changes. Three rounds is the cap either way: a finding
-still open then is structural, so escalate it to your partner.
+Record the base in the task's `TaskCreate` entry when you dispatch, before the
+agent's first commit lands. Recovering it afterwards is archaeology, and the
+answer you will guess at is `HEAD~1`, which `references/review.md` already
+names as the standing mistake.
 
 **A finding surviving two rounds may be a defect in the criterion, not the
 work.** Before a third round, ask whether any output could satisfy it. A
@@ -101,14 +225,44 @@ criterion that rejects every attempt the same way never converges, and the
 work degrades each round as it contorts toward an unpassable test. Fixing
 the criterion is your partner's call.
 
-Never hand yourself a finding to fix while you are the one coordinating.
-Coordination and repair are separate jobs, and doing both leaves your own
-patch as the one nobody reviewed, bought with context the later tasks are
-going to need. A finding has two destinations: fixed now by the agent that
-wrote it, or recorded in the task's `TaskCreate` entry for the final review.
-A reviewer may describe severity in words; a third disposition is not
-available, and neither is a step that adjudicates findings and sorts them
-into one.
-
-The final review covers cross-task integration and anything deferred, not
-lines a per-task review cleared.
+## What the reviewer is asked
+
+The tier buys a dispatch; it does not say what the dispatch is for. Name the
+claim the review has to settle, and it differs by row:
+
+- **Tier 0**, spot-checked rather than dispatched: that the task is actually
+  inert. The claim is that nothing observable changes when this lands by
+  itself, and one caller already reaching the new path falsifies it.
+- **Tier 1**: that `Offers` matches what the plan promised later tasks, since
+  those tasks are being built blind against exactly that signature.
+- **Tier 2**: that the words are true of the code as it now stands. That is
+  the whole reason the row exists and the one claim no stat reaches.
+- **Tier 3, `Flips`**: that the invariant the flip establishes holds, and
+  holds from that commit onward rather than only under the test the task
+  wrote for itself.
+- **Tier 3, everything else**: whatever the trigger was. A task flagged for
+  concurrency gets asked about concurrency.
+
+## A finding about another task
+
+Contracts mean tasks are built blind, so a reviewer reading Task 6 will
+sometimes be right about Task 2. That finding fits neither destination: Task
+6's agent cannot act on it, and it does not quietly become yours to fix.
+
+Record it on the earlier task's `TaskCreate` entry, and send it to that task's
+agent as well if that agent is still live. If it invalidates an `Offers` that
+later tasks have already built against, it has stopped being a finding and
+become a plan change, which is your partner's call rather than something to
+absorb into the next task's brief.
+
+## The final review
+
+It covers cross-task integration and everything the record accumulated, not
+lines a per-task review already cleared. It is a dispatch, on the stronger
+model, and it gets the whole-plan diff and the deferred findings as a list.
+
+Size the brief to what it is actually carrying, and say which of two things it
+is. After nine per-task reviews cleared, it is an integration check. When
+pre-flight chose to skip per-task reviews, it is the only review the plan will
+ever get. Sending the same brief to both is how a plan ends up with one skim
+standing in for nine reviews.

package/skills/sluice/references/meter.md

@@ -26,6 +26,13 @@ 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.
 
+The agent line carries a concurrency factor next to the wall-clock: agent time
+summed, over the span those agents actually occupied. 1.0× means every agent
+had the clock to itself. That is the right number for a plan whose graph was a
+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.
+
 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.

package/skills/sluice/references/review.md

@@ -11,17 +11,25 @@ mistake, showing the last of five commits and burying the rest. Send what
 you built and what it is meant to do alongside the path, and nothing about
 how you got there.
 
+Name the claim the review has to settle as well. A diff and an intent with no
+question attached buys a general opinion, which is the most expensive kind of
+finding to receive and the least actionable one.
+
 Leave every finding open to the reviewer; steering them away from an issue
 first is the same mistake as reviewing it yourself. A finding that looks
 wrong still gets raised, then argued.
 
-Every finding has one of two destinations. Either it blocks, and the work
-stays where it is until the fix lands, or it goes onto the task's record,
-which is what the final review reads. Reviewers grade findings Critical,
-Important or Minor, and the grade picks between the two: only Minor may wait
-for the record, and anything graded above it blocks. A third destination is
-not on offer, so neither is the adjudication step that would sort findings
-into it; that sorting costs more than the findings are worth.
+Every finding has one of two destinations. Either it goes back to the agent
+that wrote the code and the work stays where it is until the fix lands, or it
+goes onto the task's record, which is what the final review reads. Reviewers
+grade findings Critical, Important or Minor, and the grade picks between the
+two: only Minor may wait for the record, and anything above it blocks.
+
+The grade is the sort, and it has to be load-bearing. The alternative is you
+reading every finding to decide where it goes, which is an adjudication pass
+that costs more than the findings are worth and puts the coordinator back
+inside the diff it dispatched to stay out of. A third destination is not on
+offer, so neither is that pass.
 
 Send findings back to the agent that wrote the code: it already holds the
 task and its reasoning, memory you would otherwise rebuild. Three rounds is

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

@@ -119,8 +119,21 @@ SUMMARY="$(jq -s '
           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
 
+  # 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)
+     | reduce .[] as $i ([];
+         if (length == 0) or (.[-1].e < $i.s)
+         then . + [$i]
+         else .[0:-1] + [{ s: .[-1].s, e: ([.[-1].e, $i.e] | max) }] end)
+     | map(.e - .s) | add // 0) as $agent_span
+
   | { empty: false,
       trail: ($trail | join(" → ")),
       elapsed: $elapsed, waiting: $waiting,
@@ -130,7 +143,10 @@ SUMMARY="$(jq -s '
       out_tok: $out_tok, cache_tok: $cache_tok,
       agents: $agents,
       agent_tokens: ([ $agents[].tokens ] | add // 0),
-      agent_ms: ([ $agents[].ms ] | add // 0) }
+      agent_ms: ([ $agents[].ms ] | add // 0),
+      concurrency: (if $agent_span > 0
+                    then (([ $agents[].ms ] | add // 0) / 1000) / $agent_span
+                    else 0 end) }
   end
 ' "$TRANSCRIPT" 2>/dev/null)"
 
@@ -216,8 +232,11 @@ 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 ))")"
+  # 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')")"
 
   # 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.

package/skills/sluice/skill.json

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