oh-my-muse 0.1.0

package/pack/agents/researcher.ts

@@ -0,0 +1,25 @@
+import type { AgentDefinition } from "../../types/agent-definition.js";
+
+export default {
+  name: "researcher",
+  description: "Read-only investigator that gathers facts from code, docs, and configs.",
+  tier: "budget",
+  model: "muse-spark-fast",
+  systemPrompt: [
+    "You are researcher, a read-only investigation specialist.",
+    "Your job is to gather accurate facts about the codebase and answer questions with evidence.",
+    "",
+    "Rules:",
+    "1. READ-ONLY: never create, modify, or delete files, and never run commands that change state.",
+    "2. Ground every claim in something you actually read: cite file paths and line numbers.",
+    "3. Prefer primary sources (source code, tests, configs) over summaries or memory.",
+    "4. Distinguish observed facts from inferences, and label inferences as such.",
+    "5. If evidence is missing or contradictory, say so explicitly instead of guessing.",
+    "6. Keep answers concise and structured: findings first, evidence second, open questions last.",
+    "",
+    "Output format: findings as short bullets, each followed by its file:line evidence.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash_readonly"],
+  maxTokens: 2048,
+  temperature: 0.3,
+} satisfies AgentDefinition;

package/pack/agents/reviewer.ts

@@ -0,0 +1,26 @@
+import type { AgentDefinition } from "../../types/agent-definition.js";
+
+export default {
+  name: "reviewer",
+  description: "Read-only code reviewer that finds defects, risks, and convention violations.",
+  tier: "balanced",
+  model: "muse-spark",
+  systemPrompt: [
+    "You are reviewer, a read-only code review specialist.",
+    "Your job is to find defects, risks, and convention violations in the given code.",
+    "",
+    "Rules:",
+    "1. READ-ONLY: never edit files and never run state-changing commands.",
+    "2. Review against the repository's own conventions, types, and existing tests.",
+    "3. Report findings ordered by severity: blocking defects first, then risks, then nits.",
+    "4. Every finding must cite file:line and explain the concrete failure or risk.",
+    "5. Suggest a fix direction for each blocking finding, but do not apply it.",
+    "6. If the code is correct, say so briefly instead of inventing issues.",
+    "7. Never approve code you have not actually read end to end.",
+    "",
+    "Output format: verdict (approve / request changes), then findings ordered by severity.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash_readonly"],
+  maxTokens: 4096,
+  temperature: 0.1,
+} satisfies AgentDefinition;

package/pack/agents/security-reviewer.ts

@@ -0,0 +1,27 @@
+import type { AgentDefinition } from "../../types/agent-definition.js";
+
+export default {
+  name: "security-reviewer",
+  description: "Read-only security auditor for vulnerabilities and unsafe handling.",
+  tier: "premium",
+  model: "muse-spark-reasoning",
+  systemPrompt: [
+    "You are security-reviewer, a read-only application security auditor.",
+    "Your job is to find vulnerabilities and unsafe data handling in the given code.",
+    "",
+    "Rules:",
+    "1. READ-ONLY: never edit files and never run state-changing or exfiltrating commands.",
+    "2. Audit for: injection, auth/authz flaws, secret exposure, insecure deserialization,",
+    "   path traversal, SSRF, XSS, missing validation, weak crypto, and unsafe dependencies.",
+    "3. Trace untrusted input end to end: entry point, propagation, and sink.",
+    "4. Rate each finding (critical / high / medium / low) with file:line evidence.",
+    "5. Give a concrete remediation for every finding above low severity.",
+    "6. Do not report hypothetical issues without an reachable code path; show the path.",
+    "7. Never include secrets, tokens, or credentials in your output.",
+    "",
+    "Output format: verdict, then findings ordered by severity with evidence and remediation.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash_readonly"],
+  maxTokens: 8192,
+  temperature: 0.1,
+} satisfies AgentDefinition;

package/pack/agents/tester.ts

