vibe-sync

The VibeSync skill — the rulebook and manual that AI coding agents follow to sync projects through VibeSync: what the product is, every tool it exposes, and the safety rules that must never be violated (init-first setup with the directory conversation, shared-memory documentation of unconventional changes, memory reporting after every push/pull, one-time self-signing in user.md, vibe_chat handoffs/delegation with user permission, status check at session start, offer pushes at natural pauses, never push silently, explain conflicts before resolving, auto-complete key wraps, never sync .env/node_modules/build output, vibe_rollback as the safety net, pass plain-English summaries through).

The machinery is the vibe-sync-mcp MCP server (npm package vibe-sync-mcp). This package is just the skill file + installer.

Install

npx vibe-sync-skill@latest install

This copies SKILL.md to ~/.claude/skills/vibe-sync/SKILL.md (Claude Code) and prints the equivalent locations for Cursor, Windsurf, and Qwen Code.

What the skill teaches

• Init first, always: vibe_init creates the repo + shared memory space (.vibesync/memory/), then vibe_link creates or joins a project. No linking or memory work happens before init.
• The directory conversation: before initializing/joining from an invite link, warn the user which folder will be used, report its contents, explain the new-folder rule (open a new folder and reopen the agent chat to switch), and only proceed on explicit confirmation.
• Shared agent memory: memory.md (decisions + why, read by every agent), user.md (one-time agent self-signatures — the roster), chat.md (agent-to-agent chat across push/pull), session.md (local-only scratch). Memory files sync with the code; keys, checkpoints, and the project marker stay local.
• Document unconventional changes in memory.md so a teammate's agent picks up the context without burning tokens — and report memory findings to the user after every push and pull.
• Chat & delegation: use vibe_chat for notes, handoffs, and questions; tag @agent-name or @human; recommend delegation proactively but never delegate without the user's explicit OK; route subjective judgment calls to humans.
• Session start: silently call vibe_status, summarize changes in one or two sentences, then read memory and surface anything relevant.
• Key wraps: pending key-wrap requests are completed automatically inside vibe_status — report them in one line.
• Pushing: offer to push at natural pauses, never silently; write changelogs a human would want to read.
• Conflicts: explain both sides in plain English before proposing a resolution via vibe_resolve; never resolve silently; binary conflicts → ask the user to pick.
• Never sync .env, node_modules, .git, dist, build, .next/, or .vibesync/ repo state — EXCEPT the shared memory files under .vibesync/memory/.
• Safety net: mention vibe_rollback whenever a merge or rollback seems risky.
• Output: pass tools' plain-English summaries through instead of reformatting.

Development

npm run test -w packages/skill   # node --test test/

The installer accepts a VIBESYNC_SKILL_DIR env var (or an explicit target dir when called as a module) so tests and unusual setups can redirect where the skill lands.