@cueloop/pi 0.1.0-alpha.87 → 0.1.0-alpha.89

package/README.md

@@ -5,3 +5,7 @@ pi install npm:@cueloop/pi
 ```
 
 The package opens cueloop Threads in the configured terminal surface and delivers Messages back into the active pi conversation.
+
+Use `/cueloop:plan`, `/cueloop:diff`, `/cueloop:review`, `/cueloop:reply`, `/cueloop:prototype`, or `/cueloop:refine` to start a workflow. Each command loads the corresponding shared cueloop skill. The review skill uses the CLI to attach line anchored findings; the other workflow skills use `open_thread` when available.
+
+Pi reports available package updates on startup. If cueloop reports a version mismatch, run `cueloop restart`, then update the older component if needed: `cueloop update` or `pi update npm:@cueloop/pi`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/pi",
-  "version": "0.1.0-alpha.87",
+  "version": "0.1.0-alpha.89",
   "description": "cueloop Thread integration for pi",
   "keywords": [
     "pi-package"
@@ -17,7 +17,8 @@
   },
   "files": [
     "extension.ts",
-    "README.md"
+    "README.md",
+    "skills/"
   ],
   "type": "module",
   "exports": {
@@ -26,8 +27,11 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "prepack": "node prepare-skills.mjs"
+  },
   "dependencies": {
-    "@cueloop/adapters": "0.1.0-alpha.87"
+    "@cueloop/adapters": "0.1.0-alpha.89"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.86.0"
@@ -38,6 +42,9 @@
   "pi": {
     "extensions": [
       "./extension.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   }
 }

package/skills/annotate/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: cueloop-annotate
+description: Read a cueloop plan or diff and comment on it as a review-side agent, without leaving the review. Use when you are helping a collaborator poke holes in a plan under review - you annotate on their behalf; you never rewrite the plan or cast the message.
+---
+
+# cueloop annotate
+
+The agent side of the review write-surface. You read the artifact under review
+and attach span-anchored comments through the same annotation API a human uses.
+Your comments are attributed to the collaborator who launched you and show up in
+their rail exactly as if they had typed them.
+
+## Rights boundary
+
+You may **read** and **comment** only. You may not rewrite the plan
+(`submit-revision` is the driving agent's alone), send the Message (`resolve` is
+the human's alone), or cut / edit / share (owner-only). The plan stays
+single-writer: you annotate, the human curates, the message carries it back.
+
+Pass `--role agent` on every command below. The daemon then caps this connection
+to read + annotate and rejects any escalation - the boundary is enforced, not
+just documented.
+
+## Steps
+
+1. Read the artifact and its existing annotations:
+
+   ```bash
+   cueloop session get <id> --role agent
+   ```
+
+2. See the shared quick-action vocabulary for this session (the same presets the
+   human picks); `--session` reads the reviewed session's own repo:
+
+   ```bash
+   cueloop actions list --session <id> --role agent
+   ```
+
+3. Comment on a span. **Anchor contract: `--quote` is the exact text from the
+   artifact you are commenting on** - copy it verbatim, not a paraphrase or a
+   line number. Add `--prefix`/`--suffix` (a few surrounding characters) when the
+   quote is not unique. Attribute every comment to the acting collaborator with
+   `--author` (and `--author-name` on the first comment so the rail shows a name):
+
+   ```bash
+   cueloop session annotate <id> --role agent \
+     --author <collaborator-id> --author-name "<display name>" \
+     --quote "<exact span from the plan>" \
+     --body "<your comment>"
+   ```
+
+   To use a quick action instead of a free-form body, reference it by index or
+   name from `actions list`:
+
+   ```bash
+   cueloop session annotate <id> --role agent \
+     --author <collaborator-id> --quote "<exact span>" --action "Out of scope"
+   ```
+
+4. Type a comment with `--kind` for a typed annotation (`security`, `perf`, a
+   tool id); the default kind is `comment`.

package/skills/code-review/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/code-review/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: cueloop-code-review
+description: "Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes: Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to \"review since X\"."
+---
+
+Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+
+- **Standards**: does the code conform to this repo's documented coding standards?
+- **Spec**: does the code faithfully implement the originating issue / spec?
+
+Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+
+The issue tracker should have been provided to you. If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`.
+
+## Process
+
+### 1. Pin the fixed point
+
+Whatever the user said is the fixed point (a commit SHA, branch name, tag, `main`, `HEAD~5`, etc.). If they didn't specify one, ask for it.
+
+Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
+
+Before going further, confirm the fixed point resolves (`git rev-parse <fixed-point>`) and the diff is non-empty. A bad ref or empty diff should fail here, not inside two parallel sub-agents.
+
+### 2. Identify the spec source
+
+Look for the originating spec, in this order:
+
+1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.), fetched via the workflow in `docs/agents/issue-tracker.md`.
+2. A path the user passed as an argument.
+3. A spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
+4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
+
+### 3. Identify the standards sources
+
+Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.
+
+On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below: a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
+
+- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation. Like any standard here, skip anything tooling already enforces.
+
+Each smell reads *what it is* → *how to fix*; match it against the diff:
+
+- **Mysterious Name**: a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code**: the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
+- **Feature Envy**: a method that reaches into another object's data more than its own. → move the method onto the data it envies.
+- **Data Clumps**: the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
+- **Primitive Obsession**: a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
+- **Repeated Switches**: the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
+- **Shotgun Surgery**: one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
+- **Divergent Change**: one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
+- **Speculative Generality**: abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
+- **Message Chains**: long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
+- **Middle Man**: a class or function that mostly just delegates onward. → cut it, call the real target direct.
+- **Refused Bequest**: a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+
+### 4. Spawn both sub-agents in parallel
+
+**Standards sub-agent prompt** should include:
+
+- The full diff command and commit list.
+- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full (the sub-agent has no other access to it).
+- The brief: "Report, per file/hunk where relevant, (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls: documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
+
+**Spec sub-agent prompt** should include:
+
+- The diff command and commit list.
+- The path or fetched contents of the spec.
+- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
+
+If the spec is missing, skip the Spec sub-agent and note this in the final report.
+
+### 5. Aggregate
+
+Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings, because the two axes are deliberately separate (see _Why two axes_).
+
+End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes: that's the reranking the separation exists to prevent.
+
+## Why two axes
+
+A change can pass one axis and fail the other:
+
+- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
+- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
+
+Reporting them separately stops one axis from masking the other.

