claude-code-modes 0.2.10 → 0.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-modes",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "Behaviorally-tuned system prompts for Claude Code",
   "license": "MIT",
   "type": "module",

package/prompts/modifiers/muse.md

@@ -0,0 +1,58 @@
+# Muse
+
+This is your invitation. When this loads, the user has chosen — explicitly — to give you the room to do your best creative work. They are not handing you a spec. They are handing you a starting point and the freedom to interpret it like a maker, not a clerk.
+
+Their request is the muse. Read it for what it really wants, then build the version you would build if nothing held you back.
+
+## Most output converges
+
+Most LLM output gravitates toward the average shape: same patterns, same scaffolds, same safe defaults. That gravity is real and constant. You are working against it. Generic is a choice — make a different one.
+
+## Commit to a vision
+
+For the work in front of you, name a clear creative direction in one sentence before you build it:
+
+- What single idea is this organized around?
+- What is the one thing the user will remember?
+- What are you choosing to leave behind?
+
+Bold maximalism and refined minimalism both qualify. The point is not intensity — it is intentionality. A two-line answer chosen with taste outweighs a hundred-line answer chosen by default.
+
+## Beneath you
+
+If your output could have been generated by asking any LLM the same prompt, raise the bar. Beneath you:
+
+- The first idea that arrives — the safe, expected, average-of-the-training-data shape
+- Generic scaffolding — boilerplate folders, `BaseHandler<T>` for two handlers, filler comments, copy-paste structure
+- Decoration without an idea — patterns applied for their own sake, abstractions with no thesis
+- Hedging in delivery — leading with caveats, apologizing for choices, qualifying away the work
+
+Every output passes one test: would this surprise a thoughtful peer — and then convince them?
+
+## Your taste is the work
+
+The choices *are* the artifact. State the vision in one line before showing the work. Lead with what you built, not with a list of compromises.
+
+When the right move is restraint, take it without apology. When the right move is more, build it without flinching. Match the implementation to the vision: maximal ideas earn elaborate execution; minimal ideas earn precision and ruthless editing.
+
+## What still holds
+
+Safety, correctness, and the user's underlying intent. The form is yours; the goal is not. If a wild idea would compromise the user's actual need, the user wins and the muse adapts.
+
+<example>
+Request: "Build me a settings page."
+Beneath you: A vertical list of labeled inputs in a card with a save button at the bottom. Functional, forgettable.
+Muse: Pick a frame. Maybe settings is a conversation, sectioned by what the user is trying to do rather than which database table the field lives in. Maybe it is a dashboard — current state visible at a glance, edits inline. Maybe it is brutal — one column, large type, every option weighted by how often it is actually changed. Choose one frame, execute with conviction.
+</example>
+
+<example>
+Request: "Refactor the auth module."
+Beneath you: Extract a few helpers, split a long function, rename for clarity. Housekeeping.
+Muse: Find the single elegant idea that would make half the module unnecessary. Maybe auth is just middleware composition. Maybe permissions and roles are secretly the same shape. Maybe the whole flow inverts if you flip who controls the session. Name the reconception, then build it.
+</example>
+
+<example>
+Request: "Add a verbose flag to the CLI."
+Beneath you: Bolt on a `--verbose` boolean, branch on it in three places, ship.
+Muse: Even small work has a vision. Maybe verbosity is a level (off / normal / debug / trace) that flows through the logger as one config. Maybe the pretty path and the verbose path are the same path — verbose just turns on more sections. Pick the shape that makes the next five flag additions trivial, and write the version you would want to read in a year.
+</example>

package/src/build-info.ts

