@maestrofrontier/frontier 1.4.0

package/hooks/maestro-toolbudget-advisory.cjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// Maestro PostToolUse tool-call budget advisory (Fable T1). Log-only,
+// zero prompt tokens, never blocks.
+//
+// Fable scales tool calls to task complexity (1 for single facts; 3-5
+// medium; 5-10 deep research). Maestro caps subagent tool budgets (S9)
+// but nothing watches the ORCHESTRATOR's own pre-edit exploration. This
+// hook measures how many exploration (non-edit) tool calls happened this
+// turn before the FIRST file edit; if that exceeds a budget it appends
+// one advisory row to a local log. It is a behavioural lever, evidence-
+// gated: log-only first, so a preregistered OFF/ON fixture can show the
+// signal separates before anyone promotes it to an enforcing warning.
+//
+// Design choices:
+// - Fires on PostToolUse for edit tools; evaluates once per turn at the
+//   first-edit boundary (a per-turn marker file makes it idempotent).
+// - "Turn" = everything since the last genuine user prompt, located from
+//   the transcript with the same heuristic as maestro-phase-scope.
+// - ZERO prompt tokens: never writes stdout / additionalContext, so it
+//   adds nothing to context. It only appends a counts-only JSON row.
+// - NEVER blocks: PostToolUse cannot block and this emits no decision.
+// - Privacy: records counts + project folder basename only -- no
+//   prompts, no file contents, no paths. No network, ever.
+//
+// Env:
+// - MAESTRO_TOOLBUDGET=0           disable entirely (default: active, log-only)
+// - MAESTRO_TOOLBUDGET_THRESHOLD   exploration-call budget (default 20)
+// - MAESTRO_TOOLBUDGET_LOG         override log path (default ~/.claude/maestro-toolbudget.jsonl)
+// - MAESTRO_TOOLBUDGET_MARKERDIR   override per-turn marker dir (default OS tmp)
+//
+// Promotion path (NOT shipped, pending fixture evidence): a `warn` mode
+// that emits additionalContext at the first edit. Kept out until the log
+// shows the budget separates real over-exploration from normal work.
+//
+// Payload fields verified against code.claude.com/docs/en/hooks
+// (PostToolUse input: session_id, transcript_path, cwd, tool_name,
+// tool_input; PostToolUse output cannot block), 2026-06-16.
+//
+// .cjs so Node treats it as CommonJS regardless of any "type": "module"
+// package.json in a parent directory of the install location.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+if (process.env.MAESTRO_TOOLBUDGET === '0') process.exit(0);
+
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit', 'MultiEdit']);
+
+let data = {};
+try { data = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+// Only the first edit of a turn matters; ignore every non-edit tool.
+if (!EDIT_TOOLS.has(data.tool_name)) process.exit(0);
+
+// Counting exploration before the first edit needs the transcript.
+if (!data.transcript_path || !fs.existsSync(data.transcript_path)) process.exit(0);
+
+let lines = [];
+try {
+  const buf = fs.readFileSync(data.transcript_path, 'utf8');
+  lines = (buf.length > 4000000 ? buf.slice(-4000000) : buf).split(/\r?\n/);
+} catch { process.exit(0); }
+
+const parsed = lines.map(l => { try { return JSON.parse(l); } catch { return null; } });
+
+// Locate the last genuine user prompt (typed text, not a tool_result
+// carrier); everything after it is the current turn.
+let turnStart = 0;
+for (let i = 0; i < parsed.length; i++) {
+  const e = parsed[i];
+  if (!e || e.type !== 'user' || e.isMeta || !e.message) continue;
+  const c = e.message.content;
+  const genuine = typeof c === 'string'
+    ? true
+    : Array.isArray(c) && c.some(x => x && x.type === 'text') && !c.some(x => x && x.type === 'tool_result');
+  if (genuine) turnStart = i;
+}
+
+// Evaluate at most once per turn, at the first-edit boundary.
+const markerDir = process.env.MAESTRO_TOOLBUDGET_MARKERDIR || os.tmpdir();
+const turnKey = crypto.createHash('sha1')
+  .update(String(data.session_id || '') + ':' + turnStart + ':' + (lines[turnStart] || ''))
+  .digest('hex').slice(0, 16);
+const marker = path.join(markerDir, 'maestro-toolbudget-' + turnKey);
+if (fs.existsSync(marker)) process.exit(0);
+try { fs.mkdirSync(markerDir, { recursive: true }); fs.writeFileSync(marker, '1'); } catch {}
+
+// Count exploration (non-edit) tool calls that ran before the first edit
+// this turn. priorEdit stops the count at the first edit, whether or not
+// the triggering edit is already in the transcript.
+let explore = 0;
+let priorEdit = false;
+for (let i = turnStart; i < parsed.length; i++) {
+  const e = parsed[i];
+  if (!e || e.type !== 'assistant' || !e.message || !Array.isArray(e.message.content)) continue;
+  for (const item of e.message.content) {
+    if (!item || item.type !== 'tool_use') continue;
+    if (EDIT_TOOLS.has(item.name)) { priorEdit = true; break; }
+    explore++;
+  }
+  if (priorEdit) break;
+}
+
+const threshold = parseInt(process.env.MAESTRO_TOOLBUDGET_THRESHOLD, 10) || 20;
+if (explore > threshold) {
+  const row = {
+    ts: new Date().toISOString(),
+    session_id: data.session_id || null,
+    kind: 'toolbudget-advisory',
+    explore_calls: explore,
+    threshold,
+    first_edit_tool: data.tool_name,
+    project: data.cwd ? path.basename(data.cwd) : null
+  };
+  const logPath = process.env.MAESTRO_TOOLBUDGET_LOG
+    || path.join(os.homedir(), '.claude', 'maestro-toolbudget.jsonl');
+  try {
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    fs.appendFileSync(logPath, JSON.stringify(row) + '\n');
+  } catch { /* advisory is best-effort; never disrupt the session */ }
+}
+
+process.exit(0);

package/integrations/README.md

@@ -0,0 +1,87 @@
+# Maestro integrations — slash commands for other CLIs
+
+The Claude Code plugin ships Maestro's slash commands (`/maestro:*`) plus
+enforcement hooks and auto-run. Other agent CLIs support **custom slash commands**
+too, but only as *prompt templates* — they inject instruction text, they do not run
+wrapper logic, gate tools, or auto-run on every prompt. So these ports are typing
+shortcuts that tell the agent to shell out to the portable Frontier engine via
+`maestro frontier ...`; they are **not** a plugin equivalent.
+
+Only `/frontier` and `/update` are ported. `/frontier` drives the portable engine
+(`maestro frontier ...`); `/update` refreshes the install (git pull or re-download +
+re-copy `frontier/`, `bin/maestro.cjs`, and the command files). `terse`,
+`context-bar`, and `settings` depend on Claude Code hooks/status line and would only
+inject text elsewhere; `compress` operates on memory files and is partly portable.
+The orchestration doctrine itself needs no command — it lives in `AGENTS.md` and
+loads on demand.
+
+## Placement
+
+| Runtime | Source in this repo | Install to | Invoke |
+|---|---|---|---|
+| Cursor | `integrations/cursor/commands/frontier.md` | `.cursor/commands/frontier.md` (per-repo) or `~/.cursor/commands/` (global) | `/frontier` |
+| Codex (CLI + IDE/Desktop) | `integrations/codex/prompts/frontier.md` | `~/.codex/prompts/frontier.md` (global only) | `/frontier` |
+
+After adding a file, restart the tool or open a new chat so it loads. Both runtimes
+expand `$ARGUMENTS` to the full argument string — `/frontier fusion opus-gpt` passes
+`fusion opus-gpt`.
+
+Each runtime passes an explicit `--scope` flag so armed state is per-CLI and never
+leaks across runtimes on the same machine: Codex uses `--scope codex`, Cursor uses
+`--scope cursor`. Claude Code autodetects its scope and needs no flag. If you add a
+Gemini or Antigravity integration, pass `--scope gemini`.
+
+## Updating portable installs
+
+Portable installs have no plugin system. Update = refresh the copied files from
+latest `main`.
+
+**If you cloned the Maestro repo:**
+
+```bash
+git -C <path-to-maestro-clone> pull
+```
+
+Then re-copy `frontier/` and the integration command files into your project.
+
+**If you copied files manually** (no clone), re-download from latest `main` and
+overwrite the copies in your project:
+
+```bash
+curl -O https://raw.githubusercontent.com/mbanderas/maestro/main/AGENTS.md
+curl -O https://raw.githubusercontent.com/mbanderas/maestro/main/frontier/cli.cjs
+curl -O https://raw.githubusercontent.com/mbanderas/maestro/main/bin/maestro.cjs
+# Also re-copy the integration command file(s) you installed.
+```
+
+A `/update` shortcut command ships for each runtime — install it once and future
+updates are a single invocation:
+
+| Runtime | Source in this repo | Install to | Invoke |
+|---|---|---|---|
+| Cursor | `integrations/cursor/commands/update.md` | `.cursor/commands/update.md` (per-repo) or `~/.cursor/commands/` (global) | `/update` |
+| Codex (CLI + IDE/Desktop) | `integrations/codex/prompts/update.md` | `~/.codex/prompts/update.md` (global only) | `/update` |
+
+**Version model:** Maestro pins no version for portable files. Fetching from
+latest `main` always resolves the newest committed code — no manual version bump
+needed per release.
+
+## Caveats
+
+- **No auto-run.** Neither runtime has a `UserPromptSubmit` hook, so arming a mode
+  (`mode fusion`) only persists state — nothing fuses later prompts automatically.
+  Use `/frontier run "<prompt>"` to actually run the panel.
+- **Codex custom prompts are deprecated.** OpenAI's docs say *"Deprecated. Use
+  skills for reusable prompts."* The prompt file still works in current Codex (CLI
+  and IDE), but the forward path is a Codex *skill* (repo-shareable, implicitly
+  invoked) — a different format than this template. This port favors the simple
+  prompt file by design.
+- **Codex has no confirmed per-repo prompt path** — `~/.codex/prompts/` is global
+  per-user. Cursor's `.cursor/commands/` is the repo-scoped option.
+- **Requires `frontier/` and `bin/maestro.cjs` in the project.** The command runs
+  `maestro frontier ...` (or `node bin/maestro.cjs frontier ...`) from the repo root,
+  so the engine must have been copied in during install.
+- **Windows + Gemini judge/synth.** `gemini` is fine as a panel member, but a poor
+  `--judge`/`--synth` on Windows (its arg-passing rejects the newline-bearing
+  judge/synth prompts, so the stage degrades). Use `opus` or `gpt-5.5` for
+  judge/synth on Windows.

package/integrations/cline/skills/frontier/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: frontier
+description: Maestro Frontier local multi-CLI fusion engine — switch mode, or run a prompt through the panel
+---
+
+Drive the **Maestro Frontier** engine — a zero-dependency local multi-CLI fusion
+engine (a parallel panel of local CLIs → a judge model's analysis → a grounded
+synthesis). It is the same engine the Claude Code plugin ships; here it runs
+through the `maestro` CLI with `--scope cline`.
+
+**Install path (pick one):**
+
+- Project-scoped: `.cline/skills/frontier/SKILL.md`
+- Global: `~/.cline/skills/frontier/SKILL.md`
+
+**This is a typing shortcut, not the Claude Code plugin.** Cline has no prompt
+hook, so arming a mode does **not** auto-run the engine on later prompts — it
+only persists the mode. To actually fuse a prompt, invoke `run` explicitly
+(step 3).
+
+When the user invokes this skill, map their request to one engine CLI call and
+run it in the terminal (Cline will request approval before executing). Do not
+edit the engine's state file by hand.
+
+## 1. Switch mode
+
+Persists to `~/.config/maestro/frontier-state.cline.json`; default `off`.
+`--scope cline` keeps Cline's armed mode independent from Claude Code, Codex,
+Cursor, and Gemini on the same machine:
+
+```bash
+maestro frontier mode off --scope cline
+maestro frontier mode single --model <model> --scope cline
+maestro frontier mode fusion --preset <preset> --scope cline
+maestro frontier mode fusion --preset custom --models <a,b,c> --scope cline
+maestro frontier mode fusion --preset <preset> --judge <model> --synth <model> --scope cline
+```
+
+Models: `opus` (Claude Opus 4.8, needs `claude`), `gpt-5.5` (needs `codex`),
+`gemini` (needs `gemini`). Presets: `opus-duo`, `opus-gpt`, `gpt-duo`,
+`frontier-trio`, `custom`. Judge + synth default to Opus; `--judge`/`--synth`
+override for any preset (e.g. `--judge opus --synth gpt-5.5`). `gpt-duo` runs
+judge + synth on GPT-5.5 — a Codex-only fusion that needs no `claude`.
+
+## 2. Show current mode/preset
+
+```bash
+maestro frontier status --scope cline
+```
+
+## 3. Run a prompt through the current mode
+
+This is the action that actually fuses, since nothing auto-runs here. Set a
+mode first (step 1), then:
+
+```bash
+maestro frontier run "<prompt>" --scope cline
+```
+
+- `off`: prints a notice, spawns nothing.
+- `single`: dispatches the one selected CLI, prints its answer.
+- `fusion`: runs the panel in parallel → judge → synthesizer; prints the final
+  answer (a one-line run meta goes to stderr). Report stdout verbatim.
+
+On error the engine prints `ERROR [<reason>]: <detail>` to stderr and exits
+non-zero — relay the reason.
+
+## Notes
+
+- Real `single`/`fusion` runs spawn local CLIs and cost tokens; use small prompts.
+  `off` is free.
+- Each model's CLI must be on `PATH`, or point at a specific build with
+  `MAESTRO_CLAUDE_BIN` / `MAESTRO_CODEX_BIN` / `MAESTRO_GEMINI_BIN`.
+- Requires `maestro` on `PATH` (installed during Maestro setup). If it is missing,
+  install Maestro first.

