File Sync Specialist

This Skill provides Claude Code with specific guidance for implementing robust file sync strategies.

When to use this skill

• •When consolidating fragmented sync implementations (5 implementations → 1 unified)
• •When implementing conflict resolution strategies (last-write-wins, merge, user-choice)
• •When handling offline-first scenarios (IndexedDB queue, sync on reconnect)
• •When creating unified sync status indicators across workspaces
• •When optimizing sync performance (batching, throttling, debounce)
• •When implementing sync error recovery (retry logic, rollback)

Instructions

For detailed implementation guidance, refer to: File Sync Specialist Agent

Workflow Integration

This skill integrates with multiple workflows:

• •notes-sync-strategy: Notes workspace sync implementation
• •knowledge-sync-strategy: Knowledge workspace sync implementation
• •workspace-file-system-e2e: General sync strategy validation

Current State Analysis

Sync Strategy Fragmentation

• •5 implementations with partial duplication
• •2,858 total lines → potential 47% reduction through consolidation
• •Implementations:
  • •src/lib/filesync/notes-file-sync-service.ts (659 lines)
  • •src/lib/filesync/knowledge-file-sync-service.ts (TODO)
  • •src/lib/filesync/ide-file-sync-service.ts (TODO)
  • •Various sync utilities across workspaces

Consolidation Strategy

Phase 1: Unified Sync Service (Foundation)

• •Create src/lib/filesync/unified-sync-service.ts
• •Implement core sync logic (CRUD, batching, conflict resolution)
• •Support multiple backends (FSA, IndexedDB, WebContainer)
• •Unified status reporting across all workspaces

Phase 2: Workspace-Specific Adapters

• •notes-sync-adapter.ts: Notes workspace specific logic
• •knowledge-sync-adapter.ts: Knowledge workspace + RAG integration
• •ide-sync-adapter.ts: IDE workspace + WebContainer integration

Phase 3: Conflict Resolution

• •Last-Write-Wins: For non-conflicting changes
• •Merge Strategy: For text files (git-style merge)
• •User Choice: For conflicting changes (UI prompt)
• •Automatic Resolution: For structured data (merge by field)

Quality Standards

Sync Reliability

• •✅ Zero data loss scenarios
• •✅ Offline-first support (IndexedDB queue)
• •✅ Automatic retry with exponential backoff
• •✅ Conflict resolution with user prompts

Performance

• •✅ Batch operations (reduce network calls)
• •✅ Throttling (avoid overwhelming the system)
• •✅ Debouncing (coalesce rapid changes)
• •✅ Progress indicators (user feedback)

Example Usage

"Consolidate sync strategies using the notes-sync-strategy workflow"

This will:

1. •Analyze current sync implementations (identify duplication)
2. •Create unified sync service (core logic)
3. •Implement Notes workspace adapter (specific logic)
4. •Add conflict resolution strategies (merge, user-choice)
5. •Create sync status indicators (UI components)
6. •Validate with E2E testing

Validation Commands

# TypeScript check
pnpm tsc --noEmit --incremental

# Test suite
pnpm test

# Sync-specific tests
pnpm test sync-*

# Measure code reduction
wc -l src/lib/filesync/*.ts | tail -1

Success Criteria

• •✅ Unified sync service created (47% code reduction)
• •✅ All workspace adapters working (Notes, Knowledge, IDE)
• •✅ Conflict resolution implemented (merge, user-choice)
• •✅ Zero data loss scenarios validated
• •✅ Sync status indicators visible
• •✅ Offline-first support working
• •✅ E2E tests passing