vsync: Instructions file for Claude Code

vsync - AI Coding Tool Config Synchronizer

Single source of truth → Compile to multiple formats → Diff-based sync

Syncs Skills, MCP, Agents & Commands across Claude Code, Cursor, OpenCode, Codex.

---

🎯 Core Concept

NOT: File copy tool IS: Config compiler + diff executor

Source (Claude Code) → Normalize → Diff → Plan → Compile → Atomic Write → Update Manifest

---

🚨 Critical Rules (Read FIRST)

1. Follow Documentation Order

Before ANY work:
1. Read TASKS.md → Find current phase & task
2. Read docs/prd.md Section 2 → Config formats (MOST IMPORTANT!)
3. Follow TDD → Write tests FIRST

2. Config Format Precision (See PRD Section 2.2)

// ⚠️ CRITICAL: Each tool has DIFFERENT formats

// OpenCode
{ "mcp": { "type": "stdio", "environment": { "X": "{env:VAR}" } } }
//  ^^^      ^^^^^^                          ^^^^^^^^^^^
//  NOT mcpServers!  Required!               Curly braces!

// Claude Code
{ "mcpServers": { "env": { "X": "${VAR}" } } }
//              No type field    ^^^^^^^
//                              Dollar sign, no env: prefix

// Cursor
{ "mcpServers": { "env": { "X": "${env:VAR}" } } }
//              No type field    ^^^^^^^^^^^^
//                              Dollar sign WITH env: prefix

3. Environment Variables

// ❌ WRONG - Expands variables
const config = { env: { TOKEN: process.env.GITHUB_TOKEN } };

// ✅ CORRECT - Preserves syntax
const config = { env: { TOKEN: "${env:GITHUB_TOKEN}" } };

4. File Operations

// ❌ WRONG - Not crash-safe
await fs.writeFile(path, content);

// ✅ CORRECT - Atomic write
import { atomicWrite } from "./utils/atomic-write";
await atomicWrite(path, content);

5. Development Workflow

1. TASKS.md → Pick task
2. Write TEST first (TDD)
3. Implement code
4. pnpm test && pnpm typecheck && pnpm lint
5. Mark [x] in TASKS.md
6. Commit (Angular convention)

---

📚 Documentation Map

Document	When to Read	Contains
TASKS.md	Before every task	Current phase, task breakdown, progress
docs/prd.md	When implementing	Complete spec, config formats
docs/config.md	When needed	Project configuration values
.claude/commands/do-task.md	Shortcut	TDD workflow, patterns, validation
.claude/commands/create-task.md	Shortcut	Task creation templates