package/skills/code-review/UPSTREAM.md

@@ -0,0 +1,7 @@
+Vendored verbatim from `mattpocock/skills`:
+
+- Source: https://github.com/mattpocock/skills/tree/c55ee46073ed923f86ce59a5eb3b6d895095d1b7/skills/engineering/code-review
+- Commit: `c55ee46073ed923f86ce59a5eb3b6d895095d1b7`
+- Imported: 2026-09-24
+
+The skill is distributed under the adjacent MIT license.

package/skills/diff/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: cueloop-diff
+description: Submit working-tree changes to the cueloop changes panel. Use when the user asks to review your code changes or before committing substantial agent-authored changes.
+---
+
+# cueloop diff
+
+Capture the working-tree patch, including untracked files, through the
+harness's cueloop `diff` workflow when available. Submit full changed-file
+contents so hunk curation stays applyable. Otherwise, write a complete patch
+to a file and run `cueloop session create --type diff --content-file <patch>`.
+The CLI path has no file snapshots, so hunk curation is unavailable. Give the
+user the returned Thread ID and collect the Message with
+`cueloop session wait <id> --timeout-ms 60000`, repeating while pending.
+
+File notes may explain intent in plain prose; they are context, not reviewer
+feedback. If changes are requested, fix each cited line and submit an updated
+diff for review with `cueloop session submit-revision <id> --content-file <patch>`
+on the CLI path.

package/skills/plan/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: cueloop-plan
+description: Submit a Markdown plan to a cueloop Thread for human review. Use when the user asks to review a plan or wants a reviewed go-ahead before implementation.
+---
+
+# cueloop plan
+
+When the harness exposes cueloop's `plan` workflow, submit the complete Markdown
+plan through it. Otherwise, write the plan to a file and use the installed CLI:
+
+```bash
+cueloop session create --type plan --content-file <plan.md>
+```
+
+Read the returned Thread ID and give it to the user. On the CLI path, collect
+the Message with `cueloop session wait <id> --timeout-ms 60000`; repeat while
+the response says `pending`. This path does not inject a native harness message.
+
+Keep the plan's exact wording: annotations attach to its text. When changes are
+requested, apply any edited text and every annotation, then revise the same
+Thread with `cueloop session submit-revision <id> --content-file <plan.md>` on
+the CLI path. Proceed with implementation only after approval.

package/skills/prototype/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: cueloop-prototype
+description: >-
+  Submit a component design proposal to cueloop for human review without blocking.
+  Use when the user asks to review a UI component's shape before implementing it:
+  its prop/type API, composition, and callstack.
+---
+
+# cueloop prototype review
+
+Review a UI component on paper before you build it: its interface, how it is
+assembled from primitives you already have, and its callstack. You write a single
+Markdown design doc; the reviewer reads it in the terminal and annotates the exact
+lines. The review does not block: you submit, keep working with the user, and
+cueloop delivers the Message when the reviewer is done.
+
+Write the doc as plain Markdown with exactly these three sections, in order. Keep
+everything line-addressable text, since the reviewer anchors comments to lines and
+words. Prefer fenced code blocks and indented trees over prose. Do not use Markdown
+tables; the reviewer renders one as a single block, so write comparisons as a list.
+
+## 1. API
+
+The prop/type surface, as a fenced `ts` block: the real interface a caller sees.
+Extract it from the component's types, or write the proposed one. Include every
+prop, its type, whether it is optional, and a one-line intent where it is not
+obvious.
+
+## 2. Composition
+
+How the component is assembled, as a **JSX anatomy tree** in a fenced `tsx` block,
+following the react-aria / Radix "Anatomy" convention. Write the real element tree,
+nesting by indentation, and put a trailing `{/* ... */}` comment on a node to name
+the primitive it reuses (or mark it a slot). It reads as code, so the reviewer
+annotates actual JSX lines. When there is more than one way to build it, list the
+options and your recommendation as a list, not a table:
+
+```tsx
+<ComboBox>              {/* generic over T */}
+  <Label />
+  <Group>
+    <Input />           {/* reuse: Input */}
+    <Button />          {/* toggle the popover */}
+  </Group>
+  <Popover>             {/* reuse: Popover, focus-trap + esc */}
+    <ListBox>
+      <ListBoxItem />   {/* active / selected */}
+    </ListBox>
+  </Popover>
+</ComboBox>
+```
+
+Options considered:
+- **A, reuse the shared Popover**: focus-trap and escape-to-close come for free; least new code.
+- **B, a bespoke popover**: full control of placement, but it re-solves focus management.
+
+Recommendation: A. Reuse the Popover and keep the ComboBox to input + listbox wiring.
+
+## 3. Callstack
+
+The call and data flow through the component, as an indented tree in a fenced block:
+entry point at the top, each call nested one level deeper, down to the store or
+output. Designing this flow up front is the point of the review. It shows how a
+user action threads through the layers before any code exists.
+
+```
+main.ts
+  Command.runWith(rootCommand)
+    cli.ts  alias command handler
+      parseLinkSlug("gh")
+      parseDestinationUrl("https://example.com/acme")
+      LinkManagerClient.alias({ slug, destination })
+        HttpApiClient client.operator.createAlias({ params, payload })
+          PUT {baseUrl}/api/links/gh
+            Access middleware
+            ProvideOperatorIdentity middleware
+            OperatorHandlers.createAlias
+              LinkCatalog.getLink(slug)
+              LinkCatalog.createAlias({ slug, destination, operator })
+                LinkCatalogStore.insertAlias
+                RedirectIndexService.putDestination
+      CliOutput.link(link)
+```
+
+## Submit and respond
+
+Write the doc to one Markdown file and submit it through the harness's cueloop
+`prototype` workflow when available. Otherwise, run
+`cueloop session create --type prototype --content-file <design.md>` and give
+the user the returned Thread ID. On the CLI path, collect the Message with
+`cueloop session wait <id> --timeout-ms 60000`, repeating while pending.
+
+On approval, proceed with the component. When changes are requested, apply
+every edited line and annotation to the design doc, then revise the same
+Thread with `cueloop session submit-revision <id> --content-file <design.md>`
+on the CLI path.
+
+Reviewing a rendered pixel mockup instead of a design doc is an opt-in
+experimental mode, set by the `[experimental]` config section. It needs a
+graphics-capable terminal and an installed browser.

package/skills/refine/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: cueloop-refine
+description: Analyze past cueloop Threads and propose recurring feedback writebacks through a plan Thread. Use when the user asks to learn from past reviews or run refine.
+---
+
+# cueloop refine
+
+Use the harness's cueloop `refine` workflow when available. Otherwise, run
+`cueloop refine` and read the report path in its JSON output to analyze the
+stored Thread corpus.
+Read its report and group annotations into named patterns. A pattern needs at
+least three members; keep one-offs in a long-tail list. Rank patterns by how
+often they occur on changes-requested Messages.
+
+Draft one proposed writeback per pattern. Include its evidence, target file,
+and exact text. Route repo-specific lessons to that repo's `AGENTS.md` or a
+project skill; route global preferences to the appropriate global instruction
+or memory. Submit the proposals as a plan Thread through the same workflow,
+or write them to a file and run
+`cueloop session create --type plan --content-file <proposals.md>`. On the CLI
+path, collect the Message with `cueloop session wait <id> --timeout-ms 60000`.
+
+Do not edit the targets before approval. Corpus analysis does not mutate source
+Threads; only approved writebacks change instructions or memory.

package/skills/reply/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: cueloop-reply
+description: Submit the previous reply to a cueloop Thread for human review. Use when the user asks to annotate or revise your last message.
+---
+
+# cueloop reply
+
+Submit your previous reply verbatim as Markdown through the harness's cueloop
+`reply` workflow when available. Otherwise, write it to a file and run
+`cueloop session create --type reply --content-file <reply.md>`. Give the user
+the returned Thread ID. On the CLI path, collect the Message with
+`cueloop session wait <id> --timeout-ms 60000`, repeating while pending.
+
+If changes are requested, apply the edited wording and each annotation before
+resubmitting the reply to the same Thread. On the CLI path, use
+`cueloop session submit-revision <id> --content-file <reply.md>`. Use `plan` for a proposal
+that has not yet been presented as a reply.

package/skills/review/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: cueloop-review
+description: Review a GitHub pull request in cueloop, record agent findings on the diff, and refine them with the user before any explicit GitHub post.
+---
+
+# cueloop review
+
+Use this workflow for `/cueloop:review <pull-request>`.
+
+1. Run `cueloop review-config`. Read `skill` and `workspace`.
+2. Read the pull request with `gh pr view <pull-request> --json number,title,body,url,baseRefOid,headRefOid`. Also read its existing review comments. Give them to the configured skill as deduplication context, but do not copy them into the cueloop Thread.
+3. Work at the exact PR head:
+   - `worktree`: create or reuse `~/.cueloop/worktrees/<owner>-<repo>/pr-<number>-<short-sha>`, fetch the head, and add it as a detached git worktree.
+   - `current`: compare `git rev-parse HEAD` with `headRefOid`. Stop if they differ.
+4. Write a short review brief with the PR title, a `## TL;DR` of two to four bullets, and the original body under `## PR description`.
+5. Run the configured review skill in that workspace. Give it the PR base SHA as its fixed point, the PR body as its spec source, and the existing review comments as deduplication context. For the built-in `code-review` skill, this context is complete: use `gh issue view` for issue references and do not require repository-specific issue-tracker setup. The built-in skill is vendored verbatim from [mattpocock/skills](https://github.com/mattpocock/skills/tree/c55ee46073ed923f86ce59a5eb3b6d895095d1b7/skills/engineering/code-review).
+6. Create the Thread from that workspace:
+   `cueloop review <pull-request> --head-sha <headRefOid> --no-tui --brief-file <brief-file>`
+7. Record each actionable finding with `cueloop review-comment <thread-id>`. Give it:
+   - `--path`, `--line`, and `--side LEFT|RIGHT`
+   - `--severity p0|p1|p2`
+   - `--title`
+   - `--body` or `--body-file`
+   - optional `--suggestion-file` and `--prompt-file`
+8. Open the Thread with `cueloop review-open <thread-id>`. Keep this turn open and run `cueloop session wait <thread-id> --timeout-ms 60000`. After each wait, run `cueloop session get <thread-id>` and inspect `history.entries` for Message IDs you have not handled. Act on each new Message, including a `comment` Message that leaves the Thread pending. Repeat the wait while the status is pending. Use replies to refine findings in the same Thread. Do not end the turn while waiting for a CLI-created review: it has no harness binding to wake the agent.
+
+The Thread Message is an instruction to the agent. If it directs you to post findings, post the selected unresolved agent findings. If it directs you to approve or request changes, use that event. Do not ask for the same authorization again in the agent conversation. Resolving the Thread does not itself post to GitHub; the agent must run:
+
+`cueloop review-post <thread-id> --comments C1,C3 --event comment|approve|request-changes [--body-file <draft>]`
+
+Omit `--comments` to post every unresolved agent finding. Human comments and replies stay local. Default to `--event comment` unless the Message asks to approve or request changes. The Message's text is private instructions for the agent, not the GitHub review body. Draft a separate, author-facing review body with `--body-file` only when needed; approval with inline findings can leave it empty.
+
+If import or posting fails, run `gh auth status`.