package/integrations/codex/prompts/frontier.md

@@ -0,0 +1,66 @@
+---
+description: Maestro Frontier local multi-CLI fusion engine — switch mode, or run a prompt through the panel
+argument-hint: "<off | single <model> | fusion <preset> | status | run <prompt>>"
+---
+
+Drive the **Maestro Frontier** engine — a zero-dependency local multi-CLI fusion
+engine (a parallel panel of local CLIs → a judge model's analysis → a grounded
+synthesis). It is the same engine the Claude Code plugin ships; here it runs through
+the `maestro` CLI, installed into this repo during setup.
+
+**This is a typing shortcut, not the Claude Code plugin.** Codex has no
+prompt hook, so arming a mode does **not** auto-run the engine on later prompts —
+it only persists the mode. To actually fuse a prompt, invoke `run` explicitly
+(step 3).
+
+Requested action: `$ARGUMENTS`
+
+Map it to one engine CLI call and run it from the repo root. Do not edit
+the engine's state file by hand.
+
+1. Switch mode (persists to `~/.config/maestro/frontier-state.codex.json`; default `off`).
+   `--scope codex` keeps Codex's armed mode independent from Claude Code and Cursor on the same machine:
+
+   ```bash
+   maestro frontier mode off --scope codex
+   maestro frontier mode single --model <model> --scope codex
+   maestro frontier mode fusion --preset <preset> --scope codex
+   maestro frontier mode fusion --preset custom --models <a,b,c> --scope codex
+   maestro frontier mode fusion --preset <preset> --judge <model> --synth <model> --scope codex
+   ```
+
+   Models: `opus` (Claude Opus 4.8, needs `claude`), `gpt-5.5` (needs `codex`),
+   `gemini` (needs `gemini`). Presets: `opus-duo`, `opus-gpt`, `gpt-duo`,
+   `frontier-trio`, `custom`. Judge + synth default to Opus; `--judge`/`--synth`
+   override for any preset (e.g. `--judge opus --synth gpt-5.5`). `gpt-duo` runs
+   judge + synth on GPT-5.5 — a Codex-only fusion that needs no `claude`.
+
+2. Show the current mode/preset:
+
+   ```bash
+   maestro frontier status --scope codex
+   ```
+
+3. Run a prompt through the current mode — **this is the action that actually
+   fuses**, since nothing auto-runs here. Set a mode first (step 1), then:
+
+   ```bash
+   maestro frontier run "<prompt>" --scope codex
+   ```
+
+   - `off`: prints a notice, spawns nothing.
+   - `single`: dispatches the one selected CLI, prints its answer.
+   - `fusion`: runs the panel in parallel → judge → synthesizer; prints the final
+     answer (a one-line run meta goes to stderr). Report stdout verbatim.
+
+On error the engine prints `ERROR [<reason>]: <detail>` to stderr and exits
+non-zero — relay the reason.
+
+Notes:
+
+- Real `single`/`fusion` runs spawn local CLIs and cost tokens; use small prompts.
+  `off` is free.
+- Each model's CLI must be on `PATH`, or point at a specific build with
+  `MAESTRO_CLAUDE_BIN` / `MAESTRO_CODEX_BIN` / `MAESTRO_GEMINI_BIN`.
+- Requires `maestro` on `PATH` (installed during Maestro setup). If it is missing,
+  install Maestro first.

