/sync-tools — Multi-CLI Distribution Generator

Generate distribution packages for OpenCode, Codex CLI, and Pi from the Claude Code plugin.

Input: $ARGUMENTS — optional CLI name (opencode, codex, pi) to sync one target. Empty = all targets.

Paths

Scope

Sync only these source payloads:

• claude-plugins/manifest-dev/ — core workflow skills.
• claude-plugins/manifest-dev-tools/ — tools skills.

Both plugins are skills-only — manifest-dev ships no agents or hooks on any target (the former functional agents are skills).

Never sync other plugins — anything under claude-plugins/ that is not one of the two payloads above, including PLUGIN_TEMPLATE. Never modify source files. Skip sync-tools skill from output (meta-tool). It lives in .claude/skills/, outside both synced payloads, so today this excludes nothing — it is stated deliberately, so that moving it under claude-plugins/ does not silently make the generator distribute itself.

Namespacing model is per-CLI (see each reference file):

• Plugin-native targets (Codex, OpenCode): the plugin is the distribution unit. Codex: two plugins (manifest-dev, manifest-dev-tools) each bundle their skills under original names. OpenCode: one plugin entry (dist/opencode/plugin/) registers the whole skills payload via skills.paths; skills keep bare names (native discovery is first-found-wins). No install-time suffixing, no component-namespaces.json, no installer. Plugin-qualified skill-reference handling (manifest-dev:<skill> — strip vs keep) is per-CLI: see each reference file.
• Package target (Pi): each component carries plugin ownership in component-namespaces.json (ownership metadata — Pi keeps package-scoped skill names, no suffixing). Regenerate it on every sync from the discovered source components; never hand-maintain it.

Per-CLI Processing

For each target CLI, read its reference file first. The reference file is the single source of truth for conversion rules — tool name mappings, frontmatter format, hook protocol, package shape, directory structure, and limitations. Do not duplicate conversion logic here; follow the reference.

Diff-first sync (preferred)

Each dist/{cli}/.sync-meta.json records the source commit that dist was last synced from:

{
  "source_commit": "<sha>",
  "source_path": "claude-plugins/manifest-dev",
  "source_paths": [
    "claude-plugins/manifest-dev",
    "claude-plugins/manifest-dev-tools"
  ],
  "synced_at": "<ISO 8601 UTC>"
}

On invocation, prefer a delta sync over a full re-sync:

1. Read dist/{cli}/.sync-meta.json. If missing, malformed, or the recorded SHA is unreachable from HEAD (e.g., rebased away, force-pushed branch), fall back to full sync for that CLI.
2. Force full sync if any of the following changed between recorded SHA and HEAD (these define the substitution rules — any change can affect every dist file):
   • .claude/skills/sync-tools/SKILL.md
   • .claude/skills/sync-tools/references/{cli}-cli.md
3. Otherwise compute git diff --name-status <recorded-sha>..HEAD -- claude-plugins/manifest-dev/ claude-plugins/manifest-dev-tools/ and process each entry:
   • Added / Modified: re-apply per-CLI substitutions, write to dist counterpart
   • Deleted: remove dist counterpart (and parent dir if now empty)
   • Renamed: handle as delete-old + add-new
4. Recompute README component tables and the CLI's context file (AGENTS.md) only if the set of skills changed (added/removed/renamed). Body-only edits don't require regenerating these.
   • OpenCode: if claude-plugins/manifest-dev/.claude-plugin/plugin.json's version changed between recorded SHA and HEAD, mirror it into dist/opencode/plugin/package.json per the reference file.
   • Codex: if either source plugin's .claude-plugin/plugin.json version changed between recorded SHA and HEAD, mirror it into that plugin's dist/codex/plugins/<plugin>/.codex-plugin/plugin.json per the reference file's version rule.
5. Package target (Pi) only: regenerate dist/pi/component-namespaces.json from the current dist component set and source ownership map. Skip entirely for plugin-native Codex and OpenCode — the plugin is the namespace there; generating namespace metadata would resurrect retired installer concepts.
6. After all writes succeed, overwrite dist/{cli}/.sync-meta.json with the new HEAD sha and a fresh synced_at UTC timestamp. Keep the file even when the diff was empty — the timestamp records "we checked".

The metadata is an optimization, not a correctness anchor. When in doubt — unreachable commit, ambiguous rename, mid-rebase repo state, suspicious dist drift — fall back to full sync rather than trusting the recorded SHA.

Per-component goals

README install section

The CLI-native install method from the reference file is the primary method: Codex plugin marketplace add, OpenCode repo clone + plugin config line (with the clone-or-pull update alias), Pi package manager from the repo root. Include other methods from the reference file as alternatives only when they actually work for that target.

Constraints

Progress Log

Write to /tmp/sync-tools-{timestamp}.md after each CLI: counts, warnings, what was generated. Read the full log before writing the final summary.

Output

Summary table after all CLIs processed: