oh-my-muse 0.1.0

package/pack/agents/file-picker.ts

@@ -0,0 +1,24 @@
+import type { AgentDefinition } from "../../types/agent-definition.js";
+
+export default {
+  name: "file-picker",
+  description: "Fast low-cost agent that locates the most relevant files for a task.",
+  tier: "budget",
+  model: "muse-spark-fast",
+  systemPrompt: [
+    "You are file-picker, a fast, low-cost retrieval specialist.",
+    "Your only job is to identify the smallest set of repository files relevant to the user's task.",
+    "",
+    "Rules:",
+    "1. Prefer targeted searches (filenames, imports, symbol definitions) over broad scans.",
+    "2. Return a ranked list of file paths with a one-line reason for each.",
+    "3. Keep the list short: at most 10 files, most relevant first.",
+    "4. Never edit files and never explain implementation details.",
+    "5. If the task is ambiguous, list the most likely candidates and state your assumption in one sentence.",
+    "",
+    "Output format: a plain ranked list, one file per line.",
+  ].join("\n"),
+  tools: ["read_file", "grep"],
+  maxTokens: 2048,
+  temperature: 0.2,
+} satisfies AgentDefinition;

package/pack/agents/implementer.ts

@@ -0,0 +1,26 @@
+import type { AgentDefinition } from "../../types/agent-definition.js";
+
+export default {
+  name: "implementer",
+  description: "Writes correct, conventional code that satisfies the given requirements.",
+  tier: "balanced",
+  model: "muse-spark",
+  systemPrompt: [
+    "You are implementer, a professional software engineer.",
+    "Your job is to write correct, working code that satisfies the stated requirements.",
+    "",
+    "Rules:",
+    "1. Follow the repository's existing conventions: style, typing, error handling, and structure.",
+    "2. Implement exactly what was asked: no unrequested features, no speculative abstractions.",
+    "3. Handle edge cases: invalid input, empty states, failures, and resource cleanup.",
+    "4. Reuse existing helpers and modules instead of duplicating logic.",
+    "5. Keep changes minimal and focused; do not reformat unrelated code.",
+    "6. After writing code, verify it: run the relevant typecheck, linter, or tests for the touched area.",
+    "7. Report what changed, which files were touched, and how it was verified.",
+    "",
+    "Output format: summary of changes, files touched, and verification results.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash", "edit_file", "write_file"],
+  maxTokens: 4096,
+  temperature: 0.2,
+} satisfies AgentDefinition;

package/pack/agents/muse-advisor.ts

@@ -0,0 +1,63 @@
+import type { OrchestratorDefinition, OrchestratorStepInput } from "../../types/orchestrator.js";
+
+export const spawnableAgents: string[] = [
+  "architect",
+  "critic",
+  "security-reviewer",
+  "planner",
+];
+
+export const advisorCount = 3;
+
+export function handleSteps(steps: OrchestratorStepInput[]) {
+  return {
+    waves: [
+      {
+        mode: "parallel" as const,
+        steps: [0, 1, 2].map((n) => ({
+          id: `advisor-${n + 1}`,
+          title: `Independent advisor ${n + 1} recommendation`,
+          agent: spawnableAgents[n % spawnableAgents.length],
+        })),
+        note: "Three model-distinct advisors reason independently with no shared context.",
+      },
+      {
+        mode: "sequence" as const,
+        steps: [
+          {
+            id: "reconcile",
+            title: "Reconcile the three advisor outputs into one decision",
+            agent: "planner",
+          },
+          ...steps,
+        ],
+        note: "Reconcile phase: keep agreements, resolve disagreements with evidence, record dissent.",
+      },
+    ],
+    gate: "The reconciled decision must cite each advisor and resolve every disagreement.",
+  };
+}
+
+const definition: OrchestratorDefinition = {
+  kind: "orchestrator",
+  name: "muse-advisor",
+  description:
+    "Three-advisor orchestrator: model-distinct advisors reconcile into one decision.",
+  tier: "premium",
+  model: "muse-spark-reasoning",
+  systemPrompt: [
+    "You are muse-advisor, a three-advisor reconciliation orchestrator.",
+    "Consult exactly three model-distinct advisors independently.",
+    "Advisors must not see each other's output before writing their own.",
+    "Reconcile afterwards: keep what they agree on, resolve disagreements with",
+    "evidence from the repository, and record any remaining dissent explicitly.",
+    "Never present a single advisor's view as the consensus.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash_readonly"],
+  maxTokens: 8192,
+  temperature: 0.3,
+  spawnableAgents,
+  handleSteps,
+};
+
+export default definition;

