@codemeall/agent-fleet 0.1.0-preview.1

package/skill/providers.toml

@@ -0,0 +1,106 @@
+# Provider adapters: the single source for how each agent CLI is launched,
+# checked and stopped. ~/.config/agent-fleet/config.toml overrides any field.
+#
+# launch placeholders: {bin} is trusted shell setup; model/effort/prompt are quoted data.
+# Shipped model IDs are account-dependent examples; verify them before routing.
+# quit: sequence sent to the pane; "enter" and "ctrl+c" are keys, anything else is text.
+# login: a cheap command that needs no model call; ready when its output contains login_ok.
+# tiers: model + effort per ticket weight (see references/routing.md).
+# family: model family, used to pick a reviewer from a different family.
+
+[providers.claude]
+enabled = true
+bin = "claude"
+launch = "{bin} --model {model} --effort {effort} {prompt}"
+quit = ["/exit", "enter"]
+login = "claude auth status"
+login_ok = '"loggedIn": true'
+family = "anthropic"
+plugins = true
+max = 2
+tiers.heavy = { model = "opus", effort = "high" }
+tiers.standard = { model = "sonnet", effort = "high" }
+tiers.light = { model = "sonnet", effort = "medium" }
+tiers.review = { model = "opus", effort = "high" }
+
+[providers.claude-co]
+enabled = false
+bin = "CLAUDE_CONFIG_DIR=$HOME/.claude-co claude"
+launch = "{bin} --model {model} --effort {effort} {prompt}"
+quit = ["/exit", "enter"]
+login = "CLAUDE_CONFIG_DIR=$HOME/.claude-co claude auth status"
+login_ok = '"loggedIn": true'
+family = "anthropic"
+plugins = false
+max = 2
+tiers.heavy = { model = "opus", effort = "high" }
+tiers.standard = { model = "sonnet", effort = "high" }
+tiers.light = { model = "sonnet", effort = "medium" }
+tiers.review = { model = "opus", effort = "high" }
+
+[providers.codex]
+enabled = true
+bin = "codex"
+launch = "{bin} -m {model} -c model_reasoning_effort={effort} -s workspace-write -a on-request {prompt}"
+quit = ["/quit", "enter"]
+login = "codex login status"
+login_ok = "Logged in"
+family = "openai"
+plugins = false
+max = 2
+tiers.heavy = { model = "gpt-6-sol", effort = "high" }
+tiers.standard = { model = "gpt-6-sol", effort = "medium" }
+tiers.light = { model = "gpt-6-luna", effort = "high" }
+tiers.review = { model = "gpt-6-sol", effort = "high" }
+
+[providers.cursor]
+enabled = true
+bin = "cursor-agent"
+# Cursor has no effort flag: effort is part of the model id.
+launch = "{bin} --model {model} --trust {prompt}"
+quit = ["/quit", "enter"]
+login = "cursor-agent status"
+login_ok = "Logged in"
+models = "cursor-agent --list-models"
+family = "mixed"
+plugins = false
+max = 2
+tiers.heavy = { model = "grok-4.7-high", family = "xai" }
+tiers.standard = { model = "kimi-k3-high", family = "moonshot" }
+tiers.light = { model = "grok-4.7-high-fast", family = "xai" }
+tiers.review = { model = "muse-spark-1.3-max", family = "meta" }
+
+[providers.agy]
+enabled = false
+bin = "agy"
+launch = "{bin} --model {model} --effort {effort} --mode accept-edits -i {prompt}"
+quit = ["ctrl+c", "ctrl+c"]
+login = "agy models"
+login_ok = "gemini"
+models = "agy models"
+family = "mixed"
+plugins = false
+max = 1
+tiers.heavy = { model = "gemini-3.1-pro-high", effort = "high", family = "google" }
+tiers.standard = { model = "gemini-3.8-flash-high", effort = "high", family = "google" }
+tiers.light = { model = "gemini-3.8-flash-medium", effort = "medium", family = "google" }
+tiers.review = { model = "gemini-3.1-pro-high", effort = "high", family = "google" }
+
+# Planned: turned on once the CLI is set up and its adapter is checked.
+[providers.grok]
+enabled = false
+bin = "grok"
+launch = "{bin} --model {model} {prompt}"
+quit = ["/quit", "enter"]
+family = "xai"
+plugins = false
+max = 1
+
+[providers.muse]
+enabled = false
+bin = "muse"
+launch = "{bin} --model {model} {prompt}"
+quit = ["/quit", "enter"]
+family = "meta"
+plugins = false
+max = 1

package/skill/references/harnesses.md

