Arguments. [sync|converge] [<marketplace>|all] [--allow-downgrade] [--update-other-paths]. Full form: [action] [|all] [--allow-downgrade] [--update-other-paths]. Actions: sync (default; alias update), converge. The read-only audit is its own skill, /harness-ops:plugins-audit, which the model may start; this skill is user-only because sync can update committed plugin pins in every repository on disk
Variables
Arguments: $ARGUMENTS
Scope
Guarantees that the plugins which actually load, for the machine's user scope, and for any repo you're standing in with its own project/local-scope installs, are the latest published versions of everything the marketplace offers, and surfaces any state where something older or unintended is what really runs.
Distinct from Claude Code's own background autoUpdate, which we treat as a background refresh of
already-installed plugins, never a substitute for this skill
(context/scope-semantics.md holds that reading and its pointer). This
skill covers what we do not rely on autoUpdate for: installing new catalog plugins, checking
enabledPlugins completeness, detecting and reporting scope divergence, and running on demand.
Distinct from harness-config's audit skill's plugin-drift check: that check compares a project's
committed enabledPlugins against a marketplace's upstream marketplace.json (orphan/new/rename
plugin names). This skill compares the local, already-installed state (installed_plugins.json,
per-scope enabledPlugins) against the local marketplace catalog, a different axis (install/scope
completeness, not settings-vs-upstream drift).
Never silently fixes drift it finds. sync mutates only via the documented CLI actions below,
plus the one git pull --ff-only of a directory source the user agreed to (see "userConfig:
directory_source_pull"), and never writes a committed .claude/settings.json: its Step 5
enables automatically only at user and local scope, and reports a project-scope gap rather
than filling it, because a committed file is converge's to write, behind its per-plugin confirm. After Step 4 installs
anything, sync may reorder keys in user-scope ~/.claude/settings.json (machine-local, already
written by claude plugin install -s user) so the map stays alphabetical; it never reorders a
project-scope map. converge is the one action that can touch committed settings, and only after
an explicit per-plugin confirm. See context/scope-semantics.md for
which CLI calls write that file.
For sync and the audit, the script computes every number and the model reports it. Steps 1
through 5b and the Step 6 render are one sync-run.sh call; the digest and the rendered report
are the record, and the model adds the reload guidance and answers questions. Nothing in the
report is retyped, recounted, or re-derived by the model. converge follows the same rule for
its plan: converge-plan.sh computes every row's strategy, command and class, grouped by path, and
the model presents it and runs only what the user confirms.
The skill never branches on the host to change its algorithm or its report. There is no
cloud-versus-local branch, and no detection of or coordination with a repository's bootstrap hook:
the same steps run and the same report renders wherever the skill is invoked. Three things this
invariant does not cover, because they are not algorithm or report branches: the destructive-tier
autonomy abort converge performs before touching anything (CLAUDE_CODE_REMOTE, /loop,
/schedule; see context/converge.md), the same autonomy test sync
applies before it offers or runs a directory-source pull (it then behaves as never), and the platform-portability
detection in fleet-state.sh ($OSTYPE for MSYS and Cygwin path forms), which changes how a path
is spelled and never what is computed.
Action Router
Parse $ARGUMENTS for the action (first token) and an optional marketplace target (second token:
a marketplace name, or all).
--allow-downgrade is position-independent: remove it from $ARGUMENTS first, then apply the
first-token / second-token parse to what remains, so it reads the same before, between, or after the
other two. It applies to sync only, and it opts that run into moving an install backward when the
marketplace catalog reads lower than what is installed. See context/sync.md's
"Downgrade guard".
This table is an index, not a substitute: read the linked detail file before executing any action,
except sync, which one script runs and which loads its file on the triggers under
"Running sync". Each Description names the territory an action covers, never its algorithm, the steps, their
ordering, and their failure handling live only in the linked file.
One block below is a deliberate exception to that index-only rule and has to live in the hub
rather than in a spoke: the install_new render, because we rely on ${user_config.*} being
substituted only when Claude Code renders the skill; a spoke opened later as a file read is plain
bytes, so the same token in a spoke would arrive as a literal placeholder with no error to warn
anyone.
See context/gotchas.md. The Report section below is a pointer: the report
itself is rendered by the script.
| Action | Mutates | Description | Detail |
|---|---|---|---|
sync (default) |
Yes. CLI only | Marketplace, install, and enable-state maintenance for the effective fleet | context/sync.md |
converge |
Yes. Can rewrite committed settings after confirm | Cross-scope divergence reconciliation, preview- and confirm-gated | context/converge.md |
Bare invocation (no arguments) → sync against the default marketplace. update is an alias for
sync. audit → run nothing here and point the user to /harness-ops:plugins-audit, the
read-only dry run of this algorithm. help or an unrecognized action → show this table.
Running sync
sync executes Steps 1 through 5b and renders Step 6's report as ONE bundled script call:
it prints the JSON digest, then the report. The step sequence, and the reason behind every step,
stay in context/sync.md; the script is bound to that file.
Run it. Substitute the marketplace target, the policy, and the flags into this command. The journal root is written here because we rely on
${CLAUDE_PLUGIN_DATA}resolving in skill content and not in acontext/*.mdspoke, which is read raw (see "Spoke paths" below):"${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/sync-run.sh \ [--marketplace <name> | --all] \ --journal-root "${CLAUDE_PLUGIN_DATA}/plugins-sync/runs" \ --install-new <policy> --source-pull <pull> [--quiet-auto-update <names>] \ [--allow-downgrade] [--update-other-paths] --render<pull>is the word from the Configured value line under "userConfig:directory_source_pull", andaskwhile that line shows the unset placeholder token. Passneverinstead when the session is autonomous or you cannot tell a human is present.--quiet-auto-updatetakes the names from the Configured value line under "userConfig:quiet_auto_update_marketplaces"; leave the flag out while that line shows the placeholder token or nothing.<policy>is the word from the Configured value line under "userConfig:install_new" below:all,none, orask, andaskwhen 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 asaskand named back in the digest'sinstall_new_invalidso the report can flag it, on the first pass and on an--only-installre-entry alike.Read the output. The first line is one compact JSON digest, also written to
<run_dir>/digest.json; after a blank line comes the rendered report, also written to<run_dir>/report.txt. The digest carries arun_dirthat holds every snapshot and the journal, and the fields theaskre-entry needs.Resolve a pull offer. When a block's
source_pull.statusisoffered, ask the user once per such marketplace whether to fast-forward its checkout (oneAskUserQuestionquestion per marketplace, Pull or Skip). Never ask in an autonomous session (CLAUDE_CODE_REMOTEset, or the run arrived via/loopor/schedule) or when it is unclear a human is present; the first run then had--source-pull neverand offers nothing. On a yes, run the step 1 command again with--pull-source "<the names the user agreed to, comma-separated>"added: the script checks each checkout again, fast-forwards it withgit pull --ff-onlybefore that marketplace's refresh, or refuses with the reason and touches nothing, and the sync then runs against the refreshed catalog. Its report supersedes the first one, so read the next step from its digest. A no or no answer keeps the first report and its pull-and-rerun bullet. Ask once per invocation: a marketplace the user declined staysofferedin later digests of this sync and is not asked about again. Resolve this before step 4: an install gap read from a stale checkout is not the one to offer.Resolve an
askinstall gap. When a block has a non-emptyinstall_gapandstopped_before_install: true(the report says so underAction needed), run the chunked "install and enable" offer from context/sync-install-enable.md, then re-enter for Steps 4 and 5 against the same run. The re-entry installs each pick and enables any the CLI installed disabled by default:"${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>" --renderAn empty id list is legal and means "install nothing, still complete Step 5". A dismissed or unanswered chunk declines only its own ids: leave them out of the list and keep the picks from answered chunks. When nothing was answered, the list is empty: re-enter with
--only-install "", and the report lists the declined gap underAction needed. The report that call prints supersedes the first one and covers the whole run. When the first pass stopped before install it skipped the cache-content check, and this re-entry runs that check after the installs; otherwise the re-entry reuses the finding the first pass wrote.Report. Paste the rendered report and append the one model-owned line; see the Report section below.
Load context/sync.md when a digest carries errors, a non-empty gap, a catalog
regression, a cache-content finding, a source_pull that was refused or failed, or a nonzero moved_during_run or noop_unverified count
(plugins that moved during the run under an update call that reported them current, or
already-current answers the snapshots could not confirm), and when the user asks why a step behaved
the way it did.
Marketplace resolution
No hardcoded marketplace name anywhere in this skill. Every action resolves its target the same way:
- No marketplace argument → the default: the marketplace this plugin (
harness-ops) was itself installed from, resolved dynamically byfleet-state.sh(joins${CLAUDE_PLUGIN_ROOT}againstinstalled_plugins.json's install records, never a hardcoded name). <marketplace-name>argument → that marketplace only.allargument → every marketplace inknown_marketplaces.json; per-marketplace failures are reported inline and never abort the sweep (see context/sync.md).allalso multiplies theinstall_newpolicy across every catalog: under a rendered policy ofallthis target installs every plugin published in every known marketplace. Confirm the resolved install gap with a human first, per "userConfig:install_new" below.
State inspection
Every action reads the fleet through the bundled read-only fleet-state.sh, checks cache content
through cache-content-check.sh, and reorders a user-scope enabledPlugins map only through
normalize-enabled-plugins.sh. Never hand-parse installed_plugins.json,
known_marketplaces.json, or a settings file, never write them, and never hand-write a jq
extraction where a script's --ids form exists. converge's
committed-enable check (context/converge.md Step 2) reads each path's
enabledPlugins entry from fleet-state.sh's projectEnabledEntry, never from the file. sync-run.sh calls all three during sync and /harness-ops:plugins-audit. Alongside them scripts/jq-capture.sh ships as a sourced library, never invoked: it
carries the CR-stripping jq capture and the JSON string encoder that fleet-state.sh,
cache-content-check.sh, and sync-run.sh each source from their own directory.
Read context/script-contracts.md when a step misbehaves,
when converge needs an id list, or before invoking one of the scripts from anywhere other than
sync-run.sh; it carries each script's invocation forms and the \r rule behind --ids.
The read-only audit
/harness-ops:plugins-audit runs this skill's algorithm through sync-run.sh --audit, with every
mutating CLI call replaced by a prediction, and the model may start it. It is a separate skill
because disable-model-invocation applies to a whole skill, and only the read-only action is safe
for the model to start. The Report section below still describes its render, since one
render-report.jq prints both.
Operator script: refresh and clean
scripts/reset-refresh.sh re-fetches the user-scope fleet with its configuration unchanged. It has
three levels:
previewchanges nothing and prints whatrefreshandcleanwould discard.refreshmoves the marketplace clones andcache/aside and reinstalls each user-scope record through the CLI.cleandoes the same and also discardsdata/. It keeps the moved copies as one~/.claude/plugins.bak-<ts>backup and moves that backup back on any difference.
Both runs then check that marketplaces, user installs and user enabledPlugins match their
pre-run snapshots. Neither is an action of this skill. Both refuse to run while a claude process
is running, and clean also refuses without a terminal. So the operator runs them from a terminal
with every session closed. When the user asks for one, give them these commands and do not run
them:
bash "${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/reset-refresh.sh preview
bash "${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/reset-refresh.sh refresh
bash "${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/reset-refresh.sh clean
context/refresh.md holds what each level does, its safeguards, and the probe record behind them.
Report
Step 6 is rendered by the script. sync-run.sh --render prints the fixed-section report after the
digest line, every run writes the same text to <run_dir>/report.txt, and
jq -r -f "${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/render-report.jq <run_dir>/digest.json
reproduces it from a run directory later.
The layout is fixed and reads the same on every platform. The first line is the verdict. It is
Result: <N> item(s) under Action needed when that section has items. Otherwise it is
Result: changes applied, nothing under Action needed or Result: clean, nothing changed and nothing under Action needed. In audit it is Result: see the predictions below, nothing under Action needed, or Result: no change predicted, a lower bound against the unrefreshed catalog.
The verdict counts Action needed items only. A remedy: on a row outside that section, such as
converge for divergences, still applies. Each line carries one fact. Each part of a multi-part row gets its own indented line
under a short heading: a divergence class, a timing figure, a cache tally. A list of more than three
ids also gets one line per id. A remedy is its own remedy: line under the fact it fixes. No
line is wrapped by hand, version moves read <old> -> <new>, and every character is ASCII except
text the digest carries, such as a CLI's own output. Why a row says what it says lives in
context/sync.md and
context/stale-records-cache-content.md, not in the
render, so a clean run prints no explanatory paragraphs.
Every section, conditional row, annotation, and
Action needed bullet is a function of digest fields, which is what keeps a number, an id, or a
scope from being misstated between the run and the report: the Marketplace: line with its
three-way autoUpdate slot (on; off with a remedy: line to enable it, or bare off for a
marketplace named in quiet_auto_update_marketplaces; unreadable for a
null, never rendered as off), whose status reads needs update only for refresh, update and
failure state (a failed refresh or CLI call, or an error; in audit, an update, install or enable sync
would make), source checkout behind <upstream> when a directory source's git checkout is behind
its upstream, and current otherwise, followed by , N action(s) pending when work is left to a
person (an install declined, skipped by policy or held for the ask prompt, an unfilled or project-scope enable, an
install left not enabled, a delisted plugin, a withheld downgrade), so
current, 1 action(s) pending is a fleet with nothing to update and one such action. Each pending
action is an Action needed bullet, except audit's withheld downgrades, counted once as their
Would withhold: row; the source: row under
it for a directory source (branch, upstream, ahead/behind as of the checkout's last fetch, modified
tracked files, or why freshness was not checked; the run fetches or pulls the checkout only on a
--pull-source request, and then the row names the commits it fast-forwarded from and to); the fixed In-repo: row in its three variants (skipped naming
the cwd when no project root resolved, 0 naming a root with no project/local installs, and the
counted variant, forward moves only); Behind in other paths: (the count Step 3a left alone while
off, with its remedy); Catalog moved during this run:; Updated in other paths: and Not moved in other paths:
(the records of every other present path that sync forward-updated from that path, and the
linked-worktree or user-home ones the call left behind; Would update in other paths: under audit);
Updated: (forward moves and pairs flagged
(direction unknown)) and Downgraded: (a backward move that happened during the run says so); Moved during this run: (ids
whose update call the CLI answered "already at the latest version" while the run's snapshots show
their version changed, which the run did not do and does not attribute; with a Not verified: row
for already-current answers the snapshots could not confirm); Catalog regression:; Installed: with the policy-all
recurrence clause; Normalized:; Enabled:; the Divergences: section (one line per non-zero
class, each with its remedy: lines: actionable, with its here and elsewhere counts under it and
the one converge remedy; in linked worktrees; blocked. Under a by origin: heading come the
pre-existing and newly created counts, with the per-step lines only when the run created any. A
digest from before the class split shows the machine-wide count, this project's count under it when
a root resolved, and one converge remedy) and its by project path: lines naming each present path's record
count and up to three ids (+K more past that), with the paths that are not present counted on one
line; the self-update note when this plugin's install record moved during the run; the stale project
records and user-scope cache content sections; the Timing: row (the marketplace total, with the slowest step,
the seconds outside the named steps and the clock's resolution each on its own line under it; a measurement with no threshold); and Action needed (a behind directory checkout with the
git -C <path> pull --ff-only to run and the marketplace to resync, a requested fast-forward that
was refused or failed with its reason, install and enable gaps, failed CLI calls, user-scope orphans, installs that left userConfig options unset,
installs the CLI reported as disabled by default that this run did not enable, plugins absent from the catalog (installed, or
only enabled in settings),
updated plugins whose installed build declares a monitor, reorder refusals, an unsorted
project-scope map, withheld downgrades with both versions and the likely cause, and every error).
In audit mode every call sync would make carries the would run: prefix, and a remedy sync
never runs itself (the git -C … pull --ff-only, a project-scope enable) reads the same as in
sync, unprefixed. Would withhold: sits beside Would update: whether or not a downgrade was
found; --allow-downgrade is named as ignored. Each shape is pinned to a golden file under scripts/fixtures/render/ by
scripts/sync-run.test.sh.
Paste the render as printed. Do not restate a number, an id, a scope, or a count it already
carries, and do not add rows: a row the render omitted is a row whose digest field was empty, which
is not proof that nothing happened. The render lists only what the run's snapshots establish, so the
initial report may add one caveat line when something in the run suggests more than it shows (a
Not verified: row, or Moved during this run: ids with a cause the user may ask about): state
what the report cannot establish, never a cause. Follow-up answers from the run directory stay
allowed. Per
marketplace in all mode the whole block repeats, because Steps 2 through 5 run once per
marketplace; the trailing Run journal: and Timing: rows cover the invocation.
The one line the model owns is the reload guidance, appended after the render as a two-step
rather than as a prediction about which case will trigger it: recommend bare /reload-plugins,
and /reload-plugins --force only when the bare command warns. Do not present any one cause as the
sole trigger of that warning, and do not tell the user --force would be wrong when the bare
command has already warned them. Never recommend --force pre-emptively alongside every reload: we
treat it as opting into a real token cost the bare command declines to pay on its own.
context/scope-semantics.md "/reload-plugins: bare by default,
--force for the MCP-cache-invalidation case" holds the pointers and dates. Monitors are already
covered: the render's Action needed names each updated plugin whose installed build declares one.
context/sync.md "Name the monitors" holds what that bullet says and where it was
read, so the reload line does not restate it. After the line, answer follow-up questions from the digest
and the run directory it names; load context/sync.md when a question is about
why a step behaved the way it did.
(We observed a plugin updated mid-session keep resolving to the previous version's path, which is what the self-update note reports: Claude Code 2.1.240, not re-run on 2.1.261 because it needs an interactive session. The record is in context/gotchas.md.)
Stale project records and cache content
Both are findings the render reports and this skill never fixes: a project/local record whose
projectPath is not present on this machine is named in its own section, never counted as a
divergence, never suppressed, and never reaped; a cache directory whose files disagree with the
recorded commit is named with the proved remediation, never repaired. Read
context/stale-records-cache-content.md when
stale_project_records.total > 0 or cache_content.stale_content > 0, or when the user asks why
either section reads as it does.
userConfig: install_new
Controls new-catalog-plugin install policy during sync. Ships as a string whose options
picker lists the three values below, default "ask". This skill still validates the value,
because one set by hand in settings.json never passes through the picker (context/scope-semantics.md holds the option-schema
record; for option types and fixed options, see
User configuration and
Limit a field to fixed options):
ask(default). Offer every not-yet-installed catalog plugin inAskUserQuestionchunks of at most 4 options per question and at most 4 questions per call, with a further call past 16, each chunk's question text distinct (answers are keyed by it). A chunk of 1, whether a gap of 1 or the one left over from a gap of 5, 9, 13 and so on, is a single-select Install/Skip question with no hand-added Other option. The limits are the tool's, per Handle approvals and user input: limitations (as of 2026-11-10; recheck if that section changes them). Then install and enable each pick, including one the CLI installs disabled by default. An unanswered or dismissed chunk counts as declinedall. Install every not-yet-installed catalog plugin automatically; one the CLI installs disabled by default stays off and is reportednone. Report them in "Action needed" only, never install
Any explicitly-set value other than these three is invalid; treat it as ask and note the invalid
value in the report.
all is scoped to the marketplace target, and the target is what makes it safe or catastrophic.
Against the default marketplace, the one whose fleet the operator curates, the gap is normally zero
or a handful and all is the intended convenience. Against a multi-marketplace target (all, or a
named third-party catalog) the same word means "install every plugin published in every catalog this
machine knows about." One observed run installed 2,231 plugins before it was killed; see
context/gotchas.md's "--all with install_new: all is a mass install of
every catalog". When the marketplace target is all and the rendered policy is all, do not
proceed unattended: resolve the total install gap first (one /harness-ops:plugins-audit all, or fleet-state.sh --marketplace <name> --ids missing-user-install per marketplace, which is the selector
sync-run.sh itself projects for Step 4), state the number, and get an explicit human yes. Treat the
configured value as written with the operator's own marketplace in mind, and downgrade to ask when
no human is present to receive the count.
Configured value: ${user_config.install_new}. We treat this line as rendering the configured
word into the skill content before the model sees it, but only when the key is explicitly set
in a scope Claude Code reads pluginConfigs from, read live from
settings reference: pluginConfigs
with the precedence
settings: settings precedence gives (as of 2026-11-10; recheck when either changes the scopes or their order). We treat a
project's .claude/settings.json or .claude/settings.local.json entry as doing nothing, and declaring the option in plugin.json alone does not make its value readable
here either. See context/scope-semantics.md for the read path, its
pointer, and why it differs from enabledPlugins, which this same skill reads from project and
local scope.
The manifest's "default": "ask" is not substituted for an unset key: our probe saw the render
leave the placeholder token unchanged while a sibling key set in ~/.claude/settings.json and
${CLAUDE_PLUGIN_ROOT} both substituted in the same render. That is a probed claim, not a
documented one, and it stays pointed at its dated record: the probe, its as-of date and CLI version,
the docs pointer for the default field and the substitution surfaces, the recheck trigger, the
pluginConfigs payload shape, and the probe recipe are in
context/scope-semantics.md "userConfig: an unset key renders the
literal placeholder". Read it when the rendered value looks wrong or before re-running the probe.
Substitution into content happens in what Claude Code renders, and never in a file a spoke read
returns, which is why the Configured value line lives here and cannot move to a spoke. So for
the common default-config user, with no pluginConfigs set anywhere, the Configured value line
above still shows that literal placeholder token, not ask.
Read that literal placeholder token as the expected unset state → use the default ask, and do NOT
report it as an invalid value. Only a rendered value that is a real word other than
ask/all/none (i.e. the key was set, to something unsupported) is the invalid-value case worth
flagging. Sync's Step 4 branches on the Configured value line's rendered value, or on the ask
default when that render is still the placeholder token, not on the option's name or description above.
userConfig: directory_source_pull
What sync does with a directory marketplace whose git checkout is clean (no modified tracked
files), on a branch with an upstream, not ahead of it and behind it. A string with the picker
values below, default "ask", read and rendered the same way as install_new above:
ask(default). Pass--source-pull ask; the digest marks such a checkoutoffered, and step 3 of "Runningsync" asks once per marketplace and reruns with--pull-sourceon a yes. A dirty, ahead, diverged, detached or upstream-less checkout is never offered, and the script refuses a--pull-sourcefor one, so the pull cannot discard or tangle local work.never. Pass--source-pull never; nothing is offered or pulled, and the report keeps its pull-and-rerun bullet.
An autonomous or ambiguous session behaves as never whatever the value: no human can answer the
offer there. The script applies the same rule on its own when CLAUDE_CODE_REMOTE is set. A word
other than these two is treated as ask and named in the report.
Configured value: ${user_config.directory_source_pull}. The unset placeholder token here
means the default, ask.
userConfig: update_other_paths
Whether sync also updates the lagging project and local records of every other present path. A
boolean, default false: off, the report counts them and names the remedy. Pass
--update-other-paths when the Configured value line below reads true, or when the user gave
that flag, which is position-independent like --allow-downgrade: remove it from $ARGUMENTS before
parsing the action and target. context/sync.md Step 3a says why it is off by default.
Configured value: ${user_config.update_other_paths}. The unset placeholder token here means the
default, false.
userConfig: quiet_auto_update_marketplaces
Comma-separated marketplace names whose Marketplace: line shows autoUpdate: off without the
suggestion to enable it, for a marketplace the user keeps off on purpose. A string, default
empty, which keeps the suggestion everywhere. Pass the names as --quiet-auto-update.
Configured value: ${user_config.quiet_auto_update_marketplaces}. The unset placeholder token
here, or nothing, means no names: leave the flag out.
For the option fields, the picker and where a value is stored, see
User configuration
(as of 2026-10-27; recheck when that section changes the options or default fields).
Spoke paths
The context/ files write this skill's directory as <skill-dir>, which is ${CLAUDE_SKILL_DIR}.
Put that path in place of the placeholder before running a command or writing it into a brief. We
never put a ${…} token in those files: we do not rely on one being substituted in a file read
through the Read tool, or on the Bash tool's environment carrying CLAUDE_SKILL_DIR.
- Pointer: for where each
${…}reference resolves, see Where each variable resolves. - As of: 2026-10-07
- Recheck trigger: that table adds supporting files to where a
${…}reference resolves.
Next
/harness-ops:prerequisites lists which external binaries the enabled fleet is missing.
Reference index. Load on demand
| File | Load when |
|---|---|
| context/sync.md | A sync digest meets a trigger under "Running sync", or the user asks why a step behaved as it did; it is the step sequence sync and /harness-ops:plugins-audit both execute, and the script is bound to it. |
| context/sync-install-enable.md | A digest block has a non-empty install_gap or enable_gap, or install_enable_deferred: true. Both gaps are empty on a current fleet. |
| context/converge.md | Running converge, the only action that may rewrite a committed settings file. |
| context/stale-records-cache-content.md | The digest's stale_project_records.total or cache_content.stale_content is above 0, or the user asks why either section reads as it does. |
| context/script-contracts.md | A step misbehaves, converge needs an id list, or a caller other than sync-run.sh is about to invoke fleet-state.sh, cache-content-check.sh, or normalize-enabled-plugins.sh. |
| context/scope-semantics.md | A scope, version, or reload claim needs its verified source before you act on it; also the dated userConfig unset-key probe record. |
| context/refresh.md | The user asks to refresh, clean or re-fetch the plugin fleet with its configuration unchanged, or about reset-refresh.sh's output. |
| context/gotchas.md | A run failed in a way the steps do not explain, or a safeguard looks removable. |