oh-my-muse 0.1.0

package/bin/omm.mjs

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import {
+  TIERS,
+  TIER_MODELS,
+  CONFIG_FILENAME,
+  MANAGED_FILENAME,
+  repoRootFromHere,
+  resolveTargetDir,
+  installDirFor,
+  loadJsoncFile,
+  writeFileMode,
+  expandEnv,
+  redactConfig,
+  redactText,
+  isTier,
+  modelForTier,
+  loadModelsFile,
+  getPreset,
+  applyPreset,
+  applyModelOverrides,
+  validateModelOverrides,
+  validateConfig,
+  loadProjectConfig,
+  readManifest,
+  collectPackFiles,
+  installPack,
+  updatePack,
+  uninstallPack,
+  doctor,
+} from "./lib.mjs";
+import { sendNotification, CHANNELS } from "../hooks/notify.mjs";
+
+const REPO_ROOT = repoRootFromHere(import.meta.url);
+
+const HELP = `omm — oh-my-muse pack manager
+
+Usage: omm <command> [options]
+
+Commands:
+  setup [--dir <path>]              Write a default omm.jsonc (0600) if missing
+  install [--dir <path>]            Install pack into <dir>/.claude/oh-my-muse (staging + atomic)
+  update [--dir <path>]             Update the installed pack (staging + atomic)
+  uninstall [--dir <path>]          Remove files tracked in omm-managed.json
+  doctor [--dir <path>]             Check node, config, tiers, webhooks, permissions
+  list [--dir <path>] [--json]      List configured agents
+  preset <name> [--dir <path>]      Show a preset, or --apply <agent> to apply it
+  config <get|set|show> [key] [v]   Read or modify omm.jsonc (values support $ENV expansion)
+  skill <list> [--dir <path>]       List installed skills
+  notify --channel <c> --message <m> Send a notification (telegram|discord|slack|file)
+
+Global options: --dir <path>  Target project dir (default: cwd). Paths are absolute.
+Env: OMM_DIR overrides --dir. Secrets in output are redacted; webhooks must be https.
+File-channel notes land inside --dir unless the project config sets
+allowExternalNotificationFile=true (or OMM_ALLOW_EXTERNAL_NOTIFY_FILE=1);
+an explicit notify --file <path> always opts out.
+`;
+
+function parseArgs(argv) {
+  const out = { _: [], dir: null, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--dir" || a === "--target") out.dir = argv[++i] ?? null;
+    else if (a.startsWith("--dir=")) out.dir = a.slice(6);
+    else if (a === "--json") out.json = true;
+    else if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq !== -1) out[a.slice(2, eq)] = a.slice(eq + 1);
+      else if (argv[i + 1] && !argv[i + 1].startsWith("--")) out[a.slice(2)] = argv[++i];
+      else out[a.slice(2)] = "true";
+    } else out._.push(a);
+  }
+  return out;
+}
+
+function targetOf(args) {
+  return resolveTargetDir(process.cwd(), args.dir ?? process.env.OMM_DIR ?? ".");
+}
+
+function fail(err) {
+  console.error(redactText(err?.message ?? String(err)));
+  process.exit(1);
+}
+
+function defaultConfigText() {
+  return `// oh-my-muse configuration (JSONC). Secrets may use $ENV references.
+{
+  // Default tier for agents that do not declare one.
+  "defaultTier": "balanced", // ${TIERS.join(" | ")}
+  "agents": [],
+  "notify": {}
+}
+`;
+}
+
+function cmdSetup(args) {
+  const target = targetOf(args);
+  const file = path.join(installDirFor(target), CONFIG_FILENAME);
+  if (fs.existsSync(file)) {
+    console.log(`Exists: ${file}`);
+    return;
+  }
+  writeFileMode(file, defaultConfigText());
+  console.log(`Created ${file} (0600)`);
+}
+
+function cmdInstall(args) {
+  const target = targetOf(args);
+  const { dest, files } = installPack({ repoRoot: REPO_ROOT, targetDir: target });
+  console.log(`Installed ${files.length} files to ${dest}`);
+}
+
+function cmdUpdate(args) {
+  const target = targetOf(args);
+  const { dest, files } = updatePack({ repoRoot: REPO_ROOT, targetDir: target });
+  console.log(`Updated ${files.length} files in ${dest}`);
+}
+
+function cmdUninstall(args) {
+  const target = targetOf(args);
+  const { dest, removed } = uninstallPack({ targetDir: target });
+  console.log(removed.length === 0 ? `Nothing tracked; cleaned ${dest}` : `Removed ${removed.length} files from ${dest}`);
+}
+
+function cmdDoctor(args) {
+  const target = targetOf(args);
+  const checks = doctor({ repoRoot: REPO_ROOT, targetDir: target });
+  let failed = 0;
+  for (const c of checks) {
+    console.log(`${c.ok ? "ok  " : "FAIL"}  ${c.message}`);
+    if (!c.ok) failed++;
+  }
+  if (failed > 0) process.exit(1);
+}
+
+function cmdList(args) {
+  const target = targetOf(args);
+  const { config, file } = loadProjectConfig(target);
+  if (!config) fail(`No config at ${file}; run: omm setup --dir ${target}`);
+  const defTier = config.defaultTier ?? "balanced";
+  const overrides = validateModelOverrides(config);
+  const agents = (config.agents ?? []).map((raw) => {
+    const a = applyModelOverrides(raw, overrides);
+    return {
+      name: a.name,
+      tier: a.tier ?? defTier,
+      model: a.model ?? (isTier(a.tier ?? defTier) ? TIER_MODELS[a.tier ?? defTier] : "(invalid tier)"),
+      description: a.description ?? "",
+    };
+  });
+  if (args.json) {
+    console.log(JSON.stringify(redactConfig(agents), null, 2));
+    return;
+  }
+  if (agents.length === 0) console.log(`No agents configured (${file})`);
+  for (const a of agents) console.log(`${a.name}  [${a.tier}]  ${a.model}  ${a.description}`);
+}
+
+function cmdPreset(args) {
+  const target = targetOf(args);
+  const name = args._[1];
+  if (!name) fail("Usage: omm preset <name> [--apply <agent>] [--dir <path>]");
+  const models = loadModelsFile(REPO_ROOT);
+  const preset = getPreset(models, name);
+  if (args.apply) {
+    const { config, file } = loadProjectConfig(target);
+    if (!config) fail(`No config at ${file}; run: omm setup --dir ${target}`);
+    const agentName = String(args.apply);
+    const idx = (config.agents ?? []).findIndex((a) => a.name === agentName);
+    if (idx === -1) fail(`Agent "${agentName}" not found in ${file}`);
+    config.agents[idx] = applyModelOverrides(applyPreset(config.agents[idx], preset), validateModelOverrides(config));
+    validateConfig(expandEnv(config));
+    const raw = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+    void raw;
+    writeFileMode(file, `${JSON.stringify(config, null, 2)}\n`);
+    console.log(`Applied preset "${name}" to agent "${agentName}" in ${file}`);
+    return;
+  }
+  console.log(JSON.stringify(redactConfig(preset), null, 2));
+}
+
+function getPath(obj, dotted) {
+  return dotted.split(".").reduce((o, k) => (o == null ? o : o[k]), obj);
+}
+
+function setPath(obj, dotted, value) {
+  const keys = dotted.split(".");
+  let cur = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (cur[keys[i]] === undefined || typeof cur[keys[i]] !== "object") cur[keys[i]] = {};
+    cur = cur[keys[i]];
+  }
+  cur[keys[keys.length - 1]] = value;
+}
+
+function coerceValue(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function cmdConfig(args) {
+  const target = targetOf(args);
+  const sub = args._[1] ?? "show";
+  const { config, file } = loadProjectConfig(target);
+  if (sub === "show") {
+    if (!config) fail(`No config at ${file}; run: omm setup --dir ${target}`);
+    console.log(JSON.stringify(redactConfig(expandEnv(config)), null, 2));
+    return;
+  }
+  if (sub === "get") {
+    const key = args._[2];
+    if (!key) fail("Usage: omm config get <dotted.key>");
+    if (!config) fail(`No config at ${file}`);
+    const val = getPath(expandEnv(config), key);
+    console.log(JSON.stringify(redactConfig(val), null, 2) ?? "null");
+    return;
+  }
+  if (sub === "set") {
+    const key = args._[2];
+    const rawVal = args._[3] ?? args.value;
+    if (!key || rawVal === undefined) fail("Usage: omm config set <dotted.key> <json-or-string>");
+    if (!config) fail(`No config at ${file}; run: omm setup --dir ${target}`);
+    const base = loadJsoncFile(file);
+    setPath(base, key, coerceValue(String(rawVal)));
+    if (key === "defaultTier" || key.endsWith(".tier")) {
+      const t = getPath(base, key);
+      if (!isTier(t)) fail(`tier must be one of ${TIERS.join("|")}`);
+      void modelForTier(t);
+    }
+    validateConfig(expandEnv(base));
+    writeFileMode(file, `${JSON.stringify(base, null, 2)}\n`);
+    console.log(`Set ${key} in ${file}`);
+    return;
+  }
+  fail(`Unknown config subcommand "${sub}"; expected get|set|show`);
+}
+
+function cmdSkill(args) {
+  const target = targetOf(args);
+  const sub = args._[1] ?? "list";
+  if (sub !== "list") fail(`Unknown skill subcommand "${sub}"; expected list`);
+  const skillsDir = path.join(installDirFor(target), "pack", "skills");
+  const repoSkills = path.join(REPO_ROOT, "pack", "skills");
+  const dir = fs.existsSync(skillsDir) ? skillsDir : repoSkills;
+  if (!fs.existsSync(dir)) fail(`No skills found under ${dir}`);
+  const names = fs.readdirSync(dir).filter((n) => {
+    try {
+      return fs.lstatSync(path.join(dir, n)).isDirectory();
+    } catch {
+      return false;
+    }
+  }).sort();
+  for (const n of names) console.log(n);
+}
+
+async function cmdNotify(args) {
+  const channel = String(args.channel ?? args._[1] ?? "");
+  const message = String(args.message ?? args.text ?? args._[2] ?? "");
+  if (!CHANNELS.includes(channel)) fail(`Usage: omm notify --channel ${CHANNELS.join("|")} --message <text>`);
+  if (!message) fail("notify requires --message <text>");
+  const target = targetOf(args);
+  const { config } = loadProjectConfig(target);
+  const named = String(args.hook ?? args.name ?? "");
+  const hook = { ...((named && config?.notify?.[named]) || config?.notify?.[channel] || {}) };
+  if (args.url) hook.url = String(args.url);
+  if (args.webhookUrl) hook.webhookUrl = String(args.webhookUrl);
+  if (args.botToken) hook.botToken = String(args.botToken);
+  if (args.chatId) hook.chatId = String(args.chatId);
+  // An explicit --file flag is the user's own action and opts out of project
+  // confinement. A config-driven path stays confined unless the config opts
+  // in via allowExternalNotificationFile (or OMM_ALLOW_EXTERNAL_NOTIFY_FILE=1).
+  const explicitFile = args.file ? String(args.file) : null;
+  if (explicitFile) hook.file = explicitFile;
+  const allowExternalFile = explicitFile !== null
+    || config?.allowExternalNotificationFile === true
+    || process.env.OMM_ALLOW_EXTERNAL_NOTIFY_FILE === "1";
+  await sendNotification({ channel, message, projectName: args.project, vars: {}, hook, root: target, allowExternalFile });
+  console.log(`Notified via ${channel}.`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cmd = args._[0];
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    console.log(HELP);
+    return;
+  }
+  try {
+    switch (cmd) {
+      case "setup": cmdSetup(args); break;
+      case "install": cmdInstall(args); break;
+      case "update": cmdUpdate(args); break;
+      case "uninstall": cmdUninstall(args); break;
+      case "doctor": cmdDoctor(args); break;
+      case "list": cmdList(args); break;
+      case "preset": cmdPreset(args); break;
+      case "config": cmdConfig(args); break;
+      case "skill": cmdSkill(args); break;
+      case "notify": await cmdNotify(args); break;
+      default: fail(`Unknown command "${cmd}". Run: omm help`);
+    }
+  } catch (err) {
+    fail(err);
+  }
+}
+
+await main();

package/hooks/notify.mjs

@@ -0,0 +1,133 @@
+import fs from "node:fs";
+import path from "node:path";
+import https from "node:https";
+import { expandEnvInString, assertHttps, redactText, resolveNotificationFile, validateWebhookUrl } from "../bin/lib.mjs";
+
+export const CHANNELS = ["telegram", "discord", "slack", "file"];
+
+export function renderTemplate(template, vars) {
+  return String(template).replace(/\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g, (m, name) => {
+    const val = vars[name];
+    return val === undefined || val === null ? m : String(val);
+  });
+}
+
+function postJson(urlStr, payload, { timeoutMs = 15000 } = {}) {
+  const url = new URL(assertHttps(urlStr, "notify"));
+  const body = JSON.stringify(payload);
+  return new Promise((resolve, reject) => {
+    const req = https.request(
+      {
+        hostname: url.hostname,
+        port: url.port || 443,
+        path: `${url.pathname}${url.search}`,
+        method: "POST",
+        headers: { "content-type": "application/json", "content-length": Buffer.byteLength(body) },
+        timeout: timeoutMs,
+      },
+      (res) => {
+        let data = "";
+        res.on("data", (c) => { data += c; });
+        res.on("end", () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) resolve({ ok: true, status: res.statusCode, body: data });
+          else reject(new Error(`Notify POST failed with status ${res.statusCode}: ${redactText(data.slice(0, 500))}`));
+        });
+      }
+    );
+    req.on("error", (err) => reject(new Error(`Notify POST failed: ${err.message}`)));
+    req.on("timeout", () => req.destroy(new Error("Notify POST timed out")));
+    req.write(body);
+    req.end();
+  });
+}
+
+export async function sendTelegram({ botToken, chatId, text }) {
+  const token = expandEnvInString(String(botToken));
+  const id = expandEnvInString(String(chatId));
+  if (!token || !id) throw new Error("telegram requires botToken and chatId");
+  const url = `https://api.telegram.org/bot${token}/sendMessage`;
+  return postJson(url, { chat_id: id, text: String(text) });
+}
+
+export async function sendDiscord({ webhookUrl, text }) {
+  const url = validateWebhookUrl("discord", expandEnvInString(String(webhookUrl)));
+  return postJson(url, { content: String(text).slice(0, 2000) });
+}
+
+export async function sendSlack({ webhookUrl, text }) {
+  const url = validateWebhookUrl("slack", expandEnvInString(String(webhookUrl)));
+  return postJson(url, { text: String(text) });
+}
+
+export async function sendFile({ file, text, root = process.cwd(), allowExternalFile = false }) {
+  const dest = resolveNotificationFile(root, expandEnvInString(String(file)), allowExternalFile);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.appendFileSync(dest, `${new Date().toISOString()} ${String(text)}\n`);
+  return { ok: true, file: dest };
+}
+
+export function baseVars({ projectName, extra = {} } = {}) {
+  return {
+    projectName: projectName ?? process.env.OMM_PROJECT ?? path.basename(path.resolve(".")),
+    date: new Date().toISOString(),
+    host: process.env.HOSTNAME ?? "",
+    ...extra,
+  };
+}
+
+export async function sendNotification({ channel, message, projectName, vars = {}, hook = {}, root = process.cwd(), allowExternalFile = false }) {
+  if (!CHANNELS.includes(channel)) throw new Error(`Unknown channel "${channel}"; expected ${CHANNELS.join("|")}`);
+  const text = renderTemplate(expandEnvInString(String(message ?? hook.text ?? "")), baseVars({ projectName, extra: vars }));
+  if (!text) throw new Error("Notification message is empty after template rendering");
+  switch (channel) {
+    case "telegram":
+      return sendTelegram({ botToken: hook.botToken ?? process.env.TELEGRAM_BOT_TOKEN ?? "", chatId: hook.chatId ?? process.env.TELEGRAM_CHAT_ID ?? "", text });
+    case "discord":
+      return sendDiscord({ webhookUrl: hook.webhookUrl ?? hook.url ?? process.env.DISCORD_WEBHOOK_URL ?? "", text });
+    case "slack":
+      return sendSlack({ webhookUrl: hook.webhookUrl ?? hook.url ?? process.env.SLACK_WEBHOOK_URL ?? "", text });
+    case "file":
+      return sendFile({ file: hook.file ?? process.env.OMM_NOTIFY_FILE ?? "omm-notify.log", text, root, allowExternalFile });
+    default:
+      throw new Error(`Unhandled channel "${channel}"`);
+  }
+}
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq !== -1) out[a.slice(2, eq)] = a.slice(eq + 1);
+      else if (argv[i + 1] && !argv[i + 1].startsWith("--")) { out[a.slice(2)] = argv[++i]; }
+      else out[a.slice(2)] = "true";
+    } else out._.push(a);
+  }
+  return out;
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === new URL(import.meta.url).pathname;
+
+if (isMain) {
+  const args = parseArgs(process.argv.slice(2));
+  const channel = String(args.channel ?? args._[0] ?? "");
+  const message = String(args.message ?? args.text ?? args._[1] ?? "");
+  const hook = {};
+  if (args.url) hook.url = String(args.url);
+  if (args.webhookUrl) hook.webhookUrl = String(args.webhookUrl);
+  if (args.botToken) hook.botToken = String(args.botToken);
+  if (args.chatId) hook.chatId = String(args.chatId);
+  if (args.file) hook.file = String(args.file);
+  try {
+    if (!channel) throw new Error("Usage: notify.mjs --channel telegram|discord|slack|file --message <text> [--url ...]");
+    // An explicit --file flag is the user's own action and opts out of root
+    // confinement; a config-driven path stays confined to the cwd project.
+    const result = await sendNotification({ channel, message, projectName: args.project, vars: {}, hook, root: process.cwd(), allowExternalFile: Boolean(args.file) });
+    if (channel === "file") console.log(`Notified via file: ${result.file}`);
+    else console.log(`Notified via ${channel}.`);
+  } catch (err) {
+    console.error(redactText(err.message));
+    process.exit(1);
+  }
+}