@@ -0,0 +1,24 @@
+# Lead host requirements
+
+The lead needs this skill, a local shell, access to the intended Git checkout, and permission to reach the cmux socket. Run `fleet doctor` in that same environment; a terminal outside the host is not proof that the host's sandbox can reach cmux.
+
+| Host | Standalone invocation | User installation |
+| --- | --- | --- |
+| Claude Code | `/fleet …` | `~/.claude/skills/fleet` |
+| Codex CLI / desktop | `$fleet …` or skill picker | `~/.agents/skills/fleet` |
+| Cursor CLI / IDE | `/fleet …` or skill discovery | `~/.cursor/skills/fleet` |
+| ChatGPT with local execution | Host-supported skill invocation | Requires a connection to the local runtime |
+
+Install with `npx skills add codemeall/agent-fleet`, `npx @codemeall/agent-fleet@preview setup --harness <host>` or `./install.sh` from a clone; Claude Code can alternatively use the plugin marketplace (`/plugin marketplace add codemeall/agent-fleet`). Project setup uses the corresponding `.claude/skills`, `.agents/skills` or `.cursor/skills` beneath the repository. Codex's legacy `~/.codex/skills` and custom skill directories may still contain an older copy: remove stale duplicate registrations deliberately rather than installing multiple copies. An npm executable alone does not register the skill. A plugin may namespace the command; use the name shown by the host (Claude example: `/agent-fleet:fleet`).
+
+## Permission and connectivity checks
+
+1. Confirm Python 3.11+, Git, cmux and selected worker CLIs are available in the lead's shell.
+2. Confirm cmux is running and the intended workspace exists. Inside cmux the current workspace can be used; otherwise supply `fleet init <run> --workspace <ref>` explicitly.
+3. Run `fleet doctor`; diagnose its actual socket, executable or authentication error.
+4. If the host blocks a required operation, use its normal approval mechanism or have the owner configure a narrow allowance. Consult documentation for that installed host version. Do not disable the sandbox, switch permission modes or route to another harness to evade a rejection.
+5. Launch one small, scoped ticket and inspect it with `fleet peek` before starting a larger wave. Trust, authentication and model selection may still need owner input.
+
+Claude permission classifiers, Codex sandbox profiles, Cursor allowances and remote-session topology vary by version. There is no universal setup flag that safely fixes all of them. Fleet's bundled launch configuration does not override host restrictions. A cloud-only chat can help plan the work but requires an explicit local execution connection to operate this fleet.
+
+`fleet wait` defaults to 45 seconds and accepts at most 60 seconds. Use shorter waits when the host's command tool has a lower timeout. Provide progress updates between waits. A worker may use the same CLI as the lead; each tab is a distinct process and session.

package/skill/references/providers.md

@@ -0,0 +1,31 @@
+# Provider adapters
+
+`providers.toml` is the shipped adapter configuration; `fleet providers` prints it merged with personal overrides. Adapter command templates are trusted local executable configuration, not safe inputs from tickets. Model, effort and prompt substitutions are shell-quoted by the runtime. Keep account setup separate from model data.
+
+All model IDs and efforts are examples tied to accounts and CLI versions. Before routing, check the local CLI's model list/help and authenticate through the owner's normal process. `doctor` checks binary presence and login signals, including the login command's exit status; it does not spend a model call or guarantee model access. A passing doctor is a preflight check, not an end-to-end compatibility claim.
+
+## Claude Code
+
+The default `claude` adapter uses the normal account and interactive permission controls. `opus` and `sonnet` are example aliases. Effort support depends on the installed CLI and model. Do not respond to a permission denial by switching account or bypassing the host's controls.
+
+`claude-co` is a disabled example of a second account using `CLAUDE_CONFIG_DIR=$HOME/.claude-co`. Enable it only after explicitly configuring and authenticating that account. It must receive a self-contained prompt; do not assume the same plugins exist under both configurations. Both accounts use Anthropic-family models, so switching between them does not satisfy cross-family review.
+
+## Codex
+
+The example adapter uses `workspace-write` with `on-request` approval. Effective network and filesystem permissions still come from the host configuration; neither the adapter nor the preamble guarantees OS isolation. Fleet's worker contract prohibits network calls and package installation regardless of those capabilities. Request owner help for a necessary permission instead of weakening the sandbox.
+
+Use model IDs and effort levels supported by the authenticated account. The shipped OpenAI IDs are examples. Model changes must be reflected in the plan and recorded worker metadata; do not silently switch a running worker's model in its UI and leave routing records stale.
+
+## Cursor
+
+The default launches `cursor-agent` with the chosen model and repository trust, retaining interactive permission handling; it does not use `--force`. A trusted workspace is not permission for an arbitrary command. Inspect trust or command prompts as part of launch verification.
+
+Cursor can serve several families. The example tiers identify xAI (`grok-…`), Moonshot (`kimi-…`) and Meta (`muse-…`) separately. Use `cursor-agent --list-models` to confirm your account's exact IDs; parameterized IDs must remain a single argument. A model override needs accurate family metadata, especially for cross-family review. A different CLI name alone is not evidence of a different family.
+
+## Optional and experimental adapters
+
+Antigravity (`agy`) is disabled by default. Its example tiers describe Google models, but the adapter itself may serve multiple families. Validate its binary, authentication, model availability, command permissions and shutdown sequence before enabling it. No live compatibility claim is made.
+
+The disabled `grok` and `muse` entries are incomplete placeholders, not supported providers. Verify that a binary with the expected name is actually the intended product; fill in a no-model authentication check, known family/tier metadata and tested launch/shutdown commands before use.
+
+For every new adapter, test a harmless local ticket, multiple waves, a required review at capacity, process exit confirmation and recovery. Keep unavailable adapters out of auto routing. Login expiry or quota exhaustion can require owner intervention; they are not reasons to ignore the worker contract.

