claude-dev-env 8.64.0 → 8.65.0

package/.agents/skills/mod-playbooks/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: mod-playbooks
+description: >-
+  Map of playbooks for driving a Claude Code mod (plugin) and seeing its screen: press keys, open menus and drawers, hover a reply to show its action row, click a dropdown, type in a field, fire a toast or a question card, and capture each screen as text and PNG. Use when an agent must test a mod, check a fix by looking at it, or show a mod to the operator on their own desktop.
+---
+
+# Mod playbooks
+
+## Principle
+
+An agent proves a mod works by driving it and reading the screen. It needs no person for that. A
+cloud session runs Claude Code in a pseudo-terminal, plays the steps, and reads each capture. The
+operator's desktop comes last, when a person wants to look.
+
+## Pick the route
+
+| Goal | Route | Reference |
+| --- | --- | --- |
+| Test a mod, or check a fix, with no person | Drive it in a pseudo-terminal and read the captures | [cloud-drive.md](references/cloud-drive.md) |
+| Let the operator watch the mod on their own screen | Open a desktop window from a Remote Control session | [desktop-window.md](references/desktop-window.md) |
+| Prove what the operator's window shows | Capture that window to a PNG | [desktop-capture.md](references/desktop-capture.md) |
+
+When the mod's repository ships a driver and playbooks, use them first. Look for a `drive.mjs` beside
+a `playbooks/` folder and a playbook guide in its docs. Read the guide, run the matching playbook, and
+add a playbook for any new screen you test.
+
+## Playbook map
+
+Each row is one thing an agent does to a mod, and the input that does it. The bytes are in
+[cloud-drive.md](references/cloud-drive.md).
+
+| Do this | Input | Check on screen |
+| --- | --- | --- |
+| Send a prompt | Type the text, then Enter | The scripted reply |
+| Open a slash-command menu or pane | Type the command, then Enter | The pane's title |
+| Open a pane from a footer pill | Click the pill's label | The pane's title |
+| Move between buttons in a pane | Tab forward, Shift+Tab back, Enter to press | The focused button |
+| Toggle a control | Click its label | The control's new state |
+| Close a pane | Escape | The prompt again |
+| Show a reply's action row | Hover the reply text; the row draws only under the pointer | The action labels |
+| Pick from a dropdown | Click the action, click the choice, click the confirm button | The confirm line |
+| Type in a text field | Click the field label, type, then Enter | The saved text |
+| Fire a toast | Script a tool turn the mod watches, and allow that tool | The toast's words, top right |
+| Raise a question card | Script a question tool turn, then click an option | The answered line |
+
+## Self-resolve loop
+
+1. Change the mod.
+2. Run the playbook for the screen you changed.
+3. Read the `.txt` capture for words, and open the `.png` for color and layout.
+4. On a failed step, read `failure.png`, fix the cause, and run again.
+5. Keep the passing captures as the proof, then show the operator if they asked to see it.
+
+## Limits
+
+- The cloud route proves the mod's screens. It runs a mock model, so it proves nothing about model output.
+- Drive input with the mod repository's driver, in the cloud or on the operator's PC. The desktop window is for looking only.
+- A screen that needs the operator's account, files or network stays on the desktop route.

package/.agents/skills/mod-playbooks/references/cloud-drive.md