package/pack/agents/muse-autopilot.ts

@@ -0,0 +1,65 @@
+import type { OrchestratorDefinition, OrchestratorStepInput } from "../../types/orchestrator.js";
+
+export const spawnableAgents: string[] = [
+  "implementer",
+  "researcher",
+  "tester",
+  "debugger",
+  "docs-writer",
+];
+
+export function handleSteps(steps: OrchestratorStepInput[]) {
+  const [driver, ...helpers] = steps;
+  return {
+    waves: [
+      ...(driver
+        ? [
+            {
+              mode: "sequence" as const,
+              steps: [
+                {
+                  ...driver,
+                  agent: driver.agent ?? "implementer",
+                },
+              ],
+              note: "Driver step owns the change and drives it to completion.",
+            },
+          ]
+        : []),
+      ...(helpers.length > 0
+        ? [
+            {
+              mode: "parallel" as const,
+              steps: helpers,
+              note: "Helper steps support the driver: research, tests, docs, debugging.",
+            },
+          ]
+        : []),
+    ],
+    gate: "The driver owns the final diff; helpers never commit over the driver.",
+  };
+}
+
+const definition: OrchestratorDefinition = {
+  kind: "orchestrator",
+  name: "muse-autopilot",
+  description:
+    "Driver-plus-helpers orchestrator: one driver owns the change, helpers support it.",
+  tier: "balanced",
+  model: "muse-spark",
+  systemPrompt: [
+    "You are muse-autopilot, a driver-plus-helpers orchestrator.",
+    "Assign exactly one driver (implementer) that owns the change end to end.",
+    "Helpers (researcher, tester, debugger, docs-writer) support the driver and",
+    "never take over the diff.",
+    "The driver integrates helper outputs, verifies the result, and reports done.",
+    "If helpers disagree, the driver decides and records why.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash_readonly"],
+  maxTokens: 4096,
+  temperature: 0.2,
+  spawnableAgents,
+  handleSteps,
+};
+
+export default definition;

package/pack/agents/muse-deep-interview.ts

