@maestrofrontier/frontier 1.4.4 → 1.5.0

package/integrations/codex/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.

package/integrations/codex/skills/{settings → maestro-settings}/SKILL.md

@@ -1,46 +1,55 @@
----
-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`
+---
+name: maestro-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.
+
+## Command launcher
+
+Use `node settings/cli.cjs` when Maestro is installed in the project root. If
+that file is not present 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>/settings/cli.cjs" ...
+```
+
+## Discover available commands
+
+```bash
+node settings/cli.cjs --help
+```
+
+If `settings/cli.cjs` is not present, use the plugin-root launcher above.
+
+## 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`. A project-local Maestro install is optional when
+  the skill is loaded from the Maestro Codex plugin.

package/integrations/codex/skills/{terse → maestro-terse}/SKILL.md

@@ -1,49 +1,58 @@
----
-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`
+---
+name: maestro-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.
+
+## Command launcher
+
+Use `node settings/cli.cjs` when Maestro is installed in the project root. If
+that file is not present 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>/settings/cli.cjs" ...
+```
+
+## 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, use the plugin-root launcher above.
+
+## 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`. A project-local Maestro install is optional when
+  the skill is loaded from the Maestro Codex plugin.

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

@@ -0,0 +1,31 @@
+---
+name: maestro-update
+description: Update Maestro to the latest marketplace version for Codex
+---
+
+Update **Maestro** to the latest Codex marketplace code. This refreshes the
+configured Git marketplace and reinstalls the Maestro plugin from it.
+
+When the user invokes this skill, run:
+
+```bash
+codex plugin marketplace upgrade maestro
+codex plugin add maestro@maestro
+```
+
+The update is idempotent. It will:
+
+- Pull the latest Maestro source from the repository.
+- Refresh the installed Maestro plugin cache.
+- Refresh bundled Codex skills and hooks exposed by the plugin.
+- Leave project-local configuration (state files, secrets) untouched.
+
+## Notes
+
+- Requires the Codex CLI on `PATH`.
+- After reinstalling, restart the Codex session or open a new thread so updated
+  skills and hooks take effect.
+- If the marketplace is not configured yet, run
+  `codex plugin marketplace add mbanderas/maestro` first.
+- Portable/manual installs can still be refreshed with
+  `npx github:mbanderas/maestro install --target codex` from the project root.

package/integrations/cursor/commands/frontier.md

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

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