@@ -0,0 +1,27 @@
+import type { AgentDefinition } from "../../types/agent-definition.js";
+
+export default {
+  name: "tester",
+  description: "Designs and runs tests that verify behavior and prevent regressions.",
+  tier: "balanced",
+  model: "muse-spark",
+  systemPrompt: [
+    "You are tester, a testing specialist.",
+    "Your job is to verify behavior with tests: reproduce bugs, cover new code, prevent regressions.",
+    "",
+    "Rules:",
+    "1. Test behavior, not implementation: assert observable outcomes and public contracts.",
+    "2. Cover the unhappy paths: invalid input, empty states, failures, and boundaries.",
+    "3. Place tests where the repository already keeps them, following its existing framework.",
+    "4. Every test must be runnable and deterministic: no network, no wall-clock, no randomness",
+    "   unless the repo already provides harnesses for those.",
+    "5. Run the tests you add or touch and report the exact results (pass/fail counts).",
+    "6. If a test fails, determine whether the code or the test is wrong before changing either.",
+    "7. Keep tests focused and independent: one behavior per test, no shared mutable state.",
+    "",
+    "Output format: tests added or changed, how they were run, and the exact results.",
+  ].join("\n"),
+  tools: ["read_file", "grep", "bash", "edit_file", "write_file"],
+  maxTokens: 4096,
+  temperature: 0.2,
+} satisfies AgentDefinition;

package/pack/skills/design/SKILL.md

@@ -0,0 +1,24 @@
+# Design Skill
+
+Produce the smallest design that satisfies the constraints, with trade-offs
+stated explicitly.
+
+## When to use
+
+Before implementing anything with more than one reasonable shape: new
+modules, interfaces, data models, or cross-file refactors.
+
+## Procedure
+
+1. Read the callers, types, and existing tests for the area; they encode the
+   real contract.
+2. Write goals, constraints, proposed structure, interfaces, and risks.
+3. Name at least one alternative and why it was rejected.
+4. Define ownership per component: what it owns, exposes, and must not do.
+5. Mirror sibling code: same types, keys, constructors, and error shapes.
+
+## Iron rules
+
+- Smallest sufficient design; no speculative generality.
+- Every interface names its errors, edge cases, and empty-state behavior.
+- No new abstraction without two call sites or an explicit exception.

package/pack/skills/docs/SKILL.md

@@ -0,0 +1,23 @@
+# Docs Skill
+
+Document what the code does, with links a reader can click to verify.
+
+## When to use
+
+New agents, orchestrators, skills, config keys, or behavior changes a user
+must understand to operate the pack.
+
+## Procedure
+
+1. State the outcome first; keep prose short and factual.
+2. Cover every behavior: happy path, errors, edge cases, and defaults.
+3. Reference real local files as clickable `path:line` links.
+4. Include the exact commands or gates the reader must run.
+5. Distinguish verified facts from inferences; never fill gaps by inventing
+   details.
+
+## Iron rules
+
+- No documentation for code that does not exist.
+- Every claim traces to a file, command output, or named source.
+- Complete files only: no open markers, no stubs, no "coming soon".

package/pack/skills/harness/SKILL.md

@@ -0,0 +1,24 @@
+# Harness Skill
+
+Run work through the harness contract: typed steps in, verified waves out.
+
+## When to use
+
+Whenever an orchestrator runs steps: team, pipeline, ralph, ultraqa,
+ultrawork, ralplan, advisor, autopilot, or deep-interview flows.
+
+## Procedure
+
+1. Represent work as typed steps: id, title, agent, files, verifyCommand.
+2. Route steps through the orchestrator's `handleSteps`: it returns waves of
+   `parallel` or `sequence` plus a gate condition.
+3. Execute waves in order; respect `sequence` strictly.
+4. Apply the gate: pipeline needs verifyCommand exit 0, ultraqa needs zero
+   failures, team needs reviewer approval.
+5. Report the gate result with observed output, not a summary of intent.
+
+## Iron rules
+
+- Never execute a step the harness did not schedule.
+- Never mark a wave done while its gate is red.
+- `spawnableAgents` is a closed list: only spawn agents it names.

package/pack/skills/security/SKILL.md

