Coordinator Update

/coordinator-update — Update Advisory for OSS Coordinator Installs

Purpose. Check whether a newer version of the coordinator plugin has been published, compute a classified delta between the published version and your live install, and advise a migration path that preserves your implementation shape by default — renamed personas, custom environment setup, structural divergence, project-specific customizations.

Verb-name check: /coordinator-update was checked against Claude Code platform vocabulary before ship. It does not shadow a native Claude Code command or verb (per the /fan-out lesson; coordinator-improvement-queue.md 2026-05-30).

This skill is PM-invoked, not autonomous. It computes and advises; it does not apply changes without your explicit consent. No cadence trigger, no automatic recheck.

HARD CONSTRAINTS (verbatim — self-contained for OSS consumers)

This SKILL.md is self-contained. The coordinator CLAUDE.md is NOT in scope for OSS consumers. The following rules are quoted verbatim and apply throughout this skill's execution.

Preservation Constraint

Never overwrite a consumer_modified file without the user's Claude affirmatively judging the upstream change worth it AND surfacing the tradeoff to the user. The user's own implementation shape (persona names, custom environment setup, structural divergence) is preserved by default.

Commit Safety Rule

Never git add -A or git add .. Always use scoped, labelled, explicit-path commits: git add -- <path1> <path2> ... && git commit -m "<label>" -- <path1> <path2> ... No sweep commits. No blanket staging. Stage only the named files you are applying.

Offer-Shape Rule

Compute and advise is the default. Apply is explicit-consent-gated from the user — never autonomous action. The skill runs the helper, classifies the delta, and presents a recommendation. It does NOT apply changes unless the user explicitly says "yes, apply."

Out-of-Scope (hard block — never touch these)

This skill explicitly does NOT:

• Modify your project scaffolding or session-continuity surface: tasks/, state/handoffs/, memory entries under projects/, state/lessons.md, .claude/settings.json. These paths are agent-owned, not installer-owned. No install ceremony may write into them.
• Touch consumer_added files — files you added to your install tree that have no upstream source. These are entirely yours and are never offered for overwrite or modification.
• Touch .claude-plugin/marketplace.json — this file is installer-owned and regenerated by re-running the coordinator:install flow. It is not a user customization and is excluded from the advisory set.
• Author handoffs, spinoffs, or workstream-complete artifacts.
• Push to any remote.
• Modify project-level scaffolding managed by the 2026-05-29 coordinator-currency surface (that surface governs per-project structural currency, not the plugin tree).
• Run on a source_is_live machine (a coordinator development install where the plugin source is authored directly). This skill is for OSS consumers who installed via the publish repo (the coordinator:install flow). If you are on a development machine authoring the coordinator source directly, you do not need this skill.

Step 1: Resolve Install Root

Determine INSTALL_ROOT — the directory where the coordinator plugin lives on your machine. Default: ~/.claude/plugins/coordinator-claude/.

If the user passed --install-root <dir> as $ARGUMENTS, use that path instead.

Confirm the path exists and contains a coordinator/ subdirectory. If not, surface:

"Cannot locate a coordinator install at <path>. Pass --install-root <dir> with the correct path, or confirm you installed via the OSS coordinator:install flow." Stop.

Step 2: Run the Delta Helper

Run the Chunk 2 helper to produce a classified delta. The helper is co-located at: <skill-dir>/lib/compute-update-delta.py

where <skill-dir> is the directory containing this SKILL.md — typically ~/.claude/plugins/coordinator/skills/coordinator-update/.

# Review: code-reviewer — $0 is unreliable when Claude runs this block via the Bash tool
# ($0 resolves to /bin/bash, not the skill path). Derive SKILL_DIR deterministically from
# INSTALL_ROOT, which was already resolved in Step 1.
SKILL_DIR="${INSTALL_ROOT}/coordinator/skills/coordinator-update"

# Interpreter resolution contract: COORDINATOR_PYTHON env -> machine-local
# registry pin (coordinator.python) -> PATH. See the coordinator wiki,
# machine-local-registry.md § coordinator.python resolution contract.
PYTHON_BIN="${COORDINATOR_PYTHON:-}"
if [ -z "$PYTHON_BIN" ]; then
  for _cand in python3 python; do
    command -v "$_cand" >/dev/null 2>&1 && { PYTHON_BIN="$_cand"; break; }
  done
fi
if [ -z "$PYTHON_BIN" ]; then
  echo "ERROR: no Python interpreter found. Set COORDINATOR_PYTHON to its absolute path and retry." >&2
  exit 1
fi
_cc_ml="${COORDINATOR_SETTINGS_HOME:-$HOME/.coordinator-claude-settings}/bin/machine-local"
if [ -f "$_cc_ml" ]; then
  _cc_pin="$("$PYTHON_BIN" "$_cc_ml" get coordinator.python 2>/dev/null)"
  [ -n "$_cc_pin" ] && [ -x "$_cc_pin" ] && PYTHON_BIN="$_cc_pin"
fi

# The engine root this update flow depends on is resolved by the shipped
# resolver script, which is the single source of that resolution — no other
# code in this skill hardcodes how or where it is found.
_cc_engine_root="$("$PYTHON_BIN" "${INSTALL_ROOT}/coordinator/hooks/scripts/_engine_root.py" 2>/dev/null)"
if [ -z "$_cc_engine_root" ] || [ ! -d "$_cc_engine_root" ]; then
  echo "ERROR: could not resolve the coordinator engine root via ${INSTALL_ROOT}/coordinator/hooks/scripts/_engine_root.py — consult your coordinator install's engine-setup documentation for how to register it, then retry." >&2
  exit 1
fi

"$PYTHON_BIN" "${SKILL_DIR}/lib/compute-update-delta.py" --install-root "${INSTALL_ROOT}"

The helper emits a single JSON object to stdout. Capture it. The schema:

{
  "update_status": "current | behind | offline",
  "incoming_ref": "<tag or sha, empty if offline>",
  "manual_url": "<URL if offline or for manual reference>",
  "recommended_path": "none | overwrite | cherry-pick | plan-to-ingest",
  "counts": {
    "unchanged": <n>,
    "forward_safe": <n>,
    "consumer_modified": <n>,
    "consumer_added": <n>
  },
  "consumer_modified": [
    { "path": "<relpath>", "hunk": "<diff text ≤40 lines>" }
  ],
  "consumer_added": ["<relpath>"]
}

Exit codes: 0 = current; 3 = behind; non-zero (not 3) = offline/error.

Step 3: Branch on update_status

3a. Offline

If update_status is "offline" (helper exited non-zero and not 3):

Report:

"Could not reach the coordinator update source. Check your network or visit the update manually: <manual_url from JSON> (Never reporting 'up to date' when the source is unreachable — that would be a false signal.)"

Stop here. Do not claim the install is current.

3b. Current

If update_status is "current" (exit 0, all counts zero incoming):

Report:

"Your coordinator install is up to date (at <incoming_ref>). No action needed."

Stop here.

3c. Behind

Proceed to Step 4.

Step 4: Classify and Present the Delta

The install is behind. Read the JSON and partition the delta into three buckets:

Bucket A — Forward-Safe Files (forward_safe count)

Files the upstream changed, but you have NOT modified in your live install. These are safe to take — a reinstall of these files would not destroy any of your customizations.

Summarize what they contain. Examples: "updated workstream-start.md with a new Step 3.5 gate," "added docs/wiki/new-feature.md — no local equivalent."

Bucket B — Consumer-Modified Files (consumer_modified array)

Files where BOTH the upstream changed AND you have a local edit. These carry your implementation shape — likely renamed reviewer personas, added project-specific steps, custom environment setup, structural divergence that reflects your working style.

DEFAULT: PRESERVE. These files are NOT in any apply set unless you affirmatively judge the upstream change worth taking.

For each file in consumer_modified:

1. Read the upstream hunk field (the diff of what the upstream wants to change).
2. Read your local version of the file from the install tree.
3. Judge semantically — not byte-by-byte: Is the upstream change a genuine improvement (new gate, corrected logic, important safety rule) you would want even after rebasing your edits? Or is it cosmetic restructuring / prose reorganization that your version already addresses in your own way?
4. Present your judgment to the user with the tradeoff clearly stated:
   • If worth taking: "Upstream changed <path> — this adds <what>. Your local version has <your customization>. Taking the upstream change would mean rebasing your edit onto the new structure. Recommend: cherry-pick this one."
   • If not worth taking: "Upstream changed <path> — this reorganizes <what>. Your local version already expresses the same intent in your own structure. Recommend: keep yours."
5. Surface the judgment to the user. Do NOT apply without their explicit consent.

Bucket C — Consumer-Added Files (consumer_added array)

Files you added to your install tree with no upstream equivalent.

List them. Note: "These are your additions — never touched by this skill or any update process."

Step 5: Recommend One Path

Based on the classification, recommend exactly ONE update path with reasoning:

overwrite — only when the delta is forward_safe-only (Bucket B is empty, no consumer-modified collisions). Tradeoff-free. Offer to apply all forward-safe files.

"The update is entirely forward-safe — none of the changed files overlap with your customizations. Safe to apply all <N> files. Want me to apply them?"

cherry-pick — when some upstream changes are clearly wanted (forward-safe Bucket A, plus any Bucket B files you judged worth taking) but others collide with your implementation shape. List the takeable subset explicitly.

"I recommend cherry-picking <N> files: [list]. The remaining <M> files in Bucket B have collisions with your customizations — I recommend preserving your versions of those. Want me to apply the cherry-pick subset?"

plan-to-ingest — when the delta is substantive (many Bucket B collisions, architectural changes, or load-bearing customized files that would need careful rebasing). Apply would be risky without deliberate review.

"This update contains substantive changes that overlap with your implementation shape. I recommend running /plan to ingest this deliberately rather than cherry-picking blind. Seeded problem statement: 'Reconcile coordinator install at <INSTALL_ROOT> against upstream <incoming_ref>: <N> consumer-modified files need manual rebase — focus on <top 2-3 paths by importance>. Preserve persona names and project-specific steps.'"

Stop and wait for explicit user consent before proceeding to Step 6.

Step 6: Apply (on explicit user consent only)

Only proceed here if the user explicitly said "yes" / "apply" / "go ahead" in response to Step 5's recommendation. The offer-shape rule above is non-negotiable.

6a. Git Safety Baseline

Check whether the install tree is git-tracked:

git -C "${INSTALL_ROOT}" rev-parse --git-dir 2>/dev/null

If git-tracked: confirm the working tree is clean (git -C "${INSTALL_ROOT}" status --short). If dirty, surface: "Your install tree has uncommitted changes. Commit or stash them before applying the update, so the apply is revertible." Stop and wait.

If NOT git-tracked: offer a .bak baseline before applying. For each file to be applied, copy it to <path>.bak first. Note: "Your install tree is not git-tracked. Backing up files before applying (.bak convention matching the coordinator installer's). You can restore any file from its .bak if needed."

Git-tracking your ~/.claude is recommended for exactly this reason — better future reversibility. Consider git-initializing after this session.

6b. Apply the Named Files

Apply ONLY the files in the agreed apply set from Step 5 — no more, no less. Do not stage or touch anything outside the explicit list.

For each file in the apply set:

1. Copy the incoming version from the fetched clone into the install path:

   cp "${CLONE_DIR}/${REL_PATH}" "${INSTALL_ROOT}/${REL_PATH}"
   # Review: code-reviewer (A-F1) — drop plugins/ prefix; SOURCE_DIR is the clone ROOT in the OSS publish repo (no plugins/ subdir).
   

2. Add it to the explicit staging list.

6c. Commit (git-tracked installs only)

Use a scoped, labelled commit — never git add -A:

git add -- <path1> <path2> ... && \
git commit -m "coordinator-update: apply <incoming_ref> (cherry-pick <N> of <M> files)" \
  -- <path1> <path2> ...

The commit message names the incoming ref and the apply count. Revertible via git revert.

6d. Re-Stamp the Sentinel

After a successful apply, advance the install's version.txt sentinel to the ingested SHA. This ensures the NEXT /coordinator-update run has a correct baseline and does not re-offer already-applied changes.

Find install-sentinel-write in the install tree:

The entrypoint is a Python CLI, and the extensionless-vs-.py filename varies by install vintage — probe both names rather than pinning one:

SENTINEL_WRITER=""
for _cand in "${INSTALL_ROOT}/coordinator/bin/install-sentinel-write" \
             "${INSTALL_ROOT}/coordinator/bin/install-sentinel-write.py"; do
  [ -f "$_cand" ] && { SENTINEL_WRITER="$_cand"; break; }
done

Run it under the resolved interpreter — never bash, and never as a bareword .py:

if [ -n "${SENTINEL_WRITER}" ] \
   && "$PYTHON_BIN" "${SENTINEL_WRITER}" --path "${INSTALL_ROOT}" --source "${CLONE_DIR}"; then
  :
else
  # Fallback: write the sentinel directly (same format as install-sentinel-write)
  git -C "${CLONE_DIR}" rev-parse HEAD > "${INSTALL_ROOT}/version.txt"
fi

The re-stamp is the critical close: without it, the baseline drifts and future runs will re-classify already-applied files as divergent.

6e. Report Completion

Applied: <N> files from coordinator <incoming_ref>
Preserved: <M> consumer-modified files (your implementation shape kept)
Consumer-added: <K> files (never touched)
Sentinel: re-stamped to <SHA>
Revertible: yes — via git revert <commit-hash> (or .bak files if untracked)

Step 7: Discovery Surface Note

This verb is announced in the coordinator OSS getting-started documentation and the coordinator:install completion summary as the recommended path for future updates. It is NOT surfaced on the source-is-live (meta-repo) machine — it is installed and invokable only for OSS consumers who installed via the publish-repo coordinator:install flow.

If you are reading this as a developer on the coordinator meta-repo: this skill lives at plugins/coordinator/dist/oss-only-skills/coordinator-update/SKILL.md and is injected into the OSS publish tree by the 20-inject-oss-only-skills.sh percolate hook. It is intentionally absent from the meta-repo's skills/ tree.

Notes

• Missing sentinel (no version.txt): The helper degrades to baseline-free two-way mode (exit 2 from classifier, translated to "behind" by the helper). The first successful apply run re-stamps the sentinel. Subsequent runs have a proper baseline. This is expected behavior for users who installed before Chunk 1 landed the sentinel write.
• Bundled deep-research: If the coordinator install includes the bundled deep-research add-on (installed via the coordinator:install flow with the deep-research add-on enabled), it is part of the same plugin tree and is reconciled in the same pass. No separate /deep-research-update verb exists; the coordinator tree walk covers it.
• Standalone deep-research-claude repo (historical): The former standalone deep-research-claude repo is archived read-only — deep-research now ships bundled inside the coordinator plugin (see above). The 2026-05-29 plan scope decision to defer standalone-repo detection is moot: there is no live standalone repo left to detect.