@siddicky/oh-my-musecode 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "oh-my-musecode",
+  "owner": {
+    "name": "oh-my-musecode"
+  },
+  "metadata": {
+    "description": "An OMC-shaped delivery harness for Meta Muse Code.",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "oh-my-musecode",
+      "source": "./",
+      "version": "0.1.0",
+      "description": "Ported oh-my-claudecode delivery pipeline for the muse CLI: deep-interview -> ralplan -> ralph, plus deep-dive/trace, team and cancel."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,30 @@
+{
+  "name": "oh-my-musecode",
+  "version": "0.1.0",
+  "description": "An OMC-shaped delivery harness for Meta Muse Code: deep-interview -> ralplan -> ralph, plus deep-dive/trace, team and cancel. Personas are rendered into subagent prompts rather than declared as agent definitions, because muse rejects `agents` as a plugin capability.",
+  "capabilities": {
+    "skills": [
+      "./skills/deep-interview",
+      "./skills/deep-dive",
+      "./skills/trace",
+      "./skills/ralplan",
+      "./skills/ralph",
+      "./skills/team",
+      "./skills/cancel"
+    ],
+    "hooks": [
+      "./hooks/hooks.json"
+    ],
+    "commands": [],
+    "mcpServers": [
+      {
+        "name": "omm-state",
+        "transport": "stdio",
+        "command": "node",
+        "args": [
+          "${MUSE_PLUGIN_ROOT}/dist/mcp/state-server.js"
+        ]
+      }
+    ]
+  }
+}

package/.muse-plugin/plugin.json

@@ -0,0 +1,94 @@
+{
+  "schemaVersion": 1,
+  "name": "oh-my-musecode",
+  "displayName": "oh-my-musecode",
+  "version": "0.1.0",
+  "description": "A gated delivery pipeline for muse: deep-interview to ralplan to ralph, with deep-dive, trace, team and cancel.",
+  "compat": {
+    "source": "native",
+    "manifestDir": ".muse-plugin"
+  },
+  "capabilities": {
+    "skills": [
+      {
+        "id": "deep-interview",
+        "path": "skills/deep-interview/SKILL.md",
+        "enabledDefault": true
+      },
+      {
+        "id": "deep-dive",
+        "path": "skills/deep-dive/SKILL.md",
+        "enabledDefault": true
+      },
+      {
+        "id": "trace",
+        "path": "skills/trace/SKILL.md",
+        "enabledDefault": true
+      },
+      {
+        "id": "ralplan",
+        "path": "skills/ralplan/SKILL.md",
+        "enabledDefault": true
+      },
+      {
+        "id": "ralph",
+        "path": "skills/ralph/SKILL.md",
+        "enabledDefault": true
+      },
+      {
+        "id": "team",
+        "path": "skills/team/SKILL.md",
+        "enabledDefault": true
+      },
+      {
+        "id": "cancel",
+        "path": "skills/cancel/SKILL.md",
+        "enabledDefault": true
+      }
+    ],
+    "commands": [],
+    "hooks": [
+      {
+        "id": "omm-route",
+        "event": "UserPromptSubmit",
+        "command": [
+          "node",
+          "hooks/user-prompt-submit.mjs"
+        ],
+        "timeoutMs": 5000,
+        "statusMessage": "Checking for oh-my-musecode skills"
+      },
+      {
+        "id": "omm-bootstrap",
+        "event": "SessionStart",
+        "command": [
+          "node",
+          "hooks/session-start.mjs"
+        ],
+        "timeoutMs": 5000,
+        "statusMessage": "Preparing oh-my-musecode state"
+      },
+      {
+        "id": "omm-verification-reminder",
+        "event": "Stop",
+        "command": [
+          "node",
+          "hooks/stop.mjs"
+        ],
+        "timeoutMs": 5000,
+        "statusMessage": "Checking for an active ralph run"
+      }
+    ],
+    "mcpServers": [
+      {
+        "id": "omm-state",
+        "transport": "stdio",
+        "command": [
+          "node",
+          "dist/mcp/state-server.js"
+        ]
+      }
+    ],
+    "reminders": []
+  }
+}

package/LICENSE

@@ -0,0 +1,32 @@
+MIT License
+
+Copyright (c) 2026 Abdullah Siddique
+
+This project is a port of oh-my-claudecode to Meta's Muse Code CLI, and is
+derived in part from that project's design and skill definitions:
+
+    oh-my-claudecode
+    https://github.com/Yeachan-Heo/oh-my-claudecode
+    Copyright (c) 2025 Yeachan Heo
+    Licensed under the MIT License
+
+The above copyright notices and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# oh-my-musecode
+
+An OMC-shaped delivery harness for [Meta Muse Code](https://dev.meta.ai/docs/cookbook#building-with-muse-code)
+(the `muse` CLI): a gated pipeline from a vague request to verified working
+code. It ships a native muse plugin manifest, but on muse 1.0.3 the plugins
+subsystem itself is disabled, so it installs today through `muse skills
+install` plus a `settings.json` merge instead — see Install below.
+
+It ports oh-my-claudecode's Tier-0 pipeline — `deep-interview → deep-dive/trace
+→ ralplan → ralph`, plus `team` and `cancel` — onto `muse` 1.0.3, respecting
+Muse's approval/sandbox/trust/audit model instead of working around it. See
+[`docs/recipe.md`](docs/recipe.md) for the full walkthrough and acceptance
+run.
+
+## The pipeline
+
+```
+/deep-interview  → turns a vague request into an approved spec (.omm/specs/<slug>.md)
+/deep-dive       → front door when it's unclear whether the problem is a bug or a scope
+                    question; runs trace first, then deep-interview if needed
+/trace           → root-causes a concrete symptom via parallel competing hypotheses
+/ralplan         → turns an approved spec into a consensus-reviewed PRD (.omm/state/prd.json)
+/ralph           → runs the PRD to completion: implement each story, verify its
+                    acceptance criteria, loop until done or blocked
+/team            → N persona subagents in parallel worktrees on independent tasks
+/cancel          → stop whatever pipeline stage is active and clean up .omm/ state
+```
+
+Every skill here is **explicit-invocation only**. Muse never fires a skill on
+its own because a task looks complex or ambiguous — you (or another skill's
+prose) has to name it. Each `SKILL.md` says this in its own body, because
+there is no `triggers` field in Muse's skill frontmatter to enforce it.
+Sequencing between stages works the same way: no `SKILL.md` chains
+automatically into the next one — the skill's body tells you, in prose, what
+to run next (`deep-interview` → "run `/ralplan`"; `ralplan` → "run `/ralph`").
+
+## Install
+
+```bash
+npm install
+npm run build
+node scripts/install.mjs --workspace <path> --dry-run   # preview, writes nothing
+node scripts/install.mjs --workspace <path>              # installs for real
+```
+
+`scripts/install.mjs` first probes the local `muse` build: `muse plugins
+--help` (and every other `muse plugins` subcommand) answers "plugins are not
+available in this build" on muse 1.0.3-R2198.1, and registering
+`.agents/plugins/marketplace.json` anyway just yields
+`muse skills list --source plugin --json` → `{"skills":[],"diagnostics":[]}`
+— no discovery, no error, nothing delivered. **There is no `muse plugin
+install` command on this build either.**
+
+So on 1.0.3 the installer skips the plugin route entirely and delivers
+through three routes verified to work:
+
+| Piece | Route |
+|---|---|
+| Skills | `muse skills install <dir> --scope user --force` for each of the 7 skills, landing in `$CONFIG_DIR/skills/` |
+| Hooks | a `hooks` entry merged into `$CONFIG_DIR/muse/settings.json` |
+| MCP server | an `mcpServers` entry in the same `settings.json` |
+
+(`$CONFIG_DIR` is `~/.config/muse`, or `$XDG_CONFIG_HOME/muse` when that's
+set.) The installer also runs an escalation preflight against your local
+`muse` build and reports plainly what it finds (see External critic below),
+refusing to install if an enterprise policy forbids the only escalation
+route entirely.
+
+The repo also ships a native `.muse-plugin/plugin.json` manifest — correct
+per muse's own documented plugin contract, and what a build with plugins
+*enabled* would load directly. `scripts/install.mjs` detects support at
+runtime (`pluginsSupported()`) and would use it automatically on such a
+build. On 1.0.3-R2198.1 it is inert; do not treat it as the working install
+path today. `.claude-plugin/` is kept alongside it only for Claude-family
+tooling compatibility.
+
+Confirm the skills installed:
+
+```bash
+muse skills list --source user
+```
+
+All 7 (`deep-interview`, `deep-dive`, `trace`, `ralplan`, `ralph`, `team`,
+`cancel`) should appear with `scope: "user"`.
+
+## Skills
+
+Seven skills, installed user-scoped on this build, **explicit-invocation
+only** — muse never auto-fires a skill:
+
+| Skill | What it does |
+|---|---|
+| `deep-interview` | Socratic interview gated by a measured ambiguity score, producing an approved spec |
+| `deep-dive` | Two-stage front door: runs `trace` first, then `deep-interview` if the problem turns out to be a scope question |
+| `trace` | Root-causes a concrete symptom via parallel competing hypotheses and evidence-gatherers |
+| `ralplan` | Turns an approved spec into a consensus-reviewed PRD (`prd.json`) of testable stories |
+| `ralph` | Runs the PRD to completion: implement, verify each acceptance criterion, loop until done or blocked |
+| `team` | N persona subagents in parallel, each isolated in its own worktree, for genuinely independent work |
+| `cancel` | Ends the active pipeline stage and cleans up `.omm/` state — does not revert code |
+
+## Personas
+
+Ten personas (`executor`, `planner`, `architect`, `critic`, `explore`,
+`verifier`, `code-reviewer`, `debugger`, `writer`, `test-engineer`), each a
+`SOUL.md` body plus a declaratively narrowed toolset in
+`personas/manifest.json`.
+
+These are **not muse Agent Definitions** — muse rejects `agents` as a plugin
+capability (a Claude-family plugin declaring it gets
+`unsupported-agent-schema`/`agent-overlay-inactive`, and the definitions
+never activate), so there is no route to register them as first-class agent
+types. `scripts/verify-manifest.mjs` fails the build if the plugin manifest
+ever tries to declare `agents` anyway.
+
+Instead, the bundled `omm-state` MCP server exposes `persona_list` and
+`persona_render` tools: `persona_list` returns every persona id with its
+routing description; `persona_render(id)` returns that persona's `SOUL.md`
+text plus its narrowed tool allowlist from `personas/manifest.json`, ready
+to interpolate into a `subagent_spawn(role, objective, worktree_isolation)`
+call. A skill calls `persona_list` to pick the right persona, then
+`persona_render` to pull its prompt text and tool allowlist into the
+objective it hands to `subagent_spawn` — the narrowing is advisory and the
+caller applies it, since muse has no first-class concept of a persona's
+tool scope.
+
+## State
+
+Runtime state lives under `.omm/` at the workspace root
+(`.omm/specs/`, `.omm/state/`), never under `.agents/` or `.muse/`.
+
+Those two paths are **muse-protected**: a mediated `edit_file`/`write_file`
+write there is held for human review with no standing grant, and a shell
+write fails read-only at the sandbox. `.omm/` is ordinary, unprotected
+workspace state, so hooks and the bundled MCP state server can read and write
+it freely — `src/paths.ts` is the single place that enforces this boundary
+and refuses any write that resolves into `.agents/`, `.muse/`, or `.git/`.
+
+## External critic
+
+`ralplan` and `ralph` both accept `--critic codex` (or `--critic claude`) to
+route consensus review and final verification through an external CLI
+process instead of the in-process `critic`/`verifier` personas.
+
+This buys genuine cross-model adversarial review, at two real costs, stated
+plainly rather than soft-pedaled:
+
+1. **It's session-wide, not scoped to the critic call.** muse 1.0.3 has no
+   named permission profile to escalate just the critic — `--permission-profile
+   <id>` reports the profile does not exist, and
+   `execution.permission_profiles` validates as `field_not_activated`. The
+   only route is launching the **entire session** with `muse
+   --disable-sandbox` (or `--yolo`), which removes filesystem and network
+   sandboxing for everything in that session, not just the one process that
+   needed it.
+2. **The external critic's work falls outside Muse's append-only audit
+   trail.** Its reasoning and any files it touches are not captured the way
+   an in-session `subagent_spawn` result is — `muse export` will show that
+   `ralph`/`ralplan` invoked it, not what it did internally.
+
+If an enterprise policy sets `execution.forbid_sandbox_bypass`, both
+`--disable-sandbox` and `--yolo` are refused outright and the external
+critic cannot run at all; `scripts/install.mjs` checks for this at install
+time, and `ralph`/`ralplan` check it again at run time rather than silently
+falling back to the in-process critic.
+
+## Development
+
+```bash
+npm test           # build + node --test over test/**/*.test.mjs
+npm run lint        # verify-manifest.mjs + tsc --noEmit
+npm run verify:skills  # validates all 7 skills against the muse binary, failing on any inert frontmatter key
+```
+
+## Credits and license
+
+oh-my-musecode is a port of [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)
+(MIT, Copyright (c) 2025 Yeachan Heo) to Meta's Muse Code CLI. The pipeline shape
+— `deep-interview` → `ralplan` → `ralph`, plus `deep-dive`/`trace`, `team` and
+`cancel` — and the PRD-driven persistence loop come from that project. The skill
+bodies, personas, hooks, MCP server and installer here were rewritten against
+muse's own contracts, because muse's frontmatter subset, invoke-only skills,
+protected paths and plugin capability rules differ substantially from Claude Code's.
+
+The persona model follows the Hermes profile pattern documented in Meta's
+[meta-model-cookbook](https://github.com/meta-llama/meta-model-cookbook): a
+durable SOUL body, a routing description, and a declaratively narrowed toolset,
+with project-specific conventions kept out of the persona.
+
+Licensed under the MIT License — see [LICENSE](LICENSE), which retains the
+upstream copyright notice as MIT requires.

package/dist/mcp/state-server.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * omm-state: an MCP server exposing the .omm/ state root over stdio.
+ *
+ * Skills need somewhere durable to keep PRDs, specs and run state across turns.
+ * That cannot be `.agents/` or `.muse/` — muse protects both — so this server is
+ * the sanctioned way to reach `.omm/`.
+ *
+ * Every tool resolves its path through StateStore, which fails closed on a
+ * protected or escaping path. A refusal is returned as a tool error rather than
+ * thrown, so the model sees why it was refused and can correct itself.
+ */
+export {};

package/dist/mcp/state-server.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * omm-state: an MCP server exposing the .omm/ state root over stdio.
+ *
+ * Skills need somewhere durable to keep PRDs, specs and run state across turns.
+ * That cannot be `.agents/` or `.muse/` — muse protects both — so this server is
+ * the sanctioned way to reach `.omm/`.
+ *
+ * Every tool resolves its path through StateStore, which fails closed on a
+ * protected or escaping path. A refusal is returned as a tool error rather than
+ * thrown, so the model sees why it was refused and can correct itself.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { StateStore } from '../state.js';
+import { loadPersonas, renderPersonaPrompt } from '../personas.js';
+import { EscapedStateRootError, ProtectedPathError } from '../paths.js';
+const store = new StateStore({
+    workspaceRoot: process.env.MUSE_WORKSPACE_ROOT ?? process.cwd(),
+});
+/** Wraps a store call so a policy refusal becomes a legible tool error. */
+function guarded(run) {
+    try {
+        return { content: [{ type: 'text', text: run() }] };
+    }
+    catch (err) {
+        if (err instanceof ProtectedPathError || err instanceof EscapedStateRootError) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+        throw err;
+    }
+}
+const server = new McpServer({ name: 'omm-state', version: '0.1.0' }, {
+    instructions: 'Durable state for oh-my-musecode, rooted at .omm/. Paths are relative to that ' +
+        'root. Writes to .agents/ or .muse/ are refused: muse protects them.',
+});
+server.registerTool('state_read', {
+    title: 'Read oh-my-musecode state',
+    description: 'Read a file from the .omm/ state root. Path is relative to .omm/. Returns an ' +
+        'empty result when the file does not exist.',
+    inputSchema: {
+        path: z.string().describe('Path relative to the .omm/ state root, e.g. "state/ralph-state.json"'),
+    },
+}, async ({ path }) => guarded(() => {
+    const contents = store.read(path);
+    return contents ?? `(no state at ${path})`;
+}));
+server.registerTool('state_write', {
+    title: 'Write oh-my-musecode state',
+    description: 'Write a file into the .omm/ state root, creating parent directories. Path is ' +
+        'relative to .omm/. Refuses any path that escapes the root or lands in a ' +
+        'muse-protected directory (.agents/, .muse/, .git/).',
+    inputSchema: {
+        path: z.string().describe('Path relative to the .omm/ state root'),
+        contents: z.string().describe('Full file contents to write'),
+    },
+}, async ({ path, contents }) => guarded(() => `wrote ${store.write(path, contents)}`));
+server.registerTool('state_clear', {
+    title: 'Clear oh-my-musecode state',
+    description: 'Remove a file or directory from the .omm/ state root. A missing target is a ' +
+        'no-op. Subject to the same protected-path refusal as state_write.',
+    inputSchema: {
+        path: z.string().describe('Path relative to the .omm/ state root'),
+    },
+}, async ({ path }) => guarded(() => (store.clear(path) ? `cleared ${path}` : `nothing to clear at ${path}`)));
+server.registerTool('persona_render', {
+    title: 'Render an oh-my-musecode persona',
+    description: 'Return a persona\'s SOUL text and routing description, ready to interpolate into a ' +
+        'subagent_spawn objective, plus the tool allowlist that child should be narrowed to. ' +
+        'Personas are prompts, not muse agent definitions: muse rejects `agents` as a plugin ' +
+        'capability, so the narrowing is advisory and the caller must apply it.',
+    inputSchema: {
+        id: z
+            .string()
+            .describe('Persona id, e.g. "executor", "critic", "verifier". Omit nothing; ids are exact.'),
+    },
+}, async ({ id }) => {
+    try {
+        const persona = loadPersonas().find((p) => p.id === id);
+        const rendered = renderPersonaPrompt(id);
+        const tools = persona ? persona.tools.join(', ') : '';
+        return {
+            content: [
+                { type: 'text', text: `${rendered}\n\nNarrow this child's tools to: ${tools}` },
+            ],
+        };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: err.message }], isError: true };
+    }
+});
+server.registerTool('persona_list', {
+    title: 'List oh-my-musecode personas',
+    description: 'List every available persona id with its routing description, so a skill can choose ' +
+        'the right one before calling persona_render.',
+    inputSchema: {},
+}, async () => ({
+    content: [
+        {
+            type: 'text',
+            text: loadPersonas()
+                .map((p) => `${p.id}: ${p.description}`)
+                .join('\n'),
+        },
+    ],
+}));
+await server.connect(new StdioServerTransport());
+//# sourceMappingURL=state-server.js.map