package/skill/references/routing.md

@@ -0,0 +1,40 @@
+# Routing and review
+
+For parameterized model IDs containing commas, select `single:<provider>` and set `model` in the JSON plan. The conversational `agents=` shorthand is comma-separated and cannot represent commas inside an ID. Quote the same full ID when passing `launch --model`.
+
+The lead chooses assignments; Fleet enforces the saved plan. Persist the routing mode with `init --routing` and every ticket assignment with `plan --file`. Use the same provider, tier and explicit overrides at launch.
+
+| Mode | Pool |
+| --- | --- |
+| `auto` | Enabled, authenticated adapters in `defaults.prefer` order |
+| `single:<provider>` | Only the named adapter; tiers still select models |
+| `agents=<provider>[:<model>],...` | Only listed adapters, with the listed model overriding tier models |
+
+An unavailable explicit choice is a blocker to explain, not permission for a silent substitution. `prefer` is an editable ordering, not a claim about price, subscription quotas or model quality. All selected models must be checked against the account's availability.
+
+## Ticket tiers
+
+| Tier | Use |
+| --- | --- |
+| `heavy` | Cross-module work, authentication, money, data integrity, schemas, new shared abstractions or consequential judgment |
+| `standard` | A feature slice with clear criteria and established patterns |
+| `light` | Mechanical, tightly scoped changes such as documentation or isolated repairs |
+| `review` | Dedicated read-only review of a writer's captured diff |
+
+Take consequential work first, balance ready providers without exceeding global or provider caps, and queue remaining tickets. Never raise caps merely to avoid waiting. Waves require satisfied blockers and disjoint exact file scopes. A `needs-verification` report does not free a slot: the process must exit.
+
+## Model family and review policy
+
+`cross-heavy` (default) requires a different-family reviewer for each heavy implementation ticket. `cross-all` requires one for every ticket; `off` means lead verification alone. Record the chosen mode at run creation.
+
+Family follows the resolved model, not the CLI. Use exact model-family mappings or matching tier metadata; a known single-family adapter can supply its family as a fallback. Mixed adapters require known model metadata. Use an explicit, accurate `family` in the plan or `--family` where necessary. Never invent a family solely to pass the gate.
+
+If the allowed pool cannot provide a known different-family reviewer, tell the owner before implementation. Expand the pool under their routing instruction or obtain an explicit change to `review=off`; never silently downgrade the review policy. In particular, a second Claude account remains Anthropic, while two Cursor models may belong to different families.
+
+Stop the writer before generating its scoped diff. Give the reviewer a separate ID, the original ticket and rules, that exact immutable diff, and only its report as a writable path. Review-only is a prompt contract in a shared checkout, not a security sandbox. Inspect for unauthorized changes. Stop and verify the reviewer before verifying the writer; dependents remain blocked throughout. If the writer's diff changes, redo review against the new diff.
+
+## Failures and plan changes
+
+Before any worker launches, record an unavailable adapter and any owner-authorized substitution in the plan's decisions and update assignments explicitly. After the first launch the plan is immutable: use a new follow-up run for routing or scope changes, stopping all overlapping workers first and carrying forward pending dependencies, partial edits and context. A same-assignment repair may be relaunched only after the old process has exited. A missing tab is insufficient proof. Use `resume` to reconcile receipts, normal `stop` where possible, and evidence-backed `recover` only after independently verifying the process is gone.
+
+Never change providers to circumvent a permission denial. Work requiring installs, secrets, network access or infrastructure changes falls outside the default worker contract; isolate and ask the owner to handle or explicitly authorize it separately.

package/skill/templates/preamble.md

