plugin: ship /sync-workflows skill to orchestrate plugin + gh-aw updates (not agent-team-specific)

[verkyyi]

Summary

Any Claude Code plugin that ships gh-aw workflows (this one ships agent-team; consumers often also install workflows from githubnext/agentics or other plugins) creates a two-layer update surface for end users, with no orchestrator:

Layer	Command	Scope
A. Plugin skills	claude plugin update <plugin>@<marketplace> (requires Claude Code restart)	/install-* skills, /discover-workflows, docs
B. Workflow sources	gh aw update per consumer repo	.github/workflows/*.md + .lock.yml

Nothing reminds the user to run both. Consequences observed on verkyyi/agentfolio on 2026-04-20:

• After 4 days, the install was 7 commits behind upstream — including commit c99b00f ("Fix critical end-user journey gaps surfaced in v0.2 audit") which fixes a silently-broken gh run list --workflow=<name> lookup in the reviewer agent plus install prerequisite checks.
• User had no signal updates existed. Discovery required manual diff against gh api repos/.../compare/<pin>...main.
• Running the two commands independently is error-prone: gh aw update silently advances SHA-pinned workflows to upstream HEAD. The "pin" in source: ...@<SHA> is decorative — gh aw update --help confirms: "If the ref is a commit SHA, it fetches the latest commit from the default branch."

Scope: not agent-team-specific

The problem applies to every plugin-installed workflow, not just agent-team. The consumer repo above has daily-repo-status.md from githubnext/agentics alongside the four agent-team files — both sets face the same orchestration gap. Solve once, generically.

Proposal

Ship a single skill, conservatively scoped: /sync-workflows.

1. Introspect: for each .md in .github/workflows/ with a source: line, resolve the owner/repo against ~/.claude/plugins/installed_plugins.json (known plugin) or mark as external (e.g. githubnext/agentics). Group files by source.
2. Preview: fetch upstream HEAD for each unique source repo and display a compact table:

   plugin: github-agent-runner (installed 0.2.0, 7 commits behind)
     catalog/agent-team/spec-agent.md        cb66d12 → ba1eb4e (no behavior change)
     catalog/agent-team/reviewer-agent.md    cb66d12 → ba1eb4e (+9 -1, gh run list lookup fix)
     catalog/agent-team/implementer-agent.md main    → ba1eb4e (was unpinned!)
   external: githubnext/agentics (5 commits behind)
     workflows/daily-repo-status.md          96b9d4c → f001a3b
   

3. Diff: for every updated file, print a unified diff against a tmp-dir copy so the user sees actual prompt/config changes, not just SHA bumps.
4. Apply (after confirm): run claude plugin update <plugin>@<marketplace> + gh aw update --create-pull-request in that order. One PR per source plugin so they can be reviewed independently.
5. Summarize: final message includes each PR URL, the Claude Code restart reminder (for layer A), and commit-message snippets between pinned SHA and new HEAD as a poor-man's changelog.

Why in this plugin

• This plugin already ships /install-* skills that know the install shape — the sync skill is the symmetric counterpart.
• Applies to any plugin that installs gh-aw workflows. github-agent-runner is a reasonable place to prototype; the skill can be generalized / adopted by the plugin system later.
• Companion to #58 (consumer-facing feedback-out skill): updates-in + feedback-out = closed consumer loop.

Acceptance

• Skill file ships under the plugin's skills/ directory.
• Works for all source repos (this plugin + external like githubnext/agentics), not only agent-team.
• Preview step does not mutate the repo.
• Apply step opens one PR per source plugin.
• Gracefully handles "Docker/crane not present locally" by falling back to --no-compile and calling out in the PR body that gh aw compile should run on a Docker-equipped host before merge (otherwise image digests degrade to tag-only refs).
• Documents the claude plugin update <name> restart requirement in the final summary.
• If the plugin itself isn't the only source of workflows in the repo (e.g. githubnext/agentics), the skill still runs correctly and groups the PRs by source.

[verkyyi]

Additional finding: claude plugin update is a no-op when only catalog/skills change

Tested on verkyyi/agentfolio today:

$ claude plugin update github-agent-runner@github-agent-runner
✔ github-agent-runner is already at the latest version (0.2.0).

…despite upstream having 7 commits beyond the pinned SHA cb66d12, including c99b00f which modifies skills/install-agent-team/SKILL.md. Layer A is passive — it only bumps when the .claude-plugin manifest version field changes, not when underlying skill/catalog files change.

Implications for the proposed /sync-workflows skill:

• Cannot rely on claude plugin update to bring skills to HEAD. Options:

  • Plugin maintainer bumps the manifest version on every skill/catalog change (process burden, version thrash).
  • The sync skill force-refreshes the plugin cache by git fetch --depth=1 origin main && git reset --hard origin/main inside ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/ — invasive but cache-local.
  • A new claude plugin update --force or --refresh-from-ref flag (would need Claude Code core change).

• Alternatively: document that end users should bump plugin manifest version in this repo on every meaningful skill/catalog change, as a convention. Slightly annoying but the simplest fix that works with today's Claude Code behavior.

[verkyyi]

Further finding: version-gated update path + cache/marketplace split

Verified the update mechanics on verkyyi/agentfolio:

• Marketplace clone at ~/.claude/plugins/marketplaces/github-agent-runner/ is already at HEAD 524090c — git-tracked, fetched in the background without user action.
• Its .claude-plugin/plugin.json still declares version: "0.2.0", matching the installed record.
• claude plugin update compares the version strings → match → "already at latest", even though 8 commits (including c99b00f) landed since.

So answering "would a version bump make claude plugin update work?" — yes, but with caveats worth designing around:

1. Maintainer discipline required

8 substantive commits (reviewer-agent fix, tier-2/3 test suites, audit patches) landed without a plugin.json bump. Reasonable not to bump on test-only commits, but consumers lose the update signal for mixed batches. A convention like "bump patch on any catalog/ or skills/ change" would restore it.

2. Mechanical quirk: installed cache can vanish

On my system right now, ~/.claude/plugins/cache/github-agent-runner/github-agent-runner/0.2.0/ doesn't exist — the directory is gone. But the plugin's skills still load in this session. installed_plugins.json still points to that dead path with gitCommitSha: cb66d12.

This suggests Claude Code actually loads skill content from the marketplace clone at runtime, making the cache/ materialization and the version field partly symbolic. If confirmed, consumers may be silently on HEAD for skills (reading from the marketplace clone) while installed_plugins.json reports a stale SHA.

3. Implication for the proposed /sync-workflows skill

The skill should not rely on version bumps or claude plugin update as the source of truth. The authoritative source is the marketplace clone:

git -C ~/.claude/plugins/marketplaces/<plugin>/ rev-parse HEAD

Compare that against the SHAs in .github/workflows/*.md source: lines to decide whether an update is needed, regardless of what version or installed_plugins.json say. If the skill wants to refresh the installed cache too, it can git -C ~/.claude/plugins/marketplaces/<plugin>/ fetch + reconcile rather than going through claude plugin update.