@iceinvein/agent-skills 0.8.5 → 0.10.0

package/package.json

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

package/skills/index.json

@@ -281,9 +281,9 @@
   },
   {
     "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 each dispatched agent cost where the transcript recorded it. Claude Code only; stands down where the superpowers pipeline governs the repo.",
+    "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 and one status command can answer where the run is, 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.8.0"
+    "version": "0.12.0"
   },
   {
     "name": "temporal-coupling-detector",

package/skills/sluice/SKILL.md

@@ -90,6 +90,16 @@ 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.
 
+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
+only; pre-flight still wants answers, and an approval is not one.
+
+The run's state goes in `.sluice/run.json`, written a command at a time by
+`scripts/status.sh`. That is what makes the breakdown readable from outside the
+session running it: a statusline segment while it runs, `status.sh show` after a
+compaction, and neither costing your partner a turn to ask. `references/status.md`
+
 **Read `references/deep-channel.md` before you write the plan.** It carries the
 plan format, the pre-flight questions, the run record, the dispatch rules and
 the review tiers, and none of those are derivable from what is on this page.
@@ -141,10 +151,11 @@ this question the place to ask; genuine unavailability is the tool not being
 there at all, which `references/deep-channel.md` handles separately. Review that
 turns out to be missing is only actionable while the plan can still change.
 
-All three answers go into the run record before Task 1's first edit, each with
-the reason it went that way. Those rows are what discharge pre-flight, not the
-approval: one reply arrives for several obligations, so a "yes" with no rows
-behind it signed off the plan and nothing else.
+All three answers go into `run.json` and the run record before Task 1's first
+edit, the answer in the first and the reason in the second. Those rows are what
+discharge pre-flight, not the approval: one reply arrives for several
+obligations, so a "yes" with no rows behind it signed off the plan and nothing
+else.
 
 Three from that file that catch people out: concurrent implementers need a
 worktree each and the flip runs alone, review is tiered rather than automatic,

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

@@ -46,6 +46,16 @@
   the instruction out again in full. "TBD" is another. So is naming a type
   or a function that no task in the plan ever creates.
 
+**Run `scripts/plan.sh validate <plan>` on the finished plan, before pre-flight.**
+Most of what this section asks for needs no judgement to check: a `Needs` no
+task `Offers`, a "TBD", a step deferring to a neighbour, a missing `Contract`,
+a plan with no flip or two of them, a `Model` mark on a task the tier table
+sends to tier 3. Those come back as errors with the task number on them. The
+warnings are the judgement calls left to you: a step with no proof, a `Needs`
+satisfied only by a later task, two tasks whose `Touches` overlap. Reading the
+plan yourself catches these on a good day, and the point of a check is the
+other kind of day.
+
 ```
 # Plan: <topic>
 ## Ground Rules
@@ -72,14 +82,33 @@ Split it. A plan with none is not a `deep` plan: nothing in it does anything.
 ## The run record
 
 A `deep` run outlives its own context, so what it learns has to sit on disk
-rather than in the session. Open one file for the run before pre-flight and
-write it as you go. It holds what a stranger resuming tomorrow would need and
-you would otherwise be recalling: the base each task was dispatched from, each
-task with its status and its commits, the three answers pre-flight settled,
-review, model and workspace, with the reason each one went that way, and any finding
-belonging to a task other than the one that surfaced it. Those pre-flight rows
-come first and open the file, because they are also what says the stop happened
-at all.
+rather than in the session. That lands in two files, and which one a thing goes
+in follows from who has to read it.
+
+`.sluice/run.json` holds the state that moves: each task with its status, base
+and commit, its tier, its `Model` mark and its `Flips` line, and the answers
+pre-flight settled. `scripts/status.sh` writes and reads it, and
+`references/status.md` carries the commands and the statusline segment that
+makes a run visible without anyone asking. Open it with `init` when you open the
+record, seed the rows with `scripts/plan.sh import <plan>` rather than typing a
+command per task, then flip each task as it moves. It carries the ids, the names,
+the flip, the model marks and the tiers, the last of these floored off `Touches`
+and the contract graph rather than guessed. Import is safe to re-run: a status, a
+review mark or a ratified model already recorded is left alone and a tier is only
+ever raised, so resuming after a compaction cannot rewind the run.
+
+The record is the other file, and it holds what a status cannot: the reason
+review went the way it did, the reason a task was downshifted, the reason the
+workspace answer went that way, any finding belonging to a task other than the
+one that surfaced it, and whatever else a stranger resuming tomorrow would need
+and could not derive. **It no longer carries task rows with statuses in them.**
+Status written in both places drifts, and once it has there are two answers and
+nothing to say which is stale.
+
+Pre-flight lands in both, which is the one deliberate overlap: `run.json` holds
+the answer, so the file can say whether the stop happened at all, and the record
+holds the reason, so a reader can tell whether it should have gone that way.
+Those rows come first and open the record for the same reason they always did.
 
 Where it goes follows the repo if the repo has a convention, and
 `docs/plans/YYYY-MM-DD-<topic>-record.md` if it does not. It belongs to you
@@ -88,11 +117,42 @@ task's `Touches` names it, and you commit it yourself alongside the plan.
 Assembling it at handback defeats it: a record written from memory is memory,
 which is the one thing the file exists to replace.
 
-A file only outlives compaction if you go back to it. Read it before the next
-dispatch whenever this session has been summarised, and treat what it says over
-what you remember, including where the two agree. Each task closes by writing
-its commit into the record, which means asking the implementer to report the
-SHA it committed and putting that in the row rather than deriving it later.
+A file only outlives compaction if you go back to it. Run `status.sh show` and
+read the record before the next dispatch whenever this session has been
+summarised, and treat what they say over what you remember, including where the
+two agree. Each task closes by writing its commit into `run.json`, which means
+asking the implementer to report the SHA it committed and passing it to
+`status.sh task <id> --status done --commit <sha>` rather than deriving it later.
+
+## The design stop and plan mode
+
+The design stop is a stop because a plan written against the wrong design wastes
+a plan's worth of work. Sluice enforced it with a sentence, "a stop ends your
+turn", which is the weakest gate available in a harness that has a real one.
+
+Claude Code's plan mode is the real one. `EnterPlanMode` needs your partner's
+consent to enter, `ExitPlanMode` will not proceed without their approval, and
+edits are held shut in between, so the design cannot be quietly built against
+while it is still a draft. Take the design stop through it.
+
+What that changes: the design gets drafted in the plan file the harness names,
+and `ExitPlanMode` is the sign-off rather than a paragraph asking for one.
+
+What it does not replace is pre-flight. That stop wants three answers, and an
+approval is not an answer to any of them, so it stays where it is, after plan
+mode has exited and the plan is written. One enforced gate does not collapse two
+stops into one; it only makes the first of them hold.
+
+**The harness's plan file is not the artifact.** It belongs to the mode and not
+to the run. On approval, write the design to `docs/specs/YYYY-MM-DD-<topic>.md`,
+the plan to `docs/plans/YYYY-MM-DD-<topic>.md`, and open the run record and
+`run.json`. Those are the durable files, the ones a session resuming next week
+reads, and none of them is the one you drafted in.
+
+Where plan mode is unavailable, the prose stop is what you have and it is the
+same stop: end the turn on the design 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.
 
 ## Pre-flight
 
@@ -155,9 +215,10 @@ is the declared schedule the dispatch rules reject.
 If one of the two has only one live answer, say which and ask the other. A stop
 down to a single question is still a stop.
 
-**Write the answers into the run record before Task 1's first edit.** Both of
-them, each with the reason it went that way. This is what discharges pre-flight,
-rather than the approval you got, and the distinction is the whole point: a stop
+**Write the answers down before Task 1's first edit.** Both files:
+`status.sh preflight` for the answers, the run record for the reason each one
+went that way. That pair is what discharges pre-flight, rather than the
+approval you got, and the distinction is the whole point: a stop
 that carries the plan and pre-flight together has one reply for two obligations,
 so a bare "yes" satisfies the plan and leaves no trace either way of the
 questions. Rows in a file leave that trace. If Task 1 is about to open and the
@@ -175,19 +236,32 @@ about it.
 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
+with disjoint `Touches` can go at the same time.
+
+**`scripts/status.sh ready` does that read.** It prints the ready set, names which
+of them share a path and so cannot go together, says which tasks are still waiting
+on a contract and what for, and holds the flip out of every wave. Run it before
+each wave rather than deriving it again by hand, and note that it also checks the
+candidates against whatever is already `active` or in `review`: those hold their
+paths too, and a wave checked only against itself reads as safe while colliding
+with work in flight. 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.
+blocking finding. A derived one just recomputes, which is the whole reason `ready`
+reads the run state rather than the plan: it sees what has actually landed.
 
-- One line per task in the run record, marked in progress then complete as it
+- One row per task in `run.json`, flipped to `active` and then `done` as it
   moves. 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.
+- **Label the dispatch `T<n>: <task name>`.** The harness lists running agents
+  under whatever label the dispatch gave them, so labelled by task that list
+  reads as the plan and labelled anything else it reads as a row of anonymous
+  agents. It costs nothing and it is the only place a partner can see which
+  task is in flight without asking.
 - **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.
@@ -246,8 +320,8 @@ Three things change. The plan stops being a brief for strangers and becomes
 your own worklist, so its stop is no longer buying alignment with the agents
 who will carry it out, only your partner's read of work you will do yourself.
 Task isolation is gone, so
-the run record now carries all of the state that outlives compaction and
-matters more, not less. And fresh context is unavailable, which was the entire thing
+`run.json` and the record now carry all of the state that outlives compaction
+and matter more, not less. And fresh context is unavailable, which was the entire thing
 review was buying.
 
 One thing does not change: the work still owes a review. Reading your own diff
@@ -301,14 +375,22 @@ 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.
 
+**Mark each review with `status.sh task <id> --reviewed` when it comes back.**
+What that buys is a count of what this table promised and nobody delivered: tasks
+that are done, that qualified for a dispatch, and that carry no mark. `show` and
+the statusline both carry it from the moment it exists, which is the whole point.
+Unmarked, the count sits permanently non-zero and stops being a signal, and
+"review outstanding" goes back to first appearing in the closing summary, at the
+one moment your partner can no longer do anything about it.
+
 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.
 
-Record the base against that task in the run record when you dispatch, before
-the agent's first commit lands. Recovering it afterwards is archaeology, and the
+Record the base against that task with `status.sh task <id> --base <sha>` 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.
 

package/skills/sluice/references/status.md

@@ -0,0 +1,213 @@
+# Run state
+
+The plan says what the tasks are. The run record says why each decision went
+the way it did. Neither answers "where is this right now" to anything but a
+model reading prose, which is why a `deep` run is invisible from outside the
+session that is running it: your partner has to ask, and asking costs a turn
+and gets an answer from memory.
+
+`.sluice/run.json` is that answer in a form something else can read. One file
+per tree, holding only what changes as the run moves.
+
+```
+bash <skill-dir>/scripts/status.sh init --topic <t> --channel deep \
+     --plan docs/plans/<date>-<topic>.md --record docs/plans/<date>-<topic>-record.md
+bash <skill-dir>/scripts/status.sh task 3 --name "adapter seam" --tier 1 --model cheap
+bash <skill-dir>/scripts/status.sh task 3 --status active --base 75014c9
+bash <skill-dir>/scripts/status.sh task 3 --status done --commit 2c7f261
+bash <skill-dir>/scripts/status.sh task 3 --reviewed
+bash <skill-dir>/scripts/status.sh preflight --review "tier 3 only" --model "6 of 9 cheap" \
+     --workspace "one worktree per implementer"
+bash <skill-dir>/scripts/status.sh show
+bash <skill-dir>/scripts/status.sh ready
+bash <skill-dir>/scripts/status.sh line --full
+bash <skill-dir>/scripts/status.sh close
+```
+
+`--dir <path>` reads another tree, which is what the statusline uses. Statuses
+are `todo`, `active`, `review`, `done` and `blocked`. A new id needs `--name`;
+after that every call is a bare flip, so keeping it current costs one command
+per transition rather than a paragraph. `close` archives the run under
+`.sluice/archive/` and frees the tree for the next one.
+
+A command that cannot finish leaves the state exactly as it found it, so a
+failed `task` never costs you the rows already in the file. Two argument rules
+follow from that being worth guaranteeing: a value beginning with `--` is
+rejected rather than accepted as a value, and a flag with no value at all is
+rejected rather than taking the next flag as one.
+
+Gitignore `.sluice/`. It is working state, and everything durable in it lands
+somewhere else anyway: the commits are in git and the reasons are in the record,
+which is the file that does get committed.
+
+Open it with `init` when you open the run record, at the same point and for the
+same reason, then seed the rows with `plan.sh import <plan>` rather than a
+command per task. The ids, names, the flip, the `Model` marks and the tiers are
+all fixed the moment the plan is written and are already in the file, so typing
+them again is transcription with a chance of error in it.
+
+The tier import writes is a floor read off `Touches`: an `(edit)` means existing
+code changed, no `(test)` means nothing executable covers the task, and `Flips`
+or a `Review` flag is tier 3 outright. Raise one by hand with `--tier` where the
+work is more delicate than its paths suggest; nothing lowers it for you, because
+the tier table takes the highest row a task matches.
+
+Re-importing is safe and is the right move after the plan changes. It refreshes
+names, the contract graph and the flip, moving the flip when the plan moved it,
+and it raises a tier without ever lowering one. A status, a review mark or a model
+ratified at pre-flight is left alone, so resuming after a compaction cannot rewind
+the run. The one consequence worth knowing: adding a missing `(test)` to a plan
+will not drop a task from tier 2 back to tier 1, because the tier table takes the
+highest row a task matches and nothing here can tell a correction from a
+regression. Lower it by hand with `--tier` if that is what you mean.
+
+## What goes where
+
+**`run.json` owns status. The record owns why.** A status written into both
+drifts, and the moment it does there are two answers and no way to tell which
+is stale. So the record stops carrying task rows with statuses in them and
+carries what a status cannot hold: the reason review went the way it did, the
+reason a task was downshifted, a finding that belongs to a task other than the
+one that surfaced it, and what a stranger resuming tomorrow would need and
+could not derive.
+
+Pre-flight answers land in both, and that is deliberate rather than an
+exception: `run.json` holds the answer so the file can say whether the stop
+happened, the record holds the reason so a reader can tell whether it should
+have gone that way. Those are different claims.
+
+## Reading it back
+
+`show` prints the whole run: channel, topic, how many tasks are done, the plan
+and record paths, the pre-flight answers, and a row per task with its base,
+commit, tier and model. Run it after compaction instead of reconstructing the
+run from what you remember, and run it in the message that hands the work back,
+where "four of nine, task five blocked" is a fact your partner can act on.
+
+`show --json` is the same state for another reader. `line` is the compact
+one-line form and `line --full` the wide one; both exit 0 in silence on a missing
+run, unreadable state or a missing jq, because their caller is a status bar with
+nowhere to put an error.
+
+`line --full` renders three rows: the run and its clock, the bar alone, then the
+detail. The bar gets a row to itself so it never competes with text for width,
+which is what lets a cell be wide enough to read as a block rather than a tick.
+
+A group of cells per task, one repeated glyph each: `▰` done, `◈` active, `▨` in
+review, `▮` blocked, `▱` still to do. The glyphs are distinct before they are
+coloured, so the rows survive having their colour stripped. The width is chosen
+from what the whole bar would occupy, gaps included, rather than from the task
+count: keyed off the count alone the schedule was not monotonic, and thirty tasks
+at two cells each ran wider than twelve at three.
+
+**A done task still owed a review trails the review glyph**, `▰▰▨` against
+`▰▰▰`. Debt then reads in position rather than only as a count at the end of the
+row, which is the difference between knowing how much there is and knowing where.
+Tier 0 was never owed a dispatch, so it reads as plainly done. On a plan long
+enough to narrow cells to one, there is no trailing cell to give up and the
+positional reading stops: the count in the third row is then the only carrier,
+which is why it is printed whether or not the bar could show the same thing.
+
+**The flip draws as a rule, `┃`, before its task.** Everything left of it is inert
+and safe to leave landed; everything right of it is not. That is what the flip
+means, and it is a boundary between tasks rather than a property of one, so a
+name in the header could not say it. `plan.sh validate` rejects a plan with two
+flips and `import` clears a stale one, so the bar is only ever asked to draw the
+single legal case.
+
+The third row carries the progress count, whichever task wants attention, and the
+review debt. A blocked task displaces the active one there, being the one of the
+two worth interrupting for, and a `+n` follows when more than one task shares that
+state, since a plan running four wide has four actives by design.
+
+Mark a review with `task <id> --reviewed` when a reviewer comes back. What that
+buys is the debt count: a task that is done, that the tier table owed a dispatch,
+and that nobody marked. Tier 0 is excluded, having only ever been owed a stat
+read. Without it "review outstanding" first appears in the closing summary, at
+the one moment your partner can no longer do anything about it, and `show` and
+the statusline both carry it from the moment it exists.
+
+## The next wave
+
+`ready` answers the one question the other commands do not: not what the state is,
+but what may go now. A task is ready when every symbol it `Needs` is offered by a
+task already done, and two ready tasks are safe together when their `Touches` are
+disjoint.
+
+```
+6 ready now · a worktree each
+  T1  extract the bundle writer              src/cli/adapters/bundle.ts, …
+  T4  record what the harness offers         skills/sluice/scripts/status.sh, …
+  T4 and T5 share skills/sluice/scripts/status.sh, so not together
+
+2 waiting on a contract
+  T2  cursor and gemini write bundles        needs writeBundle
+
+the flip runs alone
+  T8  sluice installs on four harnesses
+```
+
+It reads the graph `plan.sh import` recorded, so a run seeded before that existed
+says so and tells you to re-import rather than reporting everything ready. The
+flip is held out of every wave whatever the graph says, because the invariant it
+establishes is what the tasks after it are checked against.
+
+Derive the wave here rather than writing wave numbers into the plan. A declared
+schedule is wrong the moment one task lands late; this recomputes.
+
+## Statusline
+
+This is the part that makes a run visible without anyone asking. Give it rows of
+its own rather than a segment among the badges: it then costs nothing when no run
+is live and contends with nothing for width when one is, which is what lets the
+bar be wide and the task carry its name rather than only its number.
+
+Capture it wherever the statusline command builds its other lines, keyed off the
+state file existing so a session with no run spawns no process at all:
+
+```bash
+sluice_line=""
+if [ -n "$cwd" ] && [ -f "$cwd/.sluice/run.json" ]; then
+  for sluice_sh in "$cwd/.claude/skills/sluice/scripts/status.sh" \
+                   "$HOME/.claude/skills/sluice/scripts/status.sh"; do
+    [ -f "$sluice_sh" ] || continue
+    sluice_line=$(bash "$sluice_sh" line --full --dir "$cwd" 2>/dev/null)
+    break
+  done
+fi
+```
+
+then print it last, after whatever else the command emits:
+
+```bash
+if [ -n "$sluice_line" ]; then printf '%s\n' "$sluice_line"; fi
+```
+
+`if` rather than `[ ... ] &&`: as the last command of a statusline script the
+short form makes it exit 1 on every render with no run live, which is the common
+case. `%s` rather than `%b`: the render already carries real escape bytes, and
+`%b` would reinterpret a backslash inside a task name. `$cwd` is
+`workspace.current_dir` from the JSON the harness sends on stdin. It renders as:
+
+```
+⧗ deep · sluice-cross-harness   ◷ 38m
+  ▰▰▰ ▰▰▨ ▨▨▨ ◈◈◈ ▱▱▱ ▮▮▮ ▱▱▱ ┃ ▱▱▱ ▱▱▱
+  2/9 done · !T6 model tiers rather than model names +1 · ⟲1 unreviewed
+```
+
+The colour comes out of the script rather than being applied by the caller,
+because the mapping from state to colour belongs next to the state. A caller that
+coloured the line itself would have to re-derive each cell's meaning from its
+glyph, which is the same fact stored twice.
+
+A run that is only visible to the session running it is a run your partner
+cannot redirect. That is the same argument the channel announcement makes, and
+the statusline is where it holds for the hour after the announcement scrolled
+away.
+
+## Friction
+
+"I know which task I'm on." You do, until this session is summarised. The file
+costs one command per transition and is the only thing in the run that survives
+that, and a plan whose progress lives in one context window is a plan nobody
+outside that window can read.