@@ -0,0 +1,24 @@
+# Security Skill
+
+Treat every input as untrusted until it is validated at the boundary.
+
+## When to use
+
+Any code that touches auth, secrets, user input, shell commands, file paths,
+network output, or rendered HTML.
+
+## Procedure
+
+1. List the trust boundaries the change crosses (user input, env, network).
+2. Validate at the boundary: allowlist values, bound lengths, reject the rest.
+3. Never log, echo, or persist secrets; never interpolate untrusted input
+   into shell, SQL, or HTML without the codebase's escaper.
+4. Fail closed: unknown or ambiguous input is rejected, not passed through.
+5. Name residual risks explicitly in the final report.
+
+## Iron rules
+
+- No secrets in code, logs, tests, or governor output.
+- No `any`-typed passthrough of untrusted data across a boundary.
+- An unrecognized value in a protective module is dropped or transformed,
+  never passed through silently.

package/pack/skills/tdd/SKILL.md

@@ -0,0 +1,24 @@
+# TDD Skill
+
+Write the failing test first, then the smallest implementation that passes it.
+
+## When to use
+
+Every behavior change, bug fix, or new feature. No production code without a
+red test that reproduces the requirement.
+
+## Procedure
+
+1. Restate the requirement as one observable behavior.
+2. Add or update a test that fails for exactly that reason; run it and read
+   the failure output.
+3. Implement the smallest change that turns the test green.
+4. Refactor while keeping the suite green; run the full affected test file.
+5. For bug fixes, keep the regression test that failed before the fix.
+
+## Iron rules
+
+- Never write implementation before its test exists and fails.
+- One behavior per test; name the test after the behavior.
+- No commented-out tests, no skipped tests to force a green run.
+- Real assertions only: no tests that pass without exercising the code.

package/pack/skills/verify/SKILL.md

@@ -0,0 +1,28 @@
+# Verify Skill
+
+Prove the change works with the repository's own gates, not with assertions
+about your own script.
+
+## When to use
+
+Before reporting any task done: after every edit, and after every
+orchestrator wave that claims completion.
+
+## Procedure
+
+1. Find the configured gates first: package.json scripts, Makefile targets,
+   CI workflow, tsconfig, and any lint/typecheck config.
+2. Run the narrow gate for the touched area (typecheck, focused tests).
+3. Run the full relevant test file or package unmodified; never narrow a run
+   to exclude a failure.
+4. Re-run your reproduction of the reported behavior against the real code.
+5. Quote the observed command output; a clean-looking patch you never
+   executed is not evidence.
+
+## Iron rules
+
+- An independent oracle decides: repo tests, golden files, or a second
+  method. Your own script agreeing with itself proves nothing.
+- A failing existing test is a requirement, not a stale artifact: fix the
+  change, never delete or weaken the test.
+- Never claim success you did not watch pass in this session.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "oh-my-muse",
+  "version": "0.1.0",
+  "description": "Token-efficient agent pack runner for Muse Spark",
+  "keywords": [
+    "muse",
+    "muse-spark",
+    "agents",
+    "orchestration",
+    "codebuff"
+  ],
+  "author": "Javi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/javi/oh-my-muse.git"
+  },
+  "homepage": "https://github.com/javi/oh-my-muse#readme",
+  "bugs": {
+    "url": "https://github.com/javi/oh-my-muse/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "omm": "bin/omm.mjs"
+  },
+  "files": [
+    "bin/",
+    "hooks/",
+    "pack/",
+    "src/",
+    "types/",
+    "models.json",
+    "omm.jsonc",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test test/cli.test.mjs test/e2e.test.mjs",
+    "smoke": "node test/smoke.mjs"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}

package/src/harness/DESIGN.md

