# Stack-Plugin Sync (Step 3c)

Stack skills are distributed as versioned plugins in the `mmerterden/multi-agent-plugins` marketplace. The pipeline's `pipeline/skills/shared/external/` is the **single authoring source**; the marketplace is a derived, versioned publish artifact. This step rebuilds it and publishes only when something changed.

**Source of truth:** author/vendor knowledge skills in `pipeline/skills/shared/external/` (the pipeline's own phases also consume them). The plugins' authored lifecycle skills (`index` / `reference` / `workflow` / `tools`) live in the plugins repo and are never touched by sync.

**Flow:**

```bash
PLUGINS_REPO="$HOME/multi-agent-plugins"
[ ! -d "$PLUGINS_REPO/.git" ] && gh repo clone mmerterden/multi-agent-plugins "$PLUGINS_REPO"
cd "$PLUGINS_REPO" && git pull origin main

# 1. Preview what would change (routing + version bumps), no writes:
node "$HOME/multi-agent-pipeline/pipeline/scripts/build-stack-plugins.mjs" --dry-run

# 2. Apply: rebuild each stack plugin's knowledge/ from shared/external,
#    regenerate plugin.json skills[], bump the patch version of any plugin
#    whose skill set changed. Cross-stack skills -> ai-common-toolkit;
#    Apple/Xcode-only skills -> iOS plugin only.
node "$HOME/multi-agent-pipeline/pipeline/scripts/build-stack-plugins.mjs"
```

**Version-based management:** the generator bumps a plugin's `version` (patch) only when its skill set actually changed. Idempotent - a no-op run bumps nothing. Consumers pick up new versions via `/multi-agent:update` (which refreshes the catalog with `claude plugin marketplace update multi-agent-plugins`, then runs `claude plugin update` for each installed plugin).

**Help + README freshness (mandatory when the generator reported any change):**

1. Every plugin ships a `tools/help` skill that renders its catalog LIVE from `plugin.json`, so it needs no per-skill edits - but verify each changed plugin still registers it (`grep -c "./skills/tools/help" plugins/<name>/.claude-plugin/plugin.json` = 1) and that a new plugin gets one before publish.
2. Plugin README tables sync through `python3 tools/bump.py <plugin> --set <version>`; run `python3 tools/bump.py --check` and treat DRIFT as a blocker.
3. `python3 tools/validate.py` must be clean (it also enforces the CHANGELOG heading for every bumped version - write the entry, do not backdate).
4. When the pipeline's command surface changed in the same sync (new/renamed `/multi-agent:*` commands), confirm `commands/multi-agent/help/SKILL.md` and both pipeline READMEs (`README.md`, `README.tr.md`) were updated in Step 3 before pushing here.

**Publish (only if the generator reported bumps):**

```bash
cd "$PLUGINS_REPO"
if ! git diff --quiet; then
  # Identity: routed for {owner} (platformIdentityRouting). Never a literal: this file
  # installs everywhere and would misattribute a downstream user's commits.
  git config user.name  "{identity.name}"
  git config user.email "{identity.email}"
  git add -A
  git commit -m "chore: rebuild stack plugins from pipeline shared/external"
  gh auth switch --user {owner} 2>/dev/null || true
  git push origin main
fi
```

Never author skills directly in the plugins repo's `knowledge/` - they will be overwritten on the next rebuild. Author in `shared/external`, then run this step.

---