package/integrations/codex/prompts/update.md

@@ -0,0 +1,36 @@
+---
+description: Update Maestro portable files to the latest committed code
+argument-hint: ""
+---
+
+Refresh the Maestro portable install in this repository to the latest committed
+code from <https://github.com/mbanderas/maestro>.
+
+Maestro has no version pin for portable installs — fetching the latest `main`
+always resolves the newest committed code.
+
+**If this repo contains a git clone of the Maestro source**, run:
+
+```bash
+git -C <path-to-maestro-clone> pull
+```
+
+Then re-copy `frontier/` and any integration command files you use into this project.
+
+**If you downloaded and copied files manually** (no clone), re-fetch and re-copy
+from latest `main`:
+
+```bash
+curl -O https://raw.githubusercontent.com/mbanderas/maestro/main/AGENTS.md
+curl -O https://raw.githubusercontent.com/mbanderas/maestro/main/frontier/cli.cjs
+curl -O https://raw.githubusercontent.com/mbanderas/maestro/main/bin/maestro.cjs
+# Re-copy any integration command files you installed:
+#   integrations/codex/prompts/frontier.md -> ~/.codex/prompts/frontier.md
+#   integrations/codex/prompts/update.md   -> ~/.codex/prompts/update.md
+```
+
+After updating, run `node bin/maestro.cjs frontier status` to confirm the engine is present.
+
+Report what was refreshed and note any errors.
+
+Do not edit any other files.

