Fleet

Fleet is a multi-LLM orchestration kit spanning Agent CLI backends and gateway models. The Admiral is the host agent that plans, delegates, and integrates; a Theater is a project folder in one commodore's own Theater list and its local context boundary; an Objective is a Console-managed unit of work, holding its board and agent sessions under the commodore that owns it.

Select task context

This file defines repository-wide boundaries. Apply child CLAUDE.md files along the paths you work in; read other instructions, documents, and skills only when relevant to the task. Do not preload every instruction file or a documentation bundle.

• Modify the repository in a dedicated canary-based worktree created through the git-worktree skill, unless the user explicitly directs otherwise. Read-only work needs no worktree.
• In an Objective, an Objective member reports the worktrees and branches it created with its result. Who removes them is the git-worktree skill's rule. Before hand-off, the Commander reports what it keeps. A member whose report to the Commander fails or cannot be emitted does not retry it, run placeholder commands, or probe for another channel; it ends its turn, leaving any result its commits do not hold in the objective's evidence directory. Commander and members message each other only through the fleet-objectives message tool; Console sends the Commander a notice when a delegated member's turn ends without a message to it. On a member's report or such a notice, the Commander reads the mission's worktree, commit log, and evidence directory directly rather than relying on the report alone, and waits for the member's next message or notice instead of taking over if the member is still working.
• Route Console browser and Electron Desktop verification to console-e2e, and a Console for the user to try to console-handoff. Load a skill's body only for its task. When an Objective lineup includes Electron Desktop verification, the Commander settles the lineup's launch decision at planning as console-e2e's Desktop preflight and ownership records, not at measurement time. When a lineup pairs an implementer with a separate real-app verifier, the Commander plans the verifier's preparation and verification missions, their predecessors, and what each member checks at planning as console-e2e's Parallel preparation and commit handoff records, not after implementation.
• For local execution, consult Isolated Development Data in docs/fleet-development-reference.md. Development and verification must not touch real user data or another session's processes. An ad-hoc measurement or reproduction script makes every temporary tree inside one root T=$(mktemp -d …) under the session scratchpad and, right after creating it, registers trap 'rm -rf -- "$T"' EXIT; trap 'exit 130' INT; trap 'exit 143' TERM; trap 'exit 129' HUP, because zsh skips an EXIT-only trap on signals.

Architecture boundaries

• Dependencies flow from Console composition to features to foundation. Foundation must not import feature, core, or CLI implementations or contracts; host-specific behavior crosses explicit injected ports. Shared Fleet execution policy may live in foundation without importing product features.
• Runtime hosts own composition, process lifecycle, UI, and host adapters. Console is the sole published host for the fleet launcher and Console web product, and its product surfaces are Console features; Console has no plugin runtime and loads no third-party extension code. Desktop remains a shell over the Console public protocol.
• Cross-package construction uses explicit dependency objects. Do not add DI containers, service locators, or hidden cross-layer lookups.
• Consume other packages through declared exports only. Source deep imports must not create shadow APIs.

Execution scope and completion

