@maestrofrontier/frontier 1.4.0 → 1.4.2

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

@@ -0,0 +1,91 @@
+---
+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.

package/integrations/codex/skills/settings/SKILL.md

@@ -0,0 +1,46 @@
+---
+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`

package/integrations/codex/skills/terse/SKILL.md

@@ -0,0 +1,49 @@
+---
+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`

package/integrations/codex/skills/update/SKILL.md

@@ -0,0 +1,29 @@
+---
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestrofrontier/frontier",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Achieve Frontier AI performance in your CLI by fusing the model CLIs you already run. Maestro Frontier is an opt-in, zero-dependency local multi-CLI fusion engine for AI coding agents: fan a prompt across a panel of any 1 to 8 local model CLIs you pick, have a judge model and a synthesizer you choose read the answers into a structured analysis and write one grounded synthesis (default Opus 4.8, override either with --judge/--synth). On a 100-task benchmark every fusion panel outscored its individual member models. Three adapters ship today: Opus 4.8, GPT-5.5, Gemini 3.1 Pro, with Kimi, DeepSeek, GLM, and Qwen to follow. Off, single, and fusion modes switch via /maestro:frontier. Built on Maestro orchestration discipline: decision-gated routing, verified done-claims, surgical scope, and structural enforcement hooks.",
   "keywords": ["multi-cli-fusion", "fusion-engine", "frontier", "multi-agent", "orchestration", "claude-code", "gemini", "codex", "agents", "hooks", "doctrine"],
   "license": "MIT",
@@ -27,7 +27,10 @@
     "scripts/install.cjs",
     "AGENTS.md",
     "CLAUDE.md",
+    "GEMINI.md",
+    ".cursorrules",
     "docs/orchestration.md",
+    "docs/codex.md",
     "commands/",
     "integrations/",
     "hooks/frontier-autorun.cjs",

package/scripts/install.cjs

@@ -49,6 +49,20 @@ const WRAPPER_MAP = {
   },
 };
 
