@iceinvein/agent-skills 0.1.40 → 0.3.0

package/skills/migrate/uninstall.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Run by agent-skills as a postremove step before the migrate skill bundle is
+# deleted. Reads the path recorded by install.sh and removes the PATH symlink
+# if it still points back into this bundle.
+
+SOURCE_DIR="$(cd "$(dirname "$0")" && pwd)"
+STATE_FILE="$SOURCE_DIR/.installed-cli-path"
+
+if [ ! -f "$STATE_FILE" ]; then
+  exit 0
+fi
+
+CLI_PATH="$(head -n 1 "$STATE_FILE")"
+[ -z "$CLI_PATH" ] && exit 0
+
+if [ -L "$CLI_PATH" ]; then
+  TARGET="$(readlink "$CLI_PATH")"
+  case "$TARGET" in
+    "$SOURCE_DIR"/*)
+      rm -f "$CLI_PATH"
+      echo "Removed migrate CLI symlink at $CLI_PATH"
+      ;;
+    *)
+      echo "migrate uninstall: leaving $CLI_PATH alone (points to $TARGET, not this bundle)"
+      ;;
+  esac
+fi
+
+rm -f "$STATE_FILE"

package/skills/sluice/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: sluice
+description: Use at the start of any request that changes code. Routes the work into one of four channels (bypass, fast, main, deep) by change shape, and applies only the rules that channel needs. Also use when asked to work faster or with less process.
+---
+
+# Sluice
+
+A sluice sorts material by size into channels and meters what flows through.
+Same here: pick the channel the change needs, pay for nothing else.
+
+## Route first
+
+Pick a channel from the change's shape, state it in one line, then proceed. The
+announcement is how your partner redirects you without being asked.
+
+| Channel | Signal | Rules | Say |
+|---------|--------|-------|-----|
+| `bypass` | No code change: a question, an explanation, a read | none | nothing, just answer |
+| `fast` | Existing interfaces, one subsystem (a new flag on an existing command still counts as existing) | test-first, verify | "Fast channel, existing interfaces. Test first, then implement." |
+| `main` | Adds an interface, or crosses subsystems | + agree intent, review before merge | "Main channel, new interface. Agreeing the shape first." |
+| `deep` | Several subsystems, or a plan was asked for | + written design and plan | "Deep channel, several subsystems. Design before code." |
+
+`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.
+
+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
+which part applied. `bypass` says nothing at all, because a question that gets
+announced stops being a question.
+
+**`root-cause`, `finish` and `meter` 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, triggers
+the second. Handing the work back triggers the third, whether or not it ever
+reaches an integration event. The first two fire in every channel, `bypass`
+included; `meter` cannot, because `bypass` announces nothing to measure from.
+
+## The rules
+
+One line each. Read the reference only on friction: the moment you notice
+yourself wanting to skip the rule, or arguing that this one is the exception.
+
+- **Agree intent** before building. One question at a time. Propose approaches
+  with a recommendation, not a survey. `main` agrees in a message, `deep` writes
+  it down. `references/intent.md`
+- **Test first.** The test comes before the code; run it while it should
+  still be failing, then write the least code that turns it green. Skip that
+  watching step and a green result is only an unchecked guess.
+  `references/test-first.md`
+- **Root cause** before fix. A fix that only hides the symptom has not fixed
+  anything. Three failed fixes point at the design, not your guesswork.
+  `references/root-cause.md`
+- **Verify** before claiming. Run the command in this turn and read its
+  output; the claim comes after that, never before. How sure you feel is not
+  something anyone else can check. `references/verify.md`
+- **Review** before merge. Dispatch a reviewer with fresh context and put the
+  diff on disk for it to read, so those bytes fill their context instead of
+  yours. `references/review.md`
+- **Finish** deliberately. Green suite first, then let your partner pick
+  merge, PR, or leave it. Never pick for them. `references/finish.md`
+- **Meter the run** as you hand it back. `scripts/run-stats.sh` reads the
+  ledger out of the session transcript: elapsed, tools, tokens, and what each
+  dispatched agent cost. A summary you assemble from memory is the one that
+  flatters you. `references/meter.md`
+
+## Changing channel
+
+Escalate out loud. A `fast` task that turns out to need a new interface becomes
+`main`, and you say so. Finishing quietly in the wrong channel is the failure
+this prevents; the same goes for dropping to a shallower one. Explicit
+instruction wins: "just do it" collapses to `fast`.
+
+## Deep channel
+
+Design to `docs/specs/YYYY-MM-DD-<topic>.md`, plan to
+`docs/plans/YYYY-MM-DD-<topic>.md`, unless the repo has a convention or
+your partner states a preference. Get the design signed off before code.
+
+The plan needs sign-off as well whenever agents will execute it, because each
+one sees only its own task and so nobody ever reads the plan whole. Executing
+it yourself makes it a worklist instead: write it and carry on.
+
+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.
+
+## Conflicts
+
+Sluice cannot run alongside the superpowers plugin. Superpowers requires its
+own fixed pipeline up front for anything that adds to or changes what the
+software does, not just code edits, and that pipeline overrides this router
+outright, so the two cannot be installed together.

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

@@ -0,0 +1,114 @@
+# Deep channel
+
+## Plan format
+
+- 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.
+- 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.
+- A **Touches** line lists the exact paths the task creates, edits and tests.
+- A **Review** field may name why the task needs the stronger tier (auth,
+  data, money, concurrency); the table below decides otherwise.
+- 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
+  something: a signature, a literal the code must match, a command, a test
+  body. Prose deliverables get their claims and their length, not a draft.
+- A step a stranger could not carry out from its own text is unfinished.
+  "Same as Task 3" is one such step: tasks get read out of order, so write
+  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.
+
+```
+# Plan: <topic>
+## Ground Rules
+- <exact value>
+### Task N: <name>
+**Contract:** Needs: <sig> | Offers: <sig>
+**Touches:** <path> (new) | <path> (edit) | <path> (test)
+**Review:** <reason, or omit>
+- [ ] <action> -> <proof>
+```
+
+## Dispatch rules
+
+- 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?
+- 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.
+- Match model to task: cheap for mechanical work, stronger for judgment
+  and final review.
+
+## 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.
+
+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
+`TaskCreate` now carries all of the state that outlives compaction and matters
+more, not less. And fresh context is unavailable, which was the entire thing
+review was buying.
+
+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.
+
+## Review policy
+
+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.
+
+| 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 that matches more than one row takes the strongest review of 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.
+
+**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.
+
+**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
+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.

package/skills/sluice/references/finish.md

@@ -0,0 +1,37 @@
+# Finish
+
+`finish` fires at an integration event, merging, pushing, or opening a PR,
+in every channel. A commit made in passing during `fast` channel work is
+not one of those: the branch as a whole has to be about to leave your
+hands.
+
+Start here: run every test the project has, not a sample of them. A red
+result stops the process; there is no menu after a failure. A pass from
+earlier in the session doesn't count: the tree has changed since, and
+only a run against what's here now proves anything.
+
+Confirm the base branch instead of assuming it; untangling a wrong merge
+costs far more than asking would have.
+
+With the suite green and the base confirmed, put exactly three options to
+your partner, with the run ledger above them so the choice is made against
+what the work actually cost rather than against your account of it;
+`references/meter.md` owns that. The three: merge it locally, push it and
+open a PR, or leave the branch as it stands. Those three exhaust what you may offer. Your partner may still
+ask for something off the list, most notably scrapping the branch, but the
+request has to originate with them and be unmistakable. Then stop. Which of
+the three it is belongs to them, however obvious the choice looks from where
+you are standing, so nothing moves until they say.
+
+After a local merge, run the whole suite again over the merged tree before
+deleting anything. A failure there stops the cleanup; you haven't pushed
+anything yet, so you can still walk it back.
+
+While a PR is open, the workspace survives: it is where the review
+comments get answered, and tearing it down means rebuilding it the moment
+the first one arrives. Discarding needs an explicit, confirmed ask from
+your partner. This tooling removes only the workspaces it created;
+anything else stays put.
+
+The friction line: "picking for them saves everyone a turn." Saving a
+turn is not the same as having their answer. Wait for it.

package/skills/sluice/references/intent.md

@@ -0,0 +1,29 @@
+# Agree intent
+
+Ask one question at a time. Use multiple choice when the answer set is
+bounded.
+
+Offer two or three approaches, never a survey. Put your top pick first
+and explain what makes it the better bet. Cut every feature YAGNI would
+cut before you present any of them; a lean option judged against a
+padded one is not a fair comparison.
+
+Size the request before you start refining it. "A CLI, a web dashboard and a
+sync daemon" is three projects wearing one sentence, and a question about the
+internals of any one of them comes too early. Say so the moment you notice, cut
+the work at its seams into pieces that could each ship alone, agree the order
+they go in, and take only the first into the channel. The rest wait their turn,
+each with a design and a plan of its own. One design covering four subsystems
+produces a plan wrong in four places, found only once tasks are dispatched
+against it.
+
+Scale with channel. `main` agrees in one message and writes nothing. `deep`
+writes the design and gets sign-off before code. `fast` and `bypass` never
+reach this rule.
+
+Some questions are better shown than told; `references/show-or-say.md`
+decides which. Do not restate it here.
+
+The friction line: "I already know what they want." You know the goal,
+not the constraints, and the shape in your head rarely matches theirs. One
+question costs a turn. A wrong build costs the task.

package/skills/sluice/references/meter.md

@@ -0,0 +1,38 @@
+# Meter the run
+
+Run `scripts/run-stats.sh` as part of the message that hands the work back,
+and paste its output into that message unedited:
+
+```
+bash <skill-dir>/scripts/run-stats.sh --tests "<what the suite actually printed>"
+```
+
+It reads the session transcript, so it needs no state of its own and cannot
+drift from what happened. `--tests` is the one field it cannot know: only you
+watched the suite run. Fill it from the output you read in this session, and
+leave it off entirely if no suite ran, which prints "not reported" rather
+than a number nobody checked. `--base <ref>` overrides the diff base when the
+merge-base with `main` or `master` is not where this branch actually began.
+
+The run starts at your channel announcement, not at the session, so three
+unrelated tasks in one session report as three runs. A previous ledger closes
+the run before it. `bypass` announces nothing, so there is nothing to meter
+and the script exits quietly.
+
+What the ledger is for: the cost of a channel is otherwise invisible, and a
+channel nobody can price is a channel nobody can choose between. Six agents
+and four hours of agent wall-clock on a two-file change is the sort of thing
+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.
+
+Read it before you paste it. A row showing an agent that errored, or an agent
+whose token count dwarfs every other row, is a finding about the run and
+belongs in your prose, not left for your partner to spot in a table.
+
+Exit 2 means there was no run to report. That is a fact about the work, not a
+failure: do not synthesise a ledger to fill the gap.
+
+The friction line: "I know roughly what this cost." Roughly is the problem.
+Every number here is already on disk, and the remembered version is reliably
+the flattering one.

package/skills/sluice/references/review.md

@@ -0,0 +1,42 @@
+# Review
+
+`main` and `deep` both take a review before anything merges. What routed the
+work there, a new interface or a second subsystem, is what makes one reader
+insufficient.
+
+Write the diff out and send the path: `git diff <base> <head> > <file>`. A
+pasted diff fills your context; a file fills the reviewer's, which is what
+you dispatched one for. Get the base right: `HEAD~1` is the standing
+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.
+
+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.
+
+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
+the cap, and a finding still open when the third one ends is structural, not
+local, so stop there and hand it to your partner.
+
+Receiving a finding: check it against the codebase before acting, and argue
+back with specifics when it is wrong. Agreeing just to move things along is
+not engagement.
+
+For a small fix, read the diff and confirm the covering test ran; re-review
+only for substantial logic changes. While you are the one coordinating,
+findings are not yours to fix: your patch would be the single patch nobody
+reviews, and it spends context the plan still needs.
+
+The friction line: "dispatching a reviewer for this is overkill." Skipping
+the dispatch doesn't skip the cost, it just moves the cost onto you, and
+self-review is not review.

package/skills/sluice/references/root-cause.md

@@ -0,0 +1,38 @@
+# Root cause
+
+This rule is trigger-based, not channel-assigned. Anything the code does that
+nobody intended fires it, in every channel, `bypass` included: a crash, a
+test that has just turned red, output no one can account for.
+
+It rules out patching first and understanding later. A change aimed at the
+symptom buys quiet, and the quiet ends: the defect comes back, usually
+worse.
+
+**Reproduce it first.** A fault you cannot trigger on demand is not something
+you can fix, only guess at. Then read the error to the end, stack trace and
+all; the part you skim is often the part naming the cause.
+
+**Find the origin, not the blast site.** Follow the bad value back to
+whatever produced it and repair it there. Two things shorten the walk. One is
+whatever moved recently, a commit or a dependency bump. The other is a nearby
+case that still works: set it beside the broken one and list every way the
+two diverge, including the ones you are certain cannot matter, since that is
+usually where it hides.
+
+**One hypothesis, written down.** Alter two things at once and a green
+result cannot say which earned it, so state the theory plainly, pick the
+smallest change that would confirm or kill it, and change exactly that.
+
+**The fix travels with a test that would have caught it.** Write it, see it
+fail, make the single change your hypothesis called for, then run it again.
+With the cause dead, put validation on the layers that let the bad value
+pass, so its next variant trips something loud instead of slipping by.
+
+Three failed fixes point at the design, not your guesswork. Stop and raise
+it rather than trying a fourth.
+
+A test that waits by sleeping a fixed duration will flake eventually. Poll
+for the condition it is really waiting on and fail on a timeout.
+
+The friction line: "I have seen this exact error before, I know the fix."
+Recognising the pattern skips the step where you check it still applies here.

package/skills/sluice/references/show-or-say.md

@@ -0,0 +1,36 @@
+# Show or say
+
+This is never offered at the start. What triggers it is a specific moment in
+the conversation: a question arrives that turns on how something looks rather
+than on what it means. Offer then, in a message carrying nothing else, and
+wait. Plenty of conversations never raise such a question, and in those the
+offer is simply never made.
+
+Apply the test to each question rather than deciding once: could you settle
+this in a sentence, or do the candidates have to sit side by side where an
+eye can compare them? Being about the interface does not settle it. "Should
+deleting a record ask for confirmation first?" is a policy call, so argue it
+in words. "Should the confirm button be red and set apart, or match the row
+it belongs to?" has to be looked at.
+
+Appearance is the dividing line, not subject matter. A screen layout, a
+colour pairing, a diagram of how the pieces connect, a state machine,
+anything with a spatial arrangement: show it. Anything you could write down
+as a sentence, what's in scope, which architecture to use, what a term means:
+say it.
+
+Delivery: write the page to a file and publish it with the `Artifact` tool.
+To iterate, edit that same file and republish it; the URL stays the same. If
+`artifact-design` or `artifact-diagramming` guidance is available, follow it
+instead of restating page-design rules here.
+
+Two to four options per screen, no more, and print the question on the screen
+itself rather than leaving it behind in chat. Fidelity follows the kind of
+question being asked: a question about layout wants rough wireframes, and
+real detail is worth drawing only when polish is the thing being decided.
+
+Answers come back in chat. The page puts the options up; it does not collect
+the reply.
+
+If `Artifact` is unavailable, write a self-contained HTML file instead and
+hand your partner the path.

package/skills/sluice/references/test-first.md

@@ -0,0 +1,35 @@
+# Test first
+
+Write one test for the smallest slice of behaviour you intend to add. Run it
+and watch it fail before you write anything else. Then write the minimal code
+that makes it pass, and watch it pass.
+
+The watching is the point, not a formality. A test you never saw fail might be
+broken, aimed at the wrong behaviour, or not running at all; a green result
+alone cannot tell you which. A test that passes the first time you run it is
+not testing your change, it is testing behaviour that already existed. When
+that happens, fix the test, not the code.
+
+A test is only a test if some change to the implementation would turn it red.
+Work out which change before you write the body; if there isn't one, what you
+have is an assertion that stays green whatever you build.
+
+Assertions belong on what the run actually produced: the value returned, the
+state left behind, the output written. Never point one at a mock: a green
+result then proves only that you called the mock the way you meant to, which
+you knew already. Before a mock stands in for a dependency, learn what the real
+one does on the paths your test never exercises; one that quietly drops a side
+effect will hold a broken change green.
+
+Keep helpers that exist only for tests inside the test files. If a production
+class grows a method whose only caller is a test reaching inside it, the test
+has started reshaping your design.
+
+Three cases are worth asking to skip: generated or scaffolded code, a config
+file with no logic in it, and a prototype headed for the bin before anyone
+sees it. Ask rather than assume, and treat that list as closed.
+
+The friction line: "this case is obvious enough to skip straight to the
+code." A test written once the code already works can only confirm what you
+already believe about it. By that point you have stopped hunting for the cases
+you never thought of, so the test does not find them either.

package/skills/sluice/references/verify.md

@@ -0,0 +1,26 @@
+# Verify
+
+Claiming that something works has a fixed sequence in front of it: pick the
+command that proves the claim rather than the one that would make it feel
+true, run that command in full during this turn, read its output and its exit
+code, and write the sentence only once you have. What you remember from an
+earlier run is no substitute for reading this one, however convincing it was
+at the time.
+
+| Evidence in hand | What it lets you say |
+|---|---|
+| the original symptom, retested and gone | "bug fixed" |
+| the actual diff, not its own status report | "subagent finished" |
+| a fresh full run, zero failures, exit code checked | "tests pass" |
+| a real build command at exit 0, not a clean linter | "build succeeds" |
+
+A regression test counts only once you have seen it go both ways: red with
+the fix backed out, green with the fix back in. A test that has only ever
+passed proves nothing about what it would catch.
+
+Wording is not a loophole. "Looks right", "should be good" and "that's
+sorted" are completion claims in other clothes. So is pleasure at your own
+work: "beautiful", "there we go", "nailed it" each announce that the thing
+landed, and each needs the same command run beforehand as "it passes" does.
+
+The friction line: "the change was too small to need a full run." Run it.