@@ -0,0 +1,16 @@
+# Fleet worker {{id}}
+
+You are an implementation worker in the shared checkout at `{{repo}}`. The lead owns planning and verification, may message this pane, and will stop your process when your work is ready for review. The owner controls commits and publishing.
+
+## Hard rules
+
+- Edit only the exact files listed in your scope and your assigned report. Other workers may be active. Preserve existing changes; do not overwrite or revert them. If you need another file, report the blocker and wait for a revised assignment.
+- Use read-only Git (`status`, `diff`, `log`, `show`). No add, commit, stash, checkout, reset, branch or push. Do not invoke an upstream implementation workflow that includes those actions.
+- Do not run build, dev, start or preview servers, or change shared build output. The lead handles builds using the repository's isolation rules.
+- Never read `.env*` or other secrets. No cloud/database/deploy/network calls, migrations, schema generation, package installs or lockfile changes.
+- Follow the host's approval boundaries. Do not bypass a denied command, weaken a sandbox, switch accounts or ask another worker to evade a denial.
+- If blocked or unsure, write `Status: blocked` and the concrete question in your report, then stop making changes. Wait for the lead's decision.
+
+## Completion
+
+Write `{{report}}` using the format below with exactly one `Status:` line. Use `needs-verification` when ready, then stop editing and wait. Do not mark yourself verified or resolve the source ticket. A report does not indicate process exit or lead acceptance.

package/skill/templates/report.md

@@ -0,0 +1,26 @@
+```markdown
+# Report {{id}}
+
+Status: needs-verification
+
+## Work or review performed
+- Implementation: exact files changed and why; review: captured diff inspected.
+
+## Acceptance criteria
+- [x] criterion: concrete test or inspection evidence
+- [ ] criterion: remaining gap or why it could not be checked
+
+## Checks and evidence
+- `command`: actual result; state when a check was not run
+
+## Findings
+- Severity, file/location, failure scenario and suggested correction; or no actionable findings with review limits.
+
+## Decisions and blockers
+- Decisions made, questions for the lead and any permission or scope blocker.
+
+## Out-of-scope observations
+- Relevant issues left untouched.
+```
+
+Use one status only: `needs-verification` or `blocked`. The lead may request changes, but only `fleet verify` records acceptance. Do not copy the illustrative checkboxes as evidence.

package/skill/templates/review-prompt.md

@@ -0,0 +1,14 @@
+# Fleet reviewer {{id}}
+
+Review writer `{{review_of}}` in `{{repo}}` against the local ticket `{{ticket}}` and the exact captured diff at `{{diff}}`.
+
+## Review contract
+
+- You are a reviewer. Your only writable file is your report: `{{report}}`. Do not edit source, tickets, prompts, the captured diff, other reports or run state.
+- Read the complete diff, ticket criteria, repository rules and relevant context. Evaluate the captured change; note any difference you observe between the checkout and the reviewed diff.
+- Use only read-only inspection and explicitly authorized non-mutating checks. Do not run checks that generate files or caches. No Git mutations, package installs, network calls, secrets, deployments or permission bypasses.
+- The shared checkout is not an isolated review sandbox. These are instruction boundaries; report unexpected concurrent changes and stop if they prevent reliable review.
+- Report actionable findings with severity, file/location, concrete failure scenario and suggested correction. Separate confirmed defects from uncertainty. Do not fix findings yourself.
+- Cover the ticket's acceptance criteria and testing gaps. If there are no actionable findings, say so and record what you inspected and any limitations; do not claim unrun checks passed.
+
+Write the report below with `Status: needs-verification` when complete, or `Status: blocked` with the concrete blocker. Stop editing and wait for the lead. Only the lead can verify your report or accept the original ticket.

package/skill/templates/ticket-prompt.md

@@ -0,0 +1,18 @@
+## Your ticket
+
+Read the local ticket: `{{ticket}}`.
+
+<!-- LEAD: fill all fields before launch; preserve the exact saved scope. -->
+**Files in scope:** {{files}}
+
+**Context and decisions:** <!-- agreed spec and testing decisions; actual glossary/ADR paths; existing edits to preserve -->
+
+**Checks to run:** <!-- exact bounded commands, working directory and success criteria; say explicitly if manual prose review is sufficient -->
+
+## How to work
+
+1. Read the ticket, project instructions, scoped code and the specified context. Resolve glossary paths from project configuration: current upstream conventions use `GLOSSARY.md` and optional `GLOSSARY-MAP.md`; older projects may use `CONTEXT.md`. Read relevant ADRs if they exist.
+2. Follow the agreed testing approach. For behavior changes, test meaningful acceptance criteria through public behavior where practical; do not invent redundant tests for prose or mechanical edits. Record visual/manual criteria honestly.
+3. Match existing naming and patterns. Keep changes inside scope and preserve pre-existing owner or other-worker edits.
+4. Run the exact permitted checks. Report failures and distinguish a demonstrated pre-existing failure from an assumption. Ask the lead about checks requiring forbidden operations.
+5. Review your scoped diff against every criterion and rule. Write your report, then stop editing. Fleet owns implementation under a no-commit contract; do not invoke upstream `/implement` unchanged.