+// 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'];
+
+// Runtime adapter per target. The adapter imports @AGENTS.md (Cursor has no
+// imports, so .cursorrules embeds the kernel). codex/cline/windsurf read
+// AGENTS.md directly and need no adapter.
+const ADAPTER_MAP = {
+  claude: 'CLAUDE.md',
+  gemini: 'GEMINI.md',
+  cursor: '.cursorrules',
+};
+
 // Marker dirs used for auto-detection (scanned inside project root)
 const AUTO_MARKERS = [
   { dir: '.cursor',  target: 'cursor'   },
@@ -177,48 +191,53 @@ function detectTarget(projectRoot) {
 // ---- install actions ----
 
 /**
- * Install doctrine (AGENTS.md) into project root. Append-only, idempotent.
- * @param {string} projectRoot
- * @param {boolean} dryRun
+ * Read a file from the package root. Returns string, or null (logs) on error.
+ * @param {string} rel
  * @param {(msg: string) => void} log
- * @returns {boolean} true = success (or no-op), false = error
+ * @returns {string|null}
  */
-function installDoctrine(projectRoot, dryRun, log) {
-  const dest     = path.join(projectRoot, 'AGENTS.md');
-  const srcPath  = path.join(PKG_ROOT, 'AGENTS.md');
-
-  let srcContent;
+function readPkgFile(rel, log) {
   try {
-    srcContent = fs.readFileSync(srcPath, 'utf8');
+    return fs.readFileSync(path.join(PKG_ROOT, rel), 'utf8');
   } catch (err) {
-    log(`ERROR: cannot read package AGENTS.md: ${err.message}`);
-    return false;
+    log(`ERROR: cannot read package ${rel}: ${err.message}`);
+    return null;
   }
+}
 
+/**
+ * Install a doctrine/adapter markdown file. Append-only, idempotent, never
+ * clobbers user content above the maestro block; refuses symlinks.
+ * @param {string} dest absolute destination path
+ * @param {string} srcContent content to install
+ * @param {string} label short name for logs (e.g. "AGENTS.md")
+ * @param {boolean} dryRun
+ * @param {(msg: string) => void} log
+ * @returns {boolean} true = success (or no-op), false = error
+ */
+function appendOnlyDoctrine(dest, srcContent, label, dryRun, log) {
   const block = `\n${SENTINEL}\n${srcContent}\n${SENTINEL_END}\n`;
 
-  // Check if dest exists
   let existsStat;
   try { existsStat = fs.lstatSync(dest); } catch { existsStat = null; }
 
   if (existsStat) {
     if (existsStat.isSymbolicLink()) {
-      log(`ERROR: AGENTS.md is a symlink — refusing to write through it: ${dest}`);
+      log(`ERROR: ${label} is a symlink — refusing to write through it: ${dest}`);
       return false;
     }
 
     let existing;
     try { existing = fs.readFileSync(dest, 'utf8'); } catch (err) {
-      log(`ERROR: cannot read existing AGENTS.md: ${err.message}`);
+      log(`ERROR: cannot read existing ${label}: ${err.message}`);
       return false;
     }
 
     if (existing.includes(SENTINEL)) {
-      log(`[doctrine] AGENTS.md already contains sentinel — skipping`);
+      log(`[doctrine] ${label} already contains sentinel — skipping`);
       return true;
     }
 
-    // Append block
     if (dryRun) {
       log(`[dry-run] would append maestro doctrine to existing ${dest}`);
       return true;
@@ -226,14 +245,14 @@ function installDoctrine(projectRoot, dryRun, log) {
 
     const res = safeWrite(dest, existing + block);
     if (!res.ok) {
-      log(`ERROR: failed to append to AGENTS.md: ${res.reason}`);
+      log(`ERROR: failed to append to ${label}: ${res.reason}`);
       return false;
     }
-    log(`[doctrine] appended maestro block to existing AGENTS.md`);
+    log(`[doctrine] appended maestro block to existing ${label}`);
     return true;
   }
 
-  // Absent — write fresh. Wrap in sentinel block so subsequent runs detect it.
+  // Absent — write fresh, wrapped in the sentinel so re-runs detect it.
   if (dryRun) {
     log(`[dry-run] would create ${dest}`);
     return true;
@@ -247,13 +266,43 @@ function installDoctrine(projectRoot, dryRun, log) {
   const freshContent = SENTINEL + '\n' + srcContent + '\n' + SENTINEL_END + '\n';
   const res = safeWrite(dest, freshContent);
   if (!res.ok) {
-    log(`ERROR: failed to write AGENTS.md: ${res.reason}`);
+    log(`ERROR: failed to write ${label}: ${res.reason}`);
     return false;
   }
-  log(`[doctrine] wrote AGENTS.md`);
+  log(`[doctrine] wrote ${label}`);
   return true;
 }
 
+/**
+ * Install the portable doctrine core (AGENTS.md) into the project root.
+ * @param {string} projectRoot
+ * @param {boolean} dryRun
+ * @param {(msg: string) => void} log
+ * @returns {boolean}
+ */
+function installDoctrine(projectRoot, dryRun, log) {
+  const src = readPkgFile('AGENTS.md', log);
+  if (src === null) return false;
+  return appendOnlyDoctrine(path.join(projectRoot, 'AGENTS.md'), src, 'AGENTS.md', dryRun, log);
+}
+
+/**
+ * Install the runtime adapter for a target (CLAUDE.md / GEMINI.md /
+ * .cursorrules). codex/cline/windsurf read AGENTS.md directly -> no-op.
+ * @param {string} target
+ * @param {string} projectRoot
+ * @param {boolean} dryRun
+ * @param {(msg: string) => void} log
+ * @returns {boolean}
+ */
+function installAdapter(target, projectRoot, dryRun, log) {
+  const rel = ADAPTER_MAP[target];
+  if (!rel) return true; // no adapter for this target
+  const src = readPkgFile(rel, log);
+  if (src === null) return false;
+  return appendOnlyDoctrine(path.join(projectRoot, rel), src, rel, dryRun, log);
+}
+
 /**
  * Recursively copy srcDir -> destDir, skipping *.test.cjs files.
  * @param {string} srcDir
@@ -345,9 +394,81 @@ function installEngine(projectRoot, dryRun, log) {
     }
   }
 
+  // docs/orchestration.md — the on-demand S2-S6 multi-agent protocol the
+  // kernel references. Maestro-owned reference file; copy (refuse symlinks).
+  const srcDocs  = path.join(PKG_ROOT, 'docs', 'orchestration.md');
+  const destDocs = path.join(projectRoot, 'docs', 'orchestration.md');
+  if (dryRun) {
+    log(`[dry-run] would write ${destDocs}`);
+  } else if (isSymlink(destDocs)) {
+    log(`ERROR: docs/orchestration.md is a symlink — refusing: ${destDocs}`);
+    ok = false;
+  } else {
+    try {
+      fs.mkdirSync(path.dirname(destDocs), { recursive: true });
+      fs.writeFileSync(destDocs, fs.readFileSync(srcDocs));
+      log(`[doctrine] copied ${destDocs}`);
+    } catch (err) {
+      log(`ERROR: failed to copy docs/orchestration.md: ${err.message}`);
+      ok = false;
+    }
+  }
+
   return ok;
 }
 
+/**
+ * Copy a single package template file to dest, no-clobber. Skips when dest
+ * already exists, refuses symlinks, honors dry-run. Reuses safeMkdirp +
+ * safeWrite. Shared by wrapper and Codex-skill installs.
+ * @param {string} src absolute source path (under PKG_ROOT)
+ * @param {string} dest absolute destination path
+ * @param {string} label short tag for logs (e.g. "wrapper", "codex-skill")
+ * @param {boolean} dryRun
+ * @param {(msg: string) => void} log
+ * @returns {boolean} true = success (wrote, skipped, or planned), false = error
+ */
+function installNoClobberFile(src, dest, label, dryRun, log) {
+  // Check if dest exists already (no-clobber)
+  let destStat;
+  try { destStat = fs.lstatSync(dest); } catch { destStat = null; }
+
+  if (destStat) {
+    if (destStat.isSymbolicLink()) {
+      log(`ERROR: ${label} dest is a symlink — refusing: ${dest}`);
+      return false;
+    }
+    log(`[${label}] skipped (exists, not clobbered): ${dest}`);
+    return true;
+  }
+
+  let srcContent;
+  try {
+    srcContent = fs.readFileSync(src, 'utf8');
+  } catch (err) {
+    log(`ERROR: cannot read template ${src}: ${err.message}`);
+    return false;
+  }
+
+  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, srcContent);
+  if (!res.ok) {
+    log(`ERROR: failed to write ${label} ${dest}: ${res.reason}`);
+    return false;
+  }
+  log(`[${label}] wrote ${dest}`);
+  return true;
+}
+
 /**
  * Install wrapper file (no-clobber).
  * @param {string} target
@@ -385,44 +506,31 @@ function installWrapper(target, projectRoot, userGlobal, dryRun, log) {
     dest = path.join(projectRoot, mapping.proj);
   }
 
-  // Check if dest exists already (no-clobber)
-  let destStat;
-  try { destStat = fs.lstatSync(dest); } catch { destStat = null; }
-
-  if (destStat) {
-    if (destStat.isSymbolicLink()) {
-      log(`ERROR: wrapper dest is a symlink — refusing: ${dest}`);
-      return false;
-    }
-    log(`[wrapper] skipped (exists, not clobbered): ${dest}`);
-    return true;
-  }
-
-  let srcContent;
-  try {
-    srcContent = fs.readFileSync(src, 'utf8');
-  } catch (err) {
-    log(`ERROR: cannot read template ${src}: ${err.message}`);
-    return false;
-  }
-
-  if (dryRun) {
-    log(`[dry-run] would create ${dest}`);
-    return true;
-  }
+  return installNoClobberFile(src, dest, 'wrapper', dryRun, log);
+}
 
-  if (!safeMkdirp(dest)) {
-    log(`ERROR: could not create parent dir for ${dest}`);
-    return false;
-  }
+/**
+ * Install the Codex skill templates (no-clobber) alongside the codex wrapper.
+ * Project mode -> <project>/.agents/skills/<name>/SKILL.md; --user/global mode
+ * -> ~/.agents/skills/<name>/SKILL.md (mirrors installWrapper's dest logic).
+ * @param {string} projectRoot
+ * @param {boolean} userGlobal
+ * @param {boolean} dryRun
+ * @param {(msg: string) => void} log
+ * @returns {boolean}
+ */
+function installCodexSkills(projectRoot, userGlobal, dryRun, log) {
+  const skillsRoot = userGlobal
+    ? path.join(os.homedir(), '.agents', 'skills')
+    : path.join(projectRoot, '.agents', 'skills');
 
-  const res = safeWrite(dest, srcContent);
-  if (!res.ok) {
-    log(`ERROR: failed to write wrapper ${dest}: ${res.reason}`);
-    return false;
+  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;
   }
-  log(`[wrapper] wrote ${dest}`);
-  return true;
+  return ok;
 }
 
 // ---- main entry ----
@@ -461,17 +569,24 @@ function run(argv) {
 
   let anyError = false;
 
-  // 1. Doctrine
+  // 1. Doctrine — portable AGENTS.md kernel + this target's runtime adapter.
   if (!installDoctrine(project, dryRun, log)) anyError = true;
+  if (!installAdapter(target, project, dryRun, log)) anyError = true;
 
-  // 2. Engine
+  // 2. Engine — frontier/ + bin/maestro.cjs + docs/orchestration.md.
   if (!installEngine(project, dryRun, log)) anyError = true;
 
-  // 3. Wrapper (skip if no specific target detected)
+  // 3. Wrapper — this target's /frontier command (skip if no target detected).
   if (target !== 'none') {
     if (!installWrapper(target, project, userGlobal, dryRun, log)) anyError = true;
   }
 
+  // 3b. Codex skills — the .agents/skills/<name>/SKILL.md set ships alongside
+  // the deprecated codex prompt wrapper.
+  if (target === 'codex') {
+    if (!installCodexSkills(project, userGlobal, dryRun, log)) anyError = true;
+  }
+
   if (anyError) {
     log('install completed with errors (see above)');
     return 1;