MM-Strategy

The Mutatis Mutandis strategy team's workbench. A strategist installs one small package and signs in once with MM-Work; from then on their agent host (Claude, Codex or Hermes) can do MM strategy work the MM way — the eight skills, the brand kit, artifact creation and publishing, social-signal research — while all of that intelligence stays on our server. The authoritative spec is epic #25.

What's here

• src/cli/ — the mm-strategy CLI (published): registers the MCP in each agent host, signs in, doctor, update.
• src/mcp/ — the MM MCP server (server-only): MM-Work sign-in and its own OAuth 2.1 server, the skills, the brand kit, projects, publishing, PDF, comments, presence, the scraper proxy. Tools are prefixed mm_; mm_skills_list is the entry point.
• skill/ — the routing skill the CLI installs into hosts (published).
• plugin/mm-strategy/ — the Hermes panel: a thin proxy over the server's API with the strategist's sign-in (published).
• skills/, brand/ — server content: the eight MM skills and the MM Style Kit (decisions 0002, 0004). Never in the package.
• worker/ — the artifact.mutmut.work Cloudflare worker.
• test/ — end-to-end tests driving the bundled server through the MCP client (npm test).
• scripts/ — release helpers delivered by the org bootstrap.
• docs/decisions/ — why things were chosen, one file per decision.

Who runs it

Jervaise owns the repo; Adil is project-admin. The strategy team are users, not developers: they install the package and sign in with their @mutatismutandis.co MM-Work account. Access follows the MMI Future three-level model: read for org members, developer as GitHub write, project-admin as write plus train-branch allowlist. Authority detail → Hub architecture; access runbook → repo-access.

Agent context

Read this section at the start of agent work in this repo.

• Structure search: Use available code search tools. Verify results against cited source before acting.
• Durable WHY: docs/decisions/ — one file per decision, prose only for what was chosen and rejected; never a description of current state. Do not maintain living current-state under docs/.
• Current state: code + live CLI (mmi-cli oracle org project get, board, status, org schedules, …) — registry facts, resolved live. Optional generated docs/index.md is a routing index only (mmi-cli oracle docs index --check), not product truth.
• GitHub wikis are retired org-wide — this repo does not publish to a .wiki.git; do not create one.
• Stack: TypeScript on Node 24, esbuild ESM bundles (CLI, MCP server, overlay). Server deps bundled in; the client bundle has none.
• Run locally: npm install, then npm run build; node dist/mcp.mjs serves the MCP on loopback, node dist/index.mjs doctor shows hosts.
• Verify before done: npm run check (typecheck, build, end-to-end MCP tests) — the same command the CI gate runs.
• Architecture: deep build/deploy shape → architecture.md
• Gotchas: host config paths differ per platform and per agent host — read them from src/cli/hosts.ts, never hardcode a second copy. package.json files is the IP boundary: a test packs the tarball and fails if skills/ or brand/ leak in. Credentials reach the server as environment variables the box writes at deploy, never from a file in this repo. MM-Work is not a dependency (decision 0003).

Dev synthetic test bot

Run npm run bot:dev -- --reset to exercise the dev Strategy module as MM-Work's synthetic people in headless Chrome (set CHROME_PATH if Chrome is not in the default location). mmi-cli vault secrets use supplies MMW_SYNTHETIC_SECRET without exposing it to the command line; --person test-a, --widths 390,480, and --only comments narrow a run; --theme light runs it in MM-Work's light theme. The bot refuses non-dev origins, writes screenshots to ignored tmp/bot/, and resets seeded documents both before and after --reset; board posts can persist on dev and are not cleared by that reset. Never use it on live data.

For a strategist

Not yet on npm (#45 adds the publish workflow). Until then, from a checkout of this repo:

npm install && npm run build
node dist/index.mjs install   # wires Claude Code / Codex / Hermes to the MM server, then MM-Work sign-in
node dist/index.mjs doctor    # what is wired, what is not

Once #45 ships, the one line becomes npm install -g @mutmutco/strategy.

On a real terminal install opens a branded flow: it greets you, asks which hosts to wire (Claude Code, Codex and Hermes are offered when they are on the machine), runs the steps as a checklist, and closes with a receipt. Piped or under --json/--yes it prints the same plain lines it always has — no prompts, no color.

◆  MM Strategy — Mutatis Mutandis
│
│  Welcome. Let's set up MM Strategy — about a minute.
│
◆  Install for which hosts?
│  ◻ Claude Code
│  ◻ OpenAI Codex
│  ◻ Hermes desktop
│
│  ◇  Registering MCP server
│  ◇  Writing skill files
│  ◇  Signing in
│
└  ✔  MM Strategy is ready.
   Check health any time:  mm-strategy doctor

install also turns on hourly automatic updates (mm-strategy autoupdate on|off|status); mm-strategy update brings in the newest release right now and re-wires the hosts.

Then ask your agent for MM work as usual; the mm-strategy skill routes it to the server. The Hermes panel is "MM Strategy" in the sidebar after a restart.

Start (developer)

npm install
npm run check
node dist/mcp.mjs          # MCP on http://127.0.0.1:8790/mcp

On the live box, MMWORK_ORIGIN remains the MM-Work sign-in/service endpoint (default https://mutmut.work at MMI_STAGE=main). The live backend also trusts https://rc.mutmut.work passes and ID tokens, verified against that issuer's own JWKS; MMWORK_EXTRA_ORIGINS adds comma-separated issuers for other deployments. The candidate bundle is only <MM_DATA_DIR>/rc/module.js, published by the Hub to the live host's mounted data directory and served at /rc/module.js?v=<tag>; no second server/database is started. Live /module.js and the live registry are unchanged.

npm run check verifies storage-schema.json against a fresh boot. After an additive migration, run npm run build && npm run schema:update and review/commit the snapshot. The PR gate also compares it against the base snapshot; intentional destructive changes require an exact object and issue in schema-destructive-allow.json (e.g. {"object":"column:users.google_refresh_token","issue":"#309"}). KV key prefixes and the store marker are included; old KV payload and version-read compatibility must also be exercised in tests when changing stored value shapes.

MMI developer environment

Use the canonical MMI developer-environment guide for shared setup and daily agent work.