Skip to content

CLAUDE.md

Latest commit

 

History

History
275 lines (198 loc) · 6.95 KB

CLAUDE.md

File metadata and controls

275 lines (198 loc) · 6.95 KB

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

PRD Section Quick Lookup:

  • Section 2 (Config Formats) ← READ THIS BEFORE ADAPTERS
  • Section 4 (CLI Commands) ← Before CLI work
  • Section 5 (Security) ← Before security work
  • Section 6 (Adapter Architecture) ← Before adapter design
  • Section 7 (Diff & Plan) ← Before diff/plan work
  • Section 8 (MVP Roadmap) ← For scope validation

🚀 Quick Start Commands

Execute tasks:

/do-task next         # Start next task
/do-task Phase 1.1    # Specific task

Create tasks:

/create-task feature Add feature name
/create-task bugfix Fix issue description

These commands auto-read TASKS.md, PRD, and guide TDD workflow.

🎯 Current Scope (See TASKS.md for phases)

MVP (v1.0) - COMPLETE:

  • ✅ Skills + MCP sync
  • ✅ Claude Code (source) → Cursor, OpenCode (targets)
  • ✅ Safe/Prune modes
  • ✅ Project-level config
  • ✅ Atomic writes

v1.1 - COMPLETE:

  • ✅ Agents + Commands sync
  • ✅ Codex adapter
  • ✅ User-level config

v1.2 - IN PROGRESS:

  • 🟡 Performance optimization
  • 🟡 Watch mode
  • 🟡 GitHub Action integration

⚠️ Common Mistakes (Full list in PRD Section 2)

❌ Wrong ✅ Correct
OpenCode: mcpServers mcp
OpenCode: no type type: "local/remote"
OpenCode: ${env:VAR} {env:VAR}
Claude Code: ${env:VAR} ${VAR}
Cursor: ${VAR} (uppercase) ${env:VAR}
fs.writeFile() atomicWrite()
Implement first Test first (TDD)

🔄 Automation Preferences

DO automatically:

  • Run tests/typecheck/lint
  • Update TASKS.md progress
  • Create commits (Angular convention)
  • Install listed dependencies

ASK before:

  • Adding unlisted dependencies
  • Changing PRD specifications
  • Skipping phases
  • Force operations

📦 Tech Stack & Project Structure

Architecture: pnpm monorepo

vsync/                  # Project root
├── pnpm-workspace.yaml     # Workspace config (root level)
├── cli/                    # CLI workspace package
│   ├── package.json        # CLI dependencies
│   ├── tsconfig.json       # TypeScript config
│   ├── src/                # CLI source code
│   │   ├── cli/            # CLI commands
│   │   ├── core/           # Core logic
│   │   ├── adapters/       # Tool adapters
│   │   ├── types/          # TypeScript types
│   │   ├── utils/          # Utilities
│   │   └── index.ts        # Entry point
│   └── test/               # Tests (mirrors src/)
└── (future: website/, packages/...)

Tech Stack:

  • TypeScript 5 (strict mode)
  • pnpm monorepo (CLI workspace in cli/)
  • Commander.js + Inquirer.js (CLI)
  • Vitest + mock-fs (Testing)
  • jsonc-parser (JSONC support)
  • gray-matter (Frontmatter)

✅ Definition of Done

Task complete:

  • Tests written FIRST (TDD)
  • Tests pass + typecheck + lint
  • Config formats match PRD exactly
  • Env vars NOT expanded
  • Atomic writes used
  • Task marked [x] in TASKS.md

Phase complete:

  • All tasks [x]
  • Phase status → 🟢
  • Deliverables achieved

🎓 First-Time Setup

New AI assistant? Read this order:

  1. This file (CLAUDE.md) - 5 min
  2. TASKS.md - Current phase - 5 min
  3. PRD Section 2 (Config Formats) - 10 min ← CRITICAL
  4. PRD other sections - As needed

Then: Use /do-task next to start.

📁 Working Directory

⚠️ CRITICAL: pnpm monorepo structure

  • pnpm-workspace.yaml is at project root (same level as cli/)
  • CLI code is in cli/ workspace
  • Run pnpm commands from cli/ directory
  • Source code: cli/src/
  • Tests: cli/test/
# Project structure
vsync/
├── pnpm-workspace.yaml    # Root level
└── cli/                   # Work here!
    ├── package.json
    ├── src/
    └── test/

# Commands (run from cli/)
cd cli                     # Enter CLI workspace
pnpm install               # Install dependencies
pnpm test                  # Run tests
pnpm build                 # Build CLI

Last Updated: 2026-01-24