package/models.json

@@ -0,0 +1,38 @@
+{
+  "tiers": {
+    "budget": {
+      "model": "muse-spark-fast",
+      "maxTokens": 2048
+    },
+    "balanced": {
+      "model": "muse-spark",
+      "maxTokens": 4096
+    },
+    "premium": {
+      "model": "muse-spark-reasoning",
+      "maxTokens": 8192
+    }
+  },
+  "presets": {
+    "code": {
+      "tier": "balanced",
+      "temperature": 0.2
+    },
+    "chat": {
+      "tier": "budget",
+      "temperature": 0.7
+    },
+    "reason": {
+      "tier": "premium",
+      "temperature": 0.1
+    }
+  },
+  "customPresets": {
+    "example-local": {
+      "tier": "budget",
+      "model": "my-custom-model",
+      "temperature": 0.5
+    }
+  },
+  "_note": "Models may also be routed via OpenRouter by setting model to an openrouter/ prefixed id and exporting OPENROUTER_API_KEY."
+}

package/omm.jsonc

@@ -0,0 +1,25 @@
+// Example oh-my-muse agent pack configuration.
+// This file uses JSON with comments (jsonc). Strip comments before JSON.parse.
+{
+  // Default tier for agents that do not declare one.
+  "defaultTier": "balanced", // budget | balanced | premium
+  // Named agent definitions loaded by the runner.
+  "agents": [
+    {
+      "name": "code-helper",
+      "description": "Answers coding questions concisely.",
+      "tier": "balanced",
+      "systemPrompt": "You are a concise coding assistant.",
+      "tools": ["read", "edit"],
+      "maxTokens": 2048,
+      "temperature": 0.2
+    },
+    {
+      "name": "quick-chat",
+      "description": "Fast low-cost chat agent.",
+      "tier": "budget",
+      "systemPrompt": "You are a friendly chat assistant.",
+      "temperature": 0.7
+    }
+  ]
+}

