fleet

---
name: fleet
description: >
  Manage the fleet registry of local repos and show the cross-repo health
  dashboard (read-only). TRIGGER when the user says "show my fleet",
  "fleet dashboard", "health across all my repos", "org health view",
  "how are all my repos doing", "which of my repos are drifting",
  "audit all my repos", "run doctor on every repo", "add this repo to my
  fleet", "register my repos", "scan ~/Works for repos", "list my fleet",
  "remove <repo> from my fleet", "/nyann:fleet".
  Do NOT trigger on "watch all my repos" / "watch my PRs across repos" —
  that's `watch` (CI sentinel: remote PR/check state, not governance).
  Do NOT trigger on "fix drift across all my repos" / "retrofit the
  fleet" — that's `fleet-retrofit` (this skill never mutates a repo).
  Do NOT trigger on single-repo health ("is this repo healthy") — that's
  `doctor`.
---

# fleet

> **Plugin root:** `<plugin_root>/skills/fleet/SKILL.md` — scripts live at
> `<plugin_root>/bin/fleet.sh` (registry CRUD) and
> `<plugin_root>/bin/fleet-doctor.sh` (bulk audit + dashboard).

Read-only across the board: the registry file is the only thing this skill
ever writes, and every registry mutation previews first. The registry lives
at `~/.claude/nyann/fleet.json` and holds LOCAL working-copy paths — it is
deliberately distinct from the sentinel watch-list (GitHub slugs for remote
CI polling); an entry's optional `repo` slug is the join key between the two.

## 1. Registry management

All CRUD goes through `bin/fleet.sh` (`--fleet-file` only in tests):

| User intent | Invocation |
|---|---|
| "add this repo" | `bin/fleet.sh --add <path> [--name n] [--repo o/r] [--profile p] [--tag t]` |
| "add and watch its PRs too" | append `--watch` (mirrors the slug into the sentinel watch-list; resolves the slug from the origin remote when `--repo` is omitted) |
| "remove X" | `bin/fleet.sh --remove <name-or-path>` |
| "list my fleet" | `bin/fleet.sh --list` (JSON — render it as a table) |
| "scan ~/Works for repos" | `bin/fleet.sh --scan <dir> [--depth n]` |
| "clean out dead entries" | `bin/fleet.sh --prune` |
| "what org repos am I missing?" | `bin/fleet.sh --suggest-org <org>` (gh best-effort, advisory only — nyann never clones) |

**`--scan` and `--prune` are preview-first**: the bare call prints the
candidate list and writes NOTHING. Show the list, confirm with
AskUserQuestion, then re-run with `--apply`. Never jump straight to
`--apply`.

Add validation to expect: the path must be a git repo (it is canonicalised
to the toplevel, so re-adding a subdir dedupes); a name colliding with a
different repo's name is refused — pass a distinct `--name`.

## 2. The health dashboard

```
bin/fleet-doctor.sh [--json | --markdown] [--cached] [--drift | --explain]
                    [--tag t] [--only a,b] [--jobs n] [--timeout s]
                    [--persist] [--stale-days n] [--threshold n]
```

Default is a **live** run — each repo gets a full `doctor.sh --json` pass,
so warn the user up front that a large fleet takes a while ("~15 repos ≈ a
few minutes"); progress logs stream per repo. Offer `--jobs 4` for speed
(safe: doctor is read-only, per-repo output is merged after).

- **"quick look" / "don't re-audit, just show me"** → `--cached`: reads
  each repo's persisted `memory/health.json` instantly. The board is
  labeled `cached` and rows older than `--stale-days` (default 7) are
  flagged — present it as a snapshot, never as current truth.
- **"post this to the team channel" / "give me markdown"** → `--markdown`.
- **"record the scores"** → `--persist` (each repo's own trend series).
- Filters: `--tag backend`, `--only api,web`.

Exit codes are worst-of across the fleet, mirroring doctor: 0 clean, 4 any
warn/stale/missing/error, 5 any critical.

Reading the board for the user:

- Sorted worst-first; lead your summary with the worst repos and the fleet
  header stats (avg / min / below-threshold / critical).
- `default?` in the PROFILE column means the repo was audited against the
  `default` profile because nothing better resolved (`profile_source:
  "fallback"`). **After the run**, offer once (one AskUserQuestion, not
  per repo) to pin profiles for those repos via
  `bin/fleet.sh --add <path> --profile <p>`.
- Scores are profile-relative — an 85 under `default` is not an 85 under a
  strict team profile. Don't rank repos across different profiles as if
  equivalent; the profile column is there for exactly this reason.
- `ERROR` rows never abort the run; surface the reason (dead path → offer
  `--prune`, timeout → offer `--timeout 300`).

## 3. Drift roll-up

When the user wants the actual findings, not just counts ("what exactly is
drifting?"):

- `--drift` — appends repo-tagged findings per drifted repo and (in
  `--json`) embeds each drifted repo's full doctor report under
  `repos[].drift_report`. Live mode only — the script refuses
  `--drift --cached`.
- `--explain` — plain-English narrative per drifted repo via explain-diff
  (implies `--drift`).

## 4. What to do after

- **"fix them" / "retrofit the fleet"** → hand off to `fleet-retrofit`.
  Never remediate from inside this skill.
- **Single repo deep-dive** → `doctor` against that repo.
- **"watch these repos' PRs"** → `watch` (`--add` per repo slug, or
  re-add fleet entries with `--watch`).