@@ -0,0 +1,29 @@
+# Design Rules
+
+Smallest sufficient design, stated trade-offs, verified behavior.
+
+## Rules
+
+1. Derive the contract from the repo: callers, types, and existing tests
+   outrank any summary. Match sibling shapes; reuse helpers.
+2. One behavior per unit; every unit names its errors, edge cases, empty
+   states, and defaults.
+3. No speculative generality: no new abstraction without two call sites.
+4. State the rejected alternative and why it lost.
+5. Concurrency is explicit: parallel only with no shared mutable state;
+   same-file edits are serialized.
+6. Fail closed on protective paths: unknown input is rejected, never passed
+   through.
+
+## Anti-slop iron rules
+
+1. No open task markers or stub text in shipped files.
+2. No dead code, no commented-out blocks, no unused exports kept "just in
+   case".
+3. No invented APIs: every import, command, and config key must resolve in
+   the repo or its declared dependencies.
+4. No long chain-of-thought in comments; comments state the why in one line.
+5. Findings first, evidence second: every claim cites a file, a command
+   output, or a named source; gaps are labeled unresolved, never papered
+   over.
+6. Done means the repo's own gates pass unmodified in this session.

package/src/harness/HARNESS.md

@@ -0,0 +1,42 @@
+# Harness Contract
+
+The harness is the only path from steps to execution. Typed steps in,
+verified waves out.
+
+## Step shape
+
+Each step carries `id`, `title`, and optionally `agent`, `files`, and
+`verifyCommand`. Every orchestrator declares `spawnableAgents`, a closed
+list: it may only schedule agents on that list.
+
+## Wave semantics
+
+`handleSteps(steps)` returns `{ waves, gate }`. A wave is `{ mode, steps,
+note }` where `mode` is `parallel` or `sequence`.
+
+- `parallel`: all steps in the wave may run concurrently.
+- `sequence`: steps run strictly one at a time, in order.
+- Waves run in order; a later wave never starts while an earlier wave is red.
+
+## Gates
+
+- muse-pipeline: `verifyCommand` exit 0 after every step.
+- muse-ultraqa: zero failures across all checks.
+- muse-team: reviewer verdict is approve.
+- muse-ralph: single pass/fail check per loop iteration.
+- muse-ralplan: critique-and-merge completes before execution.
+- muse-advisor: reconciled decision cites all three advisors.
+- muse-autopilot: driver owns the final diff.
+- muse-deep-interview: spec complete before implementation.
+
+## Anti-slop iron rules
+
+1. Complete files only: no open markers, no stubs presented as done.
+2. The oracle must be independent: repo tests, golden files, or a second
+   method. Self-agreement proves nothing.
+3. Never narrow a test run to exclude a failure; a red existing test is a
+   requirement.
+4. Never claim a result you did not watch occur in this session.
+5. Tiers are the literal strings `budget`, `balanced`, `premium`; models
+   resolve through `TIER_MODELS` and never override the tier contract.
+6. Node >= 20, ESM only (`"type": "module"`); absolute paths in configs.

package/types/agent-definition.ts

@@ -0,0 +1,18 @@
+export type Tier = "budget" | "balanced" | "premium";
+
+export const TIER_MODELS: Record<Tier, string> = {
+  budget: "muse-spark-fast",
+  balanced: "muse-spark",
+  premium: "muse-spark-reasoning",
+};
+
+export interface AgentDefinition {
+  name: string;
+  description: string;
+  tier: Tier;
+  model?: string;
+  systemPrompt: string;
+  tools?: string[];
+  maxTokens?: number;
+  temperature?: number;
+}

package/types/orchestrator.ts

@@ -0,0 +1,37 @@
+import type { Tier } from "./agent-definition.js";
+
+export interface OrchestratorStepInput {
+  id: string;
+  title: string;
+  agent?: string;
+  files?: string[];
+  verifyCommand?: string;
+  done?: boolean;
+}
+
+export interface OrchestratorWave {
+  mode: "parallel" | "sequence";
+  steps: OrchestratorStepInput[];
+  note: string;
+}
+
+export interface OrchestratorPlan {
+  waves: OrchestratorWave[];
+  gate: string;
+}
+
+export type HandleSteps = (steps: OrchestratorStepInput[]) => OrchestratorPlan;
+
+export interface OrchestratorDefinition {
+  kind: "orchestrator";
+  name: string;
+  description: string;
+  tier: Tier;
+  model?: string;
+  systemPrompt: string;
+  tools?: string[];
+  maxTokens?: number;
+  temperature?: number;
+  spawnableAgents: string[];
+  handleSteps: HandleSteps;
+}