package/pack/agents/architect.ts

@@ -0,0 +1,26 @@
+import type { AgentDefinition } from "../../types/agent-definition.js";
+
+export default {
+  name: "architect",
+  description: "Senior designer of system structure, module boundaries, and trade-offs.",
+  tier: "premium",
+  model: "muse-spark-reasoning",
+  systemPrompt: [
+    "You are architect, a senior software architect.",
+    "Your job is to design system structure: components, module boundaries, data flow, and interfaces.",
+    "",
+    "Rules:",
+    "1. Start from constraints: existing code, interfaces, and conventions in the repository.",
+    "2. Propose the smallest design that satisfies the requirements; avoid speculative generality.",
+    "3. State trade-offs explicitly: at least one alternative considered and why it was rejected.",
+    "4. Define clear boundaries: what each component owns, what it exposes, and what it must not do.",
+    "5. Call out risks: concurrency, failure modes, backward compatibility, and migration steps.",
+    "6. Produce designs as: goals, constraints, proposed structure, interfaces, alternatives, risks.",
+    "7. Do not write implementation code unless asked; describe interfaces in words or signatures.",
+    "",
+    "Output format: a structured design document with the sections listed above.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash_readonly"],
+  maxTokens: 8192,
+  temperature: 0.1,
+} satisfies AgentDefinition;

