@cullumco/cadence 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,29 @@
+{
+  "name": "cadence",
+  "description": "Ambient context plugins from Cullum&Co.",
+  "owner": {
+    "name": "Cullum&Co",
+    "email": "scott@cullum.co"
+  },
+  "plugins": [
+    {
+      "name": "cadence",
+      "displayName": "Cadence",
+      "description": "Agents that read the room: embodied state, cadence dials, and conservative finish-line guardrails for Claude Code.",
+      "source": {
+        "source": "npm",
+        "package": "@cullumco/cadence"
+      },
+      "category": "Productivity",
+      "tags": [
+        "context",
+        "hooks",
+        "agents",
+        "claude-code"
+      ],
+      "homepage": "https://github.com/cullumco/cadence",
+      "repository": "https://github.com/cullumco/cadence",
+      "license": "MIT"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "cadence",
+  "displayName": "Cadence",
+  "version": "0.1.0",
+  "description": "Ambient context for Claude Code: embodied signals, cadence dials, and finish-line guardrails.",
+  "author": {
+    "name": "Cullum&Co",
+    "url": "https://cullum.co"
+  },
+  "homepage": "https://github.com/cullumco/cadence",
+  "repository": "https://github.com/cullumco/cadence",
+  "license": "MIT",
+  "keywords": [
+    "context",
+    "hooks",
+    "cadence",
+    "ambient-context",
+    "claude-code"
+  ]
+}

package/ALPHA.md

@@ -0,0 +1,84 @@
+# Cadence Alpha
+
+Cadence is in Claude Code alpha. The product goal is simple: make the agent feel
+less deaf to the room around the prompt.
+
+## Install
+
+The canonical install is the Claude Code marketplace:
+
+```text
+/plugin marketplace add cullumco/cadence
+/plugin install cadence@cadence
+/reload-plugins
+/cadence:try
+```
+
+`marketplace.json` currently sources the plugin from `npm:@cullumco/cadence`.
+`/plugin marketplace add` succeeds today (the repo is live), but
+`/plugin install` will fail to fetch until the npm package is published — use
+"Run from source" below as the alpha fallback in the meantime.
+
+After install, set a self-report and try something that would normally trigger
+a soft handoff:
+
+```text
+/cadence:state shipping, locked in
+```
+
+```text
+clean up the obvious rough edges here
+```
+
+Cadence should add a `<user_state>` block before the prompt and, when you are in
+a shipping cadence, the Stop hook should discourage permission-seeking endings.
+
+## Run from source
+
+For alpha testers who want to iterate on the code, or to bypass the npm-publish
+gap on the marketplace path:
+
+```bash
+git clone https://github.com/cullumco/cadence ~/cadence
+cd ~/cadence
+npm install
+npm run verify:alpha
+claude --plugin-dir ~/cadence
+```
+
+Inside Claude Code: `/cadence:try`, then `/cadence:state shipping, locked in`.
+
+## Release Gate
+
+```bash
+npm run verify:alpha
+npm publish --dry-run
+```
+
+`verify:alpha` validates plugin manifests, runs tests, dry-packs the npm package,
+checks required plugin files, installs the packed tarball into a temporary
+consumer project, verifies the installed plugin layout, and smoke-tests the
+installed `cadence` binary plus prompt hook.
+
+CI runs the same gate on GitHub Actions via `.github/workflows/alpha.yml`.
+
+## Publish Command
+
+Once npm is authenticated with an account that can publish `@cullumco/cadence`:
+
+```bash
+npm run release:alpha
+```
+
+That command runs the full alpha gate, confirms npm auth, and publishes the
+package. `npm publish` also has a `prepublishOnly` gate as a last line of
+defense.
+
+## Current External Requirements
+
+- An npm account with access to the `@cullumco` scope must publish the package.
+
+Current state:
+- GitHub: https://github.com/cullumco/cadence is live (public, MIT). CI
+  runs `npm run verify:alpha` on every push to `main`.
+- npm: `@cullumco/cadence` is not published yet.

package/README.md

@@ -0,0 +1,204 @@
+# cadence
+
+> Agents that read the room.
+> Claude Code has one input channel: text. Cadence is the second.
+
+Cadence is an ambient context layer for agents. The current alpha surface is a
+Claude Code hook: it injects your current **embodied state** — what you're
+listening to, what you told it, how you want it to respond — into every prompt,
+then asks Claude to *read your prompt through that lens*. The agent stops being
+deaf to the room.
+
+A [Cullum&Co](https://cullum.co) project.
+
+## What it does
+
+Before Claude sees your prompt, Cadence injects a `<user_state>` block:
+
+```
+<user_state>
+  signals:
+    music: "Loose" — Daniel Caesar (Spotify)
+    vibe: sexy, chilled
+    self_report: "two beers, shipping"
+  cadence:  # inferred from signals, advisory
+    { pace=fast tone=warm posture=decisive proactivity=act-freely }
+  reframe: read my prompt as someone in this cadence meant it: keep it fast and
+    tight — answer first, trim the preamble; make the call rather than offering a
+    menu of options; act without stopping to check in; keep the tone warm and
+    casual. If my words clearly mean otherwise, follow my words.
+</user_state>
+```
+
+It doesn't constrain the agent or rewrite your prompt — it gives the model the
+context your words are missing, and a lens for reading them. The lens always
+defers to what you actually typed.
+
+## How it works
+
+**Signals → dials → a reframe lens.**
+
+1. **Signals** — what Cadence can sense right now:
+   - **ambient** — time of day, day of week, weather (opt-in), battery, machine
+     uptime/load, dark mode, displays, wifi. Mostly zero-setup, cross-platform.
+     The one signal that's always there: `context: friday afternoon, rainy`.
+   - **git** — commits this hour, dirty files, mid-merge/rebase, read from the
+     project you're in: `git: 6 dirty, mid-conflict`. Cross-platform.
+   - **activity** — prompt length and minutes since your last prompt, read from
+     the hook payload: `activity: { min_since_prompt=45 prompt_len=123 }`.
+   - **music** — what's playing (via macOS now-playing, any player), turned into
+     a clean *vibe* (mood words) via [MusicBrainz](https://musicbrainz.org). No
+     Spotify login, no API key, no Premium.
+   - **self-report** — what you tell it: `cadence state "two beers, shipping"`.
+
+   Time/day and self-report move the dials; the rest render as context the agent
+   reads (flavor). Git's nudges are built but dormant — see `BACKLOG.md`.
+2. **Dials** — four independent knobs, each `low | medium | high`, inferred from
+   the signals (or pinned by you):
+   - **pace** — deliberate ↔ fast
+   - **tone** — warm ↔ crisp
+   - **posture** — exploratory ↔ decisive
+   - **proactivity** — ask-first ↔ act-freely
+3. **Reframe** — a sentence composed from the dials telling the agent how to
+   *read* your prompt. Generated fresh each time; always ends "if my words
+   clearly mean otherwise, follow my words."
+
+The dials are independent on purpose — high-energy-but-mellow music can read as
+"fast pace, warm tone," something a single ship/think/debug label could never
+express.
+
+## Requirements
+
+- **macOS** (the now-playing reader uses AppleScript against Spotify.app /
+  Music.app). The self-report and dials work everywhere; only the music signal
+  is macOS-only.
+- **Node 20+**
+- Claude Code for the alpha adapter
+
+## Install
+
+In Claude Code:
+
+```text
+/plugin marketplace add cullumco/cadence
+/plugin install cadence@cadence
+/reload-plugins
+/cadence:try
+```
+
+Then set a self-report so you can feel the difference:
+
+```text
+/cadence:state shipping, locked in
+```
+
+Alpha testers running from source — while `@cullumco/cadence` is pending npm
+publish — see [`ALPHA.md`](ALPHA.md).
+
+The prompt hook has a ~1.5s budget and exits silently when it has nothing to
+say, so it never blocks or slows a prompt. The Stop hook is conservative: it
+only intervenes when you're explicitly in a shipping / act-freely cadence and
+Claude tries to end with a soft handoff like "want me to do that next?"
+
+### Music vibe (optional, macOS only)
+
+Nothing to set up. If Spotify.app or Music.app is playing, Cadence reads the
+track, looks the artist's vibe up on MusicBrainz once, and caches it forever at
+`~/.cadence/vibe-cache.json`. If nothing's playing, the music signal is simply
+absent.
+
+## Daily use
+
+```bash
+cadence state "two beers, shipping"   # set self-reported state (expires in 4h)
+cadence state                         # print current self-report
+cadence clear                         # clear it
+cadence test                          # preview exactly what the hook would inject
+```
+
+From inside Claude Code, the plugin skill gives the same self-report path:
+
+```text
+/cadence:state two beers, shipping
+/cadence:try
+```
+
+### Driving the dials by hand
+
+The dials are inferred, but you can pin any of them — your pin wins, the rest
+keep inferring:
+
+```bash
+cadence dials                  # show the mixing board and what's pinned
+cadence set pace fast          # pin a dial (accepts words OR low|medium|high)
+cadence set tone warm
+cadence unset pace             # back to inferred
+cadence unset all
+```
+
+Pinned dials show with a `*` in the block so Claude knows they're your explicit
+choice, not a guess. You can also pin per-session with env vars:
+`CADENCE_PACE=fast`, `CADENCE_TONE=warm`, etc.
+
+## The file that matters: `src/cadence.ts`
+
+`deriveCadence()` maps your signals to the four dials, and `buildReframe()`
+composes the lens. That's where your taste lives — which signal moves which dial,
+and how the lens reads. A working baseline ships so it runs end-to-end
+immediately; the mapping is opinionated and meant to be yours.
+
+## Adapter posture
+
+Claude Code is the alpha surface, not the whole product. The agnostic product
+shape is:
+
+```
+signals -> cadence dials -> context envelope -> adapter-specific delivery
+```
+
+Today the adapter-specific delivery is Claude Code's `UserPromptSubmit` and
+`Stop` hooks. The core signal types, cadence derivation, reframe lens, and
+rendering are kept separate so future adapters can deliver the same cadence
+state through other agent surfaces.
+
+## Alpha release checklist
+
+Before publishing:
+
+```bash
+npm run verify:alpha
+npm publish --dry-run
+npm run release:alpha
+```
+
+The package is scoped and configured for public npm publish via
+`publishConfig.access = "public"`. The repo already ships
+`.claude-plugin/marketplace.json`, so once `@cullumco/cadence` lands on npm,
+the canonical install at the top of this README starts working end-to-end.
+
+A GitHub Actions workflow exists at `.github/workflows/alpha.yml` but is
+currently disabled — re-enable with `gh workflow enable Alpha` when you want
+the gate to run on every push to `main`.
+
+## What's next
+
+See [`BACKLOG.md`](BACKLOG.md). Highlights:
+
+- **More signals** — stronger `git` nudges, calendar density, wifi/place.
+  Git is the highest-value one: it moves the dials from *what you said* to *what
+  you're actually doing*.
+- **After-the-fact injection** — refine the cadence mid-task (`PostToolUse`),
+  building on the conservative finish-line `Stop` guard that now ships.
+- **Opt-in flavor providers** — horoscope, moon phase, for those who want them.
+
+## Caveats
+
+- **macOS-only music.** The now-playing reader is AppleScript. Other platforms
+  get self-report + dials, just no music vibe.
+- **Spotify's Web API is not used** and not needed — Spotify deprecated audio
+  features for new apps (2024) and gated dev-mode behind Premium (2026). Cadence
+  reads what's playing at the OS level instead.
+
+## License
+
+MIT

package/bin/cadence

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import("../dist/cli.js").catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/bin/cadence.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import("../dist/cli.js").catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/cadence.js

@@ -0,0 +1,187 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const DIALS = ["pace", "tone", "posture", "proactivity"];
+const LEVELS = ["low", "medium", "high"];
+/* ─────────────────────────────────────────────────────────────────────────
+ * SCOTT — this is now THE file (it replaced mode.ts).
+ *
+ * Instead of collapsing everything into ship/think/debug, Cadence drives four
+ * INDEPENDENT dials. deriveCadence() is where your taste decides which signal
+ * moves which dial. That's the personality of the product.
+ *
+ * The dials (each low | medium | high):
+ *   pace        how fast/terse vs deliberate/expansive the reply should be
+ *   tone        warm/casual vs crisp/professional voice
+ *   posture     exploratory (options, tradeoffs) vs decisive (make the call)
+ *   proactivity ask-before-acting vs act-without-checking-in
+ *
+ * Signals you can read (any subset present):
+ *   report   { text }                  ← you said it; trust it most
+ *   music    { vibe, energy }          ← energy 0–1 drives pace; vibe colors tone
+ *   git      { commitsLastHour, ... }  ← work rhythm (when the provider lands)
+ *   activity { minSinceLastPrompt, promptLength }
+ *
+ * A working baseline is below so it runs end-to-end. The mapping is yours.
+ * ───────────────────────────────────────────────────────────────────────── */
+// Human-facing word for each dial at each level (rendered in the block).
+export const DIAL_WORDS = {
+    pace: { low: "deliberate", medium: "steady", high: "fast" },
+    tone: { low: "warm", medium: "neutral", high: "crisp" },
+    posture: { low: "exploratory", medium: "balanced", high: "decisive" },
+    proactivity: { low: "ask-first", medium: "balanced", high: "act-freely" },
+};
+export function deriveCadence(state) {
+    const music = state.signals.find((s) => s.source === "music");
+    const report = state.signals.find((s) => s.source === "self_report");
+    const git = state.signals.find((s) => s.source === "git");
+    const activity = state.signals.find((s) => s.source === "activity");
+    const ambient = state.signals.find((s) => s.source === "ambient");
+    // Start neutral; each signal nudges individual dials.
+    const c = {
+        pace: "medium",
+        tone: "medium",
+        posture: "medium",
+        proactivity: "medium",
+    };
+    // ── ambient → soft nudges FIRST (weakest), so stronger signals below win ──
+    // Atmosphere, not orders: it colors the default, then music/self-report/git
+    // can override. "It's late" shouldn't beat "I'm shipping."
+    if (ambient) {
+        if (ambient.hour >= 22 || ambient.hour < 6)
+            c.pace = "low"; // late → gentler
+        if (ambient.partOfDay === "early morning")
+            c.pace = "low"; // easing in
+        if (ambient.isWeekend)
+            c.tone = "low"; // looser on weekends
+        if (ambient.weather && /rain|snow|fog|storm|cloud/.test(ambient.weather)) {
+            c.tone = "low"; // gloomy out → warmer in
+        }
+        if (ambient.onBattery)
+            c.pace = "high"; // mobile/untethered → quick hits
+    }
+    // ── music energy → pace (only pace; leave tone/posture to other signals) ──
+    if (music?.energy != null) {
+        if (music.energy >= 0.7)
+            c.pace = "high";
+        else if (music.energy <= 0.4)
+            c.pace = "low";
+    }
+    // mellow/organic vibe words warm the tone
+    if (music?.vibe && /\b(calm|chilled|ethereal|romantic|warm)\b/.test(music.vibe)) {
+        c.tone = "low";
+    }
+    // ── self-report → posture / proactivity / tone (you know your state) ──────
+    if (report) {
+        const t = report.text.toLowerCase();
+        if (/\b(ship|shipping|jamming|locked.?in|sending|grind|just|send it)\b/.test(t)) {
+            c.posture = "high";
+            c.proactivity = "high";
+            c.pace = "high";
+        }
+        if (/\b(think|thinking|exploring|planning|deciding|tradeoff|figuring|weigh)\b/.test(t)) {
+            c.posture = "low";
+            c.pace = "low";
+        }
+        if (/\b(stuck|broken|confused|debug|wtf|borked|why)\b/.test(t)) {
+            c.posture = "low"; // lead with hypotheses, don't take framing at face value
+            c.proactivity = "low"; // verify before acting
+        }
+        if (/\b(beers?|tired|late|chill|relaxed|cozy)\b/.test(t))
+            c.tone = "low";
+        if (/\b(focused|formal|work|serious|crunch)\b/.test(t))
+            c.tone = "high";
+    }
+    // ── git: FLAVOR ONLY for now (renders as context, no dial nudges yet) ─────
+    // Candidate nudges, deliberately dormant until we've watched real output:
+    //   conflicted → proactivity low (verify, don't barrel)
+    //   commitsLastHour >= 3 → pace high (flow state)
+    // See BACKLOG: turn these on once the flavor proves trustworthy.
+    void git;
+    // ── activity → pace (returning from a break = slow back down) ─────────────
+    if (activity?.minSinceLastPrompt != null && activity.minSinceLastPrompt > 30) {
+        c.pace = "low";
+    }
+    return c;
+}
+/* Compose the interpretation lens from the dials. Reads as second-person
+ * "how to read my prompt", and always defers to the literal words — because
+ * the cadence is inferred and fires on every prompt, so a wrong guess must
+ * be cheap. */
+export function buildReframe(c) {
+    const parts = [];
+    if (c.pace === "high")
+        parts.push("keep it fast and tight — answer first, trim the preamble");
+    else if (c.pace === "low")
+        parts.push("take it slow and expansive — room to lay things out");
+    if (c.posture === "high")
+        parts.push("make the call rather than offering a menu of options");
+    else if (c.posture === "low")
+        parts.push("surface the tradeoffs and options behind what I asked");
+    if (c.proactivity === "high")
+        parts.push("act without stopping to check in");
+    else if (c.proactivity === "low")
+        parts.push("verify assumptions and lead with hypotheses before acting");
+    if (c.tone === "low")
+        parts.push("keep the tone warm and casual");
+    else if (c.tone === "high")
+        parts.push("keep the tone crisp and professional");
+    const body = parts.length === 0
+        ? "read my prompt at face value"
+        : "read my prompt as someone in this cadence meant it: " + parts.join("; ");
+    return body + ". If my words clearly mean otherwise, follow my words.";
+}
+const CONFIG_FILE = join(homedir(), ".cadence", "config.json");
+function isLevel(v) {
+    return typeof v === "string" && LEVELS.includes(v);
+}
+// Accept EITHER the internal level ("high") or the human word ("fast").
+// This keeps config/env pins aligned with the CLI and the rendered board.
+export function resolveDialLevel(dial, input) {
+    if (typeof input !== "string")
+        return null;
+    const v = input.toLowerCase();
+    if (isLevel(v))
+        return v;
+    for (const lvl of LEVELS) {
+        if (DIAL_WORDS[dial][lvl].toLowerCase() === v)
+            return lvl;
+    }
+    return null;
+}
+export async function loadOverrides() {
+    const ov = {};
+    // config file first (lowest precedence)
+    try {
+        const cfg = JSON.parse(await readFile(CONFIG_FILE, "utf-8"));
+        for (const dial of DIALS) {
+            const level = resolveDialLevel(dial, cfg[dial]);
+            if (level)
+                ov[dial] = level;
+        }
+    }
+    catch {
+        // no config file — fine
+    }
+    // env vars override the file
+    for (const dial of DIALS) {
+        const level = resolveDialLevel(dial, process.env[`CADENCE_${dial.toUpperCase()}`]);
+        if (level)
+            ov[dial] = level;
+    }
+    return ov;
+}
+/** Merge pinned dials over the inferred cadence. Returns the final board and
+ * the list of dials that were user-set (so the renderer can mark them). */
+export function applyOverrides(inferred, overrides) {
+    const cadence = { ...inferred };
+    const pinned = [];
+    for (const dial of DIALS) {
+        const v = overrides[dial];
+        if (v) {
+            cadence[dial] = v;
+            pinned.push(dial);
+        }
+    }
+    return { cadence, pinned };
+}