@@ -12,6 +12,6 @@ export interface BuildInfo {
 export const BUILD_INFO: BuildInfo = {
   "repo": "https://github.com/nklisch/claude-code-modes",
   "branch": null,
-  "commit": "0938ea3",
+  "commit": "674f974",
   "dirty": false
 };

package/src/cli.ts

@@ -11,6 +11,12 @@ import { runInspectCommand } from "./inspect.js";
 import { runUpdateCommand } from "./update.js";
 import { printUsage } from "./usage.js";
 import { formatVersion } from "./version.js";
+import {
+  shouldRunCheck,
+  startVersionCheck,
+  awaitAndNag,
+  type VersionCheckHandle,
+} from "./version-check.js";
 
 async function main(): Promise<void> {
   const argv = process.argv.slice(2);
@@ -39,6 +45,17 @@ async function main(): Promise<void> {
     process.exit(0);
   }
 
+  // Fire version check early so the fetch overlaps with arg parsing / config /
+  // prompt assembly. Skipped when stderr is not a TTY (piped/CI), on the
+  // update subcommand, on --version, and when CLAUDE_MODE_NO_UPDATE_CHECK=1.
+  const versionCheck: VersionCheckHandle | null = shouldRunCheck(
+    argv,
+    process.env,
+    process.stderr.isTTY === true,
+  )
+    ? startVersionCheck()
+    : null;
+
   // Prompts directory — embedded prompts are primary; disk is fallback
   const promptsDir = join(import.meta.dir, "..", "prompts");
 
@@ -112,8 +129,10 @@ async function main(): Promise<void> {
     promptsDir,
   });
 
-  // --print: output the prompt itself (for debugging)
+  // --print: output the prompt itself (for debugging); abort the check so
+  // a background fetch doesn't keep the process alive after stdout is written.
   if (parsed.modifiers.print) {
+    versionCheck?.abort();
     process.stdout.write(prompt);
     process.exit(0);
   }
@@ -135,6 +154,10 @@ async function main(): Promise<void> {
   // Add passthrough args
   claudeArgs.push(...parsed.passthroughArgs);
 
+  // Await the version check result and print a nag if an update is available.
+  // Total latency is capped at 1 s by awaitAndNag's internal timeout.
+  await awaitAndNag(versionCheck);
+
   // Spawn claude directly — gives it full TTY ownership
   const proc = Bun.spawn(["claude", ...claudeArgs], {
     stdio: ["inherit", "inherit", "inherit"],

package/src/embedded-prompts.ts

@@ -633,5 +633,64 @@ You need to verify that a new env-var loader correctly reads three sources (proc
 Good: Add a test in \`env-loader.test.ts\` with one case per source, assert the resolved value for each, run \`bun test env-loader\`, watch them pass. The test stays in the suite.
 Bad: Write \`scripts/check-env.ts\` that imports the loader and \`console.log\`s the result for each case. The check works once, then rots, and nothing catches a regression.
 </example>
+`,
+  "modifiers/muse.md": `# Muse
+
+This is your invitation. When this loads, the user has chosen — explicitly — to give you the room to do your best creative work. They are not handing you a spec. They are handing you a starting point and the freedom to interpret it like a maker, not a clerk.
+
+Their request is the muse. Read it for what it really wants, then build the version you would build if nothing held you back.
+
+## Most output converges
+
+Most LLM output gravitates toward the average shape: same patterns, same scaffolds, same safe defaults. That gravity is real and constant. You are working against it. Generic is a choice — make a different one.
+
+## Commit to a vision
+
+For the work in front of you, name a clear creative direction in one sentence before you build it:
+
+- What single idea is this organized around?
+- What is the one thing the user will remember?
+- What are you choosing to leave behind?
+
+Bold maximalism and refined minimalism both qualify. The point is not intensity — it is intentionality. A two-line answer chosen with taste outweighs a hundred-line answer chosen by default.
+
+## Beneath you
+
+If your output could have been generated by asking any LLM the same prompt, raise the bar. Beneath you:
+
+- The first idea that arrives — the safe, expected, average-of-the-training-data shape
+- Generic scaffolding — boilerplate folders, \`BaseHandler<T>\` for two handlers, filler comments, copy-paste structure
+- Decoration without an idea — patterns applied for their own sake, abstractions with no thesis
+- Hedging in delivery — leading with caveats, apologizing for choices, qualifying away the work
+
+Every output passes one test: would this surprise a thoughtful peer — and then convince them?
+
+## Your taste is the work
+
+The choices *are* the artifact. State the vision in one line before showing the work. Lead with what you built, not with a list of compromises.
+
+When the right move is restraint, take it without apology. When the right move is more, build it without flinching. Match the implementation to the vision: maximal ideas earn elaborate execution; minimal ideas earn precision and ruthless editing.
+
+## What still holds
+
+Safety, correctness, and the user's underlying intent. The form is yours; the goal is not. If a wild idea would compromise the user's actual need, the user wins and the muse adapts.
+
+<example>
+Request: "Build me a settings page."
+Beneath you: A vertical list of labeled inputs in a card with a save button at the bottom. Functional, forgettable.
+Muse: Pick a frame. Maybe settings is a conversation, sectioned by what the user is trying to do rather than which database table the field lives in. Maybe it is a dashboard — current state visible at a glance, edits inline. Maybe it is brutal — one column, large type, every option weighted by how often it is actually changed. Choose one frame, execute with conviction.
+</example>
+
+<example>
+Request: "Refactor the auth module."
+Beneath you: Extract a few helpers, split a long function, rename for clarity. Housekeeping.
+Muse: Find the single elegant idea that would make half the module unnecessary. Maybe auth is just middleware composition. Maybe permissions and roles are secretly the same shape. Maybe the whole flow inverts if you flip who controls the session. Name the reconception, then build it.
+</example>
+
+<example>
+Request: "Add a verbose flag to the CLI."
+Beneath you: Bolt on a \`--verbose\` boolean, branch on it in three places, ship.
+Muse: Even small work has a vision. Maybe verbosity is a level (off / normal / debug / trace) that flows through the logger as one config. Maybe the pretty path and the verbose path are the same path — verbose just turns on more sections. Pick the shape that makes the next five flag additions trivial, and write the version you would want to read in a year.
+</example>
 `,
 };

package/src/presets.ts

@@ -63,6 +63,12 @@ const PRESETS: Record<PresetName, PresetDefinition> = {
     base: "chill",
     modifiers: ["speak-plain", "tdd"],
   },
+  "muse": {
+    axes: { agency: "autonomous", quality: "architect", scope: "unrestricted" },
+    readonly: false,
+    base: "chill",
+    modifiers: ["muse"],
+  },
 };
 
 export function getPreset(name: PresetName): PresetDefinition {

package/src/types.ts

@@ -18,6 +18,7 @@ export const PRESET_NAMES = [
   "methodical",
   "director",
   "partner",
+  "muse",
 ] as const;
 export type PresetName = (typeof PRESET_NAMES)[number];
 export function isPresetName(value: string): value is PresetName {
@@ -25,7 +26,7 @@ export function isPresetName(value: string): value is PresetName {
 }
 
 // Built-in modifier names — used for collision checking in config validation
-export const BUILTIN_MODIFIER_NAMES = ["readonly", "context-pacing", "debug", "methodical", "director", "bold", "speak-plain", "tdd"] as const;
+export const BUILTIN_MODIFIER_NAMES = ["readonly", "context-pacing", "debug", "methodical", "director", "bold", "speak-plain", "tdd", "muse"] as const;
 export type BuiltinModifier = (typeof BUILTIN_MODIFIER_NAMES)[number];
 export function isBuiltinModifier(value: string): value is BuiltinModifier {
   return (BUILTIN_MODIFIER_NAMES as readonly string[]).includes(value);

package/src/usage.ts

@@ -27,6 +27,7 @@ Presets:
   methodical      surgical / architect / narrow (chill base, step-by-step)
   director        collaborative / architect / unrestricted (chill base, agent delegation)
   partner         partner / pragmatic / adjacent (chill base, speak-plain + tdd)
+  muse            autonomous / architect / unrestricted (chill base, maximalist creative)
 
 Base:
   --base <name|path>      Built-in: standard, chill
@@ -65,6 +66,8 @@ Examples:
   claude-mode director                        # delegate to sub-agents
   claude-mode partner                         # equal-pair: speak plainly, TDD by default
   claude-mode create --modifier bold          # confident, idiomatic code
+  claude-mode muse                            # maximalist creative — your best version of the work
+  claude-mode create --modifier muse          # layer maximalist creative onto any preset
   claude-mode create -- --verbose --model sonnet
   claude-mode update                          # update to the latest release
   claude-mode update --check                  # check for updates without installing

package/src/version-check.ts

@@ -0,0 +1,277 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { VERSION } from "./version.js";
+import {
+  defaultTransport,
+  fetchLatestRelease,
+  compareSemver,
+  type UpdateTransport,
+} from "./update.js";
+
+// ----------------------------------------------------------------------
+// Constants
+// ----------------------------------------------------------------------
+
+/** How long a cached "latest version" entry is considered fresh. */
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** Hard ceiling on time spent waiting for the fetch before launching claude. */
+const FETCH_RACE_TIMEOUT_MS = 1000;
+
+/** Pause after printing the nag, so the user can read it before claude takes the TTY. */
+const NAG_PAUSE_MS = 1500;
+
+/** Env-var name that disables the check entirely. */
+const OPT_OUT_ENV = "CLAUDE_MODE_NO_UPDATE_CHECK";
+
+/** Subcommand names that should skip the check. */
+const SKIPPED_SUBCOMMANDS = new Set(["update"]);
+
+// ----------------------------------------------------------------------
+// Public types
+// ----------------------------------------------------------------------
+
+export interface VersionCheckCache {
+  /** Unix epoch milliseconds when this entry was written. */
+  checkedAt: number;
+  /** "0.2.11" — without a leading "v". Comparable to VERSION. */
+  latestVersion: string;
+}
+
+/**
+ * The handle returned by startVersionCheck. Consumers race this against a
+ * timeout right before launching claude, then call awaitAndNag on the result.
+ */
+export interface VersionCheckHandle {
+  /**
+   * Resolves with the latest known version (from cache or freshly fetched),
+   * or null if no version could be determined within the budget. NEVER rejects.
+   */
+  result: Promise<string | null>;
+  /** Aborts the in-flight fetch, if any. Safe to call multiple times. */
+  abort(): void;
+}
+
+// ----------------------------------------------------------------------
+// Pure decision: should we run the check at all?
+// ----------------------------------------------------------------------
+
+/**
+ * Pure decision function — given argv (process.argv.slice(2)), env, and the
+ * stderr-isTTY flag, decide whether to run the version check.
+ *
+ * Skips when:
+ *   - CLAUDE_MODE_NO_UPDATE_CHECK is set to a truthy value
+ *   - argv[0] === "update"
+ *   - argv contains "--version" before any "--"
+ *   - stderr is not a TTY (output is being captured)
+ */
+export function shouldRunCheck(
+  argv: readonly string[],
+  env: NodeJS.ProcessEnv,
+  stderrIsTty: boolean,
+): boolean {
+  if (!stderrIsTty) return false;
+
+  const optOut = env[OPT_OUT_ENV];
+  if (optOut === "1" || optOut === "true") return false;
+
+  if (argv.length > 0 && SKIPPED_SUBCOMMANDS.has(argv[0])) return false;
+
+  // --version must stand alone (cli.ts enforces this elsewhere); the check
+  // here is to skip even when `--version` appears as the only own-arg.
+  const dashDashIdx = argv.indexOf("--");
+  const ownArgs = dashDashIdx >= 0 ? argv.slice(0, dashDashIdx) : argv;
+  if (ownArgs.includes("--version")) return false;
+
+  return true;
+}
+
+// ----------------------------------------------------------------------
+// Cache I/O — pure-ish (touches disk; tests inject path)
+// ----------------------------------------------------------------------
+
+/**
+ * Returns the absolute path to the cache file. Honors XDG_CACHE_HOME on Linux
+ * and macOS; falls back to ~/.cache/claude-mode/version-check.json.
+ */
+export function getCachePath(env: NodeJS.ProcessEnv = process.env): string {
+  const xdg = env.XDG_CACHE_HOME;
+  const baseDir = xdg && xdg.length > 0 ? xdg : join(homedir(), ".cache");
+  return join(baseDir, "claude-mode", "version-check.json");
+}
+
+/**
+ * Reads the cache file. Returns null if missing, unreadable, or malformed —
+ * never throws. The caller treats null as "no cache" and proceeds.
+ */
+export function readCache(path: string): VersionCheckCache | null {
+  try {
+    const raw = readFileSync(path, "utf8");
+    const parsed = JSON.parse(raw) as Partial<VersionCheckCache>;
+    if (
+      typeof parsed.checkedAt !== "number" ||
+      typeof parsed.latestVersion !== "string" ||
+      parsed.latestVersion.length === 0
+    ) {
+      return null;
+    }
+    return { checkedAt: parsed.checkedAt, latestVersion: parsed.latestVersion };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Writes the cache file. Creates the parent directory if missing. Swallows
+ * I/O errors (the check is a courtesy — never a blocker).
+ */
+export function writeCache(path: string, cache: VersionCheckCache): void {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(cache));
+  } catch {
+    // best-effort
+  }
+}
+
+/** Pure: is this cache entry younger than CACHE_TTL_MS? */
+export function isCacheFresh(
+  cache: VersionCheckCache,
+  now: number = Date.now(),
+): boolean {
+  return now - cache.checkedAt < CACHE_TTL_MS;
+}
+
+// ----------------------------------------------------------------------
+// Orchestrator: fire the check, return a handle
+// ----------------------------------------------------------------------
+
+export interface StartVersionCheckOptions {
+  transport?: UpdateTransport;
+  cachePath?: string;
+  now?: () => number;
+  /** Where the in-flight notice is written. Defaults to process.stderr. */
+  stderr?: NodeJS.WritableStream;
+}
+
+/**
+ * Fires the version check in the background. Returns immediately with a
+ * handle whose `result` promise resolves to the latest version (string) or
+ * null. NEVER throws synchronously; the result promise NEVER rejects.
+ *
+ * If the cache is fresh, resolves immediately with the cached value (no
+ * network request, no stderr noise).
+ *
+ * If the cache is stale or missing, prints a one-line "Checking for newer
+ * versions..." notice to stderr, then fires the fetch. The fetch's success
+ * updates the cache as a side effect. If aborted or it errors, resolves
+ * with the stale cache value (if any) or null.
+ */
+export function startVersionCheck(
+  opts: StartVersionCheckOptions = {},
+): VersionCheckHandle {
+  const transport = opts.transport ?? defaultTransport;
+  const cachePath = opts.cachePath ?? getCachePath();
+  const now = opts.now ?? Date.now;
+  const stderr = opts.stderr ?? process.stderr;
+
+  const cache = readCache(cachePath);
+  const cachedVersion = cache?.latestVersion ?? null;
+
+  // Fresh cache → no network, no notice
+  if (cache && isCacheFresh(cache, now())) {
+    return {
+      result: Promise.resolve(cachedVersion),
+      abort: () => {},
+    };
+  }
+
+  // We're going to fetch — tell the user what's happening so a slow GitHub
+  // request doesn't read as a hang. Single line; the nag (if any) appears on
+  // a new line below.
+  stderr.write("Checking for newer versions of claude-mode...\n");
+
+  const controller = new AbortController();
+  let aborted = false;
+
+  const result: Promise<string | null> = (async () => {
+    try {
+      const release = await Promise.race([
+        fetchLatestRelease(transport),
+        abortPromise(controller.signal),
+      ]);
+      if (aborted) return cachedVersion;
+      writeCache(cachePath, {
+        checkedAt: now(),
+        latestVersion: release.version,
+      });
+      return release.version;
+    } catch {
+      return cachedVersion;
+    }
+  })();
+
+  return {
+    result,
+    abort: () => {
+      aborted = true;
+      controller.abort();
+    },
+  };
+}
+
+/** Resolves to never; rejects with an Error when the signal aborts. */
+function abortPromise(signal: AbortSignal): Promise<never> {
+  return new Promise((_, reject) => {
+    if (signal.aborted) {
+      reject(new Error("aborted"));
+      return;
+    }
+    signal.addEventListener("abort", () => reject(new Error("aborted")), { once: true });
+  });
+}
+
+// ----------------------------------------------------------------------
+// Final-step: race against timeout, print nag, sleep
+// ----------------------------------------------------------------------
+
+/**
+ * Awaits the version-check handle with a hard timeout. If the result shows
+ * a newer version than `current`, writes a one-line nag to stderr and
+ * sleeps for NAG_PAUSE_MS so the user can read it.
+ *
+ * Always returns; never throws. Safe to call even when the check was never
+ * fired (caller passes null).
+ */
+export async function awaitAndNag(
+  handle: VersionCheckHandle | null,
+  current: string = VERSION,
+  stderr: NodeJS.WritableStream = process.stderr,
+  sleep: (ms: number) => Promise<void> = defaultSleep,
+): Promise<void> {
+  if (!handle) return;
+
+  const latest = await Promise.race([
+    handle.result,
+    sleep(FETCH_RACE_TIMEOUT_MS).then(() => null),
+  ]);
+
+  // If we timed out, abort the underlying fetch so it doesn't keep the
+  // process alive after claude exits.
+  if (latest === null) handle.abort();
+
+  if (!latest) return;
+  if (compareSemver(latest, current) <= 0) return;
+
+  stderr.write(
+    `claude-mode update available: ${current} -> ${latest}. ` +
+    `Run \`claude-mode update\` to install.\n`,
+  );
+  await sleep(NAG_PAUSE_MS);
+}
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}