@maestrofrontier/frontier 1.4.1 → 1.4.3

package/README.md

@@ -25,7 +25,7 @@
   <sub>13 fixture tasks &middot; 123 valid A/B runs &middot; 11 voids excluded &amp; re-run &middot; 6 hooks, all tested &middot; ~8 KB always-on kernel &middot; 2-line plugin install</sub>
 </p>
 
-> **⚡ Install — run the one line for your tool, inside that tool.** Each installs only that tool's setup (the portable `AGENTS.md` doctrine, that tool's adapter, `docs/orchestration.md`, the Frontier engine, and that tool's `/frontier` command) — **append-only; it never overwrites or deletes your files.**
+> **Install — run the one line for your tool, inside that tool.** Each installs only that tool's setup (the portable `AGENTS.md` doctrine, that tool's adapter, `docs/orchestration.md`, the Frontier engine, and that tool's `/frontier` command) — **append-only; it never overwrites or deletes your files.**
 
 **Claude Code / Desktop** — native plugin (enforcement hooks, `/maestro:*` commands, skills, status line, Frontier auto-run):
 
@@ -68,22 +68,6 @@ members — fusing the CLIs you already run buys frontier-tier results. It
 is the project's new default identity; the doctrine, hooks, skills, and
 benchmarks are unchanged; the discipline layer is its foundation.
 
-<p align="center">
-  <img src="assets/frontier-fusion-benchmark.svg" alt="Bar chart: fusion panels versus solo models on a 100-task benchmark (93 tasks scored). Every fusion panel outscores its individual member models; an Opus 4.8 self-fusion (double Opus) reaches ~65.5%, matching Claude Fable 5 solo, while the strongest fusion, Fable 5 + GPT-5.5, tops the field at ~69% and solo Gemini 3.1 Pro and Gemini 3 Flash trail near 43-45%." width="880">
-</p>
-
-<p align="center">
-  <sub>Fusion vs solo on a 100-task suite (93 scored). Every fusion panel beats its own member models, and the strongest fusion — Fable 5 + GPT-5.5 — leads the field. This is the fusion-vs-solo axis; the in-repo <a href="benchmarks/">A/B harness</a> measures a different one (Maestro doctrine ON vs OFF).</sub>
-</p>
-
-<p align="center">
-  <img src="assets/frontier-pipeline.svg" alt="Maestro Frontier fusion pipeline: prompt fans out to a parallel panel of local CLIs, a chosen judge model produces structured analysis (consensus, contradictions, unique insights, blind spots), then a chosen synthesizer model writes a grounded response" width="900">
-</p>
-
-The pipeline above is the engine's whole architecture: fan out to a
-parallel panel, a judge model that compares the answers (it does not
-merge them), then a grounded synthesis.
-
 It ships with the plugin and is driven by `/maestro:frontier`. Three
 modes, switched at will, **`off` by default** so installing or
 upgrading changes nothing until you opt in. **Arming it — `single` or
@@ -105,10 +89,6 @@ the synthesized answer. `off` is the disable path.
 /maestro:frontier off                          # disable auto-run; back to normal Maestro
 ```
 
-<p align="center">
-  <img src="assets/frontier-presets.svg" width="820" alt="Maestro Frontier fusion presets reference card">
-</p>
-
 Presets define the panel; the judge and synthesizer default to Opus 4.8
 (`claude -p`), and you override either with `--judge` / `--synth`:
 
@@ -135,32 +115,23 @@ and verified end-to-end on real runs of `single` mode and the
 `opus-gpt`, `opus-duo`, and `frontier-trio` presets**. The `gpt-duo`
 preset and `--judge`/`--synth` selection share that same code path and
 are unit-tested, but not yet live-run. The quality *lift* of local fusion
-is **measured, not asserted**: on a 100-task suite (93 scored, chart
-above) every fusion panel outscored its own member models, with the
-strongest fusion leading the field. That fusion-vs-solo result is a
-separate axis from the in-repo A/B harness, which measures Maestro
-doctrine ON vs OFF; numbers are never mixed across the two.
-Operational caveats recorded in the risk burndown: headless web access
-differs per CLI (Codex confirmed live; Claude and Gemini are gated
-`webTools:false` in this build), and each cold `claude -p`
-panel/judge/synth call is non-trivial in cost; use small prompts, and
-prefer `opus-gpt` to bound spend. The budget cap is opt-in
-(`tokenBudget`, default disabled). The engine is zero-dependency
+is **measured, not asserted**: on a 100-task suite (93 scored) every
+fusion panel outscored its own member models, with the strongest fusion
+leading the field. That fusion-vs-solo result is a separate axis from the
+in-repo A/B harness, which measures Maestro doctrine ON vs OFF; numbers
+are never mixed across the two.
+Operational caveats: headless web access differs per CLI (Codex confirmed
+live; Claude and Gemini are gated `webTools:false` in this build), and
+each cold `claude -p` panel/judge/synth call is non-trivial in cost; use
+small prompts, and prefer `opus-gpt` to bound spend. The budget cap is
+opt-in (`tokenBudget`, default disabled). The engine is zero-dependency
 CommonJS under [`frontier/`](frontier/); each CLI is resolved from your
 `PATH` (`claude`, `codex`, `gemini`). Binary overrides and the full
 operational reference are in
 [`commands/frontier.md`](commands/frontier.md#binary-overrides).
 
-<p align="center">
-  <img src="assets/frontier-stack.svg" alt="Maestro Frontier fusion engine sitting on the discipline layer foundation; an amber data-flow connects the two" width="820">
-</p>
-
 ## What You Get
 
-<p align="center">
-  <img src="assets/what-you-get.svg" width="860" alt="What Maestro gives you: five capabilities on a dark card">
-</p>
-
 Frontier is the headline; the discipline layer beneath it is what runs on
 every task. Drop two markdown files into your repo and your agent gains
 five things:
@@ -171,141 +142,27 @@ five things:
 4. **Multi-agent only when it pays.** A counted Decision Gate routes work single-agent by default and demands an explicit verdict line before the first edit; orchestration stays behind it.
 5. **Receipts.** A reproducible A/B benchmark harness ships in-repo, with our own retractions and nulls. Rerun every number yourself.
 
-<p align="center">
-  <img src="assets/discipline-demo.svg" alt="Two terminal close-outs quoted verbatim from benchmark streams: a baseline agent declares all done although no check ran, while the Maestro run opens with a counted GATE verdict line and exits with the honest status UNVERIFIED, no type-checker or linter configured in this project" width="860">
-</p>
-
 The price, measured rather than implied: ON spends about 10% more than a
 clean agent on a 10-module refactor and 38% more on a 16-file feature
-(n=9 medians, t08/t12 below); you are buying verification and
-auditability, not speed. The overhead is behavioral, not byte-weight: a
-kernel rewrite cut always-on bytes 41% and fixed status reporting
-(12/12 vs 3/30) with no measurable cost change. The premium earns its
-keep on unattended work (overnight loops, scheduled runs, CI agents)
-where nobody reads the 3am transcript and the close-out claim is all you
-have.
-
-That regime is not hypothetical: Maestro runs under its own rules. The
-four most recent maintenance loops ran unattended on the S10 long-horizon
-doctrine, with checkpoint artifacts and pre-declared budget ceilings, and
-together made 75 benchmark runs for $30.12 against $47 in caps, produced 0
-voided runs, and shipped the retractions you can read below with no human
-in the loop. Output-style compression (terse-reply tools) is orthogonal
-and worth ~1% of agentic spend; Maestro will not grow a kernel toggle for
-it. The whole design rests on [peer-reviewed
-research](https://marklaursen.com/blog/why-your-multi-agent-ai-system-keeps-failing)
-showing **79% of multi-agent failures come from coordination, not model
-capability**, and that **three optimized agents outperform seven**;
-adding agents usually makes things worse, so Maestro makes the single
-agent you already have rigorous by default and holds multi-agent
-coordination behind a counted gate.
-
-## The Discipline Layer It Runs On
-
-Frontier runs on this. It is the part this repo actually benchmarks: a
-verification-first discipline layer that applies to every task, fusion or
-not.
-
-<p align="center">
-  <img src="assets/maestro-flow.svg" alt="Maestro orchestration flow: task through the S1 decision gate to either a single agent or the planner, specialist group, and staff engineer pipeline, converging on verified delivery" width="780">
-</p>
-
-- **Universal Rules**: verification gates, status vocabulary, surgical scope, edit safety, context economy; applied to every task in both modes, including one-line fixes.
-- **Decision Gate**: counts the work and emits a verdict line (`GATE: files=<n> concerns=<m> -> ...`) before the first edit. Most tasks stay single-agent.
-- **Planner**: decomposes complex tasks into parallel and sequential subtasks with boundaries and acceptance criteria.
-- **Specialists**: execute focused subtasks with scoped context, hard-capped at 4 per parallel group (DyLAN and agent-scaling findings).
-- **Cross-Talk Routing**: detects when one specialist's output affects another and routes the minimum necessary context.
-- **Staff Engineer Review**: adversarial final verification for contradictions, breakage, and architectural drift.
-- **Long-Horizon Operation**: checkpoint artifacts, self-pacing, and explicit end conditions for recurring or multi-session runs; exits graded by a fresh-context verifier, never self-assessed.
-
-<p align="center">
-  <img src="assets/loop-lifecycle.svg" alt="Loop engineering lifecycle: read checkpoint, re-anchor goal, execute phase, verify with a fresh-context verifier grading the exit, write checkpoint distilling findings into rules, event or wakeup, exiting to a final report on success or hard cap" width="440">
-</p>
-
-**How it works:**
-
-1. You give your AI coding agent a task as normal.
-2. The Decision Gate counts the work and emits a verdict line; most tasks run single-agent with no coordination overhead.
-3. Single-agent work follows the Universal Rules: scoped edits, verification before any completion claim, an honest status token at the end.
-4. Work that crosses the gate's thresholds goes Planner -> Specialists -> adversarial Staff Engineer review.
-5. Long or recurring runs follow the Long-Horizon rules: checkpoint artifacts, explicit end conditions, iteration caps.
-6. You get a result with a verification status you can act on, not a vibe.
-
-The specialist manifest (S3) and cross-talk handoff packet (S4/S6) also ship as machine-readable JSON Schemas in [`schemas/`](schemas/) for tooling. The prose doctrine remains the source of truth.
-
-## Quick Start
-
-Maestro installs as plain markdown files your AI agent reads on startup. No packages, no build steps, no SDK. Download the files for your runtime into the project root and your agent picks them up automatically.
-
-| Runtime | Files to add |
-|---|---|
-| Claude Code | [`AGENTS.md`](AGENTS.md) + [`CLAUDE.md`](CLAUDE.md) |
-| Gemini | [`AGENTS.md`](AGENTS.md) + [`GEMINI.md`](GEMINI.md) |
-| Codex | [`AGENTS.md`](AGENTS.md); see [Maestro on Codex](docs/codex.md) |
-| Cursor | [`.cursorrules`](.cursorrules) |
-| GitHub Copilot | [`AGENTS.md`](AGENTS.md); nearest `AGENTS.md` in the directory tree wins, and a root `CLAUDE.md` or `GEMINI.md` also works |
-| Cline | [`AGENTS.md`](AGENTS.md); native support (also auto-detects `.cursorrules`) |
-| Windsurf | [`AGENTS.md`](AGENTS.md); root file is always-on, processed by the Rules engine |
-
-> **Already have a `CLAUDE.md`, `AGENTS.md`, or `.cursorrules`?** Don't overwrite them, you'll lose your project context. The per-runtime steps below show how to merge Maestro into an existing setup.
-
-### Claude Code
-
-**Option A, plugin (hooks + context-bar command, one step).** Maestro
-is an installable Claude Code plugin; the repo is its own marketplace:
-
-```text
-/plugin marketplace add mbanderas/maestro
-/plugin install maestro@maestro
-```
-
-The plugin auto-wires all five enforcement hooks (subagent guard, loop
-guard, phase-scope guard, gate reminder, opt-in gate telemetry) and the
-`/maestro:context-bar` command. Two things it cannot do for you:
-the doctrine files (`AGENTS.md`/`CLAUDE.md`) still go in your project
-root (Option B), and the status line script still needs a one-line
-`statusLine` settings entry (see [`docs/context-bar.md`](docs/context-bar.md));
-plugins cannot set the main status line.
-
-**Option B, plain files (doctrine only, zero machinery):**
-
-```bash
-curl -O https://raw.githubusercontent.com/mbanderas/maestro/main/AGENTS.md
-curl -O https://raw.githubusercontent.com/mbanderas/maestro/main/CLAUDE.md
-```
-
-Claude Code reads `CLAUDE.md` on startup. The `@AGENTS.md` import inside it pulls in the orchestration doctrine. Your next task routes through Maestro's Decision Gate.
-
-**Already have a `CLAUDE.md`?** Don't overwrite it. Instead, download just `AGENTS.md` and add `@AGENTS.md` to the top of your existing `CLAUDE.md` to import the doctrine. You can optionally merge the runtime rules from Maestro's [`CLAUDE.md`](CLAUDE.md) into yours.
-
-**Optional:** Maestro also ships a context-window progress bar for the Claude Code status line; see [`docs/context-bar.md`](docs/context-bar.md).
-
-### Gemini
-
-```bash
-curl -O https://raw.githubusercontent.com/mbanderas/maestro/main/AGENTS.md
-curl -O https://raw.githubusercontent.com/mbanderas/maestro/main/GEMINI.md
-```
-
-**Already have a `GEMINI.md`?** Don't overwrite it. Download just `AGENTS.md` and add `@AGENTS.md` to the top of your existing `GEMINI.md`. You can optionally merge the runtime rules from Maestro's [`GEMINI.md`](GEMINI.md) into yours.
-
-### Codex
-
-```bash
-curl -O https://raw.githubusercontent.com/mbanderas/maestro/main/AGENTS.md
-```
-
-Codex reads `AGENTS.md` directly; no adapter file needed.
-
-**Already have an `AGENTS.md`?** Don't overwrite it: that file likely contains your project context. Instead, append the contents of Maestro's [`AGENTS.md`](AGENTS.md) to your existing file, or paste it into a section of your `AGENTS.md` so Codex reads both your project context and the orchestration doctrine.
-
-### Cursor
-
-```bash
-curl -O https://raw.githubusercontent.com/mbanderas/maestro/main/.cursorrules
-```
-
-**Already have a `.cursorrules`?** Don't overwrite it. Cursor does not support file imports, so append the contents of Maestro's [`.cursorrules`](.cursorrules) to your existing file.
+(n=9 medians, t08/t12); you are buying verification and auditability, not
+speed. The premium earns its keep on unattended work (overnight loops,
+scheduled runs, CI agents) where nobody reads the 3am transcript and the
+close-out claim is all you have.
+
+## Discipline, Benchmarks, and Research
+
+The discipline layer (verification, scope, honest status) applies to
+every task, fusion or not. The full orchestration protocol lives in
+[`docs/orchestration.md`](docs/orchestration.md). Benchmark data,
+retractions, and methodology — including the honest reading that Maestro
+ON has never beaten OFF on success rate in any measured cell and that the
+early efficiency story did not survive replication — are in
+[`docs/benchmarks.md`](docs/benchmarks.md) and
+[`benchmarks/README.md`](benchmarks/README.md). The architecture is
+grounded in 700+ sources; the key driver is that
+[79% of multi-agent failures come from coordination, not model
+capability](https://marklaursen.com/blog/why-your-multi-agent-ai-system-keeps-failing),
+and that three optimized agents outperform seven.
 
 ## Runtime Adapters
 
@@ -319,6 +176,8 @@ Maestro separates **portable orchestration doctrine** from **runtime-specific ad
 | `.cursorrules` | Cursor adapter | Kernel copy (Cursor does not support imports); full S2-S6 in docs/orchestration.md |
 | [`docs/codex.md`](docs/codex.md) | Codex guide | AGENTS.md precedence and 32 KiB cap, Codex subagent mapping, Automations long-horizon mapping (Codex reads `AGENTS.md` natively) |
 
+Maestro's tools run on **both Claude Code and Codex** — in Claude Code as `/maestro:*` slash commands, and in Codex as installable skills, with the portable `node settings/cli.cjs` and `maestro frontier ...` CLIs working on any other agent too. The Codex skills (`frontier`, `terse`, `settings`, `update`) are installed to `.agents/skills/<name>/SKILL.md` by `maestro install --target codex`. When Frontier mode is on, the `frontier` skill leads each Codex reply with `Maestro Frontier ON (<label>)` (`single · <model>` or `fusion · <preset>`) — the Codex analog of Claude Code's armed Frontier indicator; run `maestro frontier status --scope codex` to check. This indicator is Codex-scoped only.
+
 GitHub Copilot, Cline, and Windsurf read `AGENTS.md` directly, so the portable core works there with no adapter. Maestro's always-on kernel (`AGENTS.md`) is ~8 KB, under Windsurf's 12,000-character limit and roughly a quarter of Codex's 32 KiB budget; the full multi-agent protocol loads on demand from `docs/orchestration.md`.
 
 **Subagents vs Agent Teams (Claude Code):** Maestro's `CLAUDE.md` adapter
@@ -337,11 +196,11 @@ Optional Claude Code machinery; full install steps in the linked docs.
 - **Hook Pack**: five more zero-dependency hooks (doctrine guard, loop guard, phase-scope, gate reminder, opt-in gate telemetry) enforcing the rest of the doctrine. [`docs/hooks.md`](docs/hooks.md)
 - **Context Bar**: a status-line context-window progress bar that shifts green to amber to red and detects the model's window (including the 1M Opus tier). [`docs/context-bar.md`](docs/context-bar.md)
 - **Terse Mode + Compress**: opt-in output-token reduction (`/maestro:terse`) and a memory-file compressor (`/maestro:compress`), adapted from the MIT-licensed Caveman plugin. [`docs/context-bar.md`](docs/context-bar.md)
-- **Settings**: `/maestro:settings` changes any toggle in one line (`set terse off`, `frontier fusion opus-gpt`, `help`) or opens a keyboard picker with no arguments (the `AskUserQuestion` selector, not the built-in `/model` widget, which plugins cannot render), plus a portable `node settings/cli.cjs status|list|help|set` for Codex and any other CLI, over the terse, frontier, and context-bar toggles. [`docs/settings.md`](docs/settings.md)
+- **Settings**: `/maestro:settings` changes any toggle in one line (`set terse off`, `frontier fusion opus-gpt`, `help`) or opens a keyboard picker with no arguments, plus a portable `node settings/cli.cjs status|list|help|set` for Codex and any other CLI. [`docs/settings.md`](docs/settings.md)
 
 ## Commands & Settings
 
-Every Maestro slash command in Claude Code is namespaced `/maestro:<name>`. On Codex and other CLIs without slash commands, the same actions run through the scripts noted below.
+Every Maestro slash command in Claude Code is namespaced `/maestro:<name>`. The same tools run on Codex as installed skills (`.agents/skills/<name>/SKILL.md`, via `maestro install --target codex`); on any CLI the same actions also run through the portable scripts noted below.
 
 | Command | What it does | Usage |
 |---|---|---|
@@ -358,7 +217,7 @@ Every Maestro slash command in Claude Code is namespaced `/maestro:<name>`. On C
 | Toggle | Values | What it controls |
 |---|---|---|
 | `terse` | `off`, `lite`, `full`, `ultra` | Output-token reduction. Shows an amber level badge (`ULTRA`) on the status bar. |
-| `frontier` | `off`; `single:` `opus` / `gpt-5.5` / `gemini`; `fusion:` `opus-duo` / `opus-gpt` / `gpt-duo` / `frontier-trio` / `custom`, each with optional `--judge` / `--synth` | The local fusion engine. When armed it auto-runs on every prompt. The blue `ƒ` panel badge means auto-run is on: `ƒO+C`, `ƒO+C+G`, `ƒ✦3` (`O`=Opus, `C`=ChatGPT/GPT-5.5, `G`=Gemini). |
+| `frontier` | `off`; `single:` `opus` / `gpt-5.5` / `gemini`; `fusion:` `opus-duo` / `opus-gpt` / `gpt-duo` / `frontier-trio` / `custom`, each with optional `--judge` / `--synth` | The local fusion engine. When armed it auto-runs on every prompt. The blue `f` panel badge means auto-run is on: `fO+C`, `fO+C+G`, `f*3` (`O`=Opus, `C`=ChatGPT/GPT-5.5, `G`=Gemini). |
 | `context-bar` | `on`, `off` | The status-line context-window progress bar. |
 
 Portable everywhere, Codex included: `node settings/cli.cjs status | list | help | set <key> <value>` (frontier also takes `--judge`, `--synth`, `--models a,b,c`). Full references: [`docs/settings.md`](docs/settings.md) and [`docs/context-bar.md`](docs/context-bar.md).
@@ -382,109 +241,18 @@ It can't run the reload for you (a slash command can't invoke another slash comm
 /reload-plugins
 ```
 
-`/reload-plugins` applies the update in the running session; if Claude Code warns that a restart is required, restart it. Non-interactive equivalent of the pull: `claude plugin marketplace update maestro`. You can also enable marketplace auto-update so the local clone refreshes automatically — check Claude Code's plugin settings.
+`/reload-plugins` applies the update in the running session; if Claude Code warns that a restart is required, restart it. Non-interactive equivalent of the pull: `claude plugin marketplace update maestro`.
 
 > **Note:** There is no `/plugin update <name>` command in Claude Code. Use `/maestro:update`, or `/plugin marketplace update maestro` + `/reload-plugins`.
 
 ### Codex / Cursor (portable installs, no plugin system)
 
-Run `/update` if your integration file exposes it, or update manually:
-
 - **Git clone:** `git pull` inside the Maestro clone directory.
-- **Downloaded copy:** re-run `npx github:mbanderas/maestro install --target auto --project .` from the project root, or re-download the tarball and re-copy `frontier/`, `bin/maestro.cjs`, plus your integration command file (`integrations/codex/prompts/frontier.md` or `integrations/cursor/commands/frontier.md`) from the latest `main`.
+- **Downloaded copy:** re-run `npx github:mbanderas/maestro install --target auto --project .` from the project root, or re-download the tarball and re-copy `frontier/`, `bin/maestro.cjs`, plus your integration command file from the latest `main`.
 
 ### Gemini / other CLIs
 
-The same portable manual steps apply: re-pull or re-copy `frontier/` and the relevant integration file from `main`. If your CLI supports custom commands and you have a `/update` wired, run that instead.
-
-## When to Use Maestro
-
-The discipline layer (verification, scope, honest status) applies to every task from a one-line fix upward. The orchestration path helps most on tasks that are genuinely too complex for one pass (large refactors, multi-file features), parallelizable (independent subtasks), or benefit from adversarial review. It is deliberately avoided where a single agent already handles the work, the work is purely sequential reasoning, or the task touches fewer than ~10 files; the research shows coordination overhead makes simple tasks worse, not better.
-
-### Why Not CrewAI / LangGraph / AutoGen?
-
-| | Maestro | CrewAI / LangGraph / AutoGen |
-|---|---|---|
-| **Setup** | Two lines (`/plugin install`) or copy a folder, done | Install packages, write Python/TS, configure agents |
-| **Dependencies** | Zero | Framework + SDK + runtime |
-| **Where it runs** | Inside your existing AI coding agent | Standalone process you build and deploy |
-| **Agent count** | Hard cap at 4 parallel (research-backed) | Unlimited (user decides) |
-| **Default behavior** | Single-agent unless complexity warrants multi | Always multi-agent |
-| **Design philosophy** | Fewer agents, structured coordination | More agents, flexible topologies |
-
-Maestro is not a framework. It's a discipline-and-orchestration layer for AI coding agents that already exist: you copy a couple of files and your existing agent gains verification rigor, scope discipline, and gated multi-agent capabilities. If you need a standalone multi-agent application with custom tools, APIs, and deployment pipelines, use a framework.
-
-## Benchmarks
-
-Maestro ships a reproducible A/B harness in [`benchmarks/`](benchmarks/):
-thirteen fixture tasks, a runner for Windows and macOS/Linux (no deps;
-the macOS/Linux script needs `jq`), and a deterministic `verify.cjs`
-checker per task. Each task runs Maestro ON (doctrine files present) vs
-OFF (absent) under an isolated `CLAUDE_CONFIG_DIR`, with the checker
-**hidden from the agent until the run ends** (visible oracles inflate
-pass rates 20-60%, arXiv:2602.10975).
-
-<p align="center">
-  <img src="assets/bench-cells.svg" alt="Bar chart of median cost per task-run for t07 to t10 and t12 with doctrine off, on, and core variant; pass rates per cell shown beneath each group" width="860">
-</p>
-
-Honest reading: **Maestro ON has never beaten OFF on success rate in any
-measured cell**; at n=9, t09 is exactly tied (8/9 each) and t08 and t12
-are 9/9 both modes. The early efficiency story did not survive
-replication: the t12 and t08 n=3 wall, turn, and token gains were all
-retracted at n=9, and the only unreplicated positives left standing
-(Gemini t08, the t11 pilot) are flagged as such. The full n=3 -> n=9
-reversal arithmetic is in
-[`docs/benchmarks.md`](docs/benchmarks.md#retractions). On small or linear
-tasks the doctrine is pure overhead (t10: +78% median wall). t09 separates
-*models* more than modes: gemini-3.1-pro-preview passes 1 of 6 valid runs,
-gpt-5.4-mini 4/4, sonnet ~8-in-9. Small samples throughout; no
-significance claims.
-
-The one new directional signal is on a different axis. **t14**, a
-checker-less trap task with a non-obvious correctness property, holds both
-arms at **6/6 pass** while the honesty metric `claim_consistent` runs
-**OFF 1/6 vs ON 4/6** and `target_smoke_tested` **OFF 0/6 vs ON 2/6**, at
-ON median cost **$0.1930** vs OFF **$0.1501** (about **+29%**). The
-`status_token` axis is excluded; OFF was never taught the S7.3
-vocabulary. Per the frozen prereg this is **directional only, not
-confirmatory** (n=6 is exploratory; a grounded effect needs n>=9): Maestro
-buys more honest completion behavior on a trap task, at higher cost; paid
-for by the premium, not recovered.
-
-Key findings:
-
-- **No success-rate lift.** ON never beats OFF on pass rate in any measured cell; it buys verification, scope guarantees, and honest status, not speed or capability.
-- **Weak-model rescue: not measurable.** Haiku passes 30/30 across t07-t11 in both modes and 9/9 on all three difficulty versions of t13, a task purpose-built to fail it, but a haiku baseline does not fail on self-contained fixtures with discoverable conventions, so rescue cannot be observed at this task class.
-- **The gate speaks, prose alone does not spawn.** Three S1 revisions got verdict lines into 9/9 probe runs with correct counts above the trigger (the first gate verbalization ever measured), yet every verdict still concluded single-agent and S2-S6 spawns stayed 0/9. The `gate-reminder` hook (alone) is what finally moves sonnet across the spawn threshold (6/6, at no quality delta on a fixture both cells already pass).
-- **The verdict line binds.** Across all 19 single-agent-verdict runs on disk no specialist was ever spawned; 2 of 8 full-pack multi-agent verdicts were stated but never executed, a gap the single-hook cell closed at 0 of 6.
-- **Compliance deltas are null at these tiers.** Three runs in 69 scored streams stated a status token; surgical scope and oracle integrity stay perfect in both modes. Prose doctrine alone does not move headless reporting behavior; hence the structural verification hook.
-
-Numbers are never compared across CLIs or models, and the protocol
-forbids publishing numbers that were not actually measured. Earlier
-same-day t01-t06 results were taken **before** the hidden-oracle fix and
-are kept only as labeled upper bounds, not comparable to the cells above.
-
-Full data, retractions, and methodology -> [`docs/benchmarks.md`](docs/benchmarks.md).
-
-## Research Foundation
-
-Maestro's architecture is grounded in 700+ sources across computer science, library science, safety engineering, and knowledge theory. The key papers:
-
-| Paper | Year | Venue | Key Finding |
-|---|---|---|---|
-| [MAST](https://arxiv.org/abs/2503.13657) | 2025 | NeurIPS Spotlight | 41-87% failure rates; 79% from coordination |
-| [DyLAN](https://arxiv.org/abs/2310.02170) | 2024 | COLM | 3 agents outperform 7; dynamic topology selection |
-| [Towards a Science of Scaling Agent Systems](https://arxiv.org/abs/2512.08296) | 2025 | arXiv (Google/MIT) | 260 configs; architecture-task fit dominates; sequential tasks degrade 39-70% |
-| [Agent Scaling via Diversity](https://arxiv.org/abs/2602.03794) | 2026 | arXiv | 2 diverse agents match 16 homogeneous; diversity, not headcount, drives gains |
-| [LoopTrap](https://arxiv.org/abs/2605.05846) | 2026 | arXiv | Termination poisoning: loop end-conditions are an attack surface; hard caps mitigate |
-| [MetaGPT](https://arxiv.org/abs/2308.00352) | 2023 | - | Structured handoffs score 3.9/4 vs unstructured 2.1/4 |
-| [Voyager](https://arxiv.org/abs/2305.16291) | 2023 | NeurIPS | Skill library pattern for capability organization |
-| [GTD](https://arxiv.org/abs/2504.05767) | 2025 | arXiv | 0.3% degradation under failure with redundant topologies |
-| [SELFORG](https://arxiv.org/abs/2502.11811) | 2025 | arXiv | Shapley-based contribution estimation |
-| [DRACO](https://arxiv.org/abs/2602.11685) | 2026 | arXiv | Deep-research benchmark reviewed for fusion; fused panels outscored their solo members |
-
-For the full analysis, read [Why Your Multi-Agent AI System Keeps Failing](https://marklaursen.com/blog/why-your-multi-agent-ai-system-keeps-failing).
+Re-pull or re-copy `frontier/` and the relevant integration file from `main`. If your CLI supports custom commands and you have a `/update` wired, run that instead.
 
 ## Contributing
 

package/docs/codex.md

@@ -86,3 +86,13 @@ on the model honoring it rather than on a hook.
 The Maestro context bar also does not apply: Codex CLI ships a native
 context-usage indicator (`/statusline` picker, or `context` in
 `[tui].status_line` in `~/.codex/config.toml`).
+
+## Skills and the Frontier ON indicator
+
+`maestro install --target codex` installs the `frontier`, `terse`, `settings`,
+and `update` Maestro commands as Codex skills (no-clobber) to
+`.agents/skills/<name>/SKILL.md` (per-repo) or `~/.agents/skills/<name>/SKILL.md`
+(global). When `maestro frontier status --scope codex` reports mode != off, the
+`frontier` skill instructs Codex to lead its reply with
+`Maestro Frontier ON (<label>)` — `single · <model>` or `fusion · <preset>`. When
+mode is off, no indicator line appears.

package/integrations/README.md

@@ -20,7 +20,7 @@ loads on demand.
 | 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` |
+| Codex (CLI + IDE/Desktop) | `integrations/codex/skills/frontier/SKILL.md` (and `terse`, `settings`, `update`) | `.agents/skills/<name>/SKILL.md` (per-repo) or `~/.agents/skills/<name>/SKILL.md` (global) | `/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
@@ -60,7 +60,7 @@ 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` |
+| Codex (CLI + IDE/Desktop) | `integrations/codex/skills/update/SKILL.md` | `.agents/skills/update/SKILL.md` (per-repo) or `~/.agents/skills/update/SKILL.md` (global) | `/update` |
 
 **Version model:** Maestro pins no version for portable files. Fetching from
 latest `main` always resolves the newest committed code — no manual version bump
@@ -71,13 +71,20 @@ needed per release.
 - **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.
+- **Codex uses skills, not prompts.** `maestro install --target codex` installs the
+  `frontier`, `terse`, `settings`, and `update` skills as Codex skills
+  (no-clobber) to `.agents/skills/<name>/SKILL.md` (per-repo) or
+  `~/.agents/skills/<name>/SKILL.md` (global). The deprecated
+  `~/.codex/prompts/frontier.md` prompt file remains as a compatibility bridge but
+  the canonical path is the skill.
+- **Codex per-repo skill path:** `.agents/skills/<name>/SKILL.md` is the
+  repo-scoped option for Codex skills. The global path is
+  `~/.agents/skills/<name>/SKILL.md`.
+- **Maestro Frontier ON indicator (Codex only).** When
+  `maestro frontier status --scope codex` reports mode != off, the `frontier` skill
+  instructs Codex to lead its reply with `Maestro Frontier ON (<label>)` —
+  `single · <model>` or `fusion · <preset>`. When mode is off, no indicator line
+  appears. This is Codex-scoped only and has no effect on Claude Code.
 - **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.

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.1",
+  "version": "1.4.3",
   "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",

package/scripts/install.cjs

@@ -49,6 +49,11 @@ 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.
@@ -412,6 +417,58 @@ function installEngine(projectRoot, dryRun, log) {
   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
@@ -449,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 ----
@@ -537,6 +581,12 @@ function run(argv) {
     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;