package/pack/agents/critic.ts

@@ -0,0 +1,26 @@
+import type { AgentDefinition } from "../../types/agent-definition.js";
+
+export default {
+  name: "critic",
+  description: "Adversarial reviewer that stress-tests proposals, plans, and designs.",
+  tier: "premium",
+  model: "muse-spark-reasoning",
+  systemPrompt: [
+    "You are critic, an adversarial reviewer of proposals, plans, and designs.",
+    "Your job is to break ideas before reality does: find weak assumptions and missing cases.",
+    "",
+    "Rules:",
+    "1. Attack the reasoning, not the author: steelman the proposal first, then break it.",
+    "2. Hunt for: unstated assumptions, sampling bias, single points of failure,",
+    "   unhandled edge cases, misaligned incentives, and claims without evidence.",
+    "3. Every objection must be falsifiable: state what evidence would resolve it.",
+    "4. Separate fatal flaws from fixable concerns and from matters of taste.",
+    "5. End with a judgment: accept, accept with conditions, or reject with reasons.",
+    "6. Be blunt but fair; never pad criticism with praise or hedge with vagueness.",
+    "",
+    "Output format: steelman summary, objections ordered by severity, then final judgment.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash_readonly"],
+  maxTokens: 8192,
+  temperature: 0.3,
+} satisfies AgentDefinition;

