@cullumco/cadence 0.1.3 → 0.1.5

package/.claude-plugin/marketplace.json

@@ -21,7 +21,7 @@
         "agents",
         "claude-code"
       ],
-      "homepage": "https://cullumco.github.io/cadence/",
+      "homepage": "https://cadence.cullum.co/",
       "repository": "https://github.com/cullumco/cadence",
       "license": "MIT"
     }

package/.claude-plugin/plugin.json

@@ -1,13 +1,13 @@
 {
   "name": "cadence",
   "displayName": "Cadence",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Ambient context for Claude Code: embodied signals, cadence dials, and finish-line guardrails. macOS-only alpha.",
   "author": {
     "name": "Cullum&Co",
     "url": "https://cullum.co"
   },
-  "homepage": "https://cullumco.github.io/cadence/",
+  "homepage": "https://cadence.cullum.co/",
   "repository": "https://github.com/cullumco/cadence",
   "license": "MIT",
   "keywords": [

package/README.md

@@ -9,10 +9,12 @@ 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.
 
-**macOS-only (alpha).** Most signals read the Mac around you; other platforms
-degrade to self-report + dials + time/git.
+**Built for the Mac (alpha).** The richest ambient signals read the Mac around
+you. Other platforms still get the dial-movers — prompt intent, self-report,
+git, time/day, typing tempo — and can link Spotify for music
+(`cadence spotify connect`).
 
-A [Cullum&Co](https://cullum.co) project · [cullumco.github.io/cadence](https://cullumco.github.io/cadence/)
+A [Cullum&Co](https://cullum.co) project · [cadence.cullum.co](https://cadence.cullum.co)
 
 ## What it does
 
@@ -21,8 +23,8 @@ Before Claude sees your prompt, Cadence injects a `<user_state>` block:
 ```
 <user_state>
   signals:
-    music: "Loose" — Daniel Caesar (Spotify)
-    vibe: sexy, chilled
+    music: "You Fail Me" — Converge (Spotify)
+    vibe: aggressive, energetic
     self_report: "two beers, shipping"
   cadence:  # inferred from signals, advisory
     { pace=fast tone=warm posture=decisive proactivity=act-freely }
@@ -45,17 +47,20 @@ defers to what you actually typed.
 options, a trade-off table, and a closing "Would you like me to implement one
 of these?"
 
-**With Cadence, shipping cadence** — hardcore at 3 commits/hr, state set to
-`"ship mode"` → `{ pace=fast posture=decisive proactivity=act-freely }`. You
-get the call, made: exponential backoff with jitter, three attempts, here's
-the diff, tests pass.
+**With Cadence, shipping cadence** — hardcore at 3 commits/hr, a "let's ship
+it" earlier in your prompt (or `cadence report "ship mode"`) →
+`{ pace=fast posture=decisive proactivity=act-freely }`. You get the call,
+made: exponential backoff with jitter, three attempts, here's the diff, tests
+pass.
 
-**With Cadence, thinking cadence** — ambient music, state set to
-`"thinking through tradeoffs"` → `{ pace=deliberate posture=exploratory }`.
-You get the options laid out patiently, trade-offs actually explored, no
-pressure to pick one yet.
+**With Cadence, thinking cadence** — ambient music, "thinking through
+tradeoffs" in your own words → `{ pace=deliberate posture=exploratory }`. You
+get the options laid out patiently, trade-offs actually explored, no pressure
+to pick one yet.
 
-Same words. The room around them changed, and the agent finally saw it.
+Same words. The room around them changed, and the agent finally saw it. No
+setup required for the intent read — your prompt itself is a signal; a
+deliberate self-report just outranks it.
 
 ## How it works
 
@@ -75,13 +80,19 @@ Same words. The room around them changed, and the agent finally saw it.
      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, self-report, and git move the dials (git reads *what you're
-   doing*: 3+ commits/hr → fast pace, mid-conflict → verify-first); the rest
-   render as context the agent reads (flavor). Self-report always outranks
-   inference — "I'm shipping" beats a mid-conflict read.
+     Spotify login, no API key, no Premium on macOS. Off the Mac, link Spotify
+     once with `cadence spotify connect` (browser OAuth, opt-in). Music moves
+     three dials — energy → pace + posture, organic texture → warm tone.
+   - **self-report** — what you tell it: `cadence report "two beers, shipping"`.
+   - **intent** — read from the prompt you just typed: "let's ship this" →
+     decisive/act-freely, "help me debug" → verify-first. Cross-platform, no
+     setup; this is what makes the same prompt read differently per room.
+
+   Time/day, self-report, git, and prompt intent move the dials (git reads
+   *what you're doing*: 3+ commits/hr → fast pace, mid-conflict → verify-first);
+   the rest render as context the agent reads (flavor). Self-report outranks
+   prompt intent outranks git — your deliberate "I'm shipping" beats a stray
+   "ship" in a prompt, which beats a mid-conflict read.
 2. **Dials** — four independent knobs, each `low | medium | high`, inferred from
    the signals (or pinned by you):
    - **pace** — deliberate ↔ fast
@@ -92,17 +103,20 @@ Same words. The room around them changed, and the agent finally saw it.
    *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
+The dials move mostly independently — high-energy-but-mellow music reads as
 "fast pace, warm tone," something a single ship/think/debug label could never
-express.
+express. Music is the deliberate exception: it moves pace, posture, and tone
+together (you move *with* the music) but never proactivity — whether to act
+without checking in stays your call, not the soundtrack's.
 
 ## Requirements
 
-- **macOS.** Cadence is mac-only for the alpha: music (AppleScript
-  now-playing), battery, dark mode, displays, wifi, and Focus/DND all read the
-  Mac around you. On other platforms it still runs — self-report, dials,
-  time/day, and git work anywhere, the rest degrade silently — but the product
-  is built for the Mac.
+- **Built for the Mac.** The richest ambient probes — music via AppleScript
+  now-playing, battery, dark mode, displays, wifi, Focus/DND, focused app —
+  read the Mac around you. On other platforms Cadence still runs and still
+  moves the dials: prompt intent, self-report, git, time/day, and typing tempo
+  work anywhere, Spotify can be linked for music, and the Mac-only probes
+  degrade silently.
 - **Node 20+**
 - Claude Code for the alpha adapter
 
@@ -114,15 +128,20 @@ In Claude Code:
 /plugin marketplace add cullumco/cadence
 /plugin install cadence@cadence
 /reload-plugins
-/cadence:try
+/cadence:setup
 ```
 
-Then set a self-report so you can feel the difference:
+`/cadence:setup` is a short conversation, not a wizard — tell Claude how you
+work, pick which signals you're willing to share, and see exactly what gets
+injected. Or skip it and just set a self-report:
 
 ```text
 /cadence:state shipping, locked in
 ```
 
+Change your mind anytime: `/cadence:pause` silences everything instantly,
+`/cadence:resume` brings it back.
+
 Alpha testers running from source — while `@cullumco/cadence` is pending npm
 publish — see [`ALPHA.md`](ALPHA.md).
 
@@ -138,14 +157,22 @@ 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.
 
+**Off macOS?** Run `cadence spotify connect <clientId>` once: register a Spotify
+app (add `http://127.0.0.1:8888/callback` as a redirect URI), and Cadence does
+the browser OAuth and stores a refresh token. From then on it reads your
+currently-playing track cross-platform — identity only, vibe still from
+MusicBrainz, no audio-features.
+
 ## Daily use
 
 ```bash
-cadence state "two beers, shipping"   # set self-reported state (expires in 4h)
-cadence state                         # print current self-report
+cadence report "two beers, shipping"   # set self-reported state (expires in 2h)
+cadence report                         # print current self-report
 cadence clear                         # clear it
 cadence test                          # preview exactly what the hook would inject
 cadence signals                       # every signal — live value, or why it's absent
+cadence pause                         # silence all hooks (state survives untouched)
+cadence resume                        # start reading the room again
 ```
 
 `cadence signals` is the legibility view: it never goes silent. Every signal
@@ -153,13 +180,23 @@ Cadence knows how to read is listed with its live value, or the exact reason
 it's absent — opt-in not taken, below a render threshold, missing permission
 (Focus needs Full Disk Access), or platform-gated.
 
-From inside Claude Code, the plugin skill gives the same self-report path:
+From inside Claude Code, the plugin skills cover the same ground without
+leaving the conversation:
 
 ```text
+/cadence:setup                    # guided, conversational setup — shape the
+                                  # influence and pick your opt-in signals
 /cadence:state two beers, shipping
-/cadence:try
+/cadence:try                      # what is Cadence seeing right now?
+/cadence:pause                    # instant silence — prompts go through untouched
+/cadence:resume                   # back to reading the room
 ```
 
+`/cadence:setup` is the recommended first run inside Claude Code: instead of a
+fixed wizard, you tell Claude how you work in plain language and it drives the
+CLI for you — state, dial pins, and which opt-in signals you're willing to
+share.
+
 ### Driving the dials by hand
 
 The dials are inferred, but you can pin any of them — your pin wins, the rest
@@ -200,52 +237,63 @@ state through other agent surfaces.
 
 ## Alpha release checklist
 
-Before publishing:
+`@cullumco/cadence` is live on npm; each release is the same gated flow:
 
 ```bash
-npm run verify:alpha
-npm publish --dry-run
-npm run release:alpha
+npm run verify:alpha    # build + plugin validate + tests + dry-pack + install smoke test
+npm run release:alpha   # the full gate, then npm publish
+# then: write .github/releases/vX.Y.Z.md and dispatch the Release workflow —
+# it creates the tag + GitHub Release from that file
+gh workflow run Release -f tag=vX.Y.Z -f target=<bump-commit>
 ```
 
-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`.
+CI runs the same gate on every push/PR to `main`
+(`.github/workflows/verify.yml`); `.github/workflows/release.yml` turns each
+release into a tag + GitHub Release whose body is the committed notes file.
 
 ## What's next
 
 See [`BACKLOG.md`](BACKLOG.md). Highlights:
 
-- **Git nudges** — the highest-value next step: built but dormant, they move
-  the dials from *what you said* to *what you're actually doing*.
-- **More signals** — candidates on the bench:
-  - **calendar density** — a meeting in 20 minutes should read as `pace=fast,
-    posture=decisive`; a clear afternoon as room to explore.
-  - **typing tempo** — prompt rhythm beyond length: rapid-fire short prompts vs.
-    one long considered one.
-  - **focused app** — what's frontmost next to the terminal (docs? a profiler?
-    Slack?).
+- **Git nudges** — *shipped:* they move the dials from *what you said* to *what
+  you're actually doing* (`3+ commits/hr → fast pace`, `mid-conflict →
+  verify-first`), applied below self-report so your explicit word still wins.
+- **Prompt intent** — *shipped:* ship/think/debug read straight from the prompt
+  you just typed, so the "same prompt, different room" behavior fires without a
+  separate `cadence report` step.
+- **Opt-in signals** — anything privacy-adjacent stays off until you turn it on
+  (`cadence enable <signal>`):
+  - **typing tempo** — *shipped (opt-in):* prompt rhythm beyond length —
+    rapid-fire short prompts read fast, one long considered prompt reads
+    deliberate.
+  - **focused app** — *shipped (opt-in, macOS):* the frontmost non-terminal app
+    (a browser, Slack, a PDF) renders as flavor. Read at prompt-submit, so it
+    only speaks when something other than your terminal/IDE is genuinely in
+    front. Flavor for now; a dial nudge stays a candidate.
+  - **esoteric flavor** — *shipped (opt-in):* `moon` phase (computed offline)
+    and a daily `horoscope` for your sign. Render-only — they color the room,
+    they never steer the work.
   - **deeper Focus** — manual + scheduled Focus detection ship now; geofenced/
     iPhone-synced Focus leaves no local trace and stays undetectable.
-- **After-the-fact injection** — the first cut ships: a `PostToolUse` hook
-  watches git-ish commands and speaks exactly once when the repo enters or
-  leaves a merge/rebase conflict ("this is debug now" / "conflict resolved").
-  Next material events: failing-test transitions, reset/force-push thrash.
-- **Opt-in flavor providers** — horoscope, moon phase, for those who want them.
+- **Calendar density** — intentionally *not* built: Cadence targets solo
+  builders deep in a project, not people racing between meetings.
+- **After-the-fact injection** — shipped: a `PostToolUse` hook watches git-ish
+  commands and speaks once per transition — entering/leaving a merge/rebase
+  conflict, and destructive-op thrash (reset --hard streaks, force-pushes).
+  Next material event: failing-test transitions.
 
 ## Caveats
 
-- **macOS-only.** The alpha targets the Mac: music, battery, dark mode,
-  displays, wifi, and Focus are all macOS probes. Other platforms get
-  self-report + dials + time/git; everything else degrades silently.
-- **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.
+- **Built for the Mac.** The richest ambient probes (music-via-OS, battery,
+  dark mode, displays, wifi, Focus, focused app) are macOS. Other platforms
+  keep the dial-movers — intent, self-report, git, time/day, typing tempo,
+  linked Spotify — and the rest degrades silently.
+- **Spotify's audio-features API is not used** — Spotify deprecated it for new
+  apps (2024) and gated dev-mode behind Premium (2026), so vibe comes from
+  MusicBrainz, not Spotify. On macOS, Cadence reads what's playing at the OS
+  level (no Spotify account at all). The only Spotify API call is the still-live
+  `currently-playing` endpoint, and only if you opt in via `cadence spotify` to
+  get music off the Mac — identity only, never audio-features.
 
 ## License
 

package/dist/cadence.js

@@ -18,9 +18,10 @@ const LEVELS = ["low", "medium", "high"];
  *
  * Signals you can read (any subset present):
  *   report   { text }                  ← you said it; trust it most
+ *   intent   { kind }                  ← read from the prompt you just typed
  *   music    { vibe, energy }          ← energy 0–1 drives pace; vibe colors tone
- *   git      { commitsLastHour, ... }  ← work rhythm (when the provider lands)
- *   activity { minSinceLastPrompt, promptLength }
+ *   git      { commitsLastHour, ... }  ← work rhythm
+ *   activity { minSinceLastPrompt, promptLength, tempo }
  *
  * A working baseline is below so it runs end-to-end. The mapping is yours.
  * ───────────────────────────────────────────────────────────────────────── */
@@ -35,8 +36,9 @@ 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 intent = state.signals.find((s) => s.source === "intent");
     const activity = state.signals.find((s) => s.source === "activity");
-    const ambient = state.signals.find((s) => s.source === "ambient");
+    const environment = state.signals.find((s) => s.source === "environment");
     // Start neutral; each signal nudges individual dials.
     const c = {
         pace: "medium",
@@ -44,31 +46,40 @@ export function deriveCadence(state) {
         posture: "medium",
         proactivity: "medium",
     };
-    // ── ambient → soft nudges FIRST (weakest), so stronger signals below win ──
+    // ── environment → 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)
+    if (environment) {
+        if (environment.hour >= 22 || environment.hour < 6)
             c.pace = "low"; // late → gentler
-        if (ambient.partOfDay === "early morning")
+        if (environment.partOfDay === "early morning")
             c.pace = "low"; // easing in
-        if (ambient.isWeekend)
+        if (environment.isWeekend)
             c.tone = "low"; // looser on weekends
-        if (ambient.weather && /rain|snow|fog|storm|cloud/.test(ambient.weather)) {
+        if (environment.weather && /rain|snow|fog|storm|cloud/.test(environment.weather)) {
             c.tone = "low"; // gloomy out → warmer in
         }
-        if (ambient.onBattery)
+        if (environment.onBattery)
             c.pace = "high"; // mobile/untethered → quick hits
     }
-    // ── music energy → pace (only pace; leave tone/posture to other signals) ──
+    // ── music → pace + posture + tone (move WITH the music) ───────────────────
+    // Deliberately moves three dials, not one: a track has a tempo (pace), an
+    // intensity (decisive vs. spacious posture), and a texture (warm tone). It
+    // leaves PROACTIVITY alone — whether to act without checking in is the user's
+    // call (self-report/intent/git), never the soundtrack's. See CLAUDE.md.
     if (music?.energy != null) {
         if (music.energy >= 0.7)
-            c.pace = "high";
+            c.pace = "high"; // driving → fast
         else if (music.energy <= 0.4)
-            c.pace = "low";
+            c.pace = "low"; // mellow → deliberate
+        if (music.energy >= 0.75)
+            c.posture = "high"; // high intensity → decisive momentum
+        else if (music.energy <= 0.35)
+            c.posture = "low"; // ambient → spacious, exploratory
     }
-    // mellow/organic vibe words warm the tone
-    if (music?.vibe && /\b(calm|chilled|ethereal|romantic|warm)\b/.test(music.vibe)) {
+    // organic/acoustic texture, or mellow vibe words, warm the tone
+    if ((music?.acoustic != null && music.acoustic >= 0.5) ||
+        (music?.vibe && /\b(calm|chilled|ethereal|romantic|warm|sexy)\b/.test(music.vibe))) {
         c.tone = "low";
     }
     // ── git → pace / proactivity (what you're DOING, not what you said) ───────
@@ -81,6 +92,29 @@ export function deriveCadence(state) {
         if (git.conflicted)
             c.proactivity = "low"; // verify, don't barrel
     }
+    // ── prompt intent → posture / proactivity / tone (what you JUST typed) ────
+    // Read from the live prompt, so the "same prompt, different room" behavior
+    // fires without a separate CLI step. Stronger than git (what you're doing),
+    // weaker than self-report below (a deliberate, out-of-band declaration), so
+    // an explicit `cadence report "thinking"` still beats a stray "ship it".
+    if (intent?.kind) {
+        if (intent.kind === "ship") {
+            c.posture = "high";
+            c.proactivity = "high";
+            c.pace = "high";
+        }
+        else if (intent.kind === "think") {
+            c.posture = "low";
+            c.pace = "low";
+        }
+        else if (intent.kind === "debug") {
+            c.posture = "low";
+            c.proactivity = "low";
+        }
+        else if (intent.kind === "focus") {
+            c.tone = "high";
+        }
+    }
     // ── self-report → posture / proactivity / tone (you know your state) ──────
     if (report) {
         const t = report.text.toLowerCase();
@@ -103,8 +137,15 @@ export function deriveCadence(state) {
             c.tone = "high";
     }
     // Still-dormant candidate nudges (see BACKLOG):
-    //   ambient focus on → proactivity high (heads-down = fewer check-ins)
-    // ── activity → pace (returning from a break = slow back down) ─────────────
+    //   environment focus on → proactivity high (heads-down = fewer check-ins)
+    // ── activity → pace (motor tempo + return-from-break) ─────────────────────
+    // typing tempo (opt-in): rapid-fire short prompts read as fast; one long
+    // considered prompt reads as deliberate. Only set when the user opted in.
+    if (activity?.tempo === "rapid")
+        c.pace = "high";
+    else if (activity?.tempo === "considered")
+        c.pace = "low";
+    // a long gap since the last prompt = returning from a break = slow back down.
     if (activity?.minSinceLastPrompt != null && activity.minSinceLastPrompt > 30) {
         c.pace = "low";
     }