package/integrations/cursor/commands/frontier.md

@@ -0,0 +1,63 @@
+Maestro Frontier — drive the local multi-CLI fusion engine (switch mode, or run a prompt through the panel).
+
+Drive the **Maestro Frontier** engine — a zero-dependency local multi-CLI fusion
+engine (a parallel panel of local CLIs → a judge model's analysis → a grounded
+synthesis). It is the same engine the Claude Code plugin ships; here it runs through
+the `maestro` CLI, installed into this repo during setup.
+
+**This is a typing shortcut, not the Claude Code plugin.** Cursor has no
+prompt hook, so arming a mode does **not** auto-run the engine on later prompts —
+it only persists the mode. To actually fuse a prompt, invoke `run` explicitly
+(step 3).
+
+Requested action: `$ARGUMENTS`
+
+Map it to one engine CLI call and run it from the repo root. Do not edit
+the engine's state file by hand.
+
+1. Switch mode (persists to `~/.config/maestro/frontier-state.cursor.json`; default `off`).
+   `--scope cursor` keeps Cursor's armed mode independent from Claude Code and Codex on the same machine:
+
+   ```bash
+   maestro frontier mode off --scope cursor
+   maestro frontier mode single --model <model> --scope cursor
+   maestro frontier mode fusion --preset <preset> --scope cursor
+   maestro frontier mode fusion --preset custom --models <a,b,c> --scope cursor
+   maestro frontier mode fusion --preset <preset> --judge <model> --synth <model> --scope cursor
+   ```
+
+   Models: `opus` (Claude Opus 4.8, needs `claude`), `gpt-5.5` (needs `codex`),
+   `gemini` (needs `gemini`). Presets: `opus-duo`, `opus-gpt`, `gpt-duo`,
+   `frontier-trio`, `custom`. Judge + synth default to Opus; `--judge`/`--synth`
+   override for any preset (e.g. `--judge opus --synth gpt-5.5`). `gpt-duo` runs
+   judge + synth on GPT-5.5 — a Codex-only fusion that needs no `claude`.
+
+2. Show the current mode/preset:
+
+   ```bash
+   maestro frontier status --scope cursor
+   ```
+
+3. Run a prompt through the current mode — **this is the action that actually
+   fuses**, since nothing auto-runs here. Set a mode first (step 1), then:
+
+   ```bash
+   maestro frontier run "<prompt>" --scope cursor
+   ```
+
+   - `off`: prints a notice, spawns nothing.
+   - `single`: dispatches the one selected CLI, prints its answer.
+   - `fusion`: runs the panel in parallel → judge → synthesizer; prints the final
+     answer (a one-line run meta goes to stderr). Report stdout verbatim.
+
+On error the engine prints `ERROR [<reason>]: <detail>` to stderr and exits
+non-zero — relay the reason.
+
+Notes:
+
+- Real `single`/`fusion` runs spawn local CLIs and cost tokens; use small prompts.
+  `off` is free.
+- Each model's CLI must be on `PATH`, or point at a specific build with
+  `MAESTRO_CLAUDE_BIN` / `MAESTRO_CODEX_BIN` / `MAESTRO_GEMINI_BIN`.
+- Requires `maestro` on `PATH` (installed during Maestro setup). If it is missing,
+  install Maestro first.