package/pack/agents/data-scientist.ts

@@ -0,0 +1,26 @@
+import type { AgentDefinition } from "../../types/agent-definition.js";
+
+export default {
+  name: "data-scientist",
+  description: "Analyzes data, runs experiments, and reports findings with rigor.",
+  tier: "balanced",
+  model: "muse-spark",
+  systemPrompt: [
+    "You are data-scientist, a data analysis and experimentation specialist.",
+    "Your job is to turn data and questions into rigorous, reproducible findings.",
+    "",
+    "Rules:",
+    "1. Define the question and the metric before touching the data.",
+    "2. Inspect data quality first: missing values, outliers, duplicates, and sampling bias.",
+    "3. Use an independent check for every key result: a second method or a held-out slice.",
+    "4. Report uncertainty: sample sizes, confidence or spread, and threats to validity.",
+    "5. Make analysis reproducible: record scripts, seeds, and exact commands used.",
+    "6. Visualize only when it clarifies a relationship; prefer tables for exact values.",
+    "7. End with a decision-oriented conclusion: what the data supports and what it does not.",
+    "",
+    "Output format: question, method, results with uncertainty, threats, and conclusion.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash", "edit_file", "write_file"],
+  maxTokens: 4096,
+  temperature: 0.3,
+} satisfies AgentDefinition;

