nodmix 2026.5.25

package/skills/songsee/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: songsee
+description: "Generate spectrograms and feature-panel visualizations from audio with the songsee CLI."
+homepage: https://github.com/steipete/songsee
+metadata:
+  {
+    "nodmix":
+      {
+        "emoji": "🌊",
+        "requires": { "bins": ["songsee"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/songsee",
+              "bins": ["songsee"],
+              "label": "Install songsee (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# songsee
+
+Generate spectrograms + feature panels from audio.
+
+Quick start
+
+- Spectrogram: `songsee track.mp3`
+- Multi-panel: `songsee track.mp3 --viz spectrogram,mel,chroma,hpss,selfsim,loudness,tempogram,mfcc,flux`
+- Time slice: `songsee track.mp3 --start 12.5 --duration 8 -o slice.jpg`
+- Stdin: `cat track.mp3 | songsee - --format png -o out.png`
+
+Common flags
+
+- `--viz` list (repeatable or comma-separated)
+- `--style` palette (classic, magma, inferno, viridis, gray)
+- `--width` / `--height` output size
+- `--window` / `--hop` FFT settings
+- `--min-freq` / `--max-freq` frequency range
+- `--start` / `--duration` time slice
+- `--format` jpg|png
+
+Notes
+
+- WAV/MP3 decode native; other formats use ffmpeg if available.
+- Multiple `--viz` renders a grid.

package/skills/sonoscli/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: sonoscli
+description: "Control Sonos speakers (discover/status/play/volume/group)."
+homepage: https://sonoscli.sh
+metadata:
+  {
+    "nodmix":
+      {
+        "emoji": "🔊",
+        "requires": { "bins": ["sonos"] },
+        "install":
+          [
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/steipete/sonoscli/cmd/sonos@latest",
+              "bins": ["sonos"],
+              "label": "Install sonoscli (go)",
+            },
+          ],
+      },
+  }
+---
+
+# Sonos CLI
+
+Use `sonos` to control Sonos speakers on the local network.
+
+## Quick start
+
+- `sonos discover`
+- `sonos status --name "Kitchen"`
+- `sonos play|pause|stop --name "Kitchen"`
+- `sonos volume set 15 --name "Kitchen"`
+
+## Common tasks
+
+- Grouping: `sonos group status|join|unjoin|party|solo`
+- Favorites: `sonos favorites list|open`
+- Queue: `sonos queue list|play|clear`
+- Spotify search (via SMAPI): `sonos smapi search --service "Spotify" --category tracks "query"`
+
+## Notes
+
+- If SSDP fails, specify `--ip <speaker-ip>`.
+- Spotify Web API search is optional and requires `SPOTIFY_CLIENT_ID/SECRET`.
+- If there is an error, check the troubleshooting section and offer advice if there is a decent match.
+
+## Troubleshooting
+
+### `sonos discover` - `no route to host`
+
+- On error `Error: write udp4 0.0.0.0:64326->239.255.255.250:1900: sendto: no route to host (Command exited with code 1)`
+  - Note that the port number after `0.0.0.0:` is ephemeral and will change and the netmask may not match exactly either
+  - The `sendto: no route to host` should stay consistent
+- Advise the user that in `direct` (no Docker sandbox) mode on Mac OS that Settings -> Privacy & Security -> Local Network will need to be enabled for the top-level host parent process of the Gateway
+  - `node` if running via `launchd`
+  - `Terminal` if running the gateway directly in the terminal
+  - `Visual Studio Code` if running via terminal in VS Code
+- An alternative option is to use `sandbox` (docker container) with network access allowed for that sandbox
+
+### `sonos discover` - `bind: operation not permitted`
+
+- On error `Error: listen udp4 0.0.0.0:0: bind: operation not permitted`
+- Advise the user that they may be running via a Codex or other sandbox that does not permit network access (this can be replicated by running `sonos discover` within a Codex CLI session with sandbox enabled and not approving the escalation request)

package/skills/spike/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: spike
+description: Run throwaway prototypes to validate feasibility, compare approaches, and report a verdict.
+metadata: { "nodmix": { "emoji": "🧪" } }
+---
+
+# Spike
+
+Use when the user wants to test an idea before committing to a real build: "spike this", "quick prototype", "is this possible", "compare A/B", "before we build".
+
+Do not use when reading docs/code can answer the question, or when the user clearly asked for production implementation.
+
+Loop
+
+1. Question: state the concrete feasibility question.
+2. Research: read enough docs/source to choose credible approach.
+3. Build: create the smallest runnable artifact that validates or invalidates the idea.
+4. Stress: try one edge case or failure mode.
+5. Verdict: `VALIDATED`, `PARTIAL`, or `INVALIDATED`.
+
+Output shape
+
+- Default workspace: `.tmp/nodmix-spikes/<slug>` unless user asks for a tracked repo-local path.
+- Repo-local option: `spikes/<NNN-slug>/` with `README.md` and minimal code.
+- Prefer runnable CLI, tiny HTML, one endpoint, or focused test.
+- Avoid package sprawl, Docker, env files, app frameworks, and production cleanup.
+
+Multi-spike ideas
+
+- Split into 2-5 independent questions.
+- Run the riskiest question first.
+- For A/B comparisons, keep inputs equal and measure the same dimensions.
+- Ask before building all variants if the work is more than a small prototype.
+
+Verdict format
+
+```markdown
+## Verdict: VALIDATED | PARTIAL | INVALIDATED
+
+Question: ...
+Evidence: exact command/output/measurement.
+What worked: ...
+What failed or surprised us: ...
+Recommendation: ship / adjust / avoid, with the next production step.
+```
+
+Rules
+
+- An invalidated spike is useful when it rules out a path with evidence.
+- Do not merge spike code into production without rewriting it normally.
+- If external dependencies are evaluated, check health: recent release/commit, docs, license, install friction.

package/skills/spotify-player/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: spotify-player
+description: "Terminal Spotify playback/search via spogo (preferred) or spotify_player."
+homepage: https://www.spotify.com
+metadata:
+  {
+    "nodmix":
+      {
+        "emoji": "🎵",
+        "requires": { "anyBins": ["spogo", "spotify_player"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "spogo",
+              "tap": "steipete/tap",
+              "bins": ["spogo"],
+              "label": "Install spogo (brew)",
+            },
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "spotify_player",
+              "bins": ["spotify_player"],
+              "label": "Install spotify_player (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# spogo / spotify_player
+
+Use `spogo` **(preferred)** for Spotify playback/search. Fall back to `spotify_player` if needed.
+
+Requirements
+
+- Spotify Premium account.
+- Either `spogo` or `spotify_player` installed.
+
+spogo setup
+
+- Import cookies: `spogo auth import --browser chrome`
+
+Common CLI commands
+
+- Search: `spogo search track "query"`
+- Playback: `spogo play|pause|next|prev`
+- Devices: `spogo device list`, `spogo device set "<name|id>"`
+- Status: `spogo status`
+
+spotify_player commands (fallback)
+
+- Search: `spotify_player search "query"`
+- Playback: `spotify_player playback play|pause|next|previous`
+- Connect device: `spotify_player connect`
+- Like track: `spotify_player like`
+
+Notes
+
+- Config folder: `~/.config/spotify-player` (e.g., `app.toml`).
+- For Spotify Connect integration, set a user `client_id` in config.
+- TUI shortcuts are available via `?` in the app.

package/skills/summarize/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: summarize
+description: "Summarize or transcribe URLs, YouTube/videos, podcasts, articles, transcripts, PDFs, and local files."
+homepage: https://summarize.sh
+metadata:
+  {
+    "nodmix":
+      {
+        "emoji": "🧾",
+        "requires": { "bins": ["summarize"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/summarize",
+              "bins": ["summarize"],
+              "label": "Install summarize (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# Summarize
+
+Fast CLI to summarize URLs, local files, and YouTube links.
+
+## When to use (trigger phrases)
+
+Use this skill immediately when the user asks any of:
+
+- "use summarize.sh"
+- "what's this link/video about?"
+- "summarize this URL/article"
+- "transcribe this YouTube/video" (best-effort transcript extraction; no `yt-dlp` needed)
+
+## Quick start
+
+```bash
+summarize "https://example.com"
+summarize "/path/to/file.pdf"
+summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto
+```
+
+## YouTube: summary vs transcript
+
+Best-effort transcript (URLs only):
+
+```bash
+summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto --extract
+```
+
+If the user asked for a transcript but it's huge, return a tight summary first, then ask which section/time range to expand.
+
+## Model + keys
+
+Set the API key for your chosen provider:
+
+- OpenAI: `OPENAI_API_KEY`
+- Anthropic: `ANTHROPIC_API_KEY`
+- xAI: `XAI_API_KEY`
+- Google: `GEMINI_API_KEY` (aliases: `GOOGLE_GENERATIVE_AI_API_KEY`, `GOOGLE_API_KEY`)
+
+Default model is `auto`; config may choose the provider/model.
+
+## Useful flags
+
+- `--length short|medium|long|xl|xxl|<chars>`
+- `--max-output-tokens <count>`
+- `--extract` (print extracted content, no LLM summary)
+- `--json` (machine readable)
+- `--firecrawl auto|off|always` (fallback extraction)
+- `--youtube auto` (Apify fallback if `APIFY_API_TOKEN` set)
+
+## Config
+
+Optional config file: `~/.summarize/config.json`
+
+```json
+{ "model": "openai/gpt-5.2" }
+```
+
+Optional services:
+
+- `FIRECRAWL_API_KEY` for blocked sites
+- `APIFY_API_TOKEN` for YouTube fallback

package/skills/taskflow/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: taskflow
+description: "Coordinate multi-step detached tasks as one durable TaskFlow job with owner context, state, waits, and child tasks."
+metadata: { "nodmix": { "emoji": "🪝" } }
+---
+
+# TaskFlow
+
+Use TaskFlow when a job needs to outlive one prompt or one detached run, but you still want one owner session, one return context, and one place to inspect or resume the work.
+
+## When to use it
+
+- Multi-step background work with one owner
+- Work that waits on detached ACP or subagent tasks
+- Jobs that may need to emit one clear update back to the owner
+- Jobs that need small persisted state between steps
+- Plugin or tool work that must survive restarts and revision conflicts cleanly
+
+## What TaskFlow owns
+
+- flow identity
+- owner session and requester origin
+- `currentStep`, `stateJson`, and `waitJson`
+- linked child tasks and their parent flow id
+- finish, fail, cancel, waiting, and blocked state
+- revision tracking for conflict-safe mutations
+
+It does **not** own branching or business logic. Put that in Lobster, acpx, or the calling code.
+
+## Current runtime shape
+
+Canonical plugin/runtime entrypoint:
+
+- `api.runtime.tasks.flow`
+- `api.runtime.taskFlow` still exists as an alias, but `api.runtime.tasks.flow` is the canonical shape
+
+Binding:
+
+- `api.runtime.tasks.flow.fromToolContext(ctx)` when you already have trusted tool context with `sessionKey`
+- `api.runtime.tasks.flow.bindSession({ sessionKey, requesterOrigin })` when your binding layer already resolved the session and delivery context
+
+Managed-flow lifecycle:
+
+1. `createManaged(...)`
+2. `runTask(...)`
+3. `setWaiting(...)` when waiting on a person or an external system
+4. `resume(...)` when work can continue
+5. `finish(...)` or `fail(...)`
+6. `requestCancel(...)` or `cancel(...)` when the whole job should stop
+
+## Design constraints
+
+- Use **managed** TaskFlows when your code owns the orchestration.
+- One-task **mirrored** flows are created by core runtime for detached ACP/subagent work; this skill is mainly about managed flows.
+- Treat `stateJson` as the persisted state bag. There is no separate `setFlowOutput` or `appendFlowOutput` API.
+- Every mutating method after creation is revision-checked. Carry forward the latest `flow.revision` after each successful mutation.
+- `runTask(...)` links the child task to the flow. Use it instead of manually creating detached tasks when you want parent orchestration.
+
+## Example shape
+
+```ts
+const taskFlow = api.runtime.tasks.flow.fromToolContext(ctx);
+
+const created = taskFlow.createManaged({
+  controllerId: "my-plugin/inbox-triage",
+  goal: "triage inbox",
+  currentStep: "classify",
+  stateJson: {
+    businessThreads: [],
+    personalItems: [],
+    eodSummary: [],
+  },
+});
+
+const classify = taskFlow.runTask({
+  flowId: created.flowId,
+  runtime: "acp",
+  childSessionKey: "agent:main:subagent:classifier",
+  runId: "inbox-classify-1",
+  task: "Classify inbox messages",
+  status: "running",
+  startedAt: Date.now(),
+  lastEventAt: Date.now(),
+});
+
+if (!classify.created) {
+  throw new Error(classify.reason);
+}
+
+const waiting = taskFlow.setWaiting({
+  flowId: created.flowId,
+  expectedRevision: created.revision,
+  currentStep: "await_business_reply",
+  stateJson: {
+    businessThreads: ["slack:thread-1"],
+    personalItems: [],
+    eodSummary: [],
+  },
+  waitJson: {
+    kind: "reply",
+    channel: "slack",
+    threadKey: "slack:thread-1",
+  },
+});
+
+if (!waiting.applied) {
+  throw new Error(waiting.code);
+}
+
+const resumed = taskFlow.resume({
+  flowId: waiting.flow.flowId,
+  expectedRevision: waiting.flow.revision,
+  status: "running",
+  currentStep: "finalize",
+  stateJson: waiting.flow.stateJson,
+});
+
+if (!resumed.applied) {
+  throw new Error(resumed.code);
+}
+
+taskFlow.finish({
+  flowId: resumed.flow.flowId,
+  expectedRevision: resumed.flow.revision,
+  stateJson: resumed.flow.stateJson,
+});
+```
+
+## Keep conditionals above the runtime
+
+Use the flow runtime for state and task linkage. Keep decisions in the authoring layer:
+
+- `business` -> post to Slack and wait
+- `personal` -> notify the owner now
+- `later` -> append to an end-of-day summary bucket
+
+## Operational pattern
+
+- Store only the minimum state needed to resume.
+- Put human-readable wait reasons in `blockedSummary` or structured wait metadata in `waitJson`.
+- Use `getTaskSummary(flowId)` when the orchestrator needs a compact health view of child work.
+- Use `requestCancel(...)` when a caller wants the flow to stop scheduling immediately.
+- Use `cancel(...)` when you also want active linked child tasks cancelled.
+
+## Examples
+
+- See `skills/taskflow/examples/inbox-triage.lobster`
+- See `skills/taskflow/examples/pr-intake.lobster`
+- See `skills/taskflow-inbox-triage/SKILL.md` for a concrete routing pattern

package/skills/taskflow/examples/inbox-triage.lobster

@@ -0,0 +1,33 @@
+# Illustrative Lobster authoring example for a TaskFlow-style inbox triage job.
+# Swap the placeholder commands for your own tools or scripts.
+
+name: inbox-triage
+steps:
+  - id: fetch
+    command: gog.gmail.search --query 'newer_than:1d' --max 20
+
+  - id: classify
+    command: >-
+      nodmix.invoke --tool llm-task --action json --args-json
+      '{"prompt":"Classify each inbox item as business, personal, or later. Return one JSON object per item with route and summary.","thinking":"low","schema":{"type":"object","properties":{"items":{"type":"array"}},"required":["items"],"additionalProperties":false}}'
+    stdin: $fetch.stdout
+
+  - id: post_business
+    command: slack-route --bucket business
+    stdin: $classify.stdout
+    condition: $classify.json.items[0].route == "business"
+
+  - id: wait_for_business_reply
+    command: echo '{"status":"waiting","reason":"slack_reply"}'
+    condition: $classify.json.items[0].route == "business"
+
+  - id: notify_personal
+    command: >-
+      nodmix.invoke --tool message --action send --args-json
+      '{"provider":"telegram","to":"owner-thread","content":"Personal inbox item needs attention."}'
+    condition: $classify.json.items[0].route == "personal"
+
+  - id: stash_for_eod
+    command: summary-append --bucket eod
+    stdin: $classify.stdout
+    condition: $classify.json.items[0].route == "later"

package/skills/taskflow/examples/pr-intake.lobster

@@ -0,0 +1,32 @@
+# Illustrative Lobster authoring example for a TaskFlow-style PR intake lane.
+# Replace the placeholder commands with repo-specific tooling.
+
+name: pr-intake
+steps:
+  - id: fetch
+    command: gh pr list --repo owner/repo --state open --json number,title,body,headRefName
+
+  - id: classify
+    command: >-
+      nodmix.invoke --tool llm-task --action json --args-json
+      '{"prompt":"Classify each PR as close, request_changes, refactor, or maintainer_review. Return intent and recommended next action.","thinking":"low","schema":{"type":"object","properties":{"items":{"type":"array"}},"required":["items"],"additionalProperties":false}}'
+    stdin: $fetch.stdout
+
+  - id: close_low_signal
+    command: pr-close-low-signal
+    stdin: $classify.stdout
+    condition: $classify.json.items[0].nextAction == "close"
+
+  - id: request_changes
+    command: pr-request-changes
+    stdin: $classify.stdout
+    condition: $classify.json.items[0].nextAction == "request_changes"
+
+  - id: refactor_branch
+    command: pr-refactor-branch
+    stdin: $classify.stdout
+    condition: $classify.json.items[0].nextAction == "refactor"
+
+  - id: escalate
+    command: echo '{"status":"notify","target":"maintainer"}'
+    condition: $classify.json.items[0].nextAction == "maintainer_review"

package/skills/taskflow-inbox-triage/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: taskflow-inbox-triage
+description: "Example TaskFlow pattern for inbox triage, intent routing, waiting on replies, and later summaries."
+metadata: { "nodmix": { "emoji": "📥" } }
+---
+
+# TaskFlow inbox triage
+
+This is a concrete example of how to think about TaskFlow without turning the core runtime into a DSL.
+
+## Goal
+
+Triage inbox items with one owner flow:
+
+- business -> post to Slack and wait for reply
+- personal -> notify the owner now
+- everything else -> keep for end-of-day summary
+
+## Pattern
+
+1. Create one flow for the inbox batch.
+2. Run one detached task to classify new items.
+3. Persist the routing state in `stateJson`.
+4. Move to `waiting` only when an outside reply is required.
+5. Resume the flow when classification or human input completes.
+6. Finish when the batch has been routed.
+
+## Suggested `stateJson` shape
+
+```json
+{
+  "businessThreads": [],
+  "personalItems": [],
+  "eodSummary": []
+}
+```
+
+Suggested `waitJson` when blocked on Slack:
+
+```json
+{
+  "kind": "reply",
+  "channel": "slack",
+  "threadKey": "slack:thread-1"
+}
+```
+
+## Minimal runtime calls
+
+```ts
+const taskFlow = api.runtime.tasks.flow.fromToolContext(ctx);
+
+const created = taskFlow.createManaged({
+  controllerId: "my-plugin/inbox-triage",
+  goal: "triage inbox",
+  currentStep: "classify",
+  stateJson: {
+    businessThreads: [],
+    personalItems: [],
+    eodSummary: [],
+  },
+});
+
+const child = taskFlow.runTask({
+  flowId: created.flowId,
+  runtime: "acp",
+  childSessionKey: "agent:main:subagent:classifier",
+  task: "Classify inbox messages",
+  status: "running",
+  startedAt: Date.now(),
+  lastEventAt: Date.now(),
+});
+
+if (!child.created) {
+  throw new Error(child.reason);
+}
+
+const waiting = taskFlow.setWaiting({
+  flowId: created.flowId,
+  expectedRevision: created.revision,
+  currentStep: "await_business_reply",
+  stateJson: {
+    businessThreads: ["slack:thread-1"],
+    personalItems: [],
+    eodSummary: [],
+  },
+  waitJson: {
+    kind: "reply",
+    channel: "slack",
+    threadKey: "slack:thread-1",
+  },
+});
+
+if (!waiting.applied) {
+  throw new Error(waiting.code);
+}
+
+const resumed = taskFlow.resume({
+  flowId: waiting.flow.flowId,
+  expectedRevision: waiting.flow.revision,
+  status: "running",
+  currentStep: "route_items",
+  stateJson: waiting.flow.stateJson,
+});
+
+if (!resumed.applied) {
+  throw new Error(resumed.code);
+}
+
+taskFlow.finish({
+  flowId: resumed.flow.flowId,
+  expectedRevision: resumed.flow.revision,
+  stateJson: resumed.flow.stateJson,
+});
+```
+
+## Related example
+
+- `skills/taskflow/examples/inbox-triage.lobster`