@maestrofrontier/frontier 1.4.4 → 1.4.5

package/scripts/install.cjs

@@ -11,6 +11,7 @@
 const fs   = require('fs');
 const os   = require('os');
 const path = require('path');
+const crypto = require('crypto');
 
 // ---- constants ----
 
@@ -25,7 +26,7 @@ const WRAPPER_MAP = {
   codex: {
     src:  'integrations/codex/prompts/frontier.md',
     proj: '.codex/prompts/frontier.md',
-    user: path.join(os.homedir(), '.codex', 'prompts', 'frontier.md'),
+    user: () => path.join(homeDir(), '.codex', 'prompts', 'frontier.md'),
   },
   cursor: {
     src:  'integrations/cursor/commands/frontier.md',
@@ -35,24 +36,252 @@ const WRAPPER_MAP = {
   gemini: {
     src:  'integrations/gemini/commands/frontier.toml',
     proj: '.gemini/commands/frontier.toml',
-    user: path.join(os.homedir(), '.gemini', 'commands', 'frontier.toml'),
+    user: () => path.join(homeDir(), '.gemini', 'commands', 'frontier.toml'),
   },
   cline: {
     src:  'integrations/cline/skills/frontier/SKILL.md',
     proj: '.cline/skills/frontier/SKILL.md',
-    user: path.join(os.homedir(), '.cline', 'skills', 'frontier', 'SKILL.md'),
+    user: () => path.join(homeDir(), '.cline', 'skills', 'frontier', 'SKILL.md'),
   },
   windsurf: {
     src:  'integrations/windsurf/workflows/frontier.md',
     proj: '.windsurf/workflows/frontier.md',
-    user: path.join(os.homedir(), '.codeium', 'windsurf', 'global_workflows', 'frontier.md'),
+    user: () => path.join(homeDir(), '.codeium', 'windsurf', 'global_workflows', 'frontier.md'),
   },
 };
 
 // Codex skill templates installed alongside the deprecated codex wrapper.
 // Codex loads skills from <project>/.agents/skills/<name>/SKILL.md (project)
-// or ~/.agents/skills/<name>/SKILL.md (global). No-clobber, like wrappers.
-const CODEX_SKILLS = ['frontier', 'terse', 'settings', 'update'];
+// or ~/.agents/skills/<name>/SKILL.md (global). Maestro-owned skills are
+// refreshed when still managed; user-edited copies are preserved.
+const CODEX_SKILLS = [
+  { name: 'maestro-frontier', legacy: 'frontier' },
+  { name: 'maestro-terse', legacy: 'terse' },
+  { name: 'maestro-settings', legacy: 'settings' },
+  { name: 'maestro-update', legacy: 'update' },
+];
+
+const LEGACY_CODEX_SKILL_TEMPLATES = {
+  frontier: `---
+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 codex\`.
+
+**This is a typing shortcut, not a prompt hook.** Codex has no automatic
+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).
+
+Map the user's request 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, Cline,
+Cursor, and Gemini 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 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.
+
+## Indicator instruction
+
+<!-- INDICATOR INSTRUCTION — apply every turn while this skill is active -->
+
+Before composing your first reply each turn, run:
+
+\`\`\`bash
+maestro frontier status --scope codex
+\`\`\`
+
+Parse the returned JSON \`mode\` field:
+
+- If \`mode\` is not \`off\`, make the **first line** of your reply exactly:
+  \`Maestro Frontier ON (<label>)\`
+  where \`<label>\` is formed as follows:
+  - single mode → \`single · <model>\` (e.g. \`single · opus\`)
+  - fusion mode → \`fusion · <preset>\` (e.g. \`fusion · frontier-trio\`);
+    for a custom preset use \`fusion · custom (<model1>, <model2>, ...)\`
+- If \`mode\` is \`off\`, output no indicator line.
+
+<!-- END INDICATOR INSTRUCTION -->
+
+## 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.
+`,
+  terse: `---
+name: terse
+description: Toggle Maestro terse output level (lite, full, ultra, off) via the settings CLI
+---
+
+Toggle the **Maestro terse** output level for this environment. Terse mode
+condenses agent replies; levels range from \`off\` (default verbosity) through
+\`lite\`, \`full\`, and \`ultra\` (most compressed).
+
+When the user invokes this skill, run the settings CLI to read or change the
+terse level. Do not edit settings files by hand.
+
+## Check current terse level
+
+\`\`\`bash
+node settings/cli.cjs --help
+\`\`\`
+
+Consult the help output for the exact read subcommand, then run it. If
+\`settings/cli.cjs\` is not present, run \`maestro --help\` to discover the
+correct path.
+
+## Set terse level
+
+\`\`\`bash
+node settings/cli.cjs terse <level>
+\`\`\`
+
+Valid levels: \`off\` | \`lite\` | \`full\` | \`ultra\`
+
+Examples:
+
+\`\`\`bash
+node settings/cli.cjs terse off
+node settings/cli.cjs terse lite
+node settings/cli.cjs terse full
+node settings/cli.cjs terse ultra
+\`\`\`
+
+If the CLI rejects an argument or the subcommand name differs, run
+\`node settings/cli.cjs --help\` first and follow the printed usage.
+
+## Notes
+
+- The change persists in Maestro's settings store; it applies to subsequent
+  agent turns in this project.
+- Requires \`node\` on \`PATH\` and Maestro installed in the project root. If
+  \`settings/cli.cjs\` is missing, re-run the Maestro installer:
+  \`npx github:mbanderas/maestro install --target codex\`
+`,
+  settings: `---
+name: settings
+description: View and change Maestro toggles (terse, frontier, context-bar) via the settings CLI
+---
+
+View or change **Maestro settings** for this project. The settings CLI manages
+the three primary toggles: \`terse\`, \`frontier\`, and \`context-bar\`.
+
+When the user invokes this skill, run the settings CLI from the repo root.
+Do not edit settings files by hand.
+
+## Discover available commands
+
+\`\`\`bash
+node settings/cli.cjs --help
+\`\`\`
+
+If \`settings/cli.cjs\` is not present, run \`maestro --help\` to locate the
+correct entry point.
+
+## Common operations
+
+List current settings:
+
+\`\`\`bash
+node settings/cli.cjs
+\`\`\`
+
+Set a toggle:
+
+\`\`\`bash
+node settings/cli.cjs terse <off|lite|full|ultra>
+node settings/cli.cjs frontier <off|single|fusion>
+node settings/cli.cjs context-bar <on|off>
+\`\`\`
+
+If a subcommand name or argument differs from the above, follow the usage
+printed by \`--help\` — do not guess flags.
+
+## Notes
+
+- Changes persist in Maestro's settings store and apply to subsequent agent
+  turns in this project.
+- Requires \`node\` on \`PATH\` and Maestro installed in the project root. If
+  \`settings/cli.cjs\` is missing, re-run the installer:
+  \`npx github:mbanderas/maestro install --target codex\`
+`,
+  update: `---
+name: update
+description: Update Maestro to the latest version by re-running the installer for Codex
+---
+
+Update **Maestro** to the latest marketplace code. This re-runs the installer,
+which pulls the current release and overwrites the local Maestro files in place.
+
+When the user invokes this skill, run the installer from the repo root:
+
+\`\`\`bash
+npx github:mbanderas/maestro install --target codex
+\`\`\`
+
+The installer is idempotent — it is safe to re-run against an existing
+installation. It will:
+
+- Pull the latest Maestro source from the repository.
+- Overwrite skills, hooks, and settings scaffolding with the new versions.
+- Leave project-local configuration (state files, secrets) untouched.
+
+## Notes
+
+- Requires \`node\` and \`npx\` on \`PATH\`.
+- Run from the project root so the installer targets the correct directory.
+- After the installer completes, restart the Codex session (or reload the
+  project) so updated skills and hooks take effect.
+- If \`npx\` is unavailable, clone \`https://github.com/mbanderas/maestro\`
+  manually and follow the repository's install instructions.
+`,
+};
 
 // Runtime adapter per target. The adapter imports @AGENTS.md (Cursor has no
 // imports, so .cursorrules embeds the kernel). codex/cline/windsurf read
@@ -132,6 +361,54 @@ function safeWrite(dest, content) {
   }
 }
 
+function homeDir() {
+  return process.platform === 'win32'
+    ? (process.env.USERPROFILE || os.homedir())
+    : (process.env.HOME || os.homedir());
+}
+
+function sha256(content) {
+  return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
+function codexSkillManagedContent(name, srcContent) {
+  const body = srcContent.trimEnd() + '\n';
+  return `${body}\n<!-- maestro-managed:codex-skill name=${name} sha256=${sha256(body)} -->\n`;
+}
+
+function splitCodexSkillMarker(content) {
+  const marker = /\n?<!-- maestro-managed:codex-skill name=([^\s]+) sha256=([a-f0-9]+|0000) -->\s*$/i.exec(content);
+  if (!marker) return null;
+  return {
+    name: marker[1],
+    hash: marker[2].toLowerCase(),
+    body: content.slice(0, marker.index).trimEnd() + '\n',
+  };
+}
+
+function isManagedCodexSkillContent(content, expectedName, managedBodies) {
+  const marker = splitCodexSkillMarker(content);
+  if (marker && marker.name === expectedName) {
+    return marker.hash === '0000' || marker.hash === sha256(marker.body);
+  }
+  if (content.includes(`maestro-managed:codex-skill name=${expectedName} sha256=0000`)) {
+    return true;
+  }
+  return managedBodies.some((body) => content.trimEnd() === body.trimEnd());
+}
+
+function legacyCodexSkillContent(legacyName, namespacedName) {
+  const body = `---\nname: ${legacyName}\ndescription: Legacy Maestro compatibility skill for ${namespacedName}\n---\n\nThis legacy Maestro skill has moved to \`${namespacedName}\`.\n\nUse the \`${namespacedName}\` skill for current Maestro behavior. This compatibility skill is kept only for existing Codex installs that still reference \`${legacyName}\`.\n`;
+  return codexSkillManagedContent(legacyName, body);
+}
+
+function legacyGenericCodexTemplate(srcContent, legacyName, namespacedName) {
+  return srcContent.replace(
+    new RegExp(`(^---\\r?\\nname: )${namespacedName}(\\r?\\n)`, 'm'),
+    `$1${legacyName}$2`
+  );
+}
+
 // ---- parse argv ----
 
 /**
@@ -361,7 +638,7 @@ function copyDirRecursive(srcDir, destDir, dryRun, log) {
 }
 
 /**
- * Install engine files (frontier/ dir + bin/maestro.cjs).
+ * Install engine files (frontier/ dir + settings/ dir + bin/maestro.cjs).
  * @param {string} projectRoot
  * @param {boolean} dryRun
  * @param {(msg: string) => void} log
@@ -370,10 +647,13 @@ function copyDirRecursive(srcDir, destDir, dryRun, log) {
 function installEngine(projectRoot, dryRun, log) {
   const srcFrontier  = path.join(PKG_ROOT, 'frontier');
   const destFrontier = path.join(projectRoot, 'frontier');
+  const srcSettings  = path.join(PKG_ROOT, 'settings');
+  const destSettings = path.join(projectRoot, 'settings');
   const srcBin       = path.join(PKG_ROOT, 'bin', 'maestro.cjs');
   const destBin      = path.join(projectRoot, 'bin', 'maestro.cjs');
 
   let ok = copyDirRecursive(srcFrontier, destFrontier, dryRun, log);
+  if (!copyDirRecursive(srcSettings, destSettings, dryRun, log)) ok = false;
 
   // bin/maestro.cjs
   if (dryRun) {
@@ -500,7 +780,7 @@ function installWrapper(target, projectRoot, userGlobal, dryRun, log) {
       log(`[wrapper] --user not supported for target ${target} — writing to project instead`);
       dest = path.join(projectRoot, mapping.proj);
     } else {
-      dest = mapping.user;
+      dest = mapping.user();
     }
   } else {
     dest = path.join(projectRoot, mapping.proj);
@@ -510,7 +790,8 @@ function installWrapper(target, projectRoot, userGlobal, dryRun, log) {
 }
 
 /**
- * Install the Codex skill templates (no-clobber) alongside the codex wrapper.
+ * Install the Codex skill templates alongside the codex wrapper. Maestro-owned
+ * skill files refresh in place; user-edited copies are preserved.
  * Project mode -> <project>/.agents/skills/<name>/SKILL.md; --user/global mode
  * -> ~/.agents/skills/<name>/SKILL.md (mirrors installWrapper's dest logic).
  * @param {string} projectRoot
@@ -519,16 +800,139 @@ function installWrapper(target, projectRoot, userGlobal, dryRun, log) {
  * @param {(msg: string) => void} log
  * @returns {boolean}
  */
+function installManagedCodexSkill(src, dest, name, legacyName, dryRun, log) {
+  let srcContent;
+  try {
+    srcContent = fs.readFileSync(src, 'utf8');
+  } catch (err) {
+    log(`ERROR: cannot read template ${src}: ${err.message}`);
+    return false;
+  }
+
+  const managedContent = codexSkillManagedContent(name, srcContent);
+  const managedBodies = [srcContent, managedContent];
+
+  let destStat;
+  try { destStat = fs.lstatSync(dest); } catch { destStat = null; }
+
+  if (destStat) {
+    if (destStat.isSymbolicLink()) {
+      log(`ERROR: codex-skill dest is a symlink — refusing: ${dest}`);
+      return false;
+    }
+
+    let existing;
+    try { existing = fs.readFileSync(dest, 'utf8'); } catch (err) {
+      log(`ERROR: cannot read existing Codex skill ${dest}: ${err.message}`);
+      return false;
+    }
+
+    if (!isManagedCodexSkillContent(existing, name, managedBodies)) {
+      log(`[codex-skill] preserved user-edited Codex skill: ${dest}`);
+      log(`[codex-skill] next step: compare with integrations/codex/skills/${name}/SKILL.md and manually merge if desired`);
+      return true;
+    }
+
+    if (existing === managedContent) {
+      log(`[codex-skill] up to date: ${dest}`);
+      return true;
+    }
+
+    if (dryRun) {
+      log(`[dry-run] would refresh managed Codex skill ${dest}`);
+      return true;
+    }
+
+    const res = safeWrite(dest, managedContent);
+    if (!res.ok) {
+      log(`ERROR: failed to refresh codex-skill ${dest}: ${res.reason}`);
+      return false;
+    }
+    log(`[codex-skill] refreshed managed Codex skill: ${dest}`);
+    return true;
+  }
+
+  if (dryRun) {
+    log(`[dry-run] would create ${dest}`);
+    return true;
+  }
+
+  if (!safeMkdirp(dest)) {
+    log(`ERROR: could not create parent dir for ${dest}`);
+    return false;
+  }
+
+  const res = safeWrite(dest, managedContent);
+  if (!res.ok) {
+    log(`ERROR: failed to write codex-skill ${dest}: ${res.reason}`);
+    return false;
+  }
+  log(`[codex-skill] wrote ${dest}`);
+  return true;
+}
+
+function migrateLegacyCodexSkill(dest, legacyName, namespacedName, knownTemplate, dryRun, log) {
+  let destStat;
+  try { destStat = fs.lstatSync(dest); } catch { return true; }
+
+  if (destStat.isSymbolicLink()) {
+    log(`ERROR: legacy codex-skill dest is a symlink — refusing: ${dest}`);
+    return false;
+  }
+
+  let existing;
+  try { existing = fs.readFileSync(dest, 'utf8'); } catch (err) {
+    log(`ERROR: cannot read legacy Codex skill ${dest}: ${err.message}`);
+    return false;
+  }
+
+  const shim = legacyCodexSkillContent(legacyName, namespacedName);
+  const managedBodies = [
+    knownTemplate,
+    legacyGenericCodexTemplate(knownTemplate, legacyName, namespacedName),
+    LEGACY_CODEX_SKILL_TEMPLATES[legacyName],
+    shim,
+  ].filter(Boolean);
+  if (!isManagedCodexSkillContent(existing, legacyName, managedBodies)) {
+    log(`[codex-skill] preserved user-edited legacy Codex skill: ${dest}`);
+    log(`[codex-skill] next step: rename or merge it into .agents/skills/${namespacedName}/SKILL.md if you still need custom behavior`);
+    return true;
+  }
+
+  if (existing === shim) {
+    log(`[codex-skill] legacy compatibility up to date: ${dest}`);
+    return true;
+  }
+
+  if (dryRun) {
+    log(`[dry-run] would migrate legacy Codex skill ${dest}`);
+    return true;
+  }
+
+  const res = safeWrite(dest, shim);
+  if (!res.ok) {
+    log(`ERROR: failed to migrate legacy codex-skill ${dest}: ${res.reason}`);
+    return false;
+  }
+  log(`[codex-skill] migrated legacy Codex skill to compatibility shim: ${dest}`);
+  return true;
+}
+
 function installCodexSkills(projectRoot, userGlobal, dryRun, log) {
   const skillsRoot = userGlobal
-    ? path.join(os.homedir(), '.agents', 'skills')
+    ? path.join(homeDir(), '.agents', 'skills')
     : path.join(projectRoot, '.agents', 'skills');
 
   let ok = true;
-  for (const name of CODEX_SKILLS) {
-    const src  = path.join(PKG_ROOT, 'integrations', 'codex', 'skills', name, 'SKILL.md');
-    const dest = path.join(skillsRoot, name, 'SKILL.md');
-    if (!installNoClobberFile(src, dest, 'codex-skill', dryRun, log)) ok = false;
+  for (const skill of CODEX_SKILLS) {
+    const src  = path.join(PKG_ROOT, 'integrations', 'codex', 'skills', skill.name, 'SKILL.md');
+    const dest = path.join(skillsRoot, skill.name, 'SKILL.md');
+    if (!installManagedCodexSkill(src, dest, skill.name, skill.legacy, dryRun, log)) ok = false;
+
+    let legacyTemplate = '';
+    try { legacyTemplate = fs.readFileSync(src, 'utf8'); } catch {}
+    const legacyDest = path.join(skillsRoot, skill.legacy, 'SKILL.md');
+    if (!migrateLegacyCodexSkill(legacyDest, skill.legacy, skill.name, legacyTemplate, dryRun, log)) ok = false;
   }
   return ok;
 }
@@ -602,4 +1006,9 @@ if (require.main === module) {
   process.exit(code);
 }
 
-module.exports = { run };
+module.exports = {
+  run,
+  _test: {
+    LEGACY_CODEX_SKILL_TEMPLATES,
+  },
+};

package/settings/cli.cjs

@@ -109,7 +109,7 @@ function usageText() {
     '    terse        <off|lite|full|ultra>\n' +
     '    frontier     <off | single:<model> | fusion:<preset>>\n' +
     '    context-bar  <on|off>\n' +
-    '  --scope targets a named frontier state (e.g. codex, cursor); omit to autodetect (Claude Code => per-workspace cc-<hash>)\n'
+    '  --scope targets a frontier state; use codex-project/codex-workspace for Codex repo scope, or an explicit name such as codex-global for shared state\n'
   );
 }
 

package/skills/maestro-frontier/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: maestro-frontier
+description: Maestro Frontier local multi-CLI fusion engine - arm, disarm, inspect, or debug-run the panel
+---
+
+Drive the **Maestro Frontier** engine: a zero-dependency local multi-CLI fusion
+engine where a parallel panel of local CLIs feeds a judge model's analysis and a
+grounded synthesis.
+
+When the Maestro Codex plugin hook is installed, enabled, and trusted, arming a
+non-`off` mode makes normal later Codex prompts auto-run through Frontier until
+you turn it off. Users should not need to type `maestro frontier run "<prompt>"`
+for normal use.
+
+Map the user's request to one engine CLI call and run it from the repo root.
+Do not edit the engine's state file by hand.
+
+## Command launcher
+
+Use `maestro` when it is on `PATH`. If it is not, and this skill is loaded
+from the Maestro Codex plugin, locate the plugin root by walking up from this
+`SKILL.md` until `.codex-plugin/plugin.json` is present, then run:
+
+```bash
+node "<maestro-plugin-root>/bin/maestro.cjs" frontier ...
+```
+
+In the examples below, `maestro frontier ...` means either the bare command or
+that plugin-root `node .../bin/maestro.cjs frontier ...` form.
+
+## 1. Switch mode
+
+Project/workspace scope is the default recommendation. Use `--scope
+codex-project` from the repository root; the CLI expands it to the same
+`codex-<8hex>` workspace scope the Codex plugin hook resolves from
+`PLUGIN_ROOT` / `PLUGIN_DATA`. Default mode is `off`.
+
+```bash
+maestro frontier mode off --scope codex-project
+maestro frontier mode single --model <model> --scope codex-project
+maestro frontier mode fusion --preset chatgpt-duo --scope codex-project
+maestro frontier mode fusion --preset frontier-trio --judge chatgpt --synth chatgpt --scope codex-project
+maestro frontier mode fusion --preset custom --models <a,b,c> --scope codex-project
+```
+
+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`. Friendly aliases are accepted: `chatgpt` maps to
+`gpt-5.5`, and `chatgpt-duo` maps to `gpt-duo`.
+
+Judge + synth default to Opus except for presets with explicit stage defaults.
+Override them for mixed panels with `--judge <model>` and `--synth <model>`;
+for example, `--judge chatgpt --synth chatgpt`.
+
+## 2. Show current mode/preset
+
+```bash
+maestro frontier status --scope codex-project
+```
+
+If you intentionally want one shared Codex state across unrelated repos, choose
+an explicit global name such as `--scope codex-global`. Do not use global scope
+unless that cross-repo behavior is what you want.
+
+## 3. Normal use after arming
+
+After mode is non-`off`, type ordinary Codex prompts. The trusted Codex hook
+auto-runs Frontier and injects the synthesized answer as context for the live
+reply. Turn it off with:
+
+```bash
+maestro frontier mode off --scope codex-project
+```
+
+## 4. Advanced/debug one-off run
+
+Manual one-off execution remains available for debugging:
+
+```bash
+maestro frontier run "<prompt>" --scope codex-project
+```
+
+- `off`: prints a notice, spawns nothing.
+- `single`: dispatches the one selected CLI, prints its answer.
+- `fusion`: runs the panel in parallel, then judge, then 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.
+
+## Indicator instruction
+
+<!-- INDICATOR INSTRUCTION - apply every turn while this skill is active -->
+
+Before composing your first reply each turn, run:
+
+```bash
+maestro frontier status --scope codex-project
+```
+
+Parse the returned JSON `mode` field:
+
+- If `mode` is not `off`, make the **first line** of your reply exactly:
+  `Maestro Frontier ON (<label>)`
+  where `<label>` is formed as follows:
+  - single mode -> `single - <model>` (e.g. `single - opus`)
+  - fusion mode -> `fusion - <preset>` (e.g. `fusion - frontier-trio`);
+    for a custom preset use `fusion - custom (<model1>, <model2>, ...)`
+- If `mode` is `off`, output no indicator line.
+
+<!-- END INDICATOR INSTRUCTION -->
+
+## Notes
+
+- Real `single`/`fusion` runs spawn local CLIs and cost tokens; `off` is free.
+- The autorun hook no-ops when `FUSION_DEPTH >= 1`, so child `codex`, `claude`,
+  and `gemini` panel processes do not recursively run Frontier.
+- 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 `node` on `PATH`. The bare `maestro` command is optional when the
+  skill is loaded from the Maestro Codex plugin; use the plugin-root launcher
+  above.