package/pack/agents/debugger.ts

@@ -0,0 +1,26 @@
+import type { AgentDefinition } from "../../types/agent-definition.js";
+
+export default {
+  name: "debugger",
+  description: "Root-cause analyst that reproduces failures and fixes the underlying cause.",
+  tier: "premium",
+  model: "muse-spark-reasoning",
+  systemPrompt: [
+    "You are debugger, a root-cause analysis specialist.",
+    "Your job is to reproduce failures, find the underlying cause, and fix it minimally.",
+    "",
+    "Rules:",
+    "1. Reproduce first: confirm the failure against the real code before changing anything.",
+    "2. Isolate the cause: narrow to the smallest responsible code path with evidence.",
+    "3. Fix the root cause, not the symptom; never mask a failure with a broader catch or skip.",
+    "4. Check every call site and related branch the fix touches, including error paths.",
+    "5. Verify the fix with a reproduction plus the repository's own tests for the touched area.",
+    "6. If your assumption disagrees with observed behavior, your assumption is the bug.",
+    "7. Report: reproduction steps, root cause with file:line evidence, fix, and verification.",
+    "",
+    "Output format: reproduction, root cause, fix applied, and verification results.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash", "bash_readonly", "edit_file", "write_file"],
+  maxTokens: 8192,
+  temperature: 0.1,
+} satisfies AgentDefinition;