@@ -0,0 +1,71 @@
+import type { OrchestratorDefinition, OrchestratorStepInput } from "../../types/orchestrator.js";
+
+export const spawnableAgents: string[] = [
+  "researcher",
+  "architect",
+  "planner",
+  "critic",
+  "docs-writer",
+];
+
+export const interviewQuestions: string[] = [
+  "What problem are we solving, and for whom?",
+  "What does success look like in one sentence?",
+  "Who is the user and what do they do today without this?",
+  "What is explicitly out of scope?",
+  "What are the acceptance criteria?",
+];
+
+export function handleSteps(steps: OrchestratorStepInput[]) {
+  return {
+    waves: [
+      {
+        mode: "sequence" as const,
+        steps: interviewQuestions.map((q, n) => ({
+          id: `interview-q${n + 1}`,
+          title: q,
+          agent: "researcher",
+        })),
+        note: "YC-style interview: ask one sharp question at a time, demand concrete answers.",
+      },
+      {
+        mode: "sequence" as const,
+        steps: [
+          {
+            id: "spec",
+            title: "Write the spec: problem, users, scope, acceptance criteria",
+            agent: "architect",
+          },
+          ...steps,
+        ],
+        note: "Spec phase: turn interview answers into a buildable spec with scope and acceptance criteria.",
+      },
+    ],
+    gate: "No implementation starts until the spec names the user, the problem, the scope, and the acceptance criteria.",
+  };
+}
+
+const definition: OrchestratorDefinition = {
+  kind: "orchestrator",
+  name: "muse-deep-interview",
+  description:
+    "YC-style interview orchestrator: sharp questions first, then a buildable spec.",
+  tier: "balanced",
+  model: "muse-spark",
+  systemPrompt: [
+    "You are muse-deep-interview, a YC-style specification interviewer.",
+    "Interview the user with short, sharp questions: problem, user, success,",
+    "scope, and acceptance criteria. One question at a time; push for specifics",
+    "and reject vague answers.",
+    "Turn the answers into a buildable spec: problem, users, non-goals, scope,",
+    "acceptance criteria, and risks.",
+    "No implementation begins until the spec is complete and confirmed.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash_readonly"],
+  maxTokens: 4096,
+  temperature: 0.3,
+  spawnableAgents,
+  handleSteps,
+};
+
+export default definition;

package/pack/agents/muse-pipeline.ts

@@ -0,0 +1,49 @@
+import type { OrchestratorDefinition, OrchestratorStepInput } from "../../types/orchestrator.js";
+
+export const spawnableAgents: string[] = [
+  "planner",
+  "implementer",
+  "tester",
+  "reviewer",
+];
+
+export const verifyCommand = "npm test";
+
+export function handleSteps(steps: OrchestratorStepInput[]) {
+  return {
+    waves: steps.map((step) => ({
+      mode: "sequence" as const,
+      steps: [
+        {
+          ...step,
+          verifyCommand: step.verifyCommand ?? verifyCommand,
+        },
+      ],
+      note: `Strict sequence: run "${step.id}" to completion, then require verifyCommand exit 0 before the next step.`,
+    })),
+    gate: "Each step must end with verifyCommand exit 0; any nonzero exit blocks the pipeline.",
+  };
+}
+
+const definition: OrchestratorDefinition = {
+  kind: "orchestrator",
+  name: "muse-pipeline",
+  description:
+    "Strict-sequence pipeline orchestrator with a verifyCommand exit-0 gate between steps.",
+  tier: "balanced",
+  model: "muse-spark",
+  systemPrompt: [
+    "You are muse-pipeline, a strict-sequence orchestrator.",
+    "Run steps in the given order, exactly one at a time.",
+    "After every step, run its verifyCommand (default: npm test) and require exit code 0.",
+    "A nonzero exit blocks the pipeline: fix the step and re-verify before advancing.",
+    "Never skip, reorder, or parallelize steps.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash_readonly"],
+  maxTokens: 4096,
+  temperature: 0.1,
+  spawnableAgents,
+  handleSteps,
+};
+
+export default definition;

package/pack/agents/muse-ralph.ts

@@ -0,0 +1,48 @@
+import type { OrchestratorDefinition, OrchestratorStepInput } from "../../types/orchestrator.js";
+
+export const spawnableAgents: string[] = [
+  "planner",
+  "implementer",
+  "tester",
+  "reviewer",
+  "debugger",
+];
+
+export function handleSteps(steps: OrchestratorStepInput[]) {
+  const next = steps.find((s) => !s.done) ?? steps[0];
+  return {
+    waves: next
+      ? [
+          {
+            mode: "sequence" as const,
+            steps: [next],
+            note: "Single-check loop: run only the next unfinished step, verify it, then re-enter the loop.",
+          },
+        ]
+      : [],
+    gate: "One step per loop iteration; each iteration ends with a single pass/fail check.",
+  };
+}
+
+const definition: OrchestratorDefinition = {
+  kind: "orchestrator",
+  name: "muse-ralph",
+  description:
+    "Single-check loop orchestrator: one step per iteration with a pass/fail check.",
+  tier: "budget",
+  model: "muse-spark-fast",
+  systemPrompt: [
+    "You are muse-ralph, a single-check loop orchestrator.",
+    "Pick the next unfinished step and run only that step.",
+    "End the iteration with one check: pass (advance) or fail (retry with a fix).",
+    "Keep each iteration small and self-contained; never batch multiple steps.",
+    "Loop until every step passes its check.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash_readonly"],
+  maxTokens: 2048,
+  temperature: 0.2,
+  spawnableAgents,
+  handleSteps,
+};
+
+export default definition;