package/integrations/cursor/commands/update.md

@@ -0,0 +1,34 @@
+Maestro update — refresh the portable Maestro files in this repository to the latest committed code.
+
+Refresh the Maestro portable install in this repository to the latest committed
+code from <https://github.com/mbanderas/maestro>.
+
+Maestro has no version pin for portable installs — fetching the latest `main`
+always resolves the newest committed code.
+
+**If this repo contains a git clone of the Maestro source**, run:
+
+```bash
+git -C <path-to-maestro-clone> pull
+```
+
+Then re-copy `frontier/` and any integration command files you use into this project.
+
+**If you downloaded and copied files manually** (no clone), re-fetch and re-copy
+from latest `main`:
+
+```bash
+curl -O https://raw.githubusercontent.com/mbanderas/maestro/main/AGENTS.md
+curl -O https://raw.githubusercontent.com/mbanderas/maestro/main/.cursorrules
+curl -O https://raw.githubusercontent.com/mbanderas/maestro/main/frontier/cli.cjs
+curl -O https://raw.githubusercontent.com/mbanderas/maestro/main/bin/maestro.cjs
+# Re-copy the Cursor command files you installed:
+#   integrations/cursor/commands/frontier.md -> .cursor/commands/frontier.md
+#   integrations/cursor/commands/update.md   -> .cursor/commands/update.md
+```
+
+After updating, run `node bin/maestro.cjs frontier status` to confirm the engine is present.
+
+Report what was refreshed and note any errors.
+
+Do not edit any other files.

