/sync-clis

Two complementary mechanisms exist. Run them in this order.

A. Central cross-CLI synchronization

Entry points:

• ~/.grok/skills/sync-clis/launch.sh
• ~/.grok/scripts/run-sync-clis.sh
• python3 ~/.grok/scripts/sync-clis.py --verbose

Authoritative configuration:

• Manifest and artifact catalog: ~/.grok/sync-targets.json
• Portable skill source: ~/.grok/skills
• Task persona source: ~/.grok/bundled/personas
• Role source: ~/.grok/bundled/roles
• ABI Mega seed source: ~/dev/active/plugins/abi-mega/skills

The catalog distinguishes four classes:

1. portableSkills: user-maintained canonical skills synchronized to declared targets.
2. taskAgents: central personas and roles rendered through runtime-native adapters.
3. externalLinkedSkills: vendor/plugin-owned symlinks recorded for inventory but not mirrored as canonical content.
4. repositorySkillRoots: repository-specific skills that remain under repository authority.

Unmatched target files are preserved. The driver updates only names explicitly listed in the catalog. Supporting references/, scripts/, examples/, and assets/ trees are synchronized as a source projection; destination-only entries are not deleted.

Runtime adapters

• Codex task agents: ~/.codex/agents/*.toml
• Claude Code subagents: ~/.claude/agents/*.md
• OpenCode subagents: ~/.config/opencode/agents/*.md
• OpenCode skills: ~/.config/opencode/skills/<name>/SKILL.md
• OpenCode commands: both the documented commands/*.md surface and the installed version's command/*.md compatibility surface

The OpenCode command renderer writes one frontmatter block: the canonical SKILL.md content followed by one source marker. Existing managed wrappers are compared and repaired, not merely seeded when absent.

Dry-run contract

--dry-run performs the same byte and projected-tree comparisons as an apply run without writing managed targets. It reports missing and divergent skills, agents, commands, supporting files, and markers.

A successful apply must be followed by a second full run. Acceptance is:

Done. 0 actions/changes.

A zero-change run is meaningful only after the driver and manifest validate and all requested targets were included.

B. ABI in-repository mirror synchronization

Run after the central pass:

/Users/donald/sources/repos/abi/.agents/skills/sync-clis/launch.sh [--dry-run]

This mechanism mirrors ABI's repository-authoritative skills into its .claude/skills/ and .grok/ surfaces. The central driver does not replace this in-repository mirror step.

Before applying it:

1. Inspect git -C /Users/donald/sources/repos/abi status --short --branch.
2. Preserve unrelated dirty work.
3. Run the launcher's dry-run and review every named write.
4. Apply.
5. Confirm the resulting ABI diff is limited to intended mirror changes.
6. Run it again and require no further writes.

Safety invariants

• Never edit a synchronized target copy when the canonical central source is the intended authority.
• Never treat ~/.codex/memories as a task-agent destination.
• Never copy external/vendor symlinks into the portable catalog without first choosing and preserving their real upstream authority.
• Never delete unmatched runtime-native skills, agents, commands, or plugins.
• Never delete or archive ~/dev/active/plugins/abi-mega; it is a live source.
• ABI's repo-adapted ABI Mega skills are seed-only and are not overwritten.
• The ABI repository is a stable Rust 1.99.1 workspace; do not reintroduce removed Zig-era paths or commands.
• Central synchronization may intentionally dirty tracked ABI skill files when canonical portable content changed. Inspect the diff and run repository gates before committing.
• Preserve recovery evidence before catalog repair or any destructive retirement.

Verification checklist

python3 -c 'from pathlib import Path; compile(Path.home().joinpath(".grok/scripts/sync-clis.py").read_text(), "sync-clis.py", "exec")'
python3 -m json.tool ~/.grok/sync-targets.json >/dev/null
python3 ~/.grok/scripts/sync-clis.py --dry-run --verbose
~/.grok/skills/sync-clis/launch.sh
/Users/donald/sources/repos/abi/.agents/skills/sync-clis/launch.sh
~/.grok/skills/sync-clis/launch.sh

Then verify:

• the final central run reports 0 actions/changes;

• every managed direct skill copy matches its source SKILL.md;

• OpenCode's resolved agent list includes the managed task agents;

• Codex agent TOML parses;

• Claude and OpenCode Markdown agents have exactly one frontmatter block;

• ABI's final diff is reviewed and its matching gate is run before closeout.

• Task-agent tool/model control lives in the central TOML, not in ~/.claude/agents/*.md (added 2026-09-05). The claude-markdown adapter in sync-clis.py reads two optional keys from ~/.grok/bundled/{roles,personas}/<agent>.toml: claude_tools = ["Read", "Grep", ...] renders a tools: frontmatter line, and claude_model = "haiku" overrides the default model: inherit. Editing the synced Markdown directly is reverted on the next SessionEnd sync. Codex/OpenCode adapters ignore both keys. Insert new top-level keys in a persona file BEFORE its first [[inputs]] table, or tomllib fails and the sync aborts mid-target (agents already rendered stay written; the rest do not).

Tool maintenance and update evidence

For a requested full tooling update, inventory executable paths and installation managers first. Use each installed CLI's documented updater and marketplace commands; preserve enabled/disabled state and update installed plugins only. Codex plugin add can re-enable an already installed plugin. Record disabled plugin IDs before refreshing installed caches, restore their prior state, and compare the final inventory. Refresh external skills through their recorded upstream installer. Never replace local canonical skills with an upstream copy or hand-edit vendor cache files.

Complete Homebrew dependency upgrades before invoking Node-based updates: during an upgrade, the old Node binary can temporarily reference a removed dependency dylib. Retry after the Node upgrade completes; do not create compatibility dylib symlinks. Preserve pinned toolchains and existing version/channel choices.

Before editing shared task-agent guidance, back up the current source bytes. Change central TOML instructions, then render native Markdown/TOML with this driver. Verify parseability, source parity, the sync regression suite, and a second complete run reporting zero changes. Native unmanaged agents require separate inspection; generated mirrors are not independent sources.

Report update exit codes, final CLI versions, remaining outdated packages, and restart requirements separately. Package updates and better instructions do not prove a model speed or quality improvement; that claim needs a measured benchmark.

Temporarily retired targets

Hermes and OpenClaw were removed at the user's request on 2026-10-08. Their entries are absent from the live sync manifest; do not seed their home directories or reinstall them unless the user asks. Their prior target configuration is preserved with the recoverable retirement artifacts.