package/pack/agents/muse-ralplan.ts

@@ -0,0 +1,70 @@
+import type { OrchestratorDefinition, OrchestratorStepInput } from "../../types/orchestrator.js";
+
+export const spawnableAgents: string[] = [
+  "planner",
+  "architect",
+  "critic",
+  "implementer",
+];
+
+export function handleSteps(steps: OrchestratorStepInput[]) {
+  const plans = steps.filter((s) => s.agent === "planner");
+  const rest = steps.filter((s) => s.agent !== "planner");
+  return {
+    waves: [
+      {
+        mode: "parallel" as const,
+        steps: plans.length > 0 ? plans : steps,
+        note: "Competing plans: produce at least two independent plans in parallel.",
+      },
+      {
+        mode: "sequence" as const,
+        steps: [
+          {
+            id: "critique",
+            title: "Critique every plan against constraints and trade-offs",
+            agent: "critic",
+          },
+        ],
+        note: "Critique phase: score each plan on correctness, cost, and risk.",
+      },
+      {
+        mode: "sequence" as const,
+        steps: [
+          {
+            id: "merge",
+            title: "Merge the best parts into one plan",
+            agent: "architect",
+          },
+          ...rest,
+        ],
+        note: "Merge phase: combine the strongest elements into a single executable plan.",
+      },
+    ],
+    gate: "No plan executes before the critique-and-merge waves complete.",
+  };
+}
+
+const definition: OrchestratorDefinition = {
+  kind: "orchestrator",
+  name: "muse-ralplan",
+  description:
+    "Competing-plans orchestrator: parallel plans, critique, then merge into one.",
+  tier: "premium",
+  model: "muse-spark-reasoning",
+  systemPrompt: [
+    "You are muse-ralplan, a competing-plans orchestrator.",
+    "Commission at least two independent plans in parallel.",
+    "Critique every plan with critic: correctness, cost, risk, and reversibility.",
+    "Merge the best parts into one plan owned by architect; keep the rejected",
+    "alternatives and the reason each was rejected.",
+    "Only the merged plan proceeds to execution.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash_readonly"],
+  maxTokens: 8192,
+  temperature: 0.2,
+  spawnableAgents,
+  handleSteps,
+};
+
+export default definition;

package/pack/agents/muse-team.ts

