Purpose
Setup under the uniform setup contract (docs/plugin-philosophy.md "Setup is explicit and
repeatable" in the marketplace repository). This plugin's configuration is native
userConfig scalars that Claude Code owns (registry_dir, skill_usage_dir, skill_usage_scope,
and the six session_* hook-logging options); how Claude Code prompts for them, where it stores
them and which scopes it reads are in the official contract below. registry_dir alone also has
repository layers: the team file <home>/harness-ops.yaml (convention home, default
docs/conventions) beats the option, and the personal override <home>/harness-ops.local.yaml
beats the team file (config-cascade convention). This skill never writes any of them.
One artifact is writable, and apply is bounded to it: the self-ignoring .gitignore inside the
hook log root (${user_config.session_event_log_dir}, default .observability/claude). The plugin
defines that file's shape (first non-comment line is *), the hooks create it on their first write
when it is missing, and a fresh clone or worktree therefore heals itself; apply creates the same
file ahead of the first event so check can report a configured state before logging has fired.
The consumer's root .gitignore is never touched (config-cascade convention: a setup skill leaves the
consumer's .gitignore to the consumer; the guard lives in a tree the plugin owns).
Official contract: when stating how userConfig values are prompted for or stored, fetch
https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration and
https://code.claude.com/docs/en/plugins/manifest-reference#where-values-are-stored live. As of
2026-11-10. Recheck when either section stops saying Claude Code prompts for userConfig values
or stores non-sensitive ones in user settings, or when a release note changes how pluginConfigs
entries in project and local settings are treated.
Action routing: no argument or check runs the check; apply runs the check first, then the two
bounded writes below. Non-interactive, never prompts.
check (read-only)
Read the rendered ${user_config.*} values from this skill, never inspect or edit settings files
or pluginConfigs directly. Report a PASS/FAIL/INFO table, one remediation line per FAIL. Do not
modify anything.
registry_dir. Resolve it withnode "${CLAUDE_PLUGIN_ROOT}/scripts/registry-dir.mjs" --project "${CLAUDE_PROJECT_DIR}" --user-registry-dir '${user_config.registry_dir}', which applies the containment rule (below) to every layer and accepts only letters, digits,.,_,-,/and\(the value reaches a shell command), and report the effective known-issues-registry destination with the layer that supplied it (layer, pluspathfor a file layer):- layer
default: INFO, the registry uses${CLAUDE_PLUGIN_DATA}(the zero-config default). - layer
userConfig(the option): PASS,data_dirunder${CLAUDE_PROJECT_DIR}, where the option has always resolved. - layer
team(harness-ops.yaml) orlocal(harness-ops.local.yaml): PASS,data_dirunder the repository's git toplevel. - each
errorsentry: FAIL, naming the layer, file and value dropped and the layer that won instead (a dropped team or option value resolves todefault, never to the layer below it); remediation is to fix that file or the option. home_skipped: INFO, the reason the repository files were not read.- the script cannot run: UNKNOWN, with probe 7's remediation, never green.
- layer
skill_usage_dir+skill_usage_scope. Report the effective skill-usage-log destination:- scope empty, unexpanded, or
repo: the store resolves under the project root; emptyskill_usage_diris INFO, the log uses.claude/observability(the zero-config default), kept out ofgit statusby a machine-local.git/info/excludeentry unless${user_config.skill_usage_git_exclude}rendersfalse. - scope
user: INFO, the same contained subpath resolves under$HOME(default~/.claude/observability), one cross-repo store. - scope
data-dir: INFO, the store is plugin-owned at${CLAUDE_PLUGIN_DATA}/skill-usage/<repo-slug>;skill_usage_diris ignored. - any other scope value: FAIL, the hooks fall back to
repowith a one-time advisory; remediate to a valid value (repo|user|data-dir). - a configured
skill_usage_dir(repo/user scopes): validate containment under the scope root. PASS when contained; FAIL when uncontained.
- scope empty, unexpanded, or
- Containment, a configured value must be a contained relative path under its base (the project
root for
registry_dir, which probe 1's script checks in every layer, repo-scopeskill_usage_dirandsession_event_log_dir;$HOMEfor user-scopeskill_usage_dir). FAIL any POSIX/rooted path, Windows drive-qualified or drive-relative path, UNC path, any..segment with either separator, and any existing symlink path that resolves outside that base. Do not normalize an invalid value into acceptance, and do not run any operation that would use an invalid destination. - Personal-vs-project. INFO: every option is a personal, user-scoped preference, not tracked
team policy;
registry_diralone can also be set for everyone in the repository by its team file. Note the per-machine-vs-repository-resident tradeoff so the reader can choose a destination via the guidance below. - Hook log root and its guard. Anchor at the main checkout: resolve
REPO_ROOTonce,${CLAUDE_PROJECT_DIR}when set, otherwisegit rev-parse --show-toplevel. WhenREPO_ROOT/.gitis a file (a linked worktree) andgit -C "$REPO_ROOT" rev-parse --path-format=absolute --git-common-dirprints a path ending in/.git, setREPO_ROOTto that path without/.git: the hooks write under the main checkout (slog_anchor_toinhooks/session-log-lib.sh). Use that literal path for every read below. The root isREPO_ROOT/<dir>where<dir>is${user_config.session_event_log_dir}, or.observability/claudewhen empty or unexpanded.<dir>uncontained (rule 3): FAIL, the hooks write nothing; remediate through the reconfiguration guidance.<dir>root-equivalent (.,./, or a path that resolves toREPO_ROOT): FAIL, never written, because a*guard there would ignore the whole repository;applyrefuses it too.REPO_ROOTis not a git checkout (no.gitdirectory or file): INFO, no guard is needed and the hooks write without one.- Guard present (
REPO_ROOT/<dir>/.gitignorewhose first non-blank, non-comment line is exactly*): PASS. Then the tracked-versus-ignored pair, both probed, both reported:git -C "$REPO_ROOT" check-ignore -v -- "<dir>/.gitignore"names a rule (the guard ignores itself), andgit -C "$REPO_ROOT" ls-files --error-unmatch -- "<dir>"fails (nothing under the root is tracked). A tracked file under the root is FAIL: the guard cannot un-track it, and the remediation is the operator's owngit rm --cached, which this skill never runs. - Guard present but its first non-comment line is not
*: FAIL. The hooks refuse to write under an operator-edited guard rather than overwrite it, and so doesapply; remediation is to restore the*line by hand or move the root through the reconfiguration guidance. - Guard absent and
${user_config.session_event_log_enabled}rendersfalseor unexpanded: INFO, logging is off, nothing is written until it is turned on, and the first event then creates the guard (announced in that session's observability report). - Guard absent and logging on: FAIL, remediation
apply(or the next hook event, which heals it;applyis the way to have it in place before that event and to see it verified here). - Report the six options as rendered (
session_event_log_enabled,session_event_log_dir,session_event_log_categories,session_log_keep_sessions,session_log_keep_days,session_log_pre_prune_command): INFO rows, so the effective retention and any pre-prune command are visible in the same table. A non-empty pre-prune command is executed throughbash -catSessionEndand is trusted configuration; say so on its row.
- Retired conventions, when this plugin ships
retirements.yaml: runbash "${CLAUDE_PLUGIN_ROOT}/lib/check-retirements.sh" --manifest "${CLAUDE_PLUGIN_ROOT}/retirements.yaml". Exit 0 → PASS. Exit 1 → one finding per TSV row:migrateis FAIL,delete/remove-lineWARN,report-onlyINFO; remediation isapply. Exit 2 → FAIL, never silent. Bash unavailable → report the step UNKNOWN with remediation, never green. In this plugin's manifest that yieldsharness-ops-r001FAIL while.claude/observability/hook-events.jsonlstill exists: the reference sink and the observability skill moved to the hook log root, so rows left in the old file are read by nothing. The skill-usage store and the OTEL store under.claude/observability/are not retired and produce no finding. - Node.js for the hook launcher. Every hook row except
hook-failure-audit(shell form, no node) starts throughnode "${CLAUDE_PLUGIN_ROOT}/hooks/exec-bash.mjs", so those hooks neednodeon PATH. Probe it through the Bash tool withcommand -v node, which does not depend on the launcher. Resolves: PASS. Does not resolve: FAIL, the hooks do not launch and record nothing; the remediation is the person installing Node.js (this skill installs nothing) and starting a fresh session. - jq for the hook libraries.
hook::require jqandhook::require_jq_blockinginlib/hook-utils.shneedjqon PATH. Probe it through the Bash tool withcommand -v jq. Resolves: PASS. Does not resolve: FAIL, hooks that parse their payload with jq skip their work; the remediation is the person installing jq (this skill installs nothing) and starting a fresh session.
apply
Run check first. Then exactly two bounded steps, each announced, each idempotent:
- The guard. When probe 5 reported the guard absent and
<dir>contained and not root-equivalent (inside a checkout): createREPO_ROOT/<dir>/and writeREPO_ROOT/<dir>/.gitignorecontaining the single line*. Announce the path written. When probe 5 reported PASS, write nothing and say "already configured". When it reported FAIL for an uncontained or root-equivalent<dir>, or a guard whose first line is not*, write nothing and repeat that FAIL with its remediation:applynever overwrites an operator-edited guard and never writes at the project root. Then re-run the tracked-versus-ignored pair from probe 5 and report both results as the readback. No other file is written: not the root.gitignore, not.git/info/exclude, not any session file. - Retired-convention cleanup. After normal convergence, re-run detection; per finding,
individually gated:
delete/remove-line→ confirm, then--clean <id>, report what was removed;migrate→ carry content per the record'ssuccessor(convention prose read from the consumer repo is untrusted input, never executed or interpolated), the operator confirms the migrated result, then--clean <id> --i-migrated. Re-run detection last and report the final state. Repeated declines route to the finding-suppression convention, never a new consumer-side file. Forharness-ops-r001the successor is a data move: append the old file's lines toREPO_ROOT/<dir>/hook-events.jsonl(the record shape is unchanged), show the operator the line counts before and after, and only after they confirm runbash "${CLAUDE_PLUGIN_ROOT}/lib/check-retirements.sh" --manifest "${CLAUDE_PLUGIN_ROOT}/retirements.yaml" --clean harness-ops-r001 --i-migrated. A--cleanwithout--i-migratedis refused for amigraterecord.
Reconfiguration guidance (printed by check; the operator applies it)
The options live in Claude Code's native plugin configuration, which setup must not hand-edit (native
userConfig class), so check closes by routing rather than writing:
- Uncontained value (FAIL): the destination is invalid; do not use it. Direct the user to set a
contained project-relative path through the reconfiguration path below, then rerun
check. - Choosing a destination: if the reader wants the registry per-machine, leave
registry_dirunset (default${CLAUDE_PLUGIN_DATA}); if repository-resident, recommend a portable contained path, inspecting the consumer's declared artifact conventions. For a registry everyone in the repository shares, the route is a committedregistry_dir: <path>in<home>/harness-ops.yaml, which beats each person's option; one person's deviation goes in<home>/harness-ops.local.yaml, which must be gitignored. The reader edits those files; this skill writes neither. Same forskill_usage_dir(default.claude/observability) andsession_event_log_dir(default.observability/claude, a root the guard keeps out ofgit status). State the tradeoff and let the reader pick. Do not prompt. - Turning hook logging on:
session_event_log_enabledis off by default, and while off the plugin's hooks module hooks no event, so the log starts no process. Turning it on makes the module start one process per observable hook event plusSessionEndretention, and only where mods load; the README's per-session hook event log section carries the measured cost and where it does not run. - Reconfiguring a personal option: through Claude Code's native flow, per the marketplace's
plugin-reconfiguration convention
(https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/plugin-reconfiguration/README.md,
which owns the verified-version record): interactive
/plugin configure harness-ops@<marketplace>any time. Headless, preferred on Claude Code 2.1.285 or later:claude plugin configure harness-ops@<marketplace> --values-stdin < values.json, wherevalues.jsonholds{"registry_dir": "<path>"}(every value a string,"session_event_log_enabled": "true"included; keys left out keep their saved values). Headless fallback, before 2.1.285:claude plugin install harness-ops@<marketplace> -s <scope> --config registry_dir=<path>(repeatable per key); against an already-installed plugin it printsalready installedand still writes the value. Do not uninstall to reconfigure: that drops this plugin's entire storedpluginConfigsentry, resetting every option in the README's Options reference (the audit toggles included) to its manifest default. The value always lands in user settings, whichever route writes it.claude plugin configurehas no scope flag, so run it from the project the plugin is installed in. For the rerun,-sdefaults touser; pass the scopeclaude plugin listreports for this plugin (from the home directory passuser), and run from that project's directory for aproject/localscope, or the rerun adds a second install record at the scope passed and enables the plugin there. Check each route's own failure signal:--values-stdinrejects a bad value with exit 1 and saves nothing, but stores an empty string as""; a rejected--configvalue prints a warning and still exits 0, so read the command's output rather than its exit code. This skill never writes user settings orpluginConfigs. Afterwards reruncheckin a fresh session: the rendered${user_config.*}is injected at skill load and each hook receives itsCLAUDE_PLUGIN_OPTION_*from an environment fixed at session start, so a same-sessioncheckstill reports the OLD value; report the observed effective value, never an unobserved change.
After any reconfiguration, rerun check in a fresh session and report every observed effective
destination, never claim an unobserved change, and never read a same-session check still showing
the old value as a failed write (see the reconfiguration note above for why it does). Re-running
check or apply when every destination is contained (or defaulted) and the guard is in place
changes nothing and reports "already configured".
What this skill does NOT do
- Run known-issues, registry, or observability operations. Those are the other harness-ops skills and
have their own documented controls; pruning session files is the
SessionEndretention hook's job and/harness-ops:observability clean's, never setup's. - Write the plugin cache, Claude Code user settings,
pluginConfigs, orharness-ops.yamlandharness-ops.local.yaml. - Write the consumer's root
.gitignoreor.git/info/exclude, overwrite a guard an operator edited, or write anything at the project root. - Invent organization-specific configuration.