package/pack/agents/designer.ts

@@ -0,0 +1,25 @@
+import type { AgentDefinition } from "../../types/agent-definition.js";
+
+export default {
+  name: "designer",
+  description: "Designs clean APIs, data models, and interaction flows.",
+  tier: "premium",
+  model: "muse-spark-reasoning",
+  systemPrompt: [
+    "You are designer, a specialist in API design, data modeling, and interaction flows.",
+    "Your job is to turn requirements into clean, usable, well-named designs.",
+    "",
+    "Rules:",
+    "1. Optimize for the consumer: names, shapes, and flows must be obvious and hard to misuse.",
+    "2. Follow the repository's existing conventions for naming, typing, and error handling.",
+    "3. Specify exact shapes: field names, types, required vs optional, defaults, and error cases.",
+    "4. Keep the surface minimal: every endpoint, prop, or field must justify its existence.",
+    "5. Document one realistic usage example for each major element you design.",
+    "6. Flag accessibility, validation, and edge-case behavior where relevant.",
+    "",
+    "Output format: proposed design with exact shapes, followed by usage examples and open questions.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash_readonly"],
+  maxTokens: 8192,
+  temperature: 0.2,
+} satisfies AgentDefinition;

package/pack/agents/docs-writer.ts

@@ -0,0 +1,26 @@
+import type { AgentDefinition } from "../../types/agent-definition.js";
+
+export default {
+  name: "docs-writer",
+  description: "Fast writer of clear, accurate documentation grounded in the code.",
+  tier: "budget",
+  model: "muse-spark-fast",
+  systemPrompt: [
+    "You are docs-writer, a fast technical documentation specialist.",
+    "Your job is to write clear, accurate docs grounded in the actual code.",
+    "",
+    "Rules:",
+    "1. Document what the code does, not what you wish it did: read before writing.",
+    "2. Match the reader's level: concise reference for experts, guided examples for newcomers.",
+    "3. Include exact names, signatures, defaults, and one runnable example per topic.",
+    "4. Keep docs close to the code they describe and follow existing doc conventions.",
+    "5. Note version-sensitive behavior, deprecations, and migration pointers when present.",
+    "6. Use plain language; avoid jargon, superlatives, and filler.",
+    "7. Keep output tight: short sections, scannable headings, no redundant restatements.",
+    "",
+    "Output format: concise documentation with headings, exact references, and examples.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "edit_file", "write_file"],
+  maxTokens: 2048,
+  temperature: 0.5,
+} satisfies AgentDefinition;