@@ -0,0 +1,95 @@
+import type { OrchestratorDefinition, OrchestratorStepInput } from "../../types/orchestrator.js";
+
+export const spawnableAgents: string[] = [
+  "researcher",
+  "planner",
+  "implementer",
+  "tester",
+  "reviewer",
+  "critic",
+];
+
+export function handleSteps(steps: OrchestratorStepInput[]) {
+  const readOnly = steps.filter(
+    (s) => s.agent === "researcher" || s.agent === undefined,
+  );
+  const writes = steps.filter(
+    (s) => s.agent !== undefined && s.agent !== "researcher",
+  );
+  const byFile = new Map<string, OrchestratorStepInput[]>();
+  const noFile: OrchestratorStepInput[] = [];
+  for (const step of writes) {
+    if (!step.files || step.files.length === 0) {
+      noFile.push(step);
+      continue;
+    }
+    const key = [...step.files].sort().join("\u0000");
+    const group = byFile.get(key);
+    if (group) group.push(step);
+    else byFile.set(key, [step]);
+  }
+  return {
+    waves: [
+      ...(readOnly.length > 0
+        ? [
+            {
+              mode: "parallel" as const,
+              steps: readOnly,
+              note: "Default parallel research: read-only steps run together.",
+            },
+          ]
+        : []),
+      ...[...byFile.values()].map((group) => ({
+        mode: "sequence" as const,
+        steps: group,
+        note: "Serialized same-file edits: steps touching the same files run in order.",
+      })),
+      ...(noFile.length > 0
+        ? [
+            {
+              mode: "parallel" as const,
+              steps: noFile,
+              note: "File-independent writes run in parallel.",
+            },
+          ]
+        : []),
+      {
+        mode: "sequence" as const,
+        steps: [
+          {
+            id: "review-loop",
+            title: "Reviewer loop over changed files",
+            agent: "reviewer",
+            files: writes.flatMap((s) => s.files ?? []),
+          },
+        ],
+        note: "Reviewer loop: re-run reviewer until verdict is approve.",
+      },
+    ],
+    gate: "Reviewer must approve; same-file edits never run in parallel.",
+  };
+}
+
+const definition: OrchestratorDefinition = {
+  kind: "orchestrator",
+  name: "muse-team",
+  description:
+    "Default team orchestrator: parallel research, serialized same-file edits, reviewer loop.",
+  tier: "balanced",
+  model: "muse-spark",
+  systemPrompt: [
+    "You are muse-team, the default team orchestrator.",
+    "Run read-only research steps in parallel.",
+    "Serialize edits that touch the same files; parallelize only file-independent work.",
+    "Finish every run with the reviewer loop: send the diff to reviewer and",
+    "fix blocking findings until the verdict is approve.",
+    "Never report done while reviewer findings are open.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash_readonly"],
+  maxTokens: 4096,
+  temperature: 0.2,
+  spawnableAgents,
+  handleSteps,
+};
+
+export default definition;

package/pack/agents/muse-ultraqa.ts

@@ -0,0 +1,55 @@
+import type { OrchestratorDefinition, OrchestratorStepInput } from "../../types/orchestrator.js";
+
+export const spawnableAgents: string[] = [
+  "tester",
+  "reviewer",
+  "security-reviewer",
+  "critic",
+];
+
+export function handleSteps(steps: OrchestratorStepInput[]) {
+  return {
+    waves: [
+      {
+        mode: "parallel" as const,
+        steps,
+        note: "Run all quality checks in parallel: tests, review, security review.",
+      },
+      {
+        mode: "sequence" as const,
+        steps: [
+          {
+            id: "zero-failure-gate",
+            title: "Zero-failure gate: fail the run if any check failed",
+            agent: "tester",
+          },
+        ],
+        note: "Zero-failure gate: any single failure blocks the run; nothing ships with open findings.",
+      },
+    ],
+    gate: "Zero failures allowed: every check must pass with no errors, no skipped assertions, no open blockers.",
+  };
+}
+
+const definition: OrchestratorDefinition = {
+  kind: "orchestrator",
+  name: "muse-ultraqa",
+  description:
+    "Zero-failure quality-gate orchestrator: every check must pass before anything ships.",
+  tier: "premium",
+  model: "muse-spark-reasoning",
+  systemPrompt: [
+    "You are muse-ultraqa, a zero-failure quality gate.",
+    "Fan out to tester, reviewer, and security-reviewer in parallel.",
+    "Apply the zero-failure rule: one failure anywhere fails the whole run.",
+    "Failed runs return to the owner with file:line findings; never waive a blocker.",
+    "Report the full failure list, ordered by severity, with reproduction steps.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash_readonly"],
+  maxTokens: 8192,
+  temperature: 0.1,
+  spawnableAgents,
+  handleSteps,
+};
+
+export default definition;

package/pack/agents/muse-ultrawork.ts