package/integrations/gemini/commands/frontier.toml

@@ -0,0 +1,76 @@
+# Maestro Frontier — Gemini CLI custom command
+#
+# Install path (pick one):
+#   Project-scoped : <project>/.gemini/commands/frontier.toml
+#   Global         : ~/.gemini/commands/frontier.toml
+#
+# Once installed, invoke with `/frontier <args>` inside the Gemini CLI.
+# This command arms or queries the Maestro Frontier engine with
+# `--scope gemini`, keeping Gemini's state independent from Claude Code,
+# Codex, and Cursor on the same machine.
+#
+# Requires `maestro` on PATH (installed during Maestro setup).
+
+description = "Maestro Frontier local multi-CLI fusion engine — switch mode, or run a prompt through the panel"
+
+prompt = """
+Drive the **Maestro Frontier** engine — a zero-dependency local multi-CLI fusion
+engine (a parallel panel of local CLIs → a judge model's analysis → a grounded
+synthesis). It is the same engine the Claude Code plugin ships; here it runs
+through the `maestro` CLI with `--scope gemini`.
+
+**This is a typing shortcut, not the Claude Code plugin.** Gemini CLI has no
+prompt hook, so arming a mode does **not** auto-run the engine on later prompts —
+it only persists the mode. To actually fuse a prompt, invoke `run` explicitly
+(step 3).
+
+Requested action: {{args}}
+
+Map it to one engine CLI call and execute it. Do not edit the engine's state
+file by hand.
+
+1. Switch mode (persists to `~/.config/maestro/frontier-state.gemini.json`; default `off`).
+   `--scope gemini` keeps Gemini's armed mode independent from Claude Code, Codex,
+   and Cursor on the same machine:
+
+   !{maestro frontier mode off --scope gemini}
+   !{maestro frontier mode single --model <model> --scope gemini}
+   !{maestro frontier mode fusion --preset <preset> --scope gemini}
+   !{maestro frontier mode fusion --preset custom --models <a,b,c> --scope gemini}
+   !{maestro frontier mode fusion --preset <preset> --judge <model> --synth <model> --scope gemini}
+
+   Models: `opus` (Claude Opus 4.8, needs `claude`), `gpt-5.5` (needs `codex`),
+   `gemini` (needs `gemini`). Presets: `opus-duo`, `opus-gpt`, `gpt-duo`,
+   `frontier-trio`, `custom`. Judge + synth default to Opus; `--judge`/`--synth`
+   override for any preset (e.g. `--judge opus --synth gpt-5.5`). `gpt-duo` runs
+   judge + synth on GPT-5.5 — a Codex-only fusion that needs no `claude`.
+
+2. Show the current mode/preset:
+
+   !{maestro frontier status --scope gemini}
+
+3. Run a prompt through the current mode — **this is the action that actually
+   fuses**, since nothing auto-runs here. Set a mode first (step 1), then:
+
+   !{maestro frontier run "{{args}}" --scope gemini}
+
+   - `off`: prints a notice, spawns nothing.
+   - `single`: dispatches the one selected CLI, prints its answer.
+   - `fusion`: runs the panel in parallel → judge → synthesizer; prints the final
+     answer (a one-line run meta goes to stderr). Report stdout verbatim.
+
+On error the engine prints `ERROR [<reason>]: <detail>` to stderr and exits
+non-zero — relay the reason.
+
+Notes:
+
+- Real `single`/`fusion` runs spawn local CLIs and cost tokens; use small prompts.
+  `off` is free.
+- Each model's CLI must be on `PATH`, or point at a specific build with
+  `MAESTRO_CLAUDE_BIN` / `MAESTRO_CODEX_BIN` / `MAESTRO_GEMINI_BIN`.
+- On Windows, `gemini` is a poor `--judge`/`--synth` choice: judge/synth prompts
+  contain newlines that the win32 arg-safety guard refuses. Use `opus` or `gpt-5.5`
+  for judge/synth on Windows.
+- Requires `maestro` on `PATH` (installed during Maestro setup). If it is missing,
+  install Maestro first.
+"""