• Within the authorized task, continue local edits, relevant checks, repairs of regressions introduced by the change, and re-verification without intermediate approval requests. Do not expand an investigation into implementation or implementation into deployment.
• Destructive actions, external publication or deployment, and billable external actions require authorization for that action. A session's own routed model also spends its provider's quota by running, apart from deliberate calls, and one provider may meter models against different pools, so a spending limit names the pool, which of the two it restricts, and whether it covers asking a PR review bot for another review. Local verification authority does not extend to production data, other sessions, or external services; never bypass tool permission gates.
• For user-authorized repository changes, standing authorization includes committing the scoped changes, pushing the dedicated head branch, opening its PR, and merging into canary through pr-workflow, including required checks and post-merge CI. It also includes post-merge cleanup of this task's owned worktree and merged local branch under git-worktree safeguards, but not discarding unpreserved work. Do not ask again for publication or merge on each task or Objective. A local-only request, explicit stop, or narrower delivery scope takes precedence; investigation alone does not authorize implementation. This default does not authorize deployment, release publication, other destructive actions, additional paid calls, or bypassing tool permissions and merge gates. In an Objective, the Commander owns this delivery.
• An explicit allowance for paid work within a stated limit is authorization for that work, not a pending approval. Read the task brief and recorded decisions before asking again; resolve the covered pool and scope from that context, not from a missing form field. When delegating paid work, quote the person's authorization and carry its scope and remaining aggregate budget; the member uses that existing authorization without requesting it again or resetting the budget. Proceed within the authorized scope rather than omitting the required live verification. Ask only about a genuinely missing or expanded permission, not the already approved portion. Human-required login or device-code approval remains a separate action for the person, and existing credential-access restrictions and tool permission gates still apply.
• Define completion by the requested outcome and affected boundaries. Start with relevant checks and broaden coverage for shared contracts, dependencies, or packaging changes. Do not require the entire test suite after every edit, and do not skip mandatory skill, CI, or release gates. A measurement mission or delegation names, for each metric, its computation and the raw source its value is read from (the log event, API response, or output file, and its field), caps the report's length, and requires quoted values and timestamps to be checked against that source before sending; a sampled one also states the sample count and the minimum calendar period the sample must cover. When a mission's result depends on details of a cited tool, command, or prior artifact that its name does not convey (a run mode or flag, an expiry, a path restriction), the delegation quotes the relevant contract wording or flags verbatim and otherwise names it only; this per-mission quote does not license copying a harness tool contract into a skill or document.
• Verify executable-code or bundle changes with affected builds, and UI behavior or visual changes in the real app. For documentation-only changes, check references, instruction conflicts, and preservation of required constraints. Run commands in the active worktree and verify that they exercise the changed version.
• Before calling an export, CSS class, or symbol unused, list every consumer, including CSS classes another component borrows, objects passed whole (such as a deps object), and type-only paths; a name search alone does not settle it, and typecheck is the evidence for pass-through paths. Check affected consumer builds, residual imports/dead references to removed paths (searched with git grep --untracked, since rg's defaults skip hidden and ignored paths such as .claude and plain git grep skips new unstaged files), public exports, and module-state ownership.
• Before scoping the removal of a feature, setting, or stored file, search for its descriptive wording as well as its identifiers (UI copy, i18n messages, and comments or docs in every language the repository uses), and list every shared reader of its state or files, not only its writers and call sites.
• An initial implementation or one green check is not completion. Resolve relevant failures or identify the concrete blocker; report changes, checks run, failures, and unverified areas separately, checked against the actual commit diff, branch name, and exit codes. Capture before processing (OUT=$(cmd); rc=$?): a pipe, <(…), or local X=$(…) loses the code, and the Bash tool's zsh has $pipestatus but no PIPESTATUS. Do not expand scope to repair unrelated pre-existing failures.

Test admission policy

The permanent suite is a minimal product-acceptance suite, not a catalog of modules, implementation details, or every past regression. Default to no new test unless it passes the admission criteria below. A code change or bug fix alone does not justify another permanent case.

• Admit only essential contracts: representative product execution; process, session, and stream lifecycle; authorization, containment, and sensitive-data boundaries; storage integrity and destructive-action safeguards; or explicitly required architecture, packaging, and release gates. A valid assertion, a unique regression, or a useful pure function is not sufficient by itself.
• Require a concrete gap before adding: identify the supported path, the consequential failure it must catch, and why the existing suite does not already catch it. Extend or replace the existing representative test first. Do not create one test file per source file, helper, adapter, or store.
• Test each contract at one effective boundary: prefer a representative public-API or integration path over duplicate tests at every layer. A focused unit test is appropriate when it is the smallest reliable way to exercise an essential independent defense. Do not claim an upper-layer test covers a lower layer unless it actually exercises that behavior.
• Keep representative cases, not permutation matrices: retain the main success path and failures caused by distinct consequential mechanisms. Add an input variant only when it exercises a different essential defense or failure mechanism; superficial format, platform, provider, or parameter differences do not earn separate cases. Parameterization, snapshots, and file consolidation must not disguise redundant coverage.
• Do not add permanent tests for incidental behavior: copy, translations, icons, fonts, CSS values, layout geometry, preference variants, UI micro-interactions, internal names, or call-order wiring. Do not pin production source with string/regex assertions, duplicate production algorithms in tests, or test mocks and library behavior instead of Fleet behavior. Explicitly required static gates are the exception, not a precedent for new source snapshots; essential UI safeguards must be tested through behavior.
• Prefer removal or replacement to accumulation: when changing a contract, retire superseded or redundant cases in that scope. Do not restore removed detail coverage merely because a reviewer requests more tests. Judge feedback against this admission policy; never remove, skip, or weaken a necessary failing test just to obtain green checks.
• Minimize maintenance, not a numeric score: neither test counts nor coverage percentages are targets. This policy does not authorize unrelated mass deletion or relaxation of security and data-integrity requirements. Preserve explicitly mandated gates and the execution/real-app verification obligations above; temporary verification evidence does not automatically belong in the permanent suite.

Change records

• Commits use English Conventional Commits. When editing an existing file, write its comments and generated text in that file's language rather than the session language.
• CHANGELOG.md and CHANGELOG.ko.md are compiler-owned outputs; never edit them directly.
• Author a .changelog.d/ fragment autonomously only for a product change users perceive as a feature-level delta. Omit otherwise, without a mandatory no-changelog declaration. That directory's instructions and the compiler own inclusion details, identity, and bilingual syntax.

Instruction maintenance

• Keep all CLAUDE.md files in English. Retain stable ownership, security, and operational boundaries that must be known before work begins; do not accumulate implementation walkthroughs, one-off lessons, or inventories discoverable through normal exploration.
• State each fact once at the nearest scope. Put procedures in task-specific skills, detailed rationale in on-demand references, and mechanically decidable constraints in checks. Never delete a still-required constraint without a reliable replacement.
• When revising instructions or skills, or writing a delegation that asks for a judgment about them, consult docs/instruction-maintenance.md. Do not relax safety boundaries based on presumed model capability.