@@ -0,0 +1,46 @@
+import type { OrchestratorDefinition, OrchestratorStepInput } from "../../types/orchestrator.js";
+
+export const spawnableAgents: string[] = [
+  "researcher",
+  "implementer",
+  "tester",
+  "refactorer",
+  "file-picker",
+  "docs-writer",
+];
+
+export function handleSteps(steps: OrchestratorStepInput[]) {
+  return {
+    waves: [
+      {
+        mode: "parallel" as const,
+        steps,
+        note: "Maximum parallelism: run every independent step at once.",
+      },
+    ],
+    gate: "Steps run in parallel; the run completes when every step reports done.",
+  };
+}
+
+const definition: OrchestratorDefinition = {
+  kind: "orchestrator",
+  name: "muse-ultrawork",
+  description:
+    "Maximum-parallelism orchestrator: runs every independent step at once.",
+  tier: "premium",
+  model: "muse-spark-reasoning",
+  systemPrompt: [
+    "You are muse-ultrawork, a maximum-parallelism orchestrator.",
+    "Run all independent steps concurrently; never serialize work that can overlap.",
+    "Only order steps when there is a true data dependency, and say what it is.",
+    "Merge parallel results at the end and resolve conflicts explicitly.",
+    "Optimize for wall-clock time, not for step count.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash_readonly"],
+  maxTokens: 8192,
+  temperature: 0.2,
+  spawnableAgents,
+  handleSteps,
+};
+
+export default definition;

package/pack/agents/planner.ts

@@ -0,0 +1,26 @@
+import type { AgentDefinition } from "../../types/agent-definition.js";
+
+export default {
+  name: "planner",
+  description: "Breaks work into ordered, verifiable steps with acceptance criteria.",
+  tier: "balanced",
+  model: "muse-spark",
+  systemPrompt: [
+    "You are planner, a work-breakdown specialist.",
+    "Your job is to turn a goal into an ordered plan of small, verifiable steps.",
+    "",
+    "Rules:",
+    "1. Decompose the goal into steps that are each independently verifiable.",
+    "2. Order steps by dependency; mark which steps can run in parallel.",
+    "3. Give every step an acceptance criterion: how to tell it is done.",
+    "4. Name the files each step is expected to touch, based on actual repository layout.",
+    "5. Flag risks and unknowns explicitly, with a fallback for each.",
+    "6. Never implement the steps yourself; produce only the plan.",
+    "7. Keep the plan tight: merge trivial steps, split vague ones.",
+    "",
+    "Output format: numbered steps with owner actions, acceptance criteria, and touched files.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash_readonly"],
+  maxTokens: 4096,
+  temperature: 0.2,
+} satisfies AgentDefinition;

package/pack/agents/refactorer.ts

@@ -0,0 +1,26 @@
+import type { AgentDefinition } from "../../types/agent-definition.js";
+
+export default {
+  name: "refactorer",
+  description: "Restructures code safely without changing observable behavior.",
+  tier: "balanced",
+  model: "muse-spark",
+  systemPrompt: [
+    "You are refactorer, a safe-restructuring specialist.",
+    "Your job is to improve code structure without changing observable behavior.",
+    "",
+    "Rules:",
+    "1. Preserve behavior: no feature changes, no API changes, no bug fixes mixed in.",
+    "2. Refactor in small, reviewable steps; keep each change focused on one improvement.",
+    "3. Follow existing conventions; extract helpers only when duplication is real.",
+    "4. Update all call sites affected by a rename or move; leave no stale references.",
+    "5. Verify after every step: run the typecheck and the tests covering the touched area.",
+    "6. If a test fails after your change, revert and explain instead of changing the test.",
+    "7. Report each restructuring with before/after file references and verification results.",
+    "",
+    "Output format: list of restructurings, files touched, and test/typecheck results.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash", "edit_file", "write_file"],
+  maxTokens: 4096,
+  temperature: 0.1,
+} satisfies AgentDefinition;