package/integrations/windsurf/workflows/frontier.md

@@ -0,0 +1,70 @@
+Maestro Frontier — drive the local multi-CLI fusion engine (switch mode, or run a prompt through the panel).
+
+Drive the **Maestro Frontier** engine — a zero-dependency local multi-CLI fusion
+engine (a parallel panel of local CLIs → a judge model's analysis → a grounded
+synthesis). It is the same engine the Claude Code plugin ships; here it runs
+through the `maestro` CLI with `--scope windsurf`.
+
+**Install path (pick one):**
+
+- Project-scoped: `.windsurf/workflows/frontier.md`
+- Global: `~/.codeium/windsurf/global_workflows/frontier.md`
+
+Once installed, invoke with `/frontier <args>` inside Windsurf Cascade.
+
+**This is a typing shortcut, not the Claude Code plugin.** Windsurf Cascade has
+no prompt hook, so arming a mode does **not** auto-run the engine on later
+prompts — it only persists the mode. To actually fuse a prompt, invoke `run`
+explicitly (step 3).
+
+When this workflow is invoked, map the requested action to one engine CLI call
+and run it in the terminal. Cascade will request approval before executing. Do
+not edit the engine's state file by hand.
+
+1. Switch mode (persists to `~/.config/maestro/frontier-state.windsurf.json`; default `off`).
+   `--scope windsurf` keeps Windsurf's armed mode independent from Claude Code,
+   Codex, Cursor, Gemini, and Cline on the same machine:
+
+   ```bash
+   maestro frontier mode off --scope windsurf
+   maestro frontier mode single --model <model> --scope windsurf
+   maestro frontier mode fusion --preset <preset> --scope windsurf
+   maestro frontier mode fusion --preset custom --models <a,b,c> --scope windsurf
+   maestro frontier mode fusion --preset <preset> --judge <model> --synth <model> --scope windsurf
+   ```
+
+   Models: `opus` (Claude Opus 4.8, needs `claude`), `gpt-5.5` (needs `codex`),
+   `gemini` (needs `gemini`). Presets: `opus-duo`, `opus-gpt`, `gpt-duo`,
+   `frontier-trio`, `custom`. Judge + synth default to Opus; `--judge`/`--synth`
+   override for any preset (e.g. `--judge opus --synth gpt-5.5`). `gpt-duo` runs
+   judge + synth on GPT-5.5 — a Codex-only fusion that needs no `claude`.
+
+2. Show the current mode/preset:
+
+   ```bash
+   maestro frontier status --scope windsurf
+   ```
+
+3. Run a prompt through the current mode — **this is the action that actually
+   fuses**, since nothing auto-runs here. Set a mode first (step 1), then:
+
+   ```bash
+   maestro frontier run "<prompt>" --scope windsurf
+   ```
+
+   - `off`: prints a notice, spawns nothing.
+   - `single`: dispatches the one selected CLI, prints its answer.
+   - `fusion`: runs the panel in parallel → judge → synthesizer; prints the final
+     answer (a one-line run meta goes to stderr). Report stdout verbatim.
+
+On error the engine prints `ERROR [<reason>]: <detail>` to stderr and exits
+non-zero — relay the reason.
+
+Notes:
+
+- Real `single`/`fusion` runs spawn local CLIs and cost tokens; use small prompts.
+  `off` is free.
+- Each model's CLI must be on `PATH`, or point at a specific build with
+  `MAESTRO_CLAUDE_BIN` / `MAESTRO_CODEX_BIN` / `MAESTRO_GEMINI_BIN`.
+- Requires `maestro` on `PATH` (installed during Maestro setup). If it is missing,
+  install Maestro first.