Notes Sync Strategy Workflow
This Workflow provides Claude Code with step-by-step guidance for implementing Notes workspace sync.
When to use this workflow
- When implementing Notes workspace file system sync
- When creating offline-first note editing
- When implementing note-specific conflict resolution (text merge, versioning)
- When integrating AI synthesis with notes (per-note, batch)
- When creating sync status indicators for Notes workspace
Workflow Steps
Step 1: Notes File System Strategy (2-3 hours)
Agent: file-sync-specialist Input: Notes workspace requirements Output: File system strategy document
Acceptance Criteria:
- Desktop: FSA API with per-note file storage
- Mobile: IndexedDB with sync-to-FSA on desktop
- Note file format defined (Markdown, metadata, attachments)
- Folder structure defined (notebooks, tags, search index)
- Permission handling (read/write per notebook)
Step 2: Sync Concurrency Handling (3-4 hours)
Agent: file-sync-specialist Input: File system strategy Output: Concurrent sync implementation
Acceptance Criteria:
- File locking per note (granular locking)
- Conflict resolution for text notes (git-style merge)
- Version history (undo/redo support)
- Conflict UI (side-by-side diff, user choice)
- Automatic save (debounce to avoid conflicts)
Step 3: AI Synthesis Integration (4-6 hours)
Agent: workspace-architect Input: Sync implementation Output: AI integration with notes
Acceptance Criteria:
- Per-note AI synthesis (summarize, expand, rewrite)
- Batch AI synthesis (process entire notebook)
- AI-powered search (semantic search across notes)
- AI tool permissions (read, write with user consent)
- Progress indicators for AI operations
Step 4: Sync Status UX/UI (2-3 hours)
Agent: component-splitter Input: AI integration Output: Sync status UI components
Acceptance Criteria:
- Sync status indicator (syncing, synced, conflict, offline)
- Conflict resolution UI (side-by-side diff, accept button)
- AI operation progress (progress bar, cancel button)
- Offline mode indicator (editing while offline)
- Error states (sync failed, retry button)
Step 5: Validation & Testing (2-3 hours)
Agent: test-writer Input: Complete Notes sync implementation Output: Test suite + validation report
Acceptance Criteria:
- Unit tests for sync logic (CRUD, conflict resolution)
- Integration tests (sync + AI integration)
- E2E tests (critical user journeys)
- Test coverage ≥80%
- Zero data loss scenarios validated
Example Usage
"Implement Notes sync strategy using the notes-sync-strategy workflow"
Validation Commands
# TypeScript check
pnpm tsc --noEmit --incremental
# Test suite
pnpm test
# Notes-specific tests
pnpm test notes-*
# Sync validation
pnpm test sync-notes-*
Success Criteria
- ✅ Notes file system sync working (read, write, sync)
- ✅ Conflict resolution implemented (text merge, user choice)
- ✅ AI integration working (per-note, batch, search)
- ✅ Sync status indicators visible
- ✅ Offline-first support (IndexedDB queue)
- ✅ Zero data loss scenarios
- ✅ Test coverage ≥80%
- ✅ E2E tests passing
Artifacts
For detailed workflow documentation, refer to: Notes Sync Strategy Workflow
Converted and distributed by TomeVault — claim your Tome and manage your conversions.