package/dist/mcp/state-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-server.js","sourceRoot":"","sources":["../../src/mcp/state-server.ts"],"names":[],"mappings":"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"}

package/dist/paths.d.ts

@@ -0,0 +1,58 @@
+/**
+ * State-root resolution and protected-path enforcement.
+ *
+ * muse protects `.agents/` and `.muse/` with two independent layers: a mediated
+ * `edit_file` write is held for human review with no standing grant, and a shell
+ * write fails read-only at the sandbox. Runtime state therefore cannot live in
+ * either, so oh-my-musecode keeps its own root at `.omm/`.
+ *
+ * This module is the single place that decides whether a path is writable, so the
+ * hooks and the MCP state server cannot drift apart on it.
+ */
+/** Directory name of the oh-my-musecode state root, relative to the workspace. */
+export declare const STATE_ROOT_DIRNAME = ".omm";
+/**
+ * Path prefixes muse protects. A write that resolves inside any of these is
+ * refused before it reaches the filesystem, so the failure is a clear error
+ * rather than an opaque read-only sandbox rejection mid-run.
+ */
+export declare const PROTECTED_DIRNAMES: readonly string[];
+export declare class ProtectedPathError extends Error {
+    readonly path: string;
+    readonly protectedSegment: string;
+    constructor(path: string, protectedSegment: string);
+}
+export declare class EscapedStateRootError extends Error {
+    readonly path: string;
+    constructor(path: string, stateRoot: string);
+}
+/** Absolute path of the state root for a workspace. */
+export declare function stateRoot(workspaceRoot: string): string;
+/**
+ * Creates the state root if absent. Returns its absolute path.
+ *
+ * Called by the SessionStart hook. Deliberately does not touch `.agents/` or
+ * `.muse/`, which the harness owns.
+ */
+export declare function ensureStateRoot(workspaceRoot: string): string;
+export declare class SymlinkedStateRootError extends Error {
+    readonly path: string;
+    constructor(root: string);
+}
+export declare class SymlinkTraversalError extends Error {
+    readonly path: string;
+    constructor(path: string, linkPath: string);
+}
+/**
+ * Resolves a caller-supplied path against the state root and refuses anything
+ * that escapes it or lands in a muse-protected directory.
+ *
+ * Both checks are needed and neither subsumes the other: the protected-path check
+ * gives an accurate message for the common mistake (`../../.agents/AGENTS.md`),
+ * while the containment check is the actual security boundary and catches every
+ * other escape.
+ *
+ * @throws {ProtectedPathError} when the path resolves into `.agents/`, `.muse/` or `.git/`
+ * @throws {EscapedStateRootError} when the path resolves outside the state root
+ */
+export declare function resolveWritablePath(workspaceRoot: string, requestedPath: string): string;