Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion plugins/claude-ops/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "claude-ops",
"version": "0.44.6",
"version": "0.45.0",
"description": "Claude Code operations toolkit. Twelve skills: audit-skill-visibility (audit whether each installed skill is actually VISIBLE to the model, and diagnose why most of a fleet never gets used \u2014 a skill is invisible when its description is dropped by Claude Code's skill-listing context budget, which sheds descriptions lowest-score-first so an unused skill loses the keywords that would let it be matched, from skills genuinely not wanted, from skills the run cannot observe at all; computes whether the listing overflows from documented settings, and withholds every cold verdict the data cannot support rather than reporting absence of data as absence of use), inventory (read-only enumeration of the complete invocable surface \u2014 every built-in CLI command with aliases and hidden/gated status, every bundled skill, and every component of every installed plugin across all marketplaces; reads the shipped binary because upstream publishes no built-in command list, and carries an integrity verdict so a drifted build reports counts as floors rather than silently short totals), audit-install-state (read-only audit of the machine-scope ~/.claude installation directory and ~/.claude.json \u2014 full inventory split into an authored surface and rolled-up bulk trees, product-managed retention vs genuinely unmanaged state, filename-scheme resolution before any process-liveness check, and deliberate/mid-experiment detection; reports, never deletes), audit-performance (read-only slowness-diagnostic capture run at the moment the machine or a session feels slow: CLI version, retention-sweep health including the silent unparsable-settings pause, a timed census walk of the install tree as a sweep-cost proxy, active-session and plugin-fleet counts, a process census, and the fan-out layer, which covers a load-labelled no-op spawn baseline, every hook that will fire bucketed per-tool-call versus per-turn with its invocation shape, the configured statusline, subagent concurrency and spawn-depth ceilings against documented defaults, whether running sessions predate the settings file they are judged by, and orphan attribution by parent liveness rather than age, plus on Windows a kernel-object census (Token objects against uptime, paged pool) that names a host-level leak beneath all four suspects; read against a bundled known-performance-issues reference that also records the causes tested and cleared; separates the four documented suspects of accumulated state, version regression, component bloat, and per-spawn fan-out cost, and routes remediation out; reports, never mutates, and never executes a discovered hook or statusline command), audit-native-overlap (map native Claude Code surfaces \u2014 built-in CLI commands, bundled skills, plugin-backed built-ins, session-provided skills \u2014 against the current repo's plugin skills and agents, so a custom component never silently duplicates what Claude Code itself ships; bare invocation is a read-only overlap report carrying the extraction's integrity floors and a shared-listing-budget exposure section, verdicts are human-gated in a committed store rendered into a generated registry whose every row carries an observable recheck trigger, and only an explicit apply step bakes presence-gated native references into descriptions and Boundary sections), observability (read locally captured telemetry \u2014 OTEL store, collector, the per-session hook event log and hook-event JSONL, ccusage \u2014 with trend reports, a per-session report of what fired, what was blocked and the event timeline, and store pruning), known-issues (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), changelog (ingest Claude Code changelog entries and integrate them into the current repo), plugins (bring a machine's plugin fleet current on demand \u2014 marketplace refresh, effective-scope updates including in-repo project/local installs, new-plugin install per policy, scope-divergence detection and explicit convergence), morning-brief (read-only gh-based operator morning view \u2014 queue-label counts, merge-ready PRs, parked decisions with their RECOMMENDED lines, and loop-lane telemetry freshness), lanes (start/restart/stop/status loop lanes as named background Claude Code sessions seeded from canonical prompt files, with per-lane model/effort, a repo-pull + marketplace-refresh launch step, and a consume-restarts action \u2014 an OS-schedulable reader that relaunches stopped lanes whose telemetry carries a restart_request), and a re-runnable setup action that settles where the known-issues registry, the skill-usage log and the hook log root live, places the root's self-ignoring guard, and detects retired conventions. Plus an opt-in, default-off per-session hook event log (one JSON line per hook event on every event the generated registry marks observable, written to <root>/sessions/<session_id>.jsonl, with SessionEnd retention by session count or age and an optional detached pre-prune command), a family of eight advisory *-audit hooks (API errors, config changes, instruction loads, permission denials, pre-compaction, skill usage, tool failures, and unsurfaced hook failures \u2014 the last also warns the user via systemMessage, since a hook that fails to launch enforces nothing and Claude Code surfaces the failure to nobody) that emit the shared hook-telemetry envelope, and a reference sink that routes envelopes under the same root: per session when the envelope carries a session id, else into the shared hook-events.jsonl the observability skill reads.",
"author": {
"name": "Melodic Software",
Expand Down
27 changes: 27 additions & 0 deletions plugins/claude-ops/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,33 @@
All notable changes to the `claude-ops` plugin are documented here. Format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.

## [0.45.0]

### Changed

- **The `plugins` skill's `sync` and `audit` run Steps 1-5b through one `sync-run.sh`
invocation with a JSON digest, instead of the model driving each step by hand.**
A current-fleet run now costs 2 model turns where it cost 14.
- **`cache-content-check.sh` batches fleet-wide** instead of spawning per plugin: 400
spawns fall to 17, and the authoring host's wall clock drops from roughly 100 s to
roughly 15 s.
- **Step 5b calls the checker once, not twice.**
- **A journal-creation failure now exits 2 before any mutation, instead of degrading.**

### Fixed

- **`--only-install` keeps first-pass update and projection failures in the
replacement digest.** Successful moves already survived through the move
ledger; a failed `claude plugin update` or a failed projection did not, so the
digest that supersedes an `ask`-policy stop could report a successful sync
while a plugin remained stale.
- **The batched cache-content join attaches a blob to every matching source
directory, not only the longest.** Nested marketplace sources such as
`plugins/alpha` and `plugins/alpha/nested` previously each received the blob
from their own `ls-tree`; longest-match-only dropped the nested subtree from
the ancestor's expected tree, so a healthy ancestor cache was reported
`stale-content` and a hole in that subtree was reported as a match.

## [0.44.6]

### Changed
Expand Down
88 changes: 80 additions & 8 deletions plugins/claude-ops/skills/plugins/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,56 @@ arrive as a literal placeholder with no error to warn anyone. See
Bare invocation (no arguments) → `sync` against the default marketplace. `help` or an unrecognized
action → show this table.

## Running `sync` and `audit`

Both actions execute Steps 1 through 5b as ONE bundled script call, then the model writes Step 6's
report from the JSON digest that call prints. The step sequence, and the reason behind every step,
stay in [context/sync.md](context/sync.md); the script is bound to that file.

1. **Run it.** Substitute the marketplace target, the policy, and the flags into this command. The
journal root is written here because `${CLAUDE_PLUGIN_DATA}` resolves in skill content and
**not** in a `context/*.md` spoke, which is read raw:

```bash
"${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/sync-run.sh \
[--marketplace <name> | --all] \
--journal-root "${CLAUDE_PLUGIN_DATA}/plugins-sync/runs" \
--install-new <policy> [--allow-downgrade]
```

`audit` is the same command with `--audit` instead of `--journal-root` (it writes to a scratch
directory it deletes) and never `--allow-downgrade`, which it ignores and says so.

`<policy>` is the word from the **Configured value** line under "userConfig: `install_new`"
below — `all`, `none`, or `ask`, and `ask` when that line still shows the unset placeholder
token. Pass the WORD, never the token: a placeholder inside a command is a shell substitution
error, not a policy. Any other value is treated as `ask` and named back in the digest's
`install_new_invalid` so the report can flag it.

2. **Read the digest.** One compact JSON object on stdout, also written to `<run_dir>/digest.json`.
It carries everything the Report needs, per marketplace, plus a `run_dir` that holds every
snapshot and the journal.

3. **Resolve an `ask` install gap.** When a block has a non-empty `install_gap` and
`stopped_before_install: true`, run the batched multi-select from
[context/sync-install-enable.md](context/sync-install-enable.md), then re-enter for Steps 4 and 5
against the same run:

```bash
"${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/sync-run.sh \
--only-install "<the ids the user picked, comma-separated>" --run-dir "<the digest's run_dir>"
```

An empty id list is legal and means "install nothing, still complete Step 5". Report from the
digest that call prints; it supersedes the first one and reuses the same cache-content finding
rather than checking again.

4. **Report.** Emit the Report section below.

Load [context/sync.md](context/sync.md) when a digest carries errors, a non-empty gap, a catalog
regression, or a cache-content finding, and when the user asks why a step behaved the way it did.
A run with none of those has nothing in the file that changes the report.

## Marketplace resolution

No hardcoded marketplace name anywhere in this skill. Every action resolves its target the same way:
Expand Down Expand Up @@ -106,17 +156,22 @@ The third form projects that same id list from a report already on disk rather t
fleet, and is the form `sync`'s steps use: each step re-reads the full report anyway, and every
selector is derivable from it. Same script, same projection, so the `\r` protection is unchanged.

`sync-run.sh` above is what calls these scripts during `sync` and `audit`; the contracts below are
what it and any other caller are bound to.

A second read-only script answers the question `fleet-state.sh` structurally cannot: whether the
files in a plugin's cache directory actually match the commit its install record claims. Run it as
Step 5b of `sync` and of `audit`:
files in a plugin's cache directory actually match the commit its install record claims. Step 5b of
`sync` and of `audit` calls it ONCE per marketplace:

```bash
"${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/cache-content-check.sh --marketplace <name> [--scope user|project|all]
"${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/cache-content-check.sh --marketplace <name> --ids
```

`--ids` emits the stale ids alone, one per line, CR-free, the same contract and for the same reason
as `fleet-state.sh --ids`. The script never writes anything and never runs `git fetch`; a commit
as `fleet-state.sh --ids`. Step 5b does not use it beside the JSON form: the ids are already in that
JSON, and a second call would repeat the run's most expensive read. It is the fallback for a JSON
that could not be produced. The script never writes anything and never runs `git fetch`; a commit
that is not in the local marketplace clone is reported as `sha-not-local`, not fetched. See
[context/sync.md](context/sync.md) Step 5b, and
[context/scope-semantics.md](context/scope-semantics.md) for the mechanism that makes a cache
Expand Down Expand Up @@ -187,9 +242,9 @@ action.
Marketplace: <name> — <current | needs update> (autoUpdate: <on|off — suggest enabling if off>)
(repeat this line per marketplace in `all` mode — Steps 2–5 run once per marketplace)
In-repo: <N> project/local install(s) updated in <project_root>
(N counts FORWARD moves only; an in-repo record moved backward, only possible under
--allow-downgrade or for an id whose catalog version could not be read, renders under
`Downgraded:` with its scope and is not counted here)
(N is `in_repo.updated | length`; it counts FORWARD moves only. An in-repo record moved
backward, only possible under --allow-downgrade or for an id whose catalog version could
not be read, renders under `Downgraded:` with its scope and is not counted here)
| 0 — <project_root> has no project/local installs
| skipped — no project context resolved from <cwd>
Updated: <N> plugin(s) — <id>@<marketplace>: <old> → <new> (only when N > 0)
Expand Down Expand Up @@ -231,8 +286,16 @@ than a lookup:
itself the primary value path, so a run in which it did nothing has to say so in the default output,
not only when it succeeds. The three variants are not cosmetic: `skipped` and `0` answer genuinely
different questions ("there was no *here* to update" versus "here has nothing installed"), and
collapsing them is the whole defect this row exists to close. `fleet-state.sh`'s top-level
`project_root` is what distinguishes them. See [context/sync.md](context/sync.md) Step 2.
collapsing them is the whole defect this row exists to close. Two digest fields pick the variant,
in this order:

- `project_root` is `null` → `skipped`, naming the cwd.
- `in_repo_records == 0` → `0 — <project_root> has no project/local installs`.
- `in_repo_records > 0` → the counted variant, with N taken from `in_repo.updated | length`.

`in_repo_records` counts the records belonging to this root whether or not any of them moved, so a
root that HAS project/local installs and updated none of them reads `0` against a named root rather
than claiming the root has nothing installed. See [context/sync.md](context/sync.md) Step 2.

Add a self-update row when Step 3's sweep updated `claude-ops` itself:

Expand Down Expand Up @@ -295,6 +358,9 @@ Stale project records: <K> record(s) across <P> path(s) not present on this mach
verdict that the directory is gone for good.)
```

`K` is `stale_project_records.total` and `P` is the length of `stale_project_records.by_path`; each
`by_path` entry is the `{path, count}` one row renders.

A project-scope enable gap is a row `sync` deliberately does not fix. Step 5 enables automatically
only where the write is not team-shared state. Give each one its runnable command rather than a
count, so acting on it is a copy, not a reconstruction:
Expand Down Expand Up @@ -349,6 +415,12 @@ Cache content: <N> install(s) whose cache files disagree with their recorded git
`claude plugin update <id>@<marketplace>`, which recreates it from the clone.
```

`N` is `cache_content.stale_content`, and one row comes from each `cache_content.stale[]` entry:
`id`, `version`, and `files_differ`, which sums every direction of disagreement — bytes that
changed, files the tree has and the cache lacks, and files the cache holds and the tree does not.
`files_differ` reads `null` when the digest fell back to the checker's `--ids` form, which knows the
ids and no per-file detail; report the ids alone then.

**The check never repairs.** It does not delete a cache directory, does not re-run an update, and
does not `git fetch` a commit the marketplace clone lacks. A commit that is not local is reported as
`sha-not-local` and left alone: fetching is a network mutation this audit does not perform, and it
Expand Down
Loading