ai: add sync-lexicons skill

Author: aspiers

.claude/skills/sync-lexicons/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: sync-lexicons
+description: Sync Hypercerts SDK with latest lexicons from the develop branch. Use when updating SDK dependencies,
+  comparing lexicon versions, or reconciling changes between SDK and lexicons repository.
+
+  **Always check the CHANGELOG.md first** - Run `cat
+  packages/sdk-core/node_modules/@hypercerts-org/lexicon/CHANGELOG.md` to see exactly what changed between versions.
+---
+
+# Sync Lexicons Skill
+
+Compare the Hypercerts lexicons repository changes between the version the SDK currently depends on and the latest
+develop branch, then update SDK files accordingly.
+
+## When to Use This Skill
+
+- When updating `@hypercerts-org/lexicon` dependency in SDK
+- When users ask "what changed in lexicons since the SDK version?"
+- Before SDK releases to ensure lexicon alignment
+- When reconciling SDK imports with new lexicons
+
+## How It Works
+
+1. **Extract current dependency**: Read SDK's `packages/sdk-core/package.json` for current `@hypercerts-org/lexicon`
+   version
+2. **Fetch develop branch**: Get latest from lexicons repo develop branch
+3. **Compare versions**: Determine semantic version difference
+4. **Generate git diff**: Show changes between the two versions in lexicons repo
+5. **Update SDK files**: Modify SDK source files to reflect new lexicon imports/exports
+
+## Key Paths
+
+- **SDK root**: `.` (current working directory)
+- **SDK package.json**: `packages/sdk-core/package.json`
+- **SDK lexicons source**: `packages/sdk-core/src/lexicons.ts`
+- **Lexicons repo**: `../hypercerts-lexicon`
+
+## Usage
+
+### Step 1: Check version of current dependency
+
+```bash
+OLD_VERSION=$(jq -r '.dependencies["@hypercerts-org/lexicon"]' packages/sdk-core/package.json)
+echo "Current SDK dependency: @hypercerts-org/lexicon@v${OLD_VERSION}"
+```
+
+### Step 2: Fetch latest develop and tags
+
+```bash
+git -C ../hypercerts-lexicon fetch --tags origin
+```
+
+### Step 3: Update SDK package.json to exact latest version
+
+```bash
+# Get the latest version tag from the lexicons repo
+NEW_VERSION=$(git -C ../hypercerts-lexicon tag --list 'v*' --sort=-version:refname | head -1 | sed 's/^v//')
+echo "Latest lexicon version: ${NEW_VERSION}"
+
+# Update to exact version (no ^ operator) using pnpm add with --save-exact
+pnpm --filter @hypercerts-org/sdk-core add --save-exact @hypercerts-org/lexicon@${NEW_VERSION}
+```
+
+### Step 4: Check CHANGELOG.md
+
+After updating the dependency, read the lexicons CHANGELOG to understand what changed:
+
+```bash
+cat packages/sdk-core/node_modules/@hypercerts-org/lexicon/CHANGELOG.md
+```
+
+Look for:
+
+- Breaking changes that require SDK updates
+- Renamed exports (e.g., `HELPER_WORK_SCOPE_VERSION_*` → `WORK_SCOPE_VERSION_*`)
+- New lexicons added
+- Deprecated/removed constants
+
+### Step 5: Compare versions and diff
+
+```bash
+# Extract the NEW version (after Step 3 update)
+NEW_VERSION=$(jq -r '.dependencies["@hypercerts-org/lexicon"]' packages/sdk-core/package.json)
+
+echo "Comparing ${OLD_VERSION} (previous) to ${NEW_VERSION} (updated)"
+
+# Show files that changed between old and new versions
+git -C ../hypercerts-lexicon diff ${OLD_VERSION}..${NEW_VERSION} --stat
+
+# Show detailed changes in lexicon JSON files
+git -C ../hypercerts-lexicon diff ${OLD_VERSION}..${NEW_VERSION} -- '*.json' | head -200
+```
+
+### Step 6: Create plan and get user approval
+
+**CRITICAL: Do NOT proceed beyond this step without explicit user approval.**
+
+Based on the CHANGELOG and git diff analysis, create a detailed plan of proposed changes:
+
+1. List all lexicons to be added (with import statements)
+2. List all lexicons to be modified (with specific changes)
+3. List all lexicons to be removed/deprecated
+4. List all constant renames or updates needed
+5. Identify test files that need updates
+6. Specify the changeset bump type (patch/minor/major) with justification
+
+Present this plan to the user and ask:
+
+> "I've analyzed the changes between v{OLD_VERSION} and v{NEW_VERSION}. Here's my proposed plan:
+>
+> [detailed plan]
+>
+> Does this plan look correct? Should I proceed with these changes?"
+
+**Wait for explicit user confirmation before proceeding to Step 7.**
+
+### Step 7: Sync SDK imports
+
+Manually update `packages/sdk-core/src/lexicons.ts` based on the changes identified:
+
+1. Add new lexicon imports from `@hypercerts-org/lexicon`
+2. Update export arrays with new entries
+3. Add new NSID entries to collection constants
+4. Remove deprecated lexicons if applicable
+
+### Step 8: Update or add tests
+
+Review and update tests to cover lexicon changes:
+
+```bash
+# Check existing lexicon tests
+ls packages/sdk-core/tests/lexicons/
+
+# Run existing tests to see if they still pass
+pnpm --filter @hypercerts-org/sdk-core test
+```
+
+For new lexicons:
+
+1. Add test cases in `packages/sdk-core/tests/lexicons/` or relevant service tests
+2. Verify new imports are registered correctly
+3. Test validation with new schemas
+
+For modified lexicons:
+
+1. Update existing test fixtures if schemas changed
+2. Add tests for new fields or validation rules
+3. Ensure backward compatibility tests still pass
+
+For removed/deprecated lexicons:
+
+1. Update tests to handle deprecation gracefully
+2. Add migration tests if needed
+
+### Step 9: Run full test suite
+
+Ensure all tests pass before committing:
+
+```bash
+# Run all tests
+pnpm test
+
+# Check coverage if needed
+pnpm test:coverage
+```
+
+Fix any failing tests before proceeding.
+
+### Step 10: Create a changeset
+
+Use the `writing-changesets` skill to document the lexicon sync:
+
+```bash
+# Load the skill for guidance
+skill writing-changesets
+```
+
+The changeset should:
+
+1. Include `@hypercerts-org/sdk-core` (always affected)
+2. Include `@hypercerts-org/sdk-react` if React hooks are affected
+3. Use appropriate bump type:
+   - **patch**: Bug fixes, internal updates with no API changes
+   - **minor**: New lexicons added, backward-compatible changes
+   - **major**: Breaking changes (renamed exports, removed lexicons, schema changes affecting types)
+4. Reference the lexicon version being synced
+5. List key changes from the CHANGELOG
+
+Example changeset content:
+
+```markdown
+---
+"@hypercerts-org/sdk-core": minor
+---
+
+Sync with @hypercerts-org/lexicon@X.Y.Z
+
+- Add new org.hypercerts.project.\* lexicons
+- Update WORK_SCOPE_VERSION constants (renamed from HELPER_WORK_SCOPE_VERSION)
+- Add support for project attachments
+```
+
+## Common Anti-Patterns to Avoid
+
+### Don't Hardcode Lexicon Names
+
+- ❌ `if (lexicon === "HYPERCERTS_LEXICONS") ...`
+- ✅ Read dynamically from the lexicons package exports
+
+### Don't Skip the CHANGELOG
+
+- ❌ Immediately update without reviewing changes
+- ✅ Always check `CHANGELOG.md` first to see exactly what changed between versions
+- ✅ Then run `git diff` for additional context
+
+### Don't Skip the Diff Step
+
+- ❌ Immediately update without reviewing changes
+- ✅ Always run `git diff` to see what actually changed
+
+### Don't Forget to Rebuild
+
+- ❌ Update imports and ship
+- ✅ Run `pnpm build` to verify type compatibility
+
+## What Gets Synced
+
+When new lexicons are added:
+
+1. **Import statements** - New `*_LEXICON_JSON` imports from `@hypercerts-org/lexicon`
+2. **Export arrays** - New entries added to `HYPERCERT_LEXICONS` array
+3. **Collection constants** - New NSID entries added to `HYPERCERT_COLLECTIONS` object
+
+When lexicons are modified:
+
+1. Review changes to understand schema updates
+2. Update corresponding type exports if needed
+3. Run tests to verify compatibility
+
+When lexicons are removed:
+
+1. Remove corresponding imports
+2. Remove from export arrays and collection constants
+3. Deprecate gracefully if SDK still needs backward compatibility