@cullumco/cadence 0.1.0

package/dist/providers/music.js

@@ -0,0 +1,151 @@
+import { exec } from "node:child_process";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { tagsToVibe } from "../vibe.js";
+/* ─────────────────────────────────────────────────────────────────────────
+ * Music = identity + vibe. No Spotify Web API, no auth, no Premium.
+ *
+ *   1. osascript asks Spotify.app / Music.app what's playing (public,
+ *      stable scripting interface — survives the macOS 15.4 MediaRemote
+ *      lockdown that killed the system-wide now-playing tap).
+ *   2. MusicBrainz turns the artist into crowd-sourced vibe tags
+ *      (keyless, 1 req/sec). Cached forever by artist — a vibe never
+ *      changes, so it's one network call per *new* artist, not per prompt.
+ * ───────────────────────────────────────────────────────────────────────── */
+const CACHE_FILE = join(homedir(), ".cadence", "vibe-cache.json");
+const MB_TIMEOUT_MS = 1000;
+const MAX_TAGS = 4;
+const UA = "cadence/0.1 (https://github.com/cullumco/cadence)";
+// `application "X" is running` does NOT launch X — safe to probe.
+const SCRIPT = `
+on tryApp(appName)
+  if application appName is running then
+    tell application appName
+      if player state is playing then
+        return appName & "|||" & (name of current track) & "|||" & (artist of current track)
+      end if
+    end tell
+  end if
+  return ""
+end tryApp
+set r to tryApp("Spotify")
+if r is "" then set r to tryApp("Music")
+return r
+`;
+function osascript(script) {
+    return new Promise((resolve) => {
+        const child = exec(`osascript -e ${JSON.stringify(script)}`, { timeout: 800 }, (err, stdout) => resolve(err ? "" : stdout.trim()));
+        child.on("error", () => resolve(""));
+    });
+}
+async function getNowPlaying() {
+    const out = await osascript(SCRIPT);
+    if (!out)
+        return null;
+    const [player, track, artist] = out.split("|||");
+    if (!track || !artist)
+        return null;
+    return { track, artist, player: player ?? "" };
+}
+async function loadCache() {
+    try {
+        return JSON.parse(await readFile(CACHE_FILE, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+async function saveCache(cache) {
+    try {
+        await mkdir(join(homedir(), ".cadence"), { recursive: true });
+        await writeFile(CACHE_FILE, JSON.stringify(cache, null, 2), "utf-8");
+    }
+    catch {
+        // cache is best-effort; never let it break the signal
+    }
+}
+// Returns CLEANED genre tags (junk filtered out), most-popular first.
+// We cache the tags, not the derived vibe — so tuning the vibe mapping
+// (tagsToVibe / GENRE_AFFECT) takes effect immediately without flushing the cache.
+async function fetchTags(artist) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), MB_TIMEOUT_MS);
+    try {
+        const url = "https://musicbrainz.org/ws/2/artist/?fmt=json&limit=1&query=" +
+            encodeURIComponent(`artist:"${artist}"`);
+        const res = await fetch(url, {
+            headers: { "User-Agent": UA },
+            signal: ctrl.signal,
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        const tags = data.artists?.[0]?.tags;
+        if (!tags || tags.length === 0)
+            return null;
+        const cleaned = tags
+            .filter((t) => t.count > 0)
+            .sort((a, b) => b.count - a.count)
+            .map((t) => t.name)
+            .filter((name) => isVibeTag(name, artist))
+            .slice(0, MAX_TAGS);
+        return cleaned.length ? cleaned : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/* A "vibe" is an adjective or genre — never a proper noun, place, or
+ * listener-org meta-tag. Blocklist (not allowlist) so novel genres
+ * (hyperpop, phonk, …) pass; we only reject known classes of junk. */
+const META_TAG = /^(seen live|favou?rites?|spotify|owned|albums i own|under \d+|my |male |female )/;
+const PLACES = new Set([
+    "toronto", "london", "uk", "usa", "us", "american", "british", "canadian",
+    "swedish", "german", "french", "australian", "japanese", "korean",
+    "english", "scottish", "irish", "norwegian", "icelandic", "dutch",
+]);
+function isVibeTag(tag, artist) {
+    const t = tag.toLowerCase().trim();
+    if (t.length < 2 || t.length > 30)
+        return false; // empty or essay-length
+    const nameWords = new Set(artist.toLowerCase().split(/\s+/));
+    if (nameWords.has(t))
+        return false; // "daniel", "caesar"
+    if (PLACES.has(t))
+        return false; // geography is trivia, not vibe
+    if (META_TAG.test(t))
+        return false; // listener-org cruft
+    return true;
+}
+// Cache stores the cleaned tags as a comma-joined string (""=known-empty).
+async function getTags(artist) {
+    const key = artist.toLowerCase();
+    const cache = await loadCache();
+    if (key in cache) {
+        const v = cache[key] ?? "";
+        return v ? v.split(",") : [];
+    }
+    const tags = await fetchTags(artist);
+    cache[key] = (tags ?? []).join(","); // cache empty too — don't re-hit MB every prompt
+    await saveCache(cache);
+    return tags ?? [];
+}
+export async function getMusicSignal() {
+    const np = await getNowPlaying();
+    if (!np)
+        return null;
+    const tags = await getTags(np.artist);
+    const vibe = tags.length ? tagsToVibe(tags) : null;
+    return {
+        source: "music",
+        track: np.track,
+        artist: np.artist,
+        player: np.player || undefined,
+        vibe: vibe && vibe.moods.length ? vibe.moods.join(", ") : undefined,
+        energy: vibe?.energy,
+    };
+}

package/dist/providers/selfreport.js

@@ -0,0 +1,19 @@
+import { readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const STATE_FILE = join(homedir(), ".cadence", "state.txt");
+const STALE_AFTER_MS = 4 * 60 * 60 * 1000;
+export async function getSelfReportSignal() {
+    try {
+        const [text, info] = await Promise.all([readFile(STATE_FILE, "utf-8"), stat(STATE_FILE)]);
+        const trimmed = text.trim();
+        if (!trimmed)
+            return null;
+        if (Date.now() - info.mtimeMs > STALE_AFTER_MS)
+            return null;
+        return { source: "self_report", text: trimmed, setAt: info.mtimeMs };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/stop.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { getMusicSignal } from "./providers/music.js";
+import { getSelfReportSignal } from "./providers/selfreport.js";
+import { getAmbientSignal } from "./providers/ambient.js";
+import { getGitSignal } from "./providers/git.js";
+import { deriveCadence, loadOverrides, applyOverrides } from "./cadence.js";
+const TOTAL_BUDGET_MS = 1500;
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return {};
+    let raw = "";
+    for await (const chunk of process.stdin)
+        raw += chunk;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+async function collectSignals(cwd) {
+    const [music, report, ambient, git] = await Promise.allSettled([
+        getMusicSignal(),
+        getSelfReportSignal(),
+        getAmbientSignal(new Date()),
+        getGitSignal(cwd),
+    ]);
+    const signals = [];
+    if (music.status === "fulfilled" && music.value)
+        signals.push(music.value);
+    if (report.status === "fulfilled" && report.value)
+        signals.push(report.value);
+    if (ambient.status === "fulfilled" && ambient.value)
+        signals.push(ambient.value);
+    if (git.status === "fulfilled" && git.value)
+        signals.push(git.value);
+    return signals;
+}
+function selfReportIsShipping(signals) {
+    const report = signals.find((s) => s.source === "self_report");
+    if (!report)
+        return false;
+    return /\b(ship|shipping|jamming|locked.?in|sending|grind|just|send it)\b/i.test(report.text);
+}
+function pinnedActFreely(cadence, pinned) {
+    return ((pinned.includes("proactivity") && cadence.proactivity === "high") ||
+        (pinned.includes("posture") && cadence.posture === "high"));
+}
+function hasShippingAuthority(signals, cadence, pinned) {
+    return selfReportIsShipping(signals) || pinnedActFreely(cadence, pinned);
+}
+export function isSoftHandoff(message) {
+    const text = message.trim().toLowerCase();
+    if (!text)
+        return false;
+    const tail = text.slice(-900);
+    const finalParagraph = tail.split(/\n\s*\n/).at(-1) ?? tail;
+    const permissionQuestion = /\b(?:do you want|would you like|want me to|should i|shall i|can i|would you prefer|should we)\b/.test(finalParagraph) && /\?\s*$/.test(finalParagraph);
+    const passiveOffer = /\b(?:let me know if|tell me if|say the word|if you want,? i can|if you'd like,? i can|happy to keep going|happy to do that next)\b/.test(finalParagraph);
+    return permissionQuestion || passiveOffer;
+}
+export function decideStop(input, signals, cadence, pinned) {
+    if (input.stop_hook_active)
+        return null;
+    if (input.background_tasks && input.background_tasks.length > 0)
+        return null;
+    if (!hasShippingAuthority(signals, cadence, pinned))
+        return null;
+    if (!isSoftHandoff(input.last_assistant_message ?? ""))
+        return null;
+    return {
+        decision: "block",
+        reason: "Cadence stop check: the user is in a shipping / act-freely cadence, but your last response ended as a soft handoff. Continue instead: make the call and complete the most likely next step, or if no tool work remains, replace the handoff with a decisive final answer. Do not ask permission unless there is a genuine blocker.",
+    };
+}
+async function main() {
+    const input = await readStdin();
+    const projectDir = input.cwd ?? process.cwd();
+    const [signals, overrides] = await Promise.all([
+        Promise.race([
+            collectSignals(projectDir),
+            new Promise((resolve) => setTimeout(() => resolve([]), TOTAL_BUDGET_MS)),
+        ]),
+        loadOverrides(),
+    ]);
+    const state = { signals, capturedAt: Date.now() };
+    const { cadence, pinned } = applyOverrides(deriveCadence(state), overrides);
+    const decision = decideStop(input, signals, cadence, pinned);
+    if (decision)
+        process.stdout.write(JSON.stringify(decision));
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().catch((err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`cadence stop: ${msg}\n`);
+        process.exit(0);
+    });
+}

package/dist/types.js

@@ -0,0 +1,16 @@
+/* ─────────────────────────────────────────────────────────────────────────
+ * Cadence signal types.
+ *
+ * Music is now IDENTITY-ONLY. Spotify's audio-features endpoint was
+ * deprecated for new apps (2024-11-27) and dev-mode went Premium-only
+ * (2026-02), so energy/valence/tempo are gone. Track + artist come from
+ * the OS now-playing channel instead — no auth, no Premium, any player.
+ *
+ * The four embodied dimensions, each a provider emitting one Signal:
+ *   - MusicSignal      → what's playing            (music)
+ *   - SelfReportSignal → what you told us          (mood, ground truth)
+ *   - ActivitySignal   → your motor/typing tempo   (mood, inferred)
+ *   - GitSignal        → your work state           (context)
+ *   - PlaceSignal      → where & in what setting    (place)
+ * ───────────────────────────────────────────────────────────────────────── */
+export {};

package/dist/vibe.js

@@ -0,0 +1,96 @@
+/* ─────────────────────────────────────────────────────────────────────────
+ * vibe.ts — turn noisy genre tags into (a) clean mood words and (b) an
+ * averaged energy (0–1). The energy feeds the PACE dial in cadence.ts; the
+ * mood words color the rendered block and the TONE dial.
+ *
+ * Grounded in deep research (see docs/vibe-research.md):
+ *   • Mood vocabulary = Cyanite.ai's verified 13-mood controlled set.
+ *   • Affect axes = Spotify's published feature definitions:
+ *       energy (0–1)  → intensity        → pace dial (fast ↔ deliberate)
+ *       valence (0–1) → positiveness     → which mood word (happy ↔ sad)
+ *       acoustic      → mellow/organic   → warms the tone dial
+ *   • No published genre→affect TABLE exists, so the table below is
+ *     hand-authored from genre knowledge. Extensible — add rows as artists miss.
+ *
+ * Pipeline: raw tags → match GENRE_AFFECT rows → average energy/valence/acoustic
+ * → pick mood words. The signal→dial mapping itself lives in cadence.ts.
+ * ───────────────────────────────────────────────────────────────────────── */
+/* Hand-authored genre→affect table. Keys are lowercase substrings matched
+ * against the incoming tags. Values are rough but defensible per the research
+ * (energy: death-metal high → Bach low; valence: euphoric high → depressed low).
+ * Order doesn't matter — every matching row is averaged. */
+const GENRE_AFFECT = {
+    // ── high energy → ship ───────────────────────────────────────────────
+    punk: { energy: 0.9, valence: 0.6, acoustic: 0.05, moods: ["aggressive", "energetic"] },
+    metal: { energy: 0.95, valence: 0.4, acoustic: 0.02, moods: ["aggressive", "dark"] },
+    hardcore: { energy: 0.95, valence: 0.45, acoustic: 0.02, moods: ["aggressive", "energetic"] },
+    "drum and bass": { energy: 0.9, valence: 0.6, acoustic: 0.03, moods: ["energetic"] },
+    "drum & bass": { energy: 0.9, valence: 0.6, acoustic: 0.03, moods: ["energetic"] },
+    techno: { energy: 0.85, valence: 0.55, acoustic: 0.02, moods: ["energetic"] },
+    house: { energy: 0.8, valence: 0.7, acoustic: 0.05, moods: ["energetic", "uplifting"] },
+    "dance": { energy: 0.82, valence: 0.75, acoustic: 0.05, moods: ["energetic", "happy"] },
+    "electronic": { energy: 0.75, valence: 0.6, acoustic: 0.05, moods: ["energetic"] },
+    "hip hop": { energy: 0.75, valence: 0.6, acoustic: 0.1, moods: ["energetic"] },
+    "hip-hop": { energy: 0.75, valence: 0.6, acoustic: 0.1, moods: ["energetic"] },
+    rap: { energy: 0.75, valence: 0.55, acoustic: 0.1, moods: ["energetic"] },
+    rock: { energy: 0.78, valence: 0.55, acoustic: 0.15, moods: ["energetic"] },
+    pop: { energy: 0.72, valence: 0.78, acoustic: 0.15, moods: ["happy", "uplifting"] },
+    funk: { energy: 0.75, valence: 0.8, acoustic: 0.1, moods: ["happy", "energetic"] },
+    disco: { energy: 0.8, valence: 0.85, acoustic: 0.1, moods: ["happy", "uplifting"] },
+    // ── mid / groovy → ship-or-think depending on energy ─────────────────
+    "r&b": { energy: 0.55, valence: 0.6, acoustic: 0.2, moods: ["sexy", "chilled"] },
+    soul: { energy: 0.55, valence: 0.65, acoustic: 0.25, moods: ["romantic", "uplifting"] },
+    reggae: { energy: 0.6, valence: 0.75, acoustic: 0.2, moods: ["chilled", "happy"] },
+    indie: { energy: 0.6, valence: 0.55, acoustic: 0.3, moods: ["chilled"] },
+    // ── low energy, organic → think ──────────────────────────────────────
+    ambient: { energy: 0.2, valence: 0.5, acoustic: 0.6, moods: ["ethereal", "calm"] },
+    "lo-fi": { energy: 0.3, valence: 0.5, acoustic: 0.4, moods: ["chilled", "calm"] },
+    lofi: { energy: 0.3, valence: 0.5, acoustic: 0.4, moods: ["chilled", "calm"] },
+    chillout: { energy: 0.3, valence: 0.55, acoustic: 0.4, moods: ["chilled", "calm"] },
+    chill: { energy: 0.35, valence: 0.55, acoustic: 0.4, moods: ["chilled"] },
+    downtempo: { energy: 0.4, valence: 0.5, acoustic: 0.35, moods: ["chilled", "ethereal"] },
+    "trip hop": { energy: 0.45, valence: 0.4, acoustic: 0.3, moods: ["dark", "chilled"] },
+    "trip-hop": { energy: 0.45, valence: 0.4, acoustic: 0.3, moods: ["dark", "chilled"] },
+    classical: { energy: 0.3, valence: 0.5, acoustic: 0.9, moods: ["epic", "calm"] },
+    acoustic: { energy: 0.3, valence: 0.55, acoustic: 0.9, moods: ["calm", "romantic"] },
+    folk: { energy: 0.4, valence: 0.55, acoustic: 0.8, moods: ["calm", "romantic"] },
+    jazz: { energy: 0.45, valence: 0.55, acoustic: 0.6, moods: ["chilled", "sexy"] },
+    "nu jazz": { energy: 0.5, valence: 0.55, acoustic: 0.4, moods: ["chilled"] },
+    "singer-songwriter": { energy: 0.4, valence: 0.5, acoustic: 0.7, moods: ["calm", "sad"] },
+    "post-rock": { energy: 0.5, valence: 0.4, acoustic: 0.4, moods: ["epic", "ethereal"] },
+    shoegaze: { energy: 0.55, valence: 0.4, acoustic: 0.3, moods: ["ethereal", "dark"] },
+    // ── low energy, low valence → debug-leaning ──────────────────────────
+    blues: { energy: 0.45, valence: 0.35, acoustic: 0.5, moods: ["sad", "dark"] },
+    slowcore: { energy: 0.25, valence: 0.3, acoustic: 0.5, moods: ["sad", "dark"] },
+    sad: { energy: 0.3, valence: 0.2, acoustic: 0.5, moods: ["sad"] },
+    melancholy: { energy: 0.3, valence: 0.25, acoustic: 0.5, moods: ["sad", "dark"] },
+    melancholic: { energy: 0.3, valence: 0.25, acoustic: 0.5, moods: ["sad", "dark"] },
+    doom: { energy: 0.5, valence: 0.2, acoustic: 0.2, moods: ["dark", "scary"] },
+};
+/** Match a list of raw tags against the affect table and aggregate. */
+export function tagsToVibe(tags) {
+    const hits = [];
+    for (const raw of tags) {
+        const t = raw.toLowerCase();
+        for (const key in GENRE_AFFECT) {
+            if (t.includes(key)) {
+                hits.push(GENRE_AFFECT[key]);
+                break; // one row per tag — don't double-count "trip hop" as "hop"
+            }
+        }
+    }
+    if (hits.length === 0)
+        return null;
+    const energy = hits.reduce((s, a) => s + a.energy, 0) / hits.length;
+    // Mood words: collect from all hits, dedupe, keep most frequent first.
+    const moodCounts = new Map();
+    for (const h of hits)
+        for (const m of h.moods) {
+            moodCounts.set(m, (moodCounts.get(m) ?? 0) + 1);
+        }
+    const moods = [...moodCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 4)
+        .map(([m]) => m);
+    return { moods, energy };
+}

package/hooks/hooks.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/hook.js\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/stop.js\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@cullumco/cadence",
+  "version": "0.1.0",
+  "description": "Agents that read the room. Ambient context, cadence dials, and finish-line guardrails for Claude Code.",
+  "type": "module",
+  "bin": {
+    "cadence": "bin/cadence"
+  },
+  "homepage": "https://github.com/cullumco/cadence",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cullumco/cadence.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cullumco/cadence/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    ".claude-plugin",
+    "hooks",
+    "skills",
+    "dist",
+    "bin",
+    "README.md",
+    "ALPHA.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --test test/cadence.test.js",
+    "prepack": "npm run build",
+    "prepublishOnly": "node scripts/verify-alpha.mjs --no-install-smoke",
+    "release:alpha": "node scripts/release-alpha.mjs",
+    "verify:alpha": "node scripts/verify-alpha.mjs",
+    "plugin:validate": "claude plugin validate .claude-plugin/plugin.json && claude plugin validate --strict .claude-plugin/marketplace.json",
+    "hook": "node dist/hook.js",
+    "cli": "node dist/cli.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.4.0"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "spotify",
+    "context",
+    "agent",
+    "hook",
+    "cadence",
+    "context-engineering"
+  ],
+  "license": "MIT",
+  "author": "Cullum&Co"
+}

package/skills/state/SKILL.md

@@ -0,0 +1,19 @@
+---
+description: Set or inspect the user's self-reported Cadence state, such as "shipping", "thinking", or "tired but pushing".
+disable-model-invocation: true
+---
+
+# Cadence State
+
+Use this skill when the user invokes `/cadence:state`.
+
+If `$ARGUMENTS` is non-empty:
+- Run `cadence state "$ARGUMENTS"` with Bash.
+- Then tell the user the state is set and will expire after four hours.
+- Keep it to one short sentence.
+
+If `$ARGUMENTS` is empty:
+- Run `cadence state` with Bash.
+- Tell the user the current state, or that none is set.
+
+Do not explain the whole product.

package/skills/try/SKILL.md

@@ -0,0 +1,19 @@
+---
+description: Show what Cadence is doing right now and give the user a quick way to feel the difference.
+disable-model-invocation: true
+---
+
+# Try Cadence
+
+When the user invokes this skill, make Cadence immediately legible.
+
+If a `<user_state>` block is present in context:
+- Briefly summarize the visible signals and cadence dials in plain English.
+- Name one concrete way that cadence should change your response style.
+- Give the user one tiny prompt to try next that would make the difference obvious.
+
+If no `<user_state>` block is present:
+- Say Cadence does not appear to be injecting context in this session yet.
+- Tell the user to install/enable the plugin or run `cadence test` from the shell.
+
+Keep the response short, warm, and practical. Do not explain the whole product.