@@ -0,0 +1,47 @@
+# Drive a mod in a pseudo-terminal
+
+A cloud session can run Claude Code with a mod loaded, press keys, click, hover, and capture the screen,
+with no PC and no person. Use the mod repository's own driver when it ships one. Build on the same parts
+when it does not.
+
+## The parts
+
+| Part | Job |
+| --- | --- |
+| `node-pty` | Runs `claude --plugin-dir <mod>` in a pseudo-terminal. |
+| `@xterm/headless` | Mirrors the output into a cell buffer, so the screen reads as text with colors. |
+| A local mock of the Messages API | Scripts each model turn, so the model calls the tool that fires the mod. Point `ANTHROPIC_BASE_URL` at it. |
+| A throwaway home and config folder | Seeds onboarding, API key approval and folder trust, so the first screen is the prompt. |
+| A renderer | Paints the cells to HTML and screenshots it with Playwright Chromium, so the capture is a PNG. |
+
+## Input bytes
+
+| Action | Bytes written to the terminal |
+| --- | --- |
+| Enter | `\r` |
+| Tab, Shift+Tab | `\t`, `\x1b[Z` |
+| Escape | `\x1b` |
+| Arrow up, down, right, left | `\x1b[A`, `\x1b[B`, `\x1b[C`, `\x1b[D` |
+| Clear the prompt line | `\x15` |
+| Left click at column `c`, row `r` (1-based) | `\x1b[<0;c;rM` then `\x1b[<0;c;rm` |
+| Hover at column `c`, row `r` | `\x1b[<35;c;rM` |
+
+Find `c` and `r` by searching the cell buffer for the text to point at. Search from the bottom row up,
+so a click lands on the newest copy of a label. Skip zero-width cells when you join a row, or wide
+characters shift every column after them.
+
+## The loop
+
+1. Write the steps: the scripted turns, then each key, click or hover, the text to wait for, and a capture.
+2. Run them. Wait for each step's text, then for the screen to stop changing, before the next step.
+3. Read the text capture for words, and open the PNG for color and layout.
+4. Fix the mod, run again, and keep the passing captures as the proof.
+
+## Gotchas
+
+- A tool the scripted turn calls needs `--allowedTools <tool>`, or a permission prompt stops the run.
+- Check the request body for your tool id, so the second request ends the turn with text.
+- A mod can refuse to draw a pane below a minimum width. Run at 180 columns unless the steps need less.
+- A toast draws in the top-right corner, over the header rows.
+- A PNG renderer can paint a wide emoji over the next cell. The text capture holds the characters as drawn.
+- A step that runs a script from the project folder fails in the sandbox, because that folder is empty.

package/.agents/skills/mod-playbooks/references/desktop-capture.md

@@ -0,0 +1,41 @@
+# Capture a desktop window
+
+Run this on the operator's PC after the mod fires. It asks the window to paint itself into a bitmap
+with `PrintWindow`, so another window on top does not spoil the image. Open the demo with
+`wt.exe -w new` and `--suppressApplicationTitle`, so its window keeps the demo title and the block
+below can find it by that title.
+
+```powershell
+Add-Type -AssemblyName System.Drawing
+Add-Type @"
+using System; using System.Runtime.InteropServices;
+public struct RECT { public int Left, Top, Right, Bottom; }
+public static class W {
+  [DllImport("user32.dll")] public static extern bool SetProcessDPIAware();
+  [DllImport("user32.dll")] public static extern bool GetWindowRect(IntPtr h, out RECT r);
+  [DllImport("user32.dll")] public static extern bool PrintWindow(IntPtr h, IntPtr hdc, uint flags);
+}
+"@
+[W]::SetProcessDPIAware() | Out-Null
+$window = Get-Process WindowsTerminal | Where-Object MainWindowTitle -like '*Mod demo*' | Select-Object -First 1
+$rect = New-Object RECT
+[W]::GetWindowRect($window.MainWindowHandle, [ref]$rect) | Out-Null
+$bitmap = New-Object System.Drawing.Bitmap ($rect.Right - $rect.Left), ($rect.Bottom - $rect.Top)
+$graphics = [System.Drawing.Graphics]::FromImage($bitmap)
+$hdc = $graphics.GetHdc()
+[W]::PrintWindow($window.MainWindowHandle, $hdc, 2) | Out-Null
+$graphics.ReleaseHdc($hdc)
+$bitmap.Save((Join-Path $env:TEMP 'mod-demo.png'))
+```
+
+Report the path and size, and say whether the image shows color and the mod's output. The PNG stays on
+the PC; a cloud session that needs to see it stages the file through the device folder tools, or has
+the PC session post it. A toast fades, so capture while it shows, or capture twice.
+
+## What went wrong before
+
+| Capture | Result |
+| --- | --- |
+| `CopyFromScreen` on the window rectangle, demo opened with `new-tab` | 1752 x 936 in color, but it showed the active tab and missed the toast. |
+| `CopyFromScreen` without `SetProcessDPIAware` | The image held the wrong region, with other windows in it. |
+| `SetProcessDPIAware`, then `PrintWindow` with flag 2 (`PW_RENDERFULLCONTENT`) | 2520 x 936 in full color, as reported by the PC session. |

package/.agents/skills/mod-playbooks/references/desktop-window.md

@@ -0,0 +1,79 @@
+# Open a mod on the operator's desktop
+
+A toast, pane or status line shows only in the Claude Code window that loads the mod. A Remote Control
+session has no window the operator can see. So the session opens a new desktop window that loads the
+mod, and the operator only looks at it.
+
+## Gotchas
+
+- A mod loaded inside the Remote Control session fires its toast there. The operator sees nothing.
+- `/plugin install` plus hot reload asks the operator to click "Enable for this session". `--plugin-dir` on a new window skips that prompt.
+- A child window inherits `NO_COLOR=1` and `CLAUDE_CODE_CHILD_SESSION=1` from the Remote Control process. The window then runs black and white. Remove both variables in the child before `claude` starts.
+- `Start-Process pwsh` opens the old console host. Launch through `wt.exe` to get Windows Terminal.
+- `wt.exe new-tab` lands in an existing Windows Terminal window. A screen capture then shows whichever tab is active. Use `wt.exe -w new` for a window of its own.
+- `wt.exe` is an app execution alias. Call it by its full path under `%LOCALAPPDATA%\Microsoft\WindowsApps`.
+- When the operator already has the same plugin installed, both copies load. A `--settings` file with `{"enabledPlugins":{"<plugin>@<marketplace>":false}}` turned off the installed copy for that one session.
+- A shell or program can rename the tab, and the window title follows it. Pass `--suppressApplicationTitle` so the capture can find the window by its demo title.
+
+## The auto mode safety check
+
+The Remote Control session runs in auto mode, and its classifier reads the operator's message that
+started the session. Two launches with the same commands went two ways:
+
+| Seed message | Result |
+| --- | --- |
+| The operator asked to see the mod run: "can i see it in action? build the mod and show me" | The window opened. |
+| The operator described a design change and asked for no run | The first step, writing the launcher script, was refused: `Permission for this action was denied by the Claude Code auto mode classifier. Reason: [Auto-Mode Bypass].` |
+
+The likely rule, inferred from these two cases: start the session on the operator's own message that asks
+to see or run the mod, and quote that ask in the instructions. When no such message exists, ask the
+operator in one line whether to open the window, and start the session on the answer. A refused
+step is final for that session; report the refusal text and stop.
+
+## Steps
+
+1. Start a Remote Control session, on the operator's message that asks to see the mod, in a folder on
+   the operator's PC that is already approved.
+2. Clone the mod's branch to a fresh temporary folder:
+
+   ```powershell
+   $dir = Join-Path $env:TEMP ('mod-demo-' + (Get-Date -Format 'HHmmss'))
+   git clone -q --depth 1 -b <branch> <repo-url> $dir
+   ```
+
+3. Write a launcher script that clears the inherited variables and starts Claude Code with the mod:
+
+   ```powershell
+   $script = Join-Path $env:TEMP 'mod-demo.ps1'
+   @"
+   Remove-Item env:NO_COLOR, env:CLAUDE_CODE_CHILD_SESSION -ErrorAction SilentlyContinue
+   Set-Location `$env:USERPROFILE
+   claude --plugin-dir '$dir\plugins\<mod>' '<one harmless prompt that fires the mod>'
+   "@ | Set-Content -Encoding utf8 $script
+   ```
+
+4. Open it in its own Windows Terminal window with PowerShell 7:
+
+   ```powershell
+   $wt = Join-Path $env:LOCALAPPDATA 'Microsoft\WindowsApps\wt.exe'
+   Start-Process $wt -ArgumentList "-w new new-tab --title `"Mod demo`" --suppressApplicationTitle pwsh -NoExit -File `"$script`""
+   ```
+
+5. Capture the window with [desktop-capture.md](desktop-capture.md) and check the PNG yourself.
+6. Tell the operator the window is open and what to look at. Hand over a pasteable command only when
+   the launch failed, and say why it failed.
+
+## Input on the operator's PC
+
+To click, hover or type into a mod on the operator's PC, run the mod repository's driver there from the
+Remote Control session, for example `node tools/visual-test/drive.mjs <playbook> <capture-folder>`.
+The driver owns its pseudo-terminal, so no input goes to a desktop window, and the auto mode check has
+nothing to refuse. One PC run of the drawer playbook passed with no refusal, where a session that sent
+operating-system keystrokes to a demo window was refused. Post the driver's PNG captures.
+Never send operating-system keystrokes or clicks to the demo window.
+
+## Verification
+
+- The operator sees the window without any click.
+- The window shows color and runs in Windows Terminal with PowerShell 7.
+- The mod loads with no failure line, and its toast or pane appears.

package/bin/ever-shipped-skills.mjs

@@ -99,6 +99,7 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'second-account-workers',
     'session-continuity',
     'session-log',
+    'mod-playbooks',
     'session-tidy',
     'pr-shared-extraction',
     'show',

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.64.0",
+    "version": "8.65.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {