Workspace Sync

Sync only the targets the user selects. Copy what's missing, merge instructions, never touch user-owned state, never overwrite what this workspace did not write. Pause where the user must act or decide (steps 2, 4–6).

Its inputs are workspace_TEMPLATE/ and adapters/, so it runs from the workspace repo and nowhere else. {workspace} = that clone (usually the cwd). Substitute the real path. ~ below is the home of the account the workspace is for; installing for another account → absolute paths and that account's rights (INSTALL.md → Prerequisites).

Fresh vs repair is not a mode — everything below is idempotent: skip any step whose result already holds (file correct, capability working), act on what's missing or broken, and say which steps you skipped. The once-only half of a first install — system info, the user interview, the optional rules — belongs to {workspace}/INSTALL.md: a target with unfilled User Info or System Info gets pointed back there, never interviewed here.

1. Select targets — ask

One multi-select question over the folders in adapters/ — no folder, no install; a harness without one goes through harness-onboard first. An unselected target is not touched. Skip any whose home doesn't exist unless the user wants it created — installing a harness the user doesn't have is noise, not service.

Read each selected target's adapters/{target}/MANIFEST.md whole: every harness fact below comes from it — {home} and {project-agent-dir}, the instruction file, how skills are reached, the agents format, the memory lever, how capabilities install, the verification levers. A fact it marks gap is reported missing, never worked around; one marked unknown gets asked rather than assumed.

~/.agents/skills/ is every target's skills home (repo scope: .agents/skills/), the Agent Skills standard. A target that doesn't read it natively gets links, never a second copy: a copy is what let the installed skills drift into two mangled versions.

2. Inventory & copy the shared template

• diff -r --strip-trailing-cr {workspace}/workspace_TEMPLATE against {home} (live copies may carry different line endings). Missing → a fresh copy, differing → a merge candidate; the inventory tells you whether this is a bootstrap or a repair. Report it before changing anything.
• Foreign files — anything at a path this sync writes that this workspace didn't write: on a first install every file already there (another setup's AGENTS.md or CLAUDE.md, skills, agents, config), on a repair a file the template doesn't know. Folders the harness writes itself (its manifest's Gotchas) are neither foreign nor touched. List them and offer a backup before the first write — a dated copy of each affected {home} and ~/.agents/ ({dir}.bak-{YYYYMMDD}) — then ask per item: keep beside, merge, or replace. Another workspace framework or doc layout among them → say plainly the two are not compatible (INSTALL.md → Compatibility) and let the user decide whether to go on.

• Copy everything missing, leaving existing files untouched (-n = no-clobber, --update=none on GNU coreutils 9.x, which warns about -n; run from {workspace} or use absolute paths). Almost everything goes to the shared home once, whatever targets were picked; only the instruction file and the agents are per target (agents below):

  cp -rn {workspace}/workspace_TEMPLATE/{skills,memory,domains,project_TEMPLATE} ~/.agents/
  cp -n {workspace}/workspace_TEMPLATE/AGENTS.md {home}/

  ~/.agents/DISPATCH-GUIDE.md is never written here: it describes one machine, so the user runs /dispatch-configurator for it. Absent = no dispatch configured, a valid state the workflows handle.

• Then link each skill folder into the directory a non-native target does read, per its manifest's Skills row — ln -s ~/.agents/skills/{name} {dir}/{name}, mklink /J on Windows. Per folder, never the skills/ directory itself, which the harness writes its own internals into. A real directory where a link belongs is the old duplicated install: diff it against the template, salvage what only it has, replace it.
• On a repair, -n is not enough — a skill whose template version changed keeps the old installed copy. Two kinds of file:
  • workspace-owned — ~/.agents/{skills,domains/domain_TEMPLATE,project_TEMPLATE}/, plus {home}'s agents directory and adapter/: overwrite from the template or the overlay (cp -r, no -n) once the diff is shown — a user edit in it → ask first, pointing at the backup; real customisations belong in the workspace repo. Deletions need doing explicitly — a skill or agent renamed, moved or dropped in the template leaves its old copy behind and keeps loading; check for a stale home too, not just a stale file. A name BUNDLES.md records is step 5's, never stale here.
  • user-owned — ~/.agents/memory/, ~/.agents/DISPATCH-GUIDE.md, ~/.agents/BUNDLES.md, the domain masters beside their template, {home}/projects/, and the target's own configuration files: leave them alone. A master is generated, not templated (domain-init rebuilds one on request).
• AGENTS.md is always a manual merge: take the template's structural changes (new sections, reworded rules), keep the user-filled ones — User Info, System Info, custom RULES, Available masters — the bundle rows are step 5's.
• Agents install flat from workspace_TEMPLATE/agents/ into the manifest's agents directory, whatever the source layout — one harness folds a subfolder into the ID, another keys off name:, so a nested copy answers to a different name in each. Where the manifest names a conversion, convert rather than skip and say you did, reading and writing UTF-8 explicitly — a default-codepage read turns every — into —. One file per agent ID; nothing else may live there — a stray file is scanned as an agent.
• New skill folders are usually discovered only next session — say so rather than claiming they're live.

3. Overlay the target's adapter

Its files already carry the paths they must land on, so this is a copy, not a transform:

cp -r  {workspace}/adapters/{target}/overlay/adapter {home}/   # workspace-owned, refreshed
cp -rn {workspace}/adapters/{target}/overlay/. {home}/         # the rest never lands over an existing file

That leaves {home}/adapter/ holding whatever the target needs later, in three folders named by what happens to them, plus files read in place:

A folder absent from a target's overlay means that target lacks that capability; report it as missing rather than working around it. A merge keeps keys already present and substitutes any {x}. Then finish the two things a copy cannot do:

• merge/* into {home}'s own config — capability entries and the instruction paths it loads.
• Point the target at ~/.agents/memory/MEMORY.md — an import in its instruction file, or an entry in its config's instructions list. Never inline a copy: it is a cache the next memory write strands, so a target with neither lever gets global memory reported as read-on-demand, not in context instead (maintain-memory owns the rule).
• Instruction budget — where the manifest names one, check the installed instruction files against it and raise the limit rather than let the tail vanish silently.

An instruction file already where the shim belongs stays: show it, then add the shim's imports to it or move its rules into AGENTS.md — the user's call, never a silent replace.

4. Install the required capabilities

Only the ones not already working, and only where the target can host them. Memory is native Markdown, no plugin — step 2 seeded ~/.agents/memory/MEMORY.md and step 3 pointed the target at it or declared it missing. See maintain-memory.

• codegraph — an MCP server, https://github.com/colbymchenry/codegraph. The CLI from its standalone bundle (install.sh / install.ps1: ~/.codegraph/ plus a link in ~/.local/bin, no shell-profile edits) — not npx, which an nvm-managed Node keeps off a non-login PATH. Then register codegraph serve --mcp per the manifest's MCP row; codegraph install --print-config {target} shows the entry without writing. Never codegraph install itself: beside the entry it writes a per-prompt hook and an instruction block — always-loaded context, step 5's rule. codegraph upgrade runs it too, on every harness it finds, selected or not, and adds alwaysLoad to the entry → snapshot those configs first, then strip hook, block and alwaysLoad everywhere again. Telemetry is on by default → ask; codegraph telemetry off.
• context7 — the ctx7 CLI with its skill, never the plugin or MCP server: npx ctx7 setup --cli -y plus the target's flag (npx ctx7 setup --help lists them). Its skill lands in the harness's own skills directory → move it to ~/.agents/skills/, linked per step 2; a rule file it writes beside it (always loaded) → delete it, the AGENTS.md row already says when. Leftover context7 plugin, MCP entry or MCP-flavoured skill (context7-mcp) → disable or delete it. Behind a sandbox proxy see the manifest's Gotchas.

CLI over MCP: a capability with a CLI installs as that CLI; an MCP server only where none exists (codegraph). Each through the mechanism the manifest's Plugins and MCP rows name, in the shape overlay/adapter/merge/ carries where it has one; a row still unknown → ask rather than guess. A marketplace the row names may not be registered on a fresh install — add it first.

GitHub access (optional — ask, don't assume)

Needed by release and any project on the PR flow; skip for a user working purely locally. The gh CLI only — winget install --id GitHub.cli / brew install gh / per distro, never the github plugin or MCP server (a leftover one → disable it). Then the user runs gh auth login: interactive and browser-based, so pause here. A target whose sandbox cannot reach the OS keyring (manifest Gotchas) needs gh auth login --insecure-storage — say plainly the token then sits in gh's hosts.yml in clear text.

5. Skill bundles (optional)

Third-party skill sets, peers of the workspace: no workspace skill ever invokes one, so any can be dropped. Catalog: references/bundles.md beside this skill. The user's pick: ~/.agents/BUNDLES.md, user-owned — | id | source | kind | ref | installed |, no rows = declined.

• Pick — manifest missing, or the user asks to change it → one multi-select question from the catalog rows (id — pick when), "Other" taking any repo URL; write the manifest. Otherwise take it as it stands. Pinned: an entry installs at its recorded ref; moving it to the source's current HEAD is an update — show the upstream diff since ref and install only on the user's OK.
• Fetch the source shallow into scratch and install only the row's take: skill folders flat into ~/.agents/skills/, linked like step 2's; agents flat per step 2's conversion rules; a plugin row through the target's plugin mechanism, reported missing on a target without one. Never hooks, commands, rules, plugin manifests, or a skill whose description loads it every session — always-loaded context overrides the workflow gate; the one exception is a plugin row whose take declares its own, named in the pick question. An "Other" source gets the same filter, its take agreed with the user first. Never run a source's own script (installer, converter) before showing it to the user and getting their OK.
• Collisions — a name a workspace skill or agent, another entry or a harness built-in command already holds → ask: skip, or install as {id}-{name}. Never overwrite.
• Needs → install with the user's OK; declined → report the entry as installed but inert. Per-project setup stays with the bundle's entry skill, never run here.
• Record the fetched ref and every installed name. An entry dropped from the manifest → delete exactly its recorded names, links included.
• Gate rows — each workflow entry gets | {entry} | {pick when} ({id} bundle) | at the {bundle workflows} row of each target's AGENTS.md; none → drop that row.

6. Restart — pause

Only if step 4 or 5 changed anything. Ask the user to restart each affected harness (and the terminal), then resume; stop here until they confirm. A new environment variable needs the restart too. Nothing changed → say so and skip.

7. Verify each target independently

Per selected target, confirm each capability is actually working, not merely present — never that a scope is loaded because its file exists: global instructions load, skills are discoverable this session, agents dispatch where the target supports them, MCP/plugin entry points run (no failing hook, no error on invoke), memory resolves or is reported as stored and manual, and domains stay inert until project-init projects one.

Reach for the manifest's Verification levers before spending a run — they answer this without a model call. Only agent dispatch still needs a real run, proven by the child's own record per the manifest's Dispatch row, never the parent's report.

Report each target as passed · skipped · failed. For any failure propose a brief troubleshooting plan and get the user's OK before any tool calls. Two traps behind a capability that is "installed" yet silently exposes nothing: an orphaned or dependency-incomplete cache directory shadowing the working one, and a remote MCP server whose credential is missing — an enabled flag in the config says nothing about either. Proof for the CLIs, run through the target's own shell so its sandbox applies: gh api user --jq .login returns the account, npx ctx7 library react "hooks" returns library IDs.

8. Done — pause for review

Summarise per target what was synced or changed. A first install continues at INSTALL.md's personalisation step; otherwise ask the user to review before further use.