@codemeall/agent-fleet 0.1.0-preview.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "agent-fleet",
+  "version": "0.1.0-preview.1",
+  "description": "Lead coding-agent CLIs in cmux from a portable Fleet skill.",
+  "author": {
+    "name": "codemeall"
+  },
+  "homepage": "https://github.com/codemeall/agent-fleet",
+  "repository": "https://github.com/codemeall/agent-fleet",
+  "license": "MIT",
+  "skills": [
+    "./skill/"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.0-preview.1
+
+Initial distributable preview, under the MIT license.
+
+- Published to npm as `@codemeall/agent-fleet` under the `preview` tag: `npx @codemeall/agent-fleet@preview setup`.
+- Install with the skills CLI: `npx skills add codemeall/agent-fleet`.
+- Install from GitHub without npm: `npx github:codemeall/agent-fleet setup`.
+- Add a Claude Code plugin marketplace manifest (`/plugin marketplace add codemeall/agent-fleet`).
+- Restructure the README around installation methods.
+- Persist ticket dependencies, exact ownership, model/effort assignments and decisions; resume existing runs.
+- Track worker exit receipts independently from reports. Failed stops retain capacity; reviewers can use a released writer slot even at capacity one.
+- Gate acceptance on lead evidence and required cross-family review of the current scoped diff.
+- Compare full Git index entries, quote model arguments, validate IDs and paths, and serialize mutations within a checkout.
+- Provide dedicated reviewer prompts and current Matt Pocock skill integration guidance.
+- Install durable skill copies for Claude Code, Codex and Cursor, preserving modified or unrelated installations.
+- Package the runtime for npm, a Claude plugin at the source root, and a generated Codex plugin bundle. Include MIT notices in standalone copies.
+- Add CI and 43 tests, including a real child-process exit receipt and installation from an npm tarball.
+
+Validated locally: automated tests, JavaScript syntax, Claude plugin manifest, generated Codex plugin and skill, and package installation. Live authenticated provider runs and marketplace installation remain unverified. The npm package has not been published by this change.
+
+Existing prototype run records are not automatically migrated: inspect and stop their workers before starting a new run. New run records use schema version 2.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codemeall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# Agent Fleet
+
+Run a fleet of coding-agent CLIs (Claude Code, Codex, Cursor) in visible [cmux](https://github.com/manaflow-ai/cmux) tabs, led by the agent you are already talking to.
+
+The lead turns approved tickets into a saved execution plan, picks a worker model and effort for each ticket, watches progress, and verifies every result before dependents start. Workers share one Git checkout with explicit file ownership. **You keep control of commits and publishing.**
+
+> **Preview `0.1.0-preview.1`.** Bundled adapters exist for Claude Code, Codex and Cursor. Live compatibility depends on your installed CLI versions, account models and local permissions. MIT licensed.
+
+- [Quick start](#quick-start)
+- [Installation](#installation)
+- [Usage](#usage)
+- [State, continuation and safety](#state-continuation-and-safety)
+- [Compatibility and adapters](#compatibility-and-adapters)
+- [Development](#development)
+
+## Quick start
+
+```sh
+# 1. Install the skill globally with the skills CLI
+npx skills add codemeall/agent-fleet -g -a claude-code -a codex -a cursor
+
+# 2. Check cmux, Python and worker CLIs
+~/.claude/skills/fleet/bin/fleet doctor
+```
+
+Restart your agent host, open it inside a cmux workspace, and ask:
+
+> Use `/fleet` with auto routing for the approved tickets in `.scratch/my-feature/issues`.
+
+## Installation
+
+### Requirements
+
+- macOS (cmux is a macOS terminal) with **Python 3.11+**, **Git** and **[cmux](https://github.com/manaflow-ai/cmux)** running with a reachable socket
+- At least one installed, authenticated worker CLI: `claude`, `codex` or `cursor-agent`
+- **Node.js 18+** for the installer (not needed at runtime)
+
+The lead host must be allowed to use the local shell, the repository and cmux. Installing the skill does not grant those permissions; see [host setup](skill/references/harnesses.md).
+
+### Pick an install method
+
+| Method | Best for | Command |
+| --- | --- | --- |
+| **skills CLI** (recommended) | Claude Code, Codex, Cursor and other agents | `npx skills add codemeall/agent-fleet` |
+| **Fleet installer (npm)** | Version-tracked installs, `fleet` on PATH | `npx @codemeall/agent-fleet@preview setup --harness all` |
+| **Claude Code plugin** | Claude Code only, managed updates | `/plugin marketplace add codemeall/agent-fleet` |
+| **Git clone** | Contributors, pinned checkouts | `./install.sh --harness all` |
+
+Pick one method per host. Installing the same skill twice (for example, with the skills CLI and the Fleet installer) leaves duplicate copies; the Fleet installer refuses to overwrite a directory it didn't create.
+
+#### Option 1: skills CLI (recommended)
+
+The [skills CLI](https://github.com/vercel-labs/skills) installs the `fleet` skill, including its bundled `bin/fleet` runtime, into your agents' skill directories:
+
+```sh
+npx skills add codemeall/agent-fleet                                     # interactive: pick agents and scope
+npx skills add codemeall/agent-fleet -g -a claude-code -a codex -a cursor # user-level, no prompts
+npx skills add codemeall/agent-fleet -a claude-code -y                    # current project only
+```
+
+Without `-g`, the skill goes into the current project (`.agents/skills/fleet`, symlinked into `.claude/skills/fleet` for Claude Code). With `-g`, it goes into your user-level skill directories. Pass `-a` once per agent. Run `npx skills add codemeall/agent-fleet --list` to preview what will be installed.
+
+To update, run `npx skills update fleet`. To remove, run `npx skills remove fleet`.
+
+#### Option 2: Fleet installer from npm
+
+The package's own installer copies the skill to each host and records the installed version, so later runs can upgrade it safely:
+
+```sh
+npx @codemeall/agent-fleet@preview setup --harness all   # one-off install
+npm install -g @codemeall/agent-fleet@preview            # also adds `fleet` to PATH
+fleet setup --harness all
+```
+
+The package is published under the `preview` tag during the preview period. To install straight from GitHub instead of npm, use `npx github:codemeall/agent-fleet setup --harness all`.
+
+Use `--harness claude`, `codex`, `cursor` or `all`. The skill is copied to:
+
+| Host | User install (default) | Project install (`--scope project`) |
+| --- | --- | --- |
+| Claude Code | `~/.claude/skills/fleet` | `<repo>/.claude/skills/fleet` |
+| Codex | `~/.agents/skills/fleet` | `<repo>/.agents/skills/fleet` |
+| Cursor | `~/.cursor/skills/fleet` | `<repo>/.cursor/skills/fleet` |
+
+For a single repository:
+
+```sh
+npx @codemeall/agent-fleet@preview setup --harness codex --scope project --root /absolute/path/to/repo
+```
+
+To update, run `setup` again with the newest version (for example, `npx @codemeall/agent-fleet@preview setup --harness all`, or `npm update -g @codemeall/agent-fleet` for a global install). Each installed copy records its version in `.fleet-install.json`. Setup replaces only copies it installed itself. If you edited an installed copy, or another skill already uses that directory, setup stops and reports it without overwriting anything.
+
+#### Option 3: Claude Code plugin marketplace
+
+This repository is also a Claude Code plugin marketplace. In Claude Code:
+
+```text
+/plugin marketplace add codemeall/agent-fleet
+/plugin install agent-fleet@agent-fleet
+```
+
+Or from a terminal:
+
+```sh
+claude plugin marketplace add codemeall/agent-fleet
+claude plugin install agent-fleet@agent-fleet
+```
+
+Plugin skills are namespaced, so you invoke this one as `/agent-fleet:fleet`. To update, run `claude plugin marketplace update agent-fleet`, then `claude plugin update agent-fleet@agent-fleet`. The plugin does not add `fleet` to your PATH. The skill finds its bundled runtime itself, and you can [add a PATH command](#put-fleet-on-your-path-optional) if you want one.
+
+#### Option 4: Git clone
+
+```sh
+git clone https://github.com/codemeall/agent-fleet.git
+cd agent-fleet
+./install.sh --harness all          # same options as `setup`
+./skill/bin/fleet doctor
+```
+
+Claude Code can also load the checkout directly as a plugin: `claude --plugin-dir /absolute/path/to/agent-fleet`.
+
+### Put `fleet` on your PATH (optional)
+
+The skill never needs `fleet` on PATH; it calls its own copied runtime. For convenience in your shell:
+
+```sh
+mkdir -p ~/.local/bin
+ln -s ~/.claude/skills/fleet/bin/fleet ~/.local/bin/fleet   # or ~/.agents/… / ~/.cursor/…
+fleet doctor
+```
+
+### Verify
+
+```sh
+fleet doctor
+```
+
+`doctor` checks cmux connectivity, worker executables and login signals. It cannot guarantee model access or a successful worker session. Launch one small ticket first (the [documentation-only example](examples/README.md) is a safe choice).
+
+### Configure
+
+Personal overrides live in `~/.config/agent-fleet/config.toml`; start from [config.example.toml](config.example.toml). No cmux workspace is pinned by default. Start the lead in the intended workspace, or pass `workspace=<ref>` explicitly.
+
+### Uninstall
+
+```sh
+npx skills remove fleet                                         # if installed with the skills CLI (add -g for global)
+npx @codemeall/agent-fleet@preview uninstall --harness all     # same --scope/--root as setup
+claude plugin uninstall agent-fleet@agent-fleet              # if installed as a Claude plugin
+```
+
+Uninstall removes only the Fleet skill it installed. It keeps modified copies, and it never touches `.fleet/` run history in your repositories.
+
+## Usage
+
+| Host | Invoke |
+| --- | --- |
+| Claude Code | `/fleet …` (plugin install: `/agent-fleet:fleet …`) |
+| Codex CLI / desktop | `$fleet …` or pick it in the skill menu |
+| Cursor | `/fleet …` |
+
+```text
+/fleet [auto | single:<provider> | agents=<provider>[:<model>],...]
+       [workspace=<ref>] [review=off|cross-heavy|cross-all]
+       -- <local tickets directory or task list>
+```
+
+The lead interprets these options and saves them with CLI commands; there's no autonomous scheduler behind them. `single:codex` restricts the pool to one adapter. Required review still needs a *different* model family, so either set `review=off` explicitly or widen the pool. Fleet does not fetch issue URLs. Export tracker tickets to local Markdown first, keeping their IDs, blockers, acceptance criteria and source links.
+
+Example request to the lead:
+
+> Use Fleet with auto routing and cross-heavy review for the approved tickets in `.scratch/settings/issues`. Carry the agreed spec and testing decisions into each worker prompt. Resume the `settings` run if it already exists.
+
+### Daily workflow
+
+Fleet starts from approved tickets. It works with plain Markdown tickets, or as the execution step after [mattpocock/skills](https://github.com/mattpocock/skills):
+
+1. Brainstorm and discuss the feature.
+2. Run upstream `grill-with-docs` (or `grill-me`), then `to-spec`, then `to-tickets`.
+3. Ask Fleet to plan and implement the resulting local tickets.
+4. The lead verifies each ticket, gets any configured cross-family review, and reports back for your review and commit.
+
+Point the lead at the real spec, glossary (`GLOSSARY.md`, optionally `GLOSSARY-MAP.md`; older repos may use `CONTEXT.md`), ADRs and tickets. Upstream `/implement` includes a commit step, so Fleet workers follow Fleet's no-commit contract instead. Workers don't need the upstream skills installed. These conventions were checked on 2026-09-30, and upstream may change them.
+
+More: [safe first run](examples/README.md) · [agent workflow](skill/SKILL.md) · [routing](skill/references/routing.md) · [host setup](skill/references/harnesses.md) · [providers](skill/references/providers.md)
+
+## State, continuation and safety
+
+- **Saved plan.** `fleet plan` saves every ticket, dependency, exact file scope, model assignment and decision. Run records, prompts, reports and exit receipts live in `.fleet/runs/<run>/`, which Git ignores. Repository-specific checks belong in `.fleet/rules.md`.
+- **Resume.** A fresh lead runs `fleet resume <run>` and reconciles reports and processes before continuing. The plan is frozen after the first launch. Record later decisions in run notes, and use a follow-up run for changed scope.
+- **Capacity.** A report does not free a slot; the worker must actually exit, and a failed stop keeps its slot. Stop an implementation worker before capturing its review diff, then stop and verify the reviewer before accepting the work. This works even with a single slot. Dependents stay blocked until `fleet verify` accepts the ticket.
+- **Isolation is by instruction, not by the OS.** All workers share one checkout. Exact file scope and read-only review are prompt rules plus lead checks. Use one active run per checkout, keep sensitive or high-conflict work out of concurrent waves, inspect scoped diffs, and run checks on the combined tree. The Git check compares the captured HEAD and index; it can't prove that no Git operation happened in between.
+
+## Compatibility and adapters
+
+| Lead or worker | Preview scope |
+| --- | --- |
+| Local Claude Code, Codex CLI, Cursor CLI | Bundled worker adapters; the lead needs shell, repository and cmux access |
+| Codex desktop / ChatGPT with local execution | Usable when the same capabilities and permissions are available |
+| Cloud-only or remote session | Needs an explicit connection to the machine running cmux |
+| Other providers or accounts | Configure and test an adapter yourself |
+
+The lead host, worker CLI, provider account and model family are independent choices. For example, a Claude lead can run Codex workers, and Cursor can serve several model families. The bundled model IDs are examples that depend on your account, so check which IDs and effort levels you can actually use before assigning work.
+
+[providers.toml](skill/providers.toml) holds launch templates, login checks, shutdown keys and tiers. Optional `claude-co`, Antigravity and placeholder adapters ship disabled. Before relying on a new adapter, test authentication, model selection, the full launch → report → confirmed exit → verify loop, crash recovery, and a full-capacity review cycle. Passing `doctor` alone doesn't certify an adapter. See [provider notes](skill/references/providers.md).
+
+## Development
+
+```sh
+python3 -m unittest discover tests -v
+npm run check
+npm pack --dry-run
+claude plugin validate .claude-plugin/marketplace.json
+```
+
+`skill/` is the single source of truth: agent instructions, runtime, templates and adapter defaults. Everything else is packaging around it.
+
+| Artifact | Source |
+| --- | --- |
+| Portable skill (`setup`, `install.sh`) | `skill/` copied to each host's skills directory |
+| Claude plugin + marketplace | `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` (repo root) |
+| Codex plugin | `npm run build` → `dist/codex/agent-fleet/` from `skill/` + `plugin-manifests/codex.json` |
+| npm package | `npm pack` (runs the build and includes the Codex bundle) |
+
+The Codex bundle expresses explicit invocation through `agents/openai.yaml`. Add it through a configured Codex plugin marketplace, because `codex plugin add` takes a marketplace selector rather than a local path. Codex marketplace discovery still needs live validation, so the portable skill install is the common path for all three hosts.
+
+**Releasing:** bump the version in `package.json`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` and `plugin-manifests/codex.json`. Run the checks above and `npm pack`, then inspect the tarball. Once npm publishing is set up, publish with `npm publish --access public --tag preview`. Setup, build and tests never publish anything.
+
+See [CHANGELOG.md](CHANGELOG.md) for changes. The review that motivated this preview is kept in [REVIEW.md](https://github.com/codemeall/agent-fleet/blob/main/REVIEW.md) as a historical assessment.

package/bin/build.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+// Codex's plugin contract expects skills/<name>/SKILL.md. Keep skill/ canonical.
+try { require('./setup.js').buildPluginSkills(); }
+catch (error) { console.error(`fleet build: ${error.message}`); process.exitCode = 1; }

package/bin/fleet.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+'use strict';
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const args = process.argv.slice(2);
+if (['setup', 'uninstall'].includes(args[0])) {
+  try { require('./setup.js').run(args[0], args.slice(1)); }
+  catch (error) { console.error(`fleet: ${error.message}`); process.exitCode = 1; }
+} else if (args[0] === '--version') {
+  console.log(require('../package.json').version);
+} else {
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    console.log('Skill installation: fleet setup --harness claude|codex|cursor|all [--scope user|project] [--root /absolute/base]');
+    console.log('Skill removal:      fleet uninstall (same options; preserves modified installations)\n');
+  }
+  const python = process.env.FLEET_PYTHON || 'python3';
+  const probe = spawnSync(python, ['-c', 'import sys; sys.exit(0 if sys.version_info >= (3, 11) else 1)'], { encoding: 'utf8' });
+  if (probe.error || probe.status !== 0) {
+    console.error('fleet: Python 3.11+ is required. Install it or set FLEET_PYTHON to its executable path.');
+    process.exitCode = 1;
+  } else {
+    const result = spawnSync(python, [path.join(__dirname, '..', 'skill', 'bin', 'fleet'), ...args], { stdio: 'inherit' });
+    if (result.error) console.error(`fleet: ${result.error.message}`);
+    if (result.signal) process.kill(process.pid, result.signal);
+    else process.exitCode = result.status ?? 1;
+  }
+}

package/bin/setup.js

@@ -0,0 +1,138 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+const OWNER = '@codemeall/agent-fleet';
+const MARKER = '.fleet-install.json';
+const HARNESSES = { claude: '.claude', codex: '.agents', cursor: '.cursor' };
+const source = path.join(__dirname, '..', 'skill');
+
+function exists(file) {
+  try { fs.lstatSync(file); return true; } catch (e) { if (e.code === 'ENOENT') return false; throw e; }
+}
+
+// Record the complete tree, including empty directories, so added user files are preserved.
+function inventory(root, forSource = false) {
+  const entries = {};
+  function walk(dir, prefix = '') {
+    for (const name of fs.readdirSync(dir).sort()) {
+      if (!prefix && name === MARKER) continue;
+      if (forSource && (name === '__pycache__' || name === '.DS_Store' || name.endsWith('.pyc'))) continue;
+      const rel = prefix ? `${prefix}/${name}` : name;
+      const file = path.join(dir, name);
+      const stat = fs.lstatSync(file);
+      if (stat.isSymbolicLink()) throw new Error(`Refusing symbolic link: ${file}`);
+      if (stat.isDirectory()) { entries[rel] = 'directory'; walk(file, rel); }
+      else if (stat.isFile()) entries[rel] = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') + `:${stat.mode & 0o777}`;
+      else throw new Error(`Unsupported file: ${file}`);
+    }
+  }
+  walk(root);
+  return entries;
+}
+
+function assertOwned(target) {
+  const stat = fs.lstatSync(target);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`Refusing unowned installation: ${target}`);
+  const marker = path.join(target, MARKER);
+  if (!exists(marker) || !fs.lstatSync(marker).isFile() || fs.lstatSync(marker).isSymbolicLink()) throw new Error(`Refusing unowned installation: ${target}`);
+  let record;
+  try { record = JSON.parse(fs.readFileSync(marker, 'utf8')); } catch { throw new Error(`Invalid ownership record: ${marker}`); }
+  const actual = inventory(target);
+  if (record.owner !== OWNER || record.format !== 1 || !record.files ||
+      Object.keys(actual).length !== Object.keys(record.files).length ||
+      Object.entries(actual).some(([name, digest]) => record.files[name] !== digest)) {
+    throw new Error(`Preserving modified or unowned installation: ${target}. Back it up and move it aside before retrying.`);
+  }
+}
+
+function assertParents(base, target) {
+  let current = path.dirname(target);
+  while (current !== base) {
+    if (exists(current) && (fs.lstatSync(current).isSymbolicLink() || !fs.lstatSync(current).isDirectory())) {
+      throw new Error(`Refusing non-directory or symbolic-link parent: ${current}`);
+    }
+    const parent = path.dirname(current);
+    if (parent === current) throw new Error(`Target escapes installation root: ${target}`);
+    current = parent;
+  }
+}
+
+function install(target, files, quiet = false) {
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const staging = fs.mkdtempSync(path.join(path.dirname(target), '.fleet-stage-'));
+  let backup;
+  try {
+    for (const [rel, digest] of Object.entries(files)) {
+      const to = path.join(staging, rel);
+      if (digest === 'directory') fs.mkdirSync(to, { recursive: true });
+      else { fs.copyFileSync(path.join(source, rel), to); fs.chmodSync(to, fs.statSync(path.join(source, rel)).mode & 0o777); }
+    }
+    fs.writeFileSync(path.join(staging, MARKER), JSON.stringify({ owner: OWNER, format: 1, version: require('../package.json').version, files: inventory(staging) }, null, 2) + '\n');
+    if (exists(target)) {
+      assertOwned(target);
+      backup = `${staging}-previous`;
+      fs.renameSync(target, backup);
+    }
+    try { fs.renameSync(staging, target); }
+    catch (error) { if (backup) fs.renameSync(backup, target); backup = undefined; throw error; }
+    if (backup) fs.rmSync(backup, { recursive: true });
+  } finally {
+    if (exists(staging)) fs.rmSync(staging, { recursive: true });
+  }
+  if (!quiet) console.log(`installed ${target}`);
+}
+
+function run(action, args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`fleet ${action} --harness claude|codex|cursor|all [--scope user|project] [--root /absolute/base]\nUser scope defaults to your home; project scope defaults to the current directory.\nCopies the skill and runtime. Does not change PATH, configuration, or plugin registries.\nModified or unowned installations are preserved and produce an error.`);
+    return;
+  }
+  const opts = { scope: 'user' };
+  for (let i = 0; i < args.length; i += 2) {
+    const key = args[i].replace(/^--/, '');
+    if (!['harness', 'scope', 'root'].includes(key) || args[i] !== `--${key}` || !args[i + 1] || args[i + 1].startsWith('--')) throw new Error(`Invalid option: ${args[i]}. Use fleet ${action} --help.`);
+    if (Object.hasOwn(opts, key) && key !== 'scope') throw new Error(`Repeated option: ${args[i]}`);
+    opts[key] = args[i + 1];
+  }
+  if (!Object.hasOwn(HARNESSES, opts.harness) && opts.harness !== 'all') throw new Error('--harness must be claude, codex, cursor, or all');
+  if (!['user', 'project'].includes(opts.scope)) throw new Error('--scope must be user or project');
+  if (opts.root && !path.isAbsolute(opts.root)) throw new Error('--root must be absolute');
+  const requestedBase = opts.root || (opts.scope === 'user' ? os.homedir() : process.cwd());
+  // Resolve the explicit root itself (e.g. macOS /tmp), but never follow harness-directory links.
+  const base = exists(requestedBase) ? fs.realpathSync(requestedBase) : path.resolve(requestedBase);
+  const harnesses = opts.harness === 'all' ? Object.keys(HARNESSES) : [opts.harness];
+  const targets = harnesses.map(name => path.join(base, HARNESSES[name], 'skills', 'fleet'));
+  for (const target of targets) { assertParents(base, target); if (exists(target)) assertOwned(target); }
+  const files = action === 'setup' ? inventory(source, true) : null;
+  for (const target of targets) {
+    if (action === 'setup') install(target, files);
+    else if (exists(target)) { assertOwned(target); fs.rmSync(target, { recursive: true }); console.log(`removed ${target}`); }
+    else console.log(`absent ${target}`);
+  }
+  if (action === 'setup') {
+    console.log('Restart your harness to discover Fleet. fleet is not added to PATH; use the copied runtime (or npx @codemeall/agent-fleet@preview):');
+    console.log(path.join(targets[0], 'bin', 'fleet'));
+  }
+}
+function buildPluginSkills() {
+  const root = fs.realpathSync(path.join(__dirname, '..'));
+  const legacy = path.join(root, 'skills', 'fleet');
+  if (exists(legacy)) { assertOwned(legacy); fs.rmSync(legacy, { recursive: true }); }
+  const pluginRoot = path.join(root, 'dist', 'codex', 'agent-fleet');
+  const target = path.join(pluginRoot, 'skills', 'fleet');
+  assertParents(root, target);
+  if (exists(target)) assertOwned(target);
+  install(target, inventory(source, true), true);
+  // Codex represents explicit invocation in agents/openai.yaml, not this Claude field.
+  const skillFile = path.join(target, 'SKILL.md');
+  fs.writeFileSync(skillFile, fs.readFileSync(skillFile, 'utf8').replace(/^disable-model-invocation: true\r?\n/m, ''));
+  const markerFile = path.join(target, MARKER);
+  const record = JSON.parse(fs.readFileSync(markerFile, 'utf8'));
+  record.files = inventory(target);
+  fs.writeFileSync(markerFile, JSON.stringify(record, null, 2) + '\n');
+  fs.mkdirSync(path.join(pluginRoot, '.codex-plugin'), { recursive: true });
+  fs.copyFileSync(path.join(root, 'plugin-manifests', 'codex.json'), path.join(pluginRoot, '.codex-plugin', 'plugin.json'));
+}
+module.exports = { run, buildPluginSkills };

package/config.example.toml

@@ -0,0 +1,21 @@
+# Optional ~/.config/agent-fleet/config.toml overrides.
+# fleet providers prints the merged configuration. No workspace is pinned.
+[defaults]
+routing = "auto"
+prefer = ["claude", "codex", "cursor"]
+max_parallel = 3
+review = "cross-heavy"
+
+# Set only when you intentionally target a validated cmux workspace:
+# workspace = "workspace:3"
+
+# Models are account-dependent examples: verify availability before assigning work.
+# [providers.codex.tiers.standard]
+# model = "gpt-6-sol"
+# effort = "medium"
+# family = "openai"
+
+# Optional second account. Authenticate it separately before enabling.
+# [providers.claude-co]
+# enabled = true
+# max = 1

package/dist/codex/agent-fleet/.codex-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "agent-fleet",
+  "version": "0.1.0-preview.1",
+  "description": "Lead coding-agent CLIs in cmux from a portable Fleet skill.",
+  "author": {
+    "name": "codemeall"
+  },
+  "homepage": "https://github.com/codemeall/agent-fleet",
+  "repository": "https://github.com/codemeall/agent-fleet",
+  "license": "MIT",
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Agent Fleet",
+    "shortDescription": "Coordinate coding agents in cmux.",
+    "longDescription": "Plan, route, launch and verify coding-agent workers with a portable local Fleet skill.",
+    "developerName": "codemeall",
+    "category": "Productivity",
+    "capabilities": [],
+    "defaultPrompt": [
+      "Use Fleet to plan and implement my tickets."
+    ]
+  }
+}

package/dist/codex/agent-fleet/skills/fleet/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codemeall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/codex/agent-fleet/skills/fleet/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: fleet
+description: Plan, launch, resume and verify a local fleet of coding-agent CLIs in visible cmux tabs for approved tickets, with saved dependencies and explicit file ownership.
+---
+
+# Fleet
+
+You are the lead. Workers are local interactive CLIs in cmux tabs sharing one checkout. You own planning, routing, decisions, review and final verification. Workers implement one ticket at a time. The owner controls commits and publishing.
+
+Use `fleet` on PATH; if unavailable, resolve this installed skill's absolute path and invoke `<absolute-skill-path>/bin/fleet`. Never guess a checkout path. Read `fleet <command> --help` when a flag is unclear.
+
+```text
+/fleet [auto | single:<provider> | agents=<provider>[:<model>],...]
+       [workspace=<ref>] [review=off|cross-heavy|cross-all]
+       -- <local tickets directory or task list>
+```
+
+These are conversational options for you to translate into CLI flags, not an autonomous scheduler. Defaults come from `fleet providers`. Read [harness requirements](references/harnesses.md), [routing](references/routing.md), and [provider notes](references/providers.md) as needed.
+
+## 1. Establish or resume the run
+
+- Read repository instructions, `.fleet/rules.md`, the agreed spec and the full tickets. Export remote issue content to local files first; a URL is not a `--ticket` input. Preserve original IDs and source links, using safe slug IDs for Fleet (`settings-copy`, not a path or URL).
+- Verify the active machine's absolute repository path. Run `fleet doctor` from it. Route only to adapters whose executable and authentication checks pass, and verify the selected model/effort is available. Doctor does not prove launch readiness.
+- If the named run exists, use `fleet resume <run>`, then inspect its complete saved plan, reports, decisions, any `notes.md` and reconciled process states. Do not initialize a replacement or relaunch a worker whose exit is unconfirmed.
+- Otherwise use `fleet init <run> [--workspace <ref>] [--routing <mode>] [--review <mode>]`. Map conversational `workspace=`, routing and `review=` directly to these flags. Init validates the selected cmux workspace; never fall back to an unrelated workspace.
+
+## 2. Save a complete plan
+
+Discover the exact repository-relative files each ticket needs. Preserve blockers, acceptance criteria, spec decisions and testing requirements. A wave contains tickets with satisfied blockers and disjoint file scopes. Existing owner edits require careful review and must be preserved.
+
+Show a compact table: wave, ticket, tier, provider/model/effort, exact files. Persist the complete graph with `fleet plan <run> --file <plan.json>` before launch:
+
+```json
+{
+  "tickets": [
+    {"id":"copy","ticket":".scratch/feature/issues/copy.md","files":["docs/copy.md"],"blockers":[],"provider":"codex","tier":"light"},
+    {"id":"guide","ticket":".scratch/feature/issues/guide.md","files":["docs/guide.md"],"blockers":["copy"],"provider":"claude","tier":"standard"}
+  ],
+  "decisions": ["Checks and context are specified in each generated prompt."]
+}
+```
+
+Optional per-ticket `model`, `effort` and `family` pin routing. The CLI validates dependencies, cycles, scope and assignments. Use exact files, not directories or globs. Record decisions and agreed routing before the first launch; the plan is immutable once workers have launched. Use one active run per checkout. Serialize CLI mutations through this lead; concurrent leads must not edit the same run.
+
+## 3. Generate prompts and launch ready tickets
+
+- `fleet prompt <run> <id>` uses the planned local ticket (`--ticket <local-path>` may supply it explicitly). Inspect the generated prompt, preserve the worker rules, and fill its context and exact checks, then remove the LEAD instruction comment before launch. Its file list must match the saved plan.
+- Resolve the actual glossary/ADR paths from project configuration. Prefer `GLOSSARY.md` and optional `GLOSSARY-MAP.md`, with `CONTEXT.md` for older repositories. Carry upstream `to-spec` testing and design decisions forward. Do not blindly invoke upstream `/implement`: it includes commits that Fleet forbids.
+- `fleet launch <run> <id> <provider> --tier <tier> [--model <model>] [--effort <effort>] [--family <family>]` must match the saved assignment. The CLI enforces blockers, active file ownership and capacity.
+- `fleet peek <run> <id>` after launch confirms progress or reveals a login, trust, model or permission prompt. Never assume creating a tab means work started.
+
+## 4. Watch and resolve blockers
+
+Use `fleet wait <run>` (45-second default; `--timeout` is bounded at 60 seconds) and report meaningful progress within your host's time limits. On `needs-verification`, inspect the report and go to verification. On `blocked`, clarify an authorized task decision with `fleet send <run> <id> <answer>` and save the decision in `.fleet/runs/<run>/notes.md` (the saved plan is frozen after launch). On timeout, inspect `fleet status` and `fleet peek` for stale or missing reports.
+
+Respect host approval boundaries. Task clarification does not authorize accepting a permission request, logging into an account, disabling a sandbox or rerouting to evade a denial. Stop and ask the owner when their action is required. A report never proves that the worker process exited.
+
+## 5. Stop, review and verify
+
+Read the implementation report and scoped changes against all criteria. Run the exact agreed checks yourself, plus appropriate combined-tree checks and visual inspection for UI work. Do not add low-value tests for prose or mechanical changes merely to satisfy a template.
+
+- For gaps while the worker is active: set the report to `Status: changes-requested`, send a bounded fix list, and wait for a new `needs-verification` report. Never mark a ticket verified by editing its report alone.
+- When ready for stable review, `fleet stop <run> <id>`. It waits for confirmed exit. A failed stop retains capacity: inspect the process before proceeding. This releases the writer slot before a reviewer is launched, including at `max_parallel=1`.
+- If required by the saved review mode, run `fleet diff <run> <id> --output <diff-path>` to capture changes against the launch baseline, including new files. Then `fleet prompt <run> <review-id> --review-of <id> --diff <diff-path>`. Inspect the dedicated reviewer prompt, which permits writing only its report; this is an instruction boundary, not OS isolation.
+- Launch that reviewer with `--tier review` on a permitted provider/model whose known family differs from the writer. Read its findings and run any necessary checks. Resolve findings before acceptance. Any changes after the reviewed diff invalidate review; stop writers, regenerate the diff and obtain a fresh review.
+- Stop the reviewer, write concrete verification evidence to a local file, then `fleet verify <run> <review-id> --evidence <evidence-file>`. Verify the writer separately with its own evidence file using the same command. The writer's process must have exited, its report must need verification, required review must be verified, and its current diff must match the reviewed content.
+- Only after successful writer verification update the source ticket's resolved status/acceptance boxes and launch newly unblocked tickets. Reviewers never resolve tickets themselves.
+
+Evidence records commands, outcomes, acceptance criteria and review disposition. Preserve failures and limits honestly. If a stopped worker needs repair within its existing assignment, relaunch only after its prior exit is confirmed; give it the existing edits and remaining scope explicitly. Scope or routing changes after the first launch need a new follow-up run: first stop every worker that could overlap, then carry forward unresolved tickets, partial edits and decisions. Do not edit run.json to bypass immutable planning.
+
+## 6. Recovery and completion
+
+Use `fleet resume <run>` after interruption. Exit receipts reconcile process state; reports and missing tabs are not exit evidence. If normal stop cannot establish exit, independently verify that the recorded worker process is truly gone, write that evidence to a file, then use `fleet recover <run> <id> --evidence <file>`. Recovery releases process state only; it does not accept implementation. Never use it just because a tab disappeared.
+
+Before finishing, run combined-tree gates and `fleet check <run>`. Check compares captured HEAD and full index entries (including already-staged content); investigate differences with the owner. It cannot prove no intervening Git action occurred. Stop remaining workers; use `--close` only when exit is confirmed and tabs are no longer needed. Report ticket outcomes, resolved model/effort, evidence, decisions, remaining limits and the owner's review/commit steps.
+
+## Shared-checkout rules
+
+- Preserve the worker preamble and exact scope. Scope additions need a conflict check and, after launch, a follow-up run before editing.
+- Use Fleet or non-focusing cmux actions. Do not take the owner's focus.
+- Run builds that would disturb a live dev server in an appropriate isolated copy; never run them over shared build output without checking repository instructions.
+- No worker commits, stages, pushes, deploys, installs packages, migrates data or accesses secrets. Network-dependent work must be handled separately under explicit owner authorization; changing providers does not remove these rules.

package/dist/codex/agent-fleet/skills/fleet/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Fleet"
+  short_description: "Lead parallel agent CLIs in cmux tabs through a batch of tickets"
+  default_prompt: "Use $fleet to implement these tickets with a fleet of agent CLIs."
+policy:
+  allow_implicit_invocation: false