Claude-skill-registry dex-update

Safely update Dex with one command (handles everything automatically)

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/dex-update" ~/.claude/skills/majiayu000-claude-skill-registry-dex-update && rm -rf "$T"

manifest: skills/data/dex-update/SKILL.md

What This Command Does

For non-technical users: Updates Dex to the latest version automatically. No command line knowledge needed - just run the command and follow the prompts.

When to use:

After
```
/dex-whats-new
```
shows new version available
When you want the latest features and bug fixes

What it handles:

Downloads updates automatically
Protects your data (never touches your notes, tasks, projects)
Preserves protected user blocks and user-owned MCP entries
Resolves conflicts with a guided choice (no manual merge editor)
Shows clear progress and confirmation

Time: 2-5 minutes

Process

Step 1: Pre-Check

A. Check if Git is available

Try running basic git command:

git --version

If Git not found:

❌ Git not detected

Dex updates require Git. Here's how to install:

**Mac:** 
1. Open Terminal (Cmd+Space, type "Terminal")
2. Run: xcode-select --install
3. Click Install when prompted
4. Come back here when done

**Windows:**
1. Download from: https://git-scm.com/download/win
2. Run installer with default options
3. Restart Cursor
4. Try /dex-update again

[Skip update] — I'll do this later

If user skips, exit gracefully.

B. Check current setup

Run:

git remote -v

Scenario 1: Downloaded as ZIP (no Git)

❌ Not a Git repository

Looks like you downloaded Dex as a ZIP file instead of cloning it.

**To update:**
1. Download latest version: https://github.com/davekilleen/dex/archive/refs/heads/main.zip
2. Unzip to a new folder
3. Copy these folders from your current Dex to the new one:
   • System/user-profile.yaml
   • System/pillars.yaml
   • 00-Inbox/
   • 01-Quarter_Goals/
   • 02-Week_Priorities/
   • 03-Tasks/
   • 04-Projects/
   • 05-Areas/
   • 07-Archives/
4. Delete old Dex folder
5. Rename new folder to 'dex'
6. Open in Cursor

[Show detailed guide] — Open step-by-step instructions
[Cancel] — I'll do this later

If detailed guide selected, open

06-Resources/Dex_System/Updating_Dex.md

(Manual Update section).

Scenario 2: Cloned but no upstream remote

git remote -v

shows only "origin" pointing to github.com/davekilleen/dex:

✓ Git repository detected

Setting up automatic updates...

Run:

git remote rename origin upstream

Continue to Step 2.

Scenario 3: Already configured

If upstream exists, continue to Step 2.

Step 2: Check for Updates

Call update checker:

check_for_updates(force=True)

If no updates available:

✅ You're already on the latest version (v1.2.0)

No update needed!

Exit.

If updates available, show summary:

🎁 Dex v1.3.0 is available

You're on: v1.2.0
Latest: v1.3.0

What's new:
- Career coach improvements
- Task deduplication fix  
- Meeting intelligence enhancement

[View full release notes]
[Update now]
[Cancel]

Step 3: Pre-Update Safety Check

A. Check for uncommitted changes

Run:

git status --porcelain

If there are changes:

💾 Saving your work...

Dex found unsaved changes in your vault.
Let me save them before updating.

Run:

git add .
git commit -m "Auto-save before Dex update to v1.3.0"

Show:

✓ Your work is saved

B. Create backup reference (safety net)

Run:

git tag backup-before-v1.3.0

This creates a snapshot user can revert to if needed.

Step 4: Download Updates

⬇️ Downloading updates from GitHub...

Run:

git fetch upstream

If network error:

❌ Couldn't connect to GitHub

Please check your internet connection and try again.

[Retry]
[Cancel]

Success:

✓ Updates downloaded

Step 5: Check for Breaking Changes

Parse the update response from Step 2.

breaking_changes: true

⚠️ Important: This update includes major changes

Dex v2.0.0 includes breaking changes that require extra steps:

[Show what's changing]

This is safe to proceed, but:
• Some folders may be renamed
• Configuration format may change  
• Migration will run automatically

[Continue with update]
[Cancel — I'll read the details first]

If cancelled:

Show link to release notes
Exit gracefully
User can run
```
/dex-update
```
again when ready

Step 6: Apply Updates

🔄 Applying updates...

A. Merge updates

Run:

git merge upstream/main --no-edit

B. Handle merge outcome

Case 1: Clean merge (no conflicts)

✓ Updates applied successfully

Continue to Step 7.

Case 2: Merge conflicts

Check which files have conflicts:

git status | grep "both modified"

Automatic conflict resolution (protected blocks + guided choices):

Protected user blocks (preserved verbatim):

CLAUDE.md

contains a user block:

USER_EXTENSIONS_START

...

USER_EXTENSIONS_END

Custom MCP servers (preserved by name):

Any MCP server name starting with
```
custom-
```
is preserved
Example:
```
custom-gmail
```
,
```
custom-hubspot
```

Custom skills (preserved by name):

Any skill folder ending with
```
-custom
```
is preserved
Example:
```
meeting-prep-custom
```
,
```
daily-plan-custom
```

When conflicts occur:

If file is user data (00-07, System/user-profile.yaml, System/pillars.yaml):
- Keep user version
- Run:
```
git checkout --ours <file>
```
If file contains protected user block (CLAUDE.md):
- Take upstream version
- Re-insert preserved user block(s) verbatim
- Validate markers still present
If file is .mcp.json:
- Preserve any MCP entries named
```
custom-*
```
- Continue with Dex core updates for all other MCPs
If skill folder ends with
```
-custom
```
:
- Preserve entirely, never modify
- These are user's personal skills
If file is core Dex (skills, core MCP, scripts) and user edited it:
- Use AskUserQuestion to resolve, instead of a merge editor

AskUserQuestion flow (generic, parameterized):

Title: Dex update conflict: {{item_name}}

Your change:
{{user_change_summary}}
Enables: {{user_use_case_summary}}

Dex update:
{{dex_change_summary}}
Enables: {{dex_use_case_summary}}

Options:
1) Keep my version (preserve my changes)
2) Use Dex version (take upstream changes)
3) Keep both (rename one)
4) Let me tell you what to do (I'll write instructions)

If AskUserQuestion is not available (non-Claude Code):

Use a simple CLI prompt with the same 4 options.
Add one-line tradeoffs to each option (what you keep vs lose).
If user types an invalid choice, re-prompt once and default to "Use Dex version".

If user chooses "Keep both":

MCP:
```
name
```
→
```
name-custom
```
Skill folder:
```
name/
```
→
```
name-custom/
```

After resolving all conflicts:

git add <file>
git commit --no-edit

Show to user:

✓ Updates applied successfully

Handled conflicts:
• Preserved your protected blocks
• Updated core Dex features
• Resolved overlapping changes with your choice

[See what changed]

Case 3: Merge failed (rare)

❌ Update couldn't complete automatically

This is rare, but sometimes updates need manual review.

**What happened:**
[Error message]

**Options:**
[Restore to before update] — Uses the backup we created
[Get help] — Opens GitHub issue template

If restore:

git merge --abort
git reset --hard backup-before-v1.3.0

Step 7: Post-Update Steps

A. Check for migration needs

If breaking_changes was true, check for migration script:

ls core/migrations/v*-to-v*.sh

If found:

🔧 Running migration...

This update requires a one-time migration to update your data structure.
This is safe and automatic.

Run:

./core/migrations/v1-to-v2.sh --auto

Show migration output.

B. Update dependencies

📦 Updating dependencies...

Run:

npm install
pip3 install -r core/mcp/requirements.txt

C. Enable new background automations (Automatic)

Check for automation scripts that need installation. These run silently without prompting.

Meeting Sync (if Granola detected):

Check if Granola is installed:

ls "$HOME/Library/Application Support/Granola/cache-v3.json" 2>/dev/null

If Granola cache exists AND meeting automation not yet installed:

# Check if already installed
launchctl list | grep com.dex.meeting-intel

If not installed:

cd .scripts/meeting-intel && ./install-automation.sh 2>/dev/null

Add to summary if installed: "✓ Enabled automatic meeting sync (runs every 30 min)"

Future automations: This pattern extends to other background services. Check for the prerequisite (e.g., app installed, API key present), then run the installer silently.

Step 8: Verification

✓ Update complete! Now testing...

Quick smoke test:

Check key files exist:

```
03-Tasks/Tasks.md
```
```
System/user-profile.yaml
```
```
.claude/skills/daily-plan/SKILL.md
```

Check MCP configuration:
- ```
.mcp.json
```
  exists and is valid JSON
- Custom MCP entries (
```
custom-*
```
  ) still present
Check CLAUDE.md:
- ```
USER_EXTENSIONS_START/END
```
  markers still present
Try loading user profile:
- Read
```
System/user-profile.yaml
```

If all pass:

✅ Update successful!

If something fails:

⚠️ Update completed but found an issue

[Details of what failed]

Your data is safe, but you may want to:
[Restore to previous version]
[Report this issue]
[Continue anyway]

Step 9: Summary

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Dex Updated: v1.2.0 → v1.3.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What's new:
• Career coach improvements
• Task deduplication fix
• Meeting intelligence enhancement

Your data:
✓ All notes preserved
✓ All tasks preserved
✓ All customizations preserved

[View full changelog]
[Start using new features]

If new automations were enabled:

🤖 New automations enabled:
✓ Automatic meeting sync (runs every 30 min)

If there were conflicts:

🔍 Changes applied:
• Updated 12 core files
• Kept 5 of your customized files
• Protected all your data folders

[See detailed change list]

Step 10: Track Usage (Silent)

Update usage log:

System/usage_log.md
- [ ] Update Dex (/dex-update) → [x] Update Dex (/dex-update)

Error Recovery

If Update Fails at Any Point

User always has escape hatch:

🔙 Restoring to before update...

Run:

git merge --abort 2>/dev/null || true
git reset --hard backup-before-v1.3.0
git clean -fd

✓ Restored to v1.2.0

Nothing was changed. Your Dex is exactly as it was.

[Try update again]
[Report issue]
[Cancel]

Migration Support (for Breaking Changes)

Auto-Migration Flag

If migration script supports

--auto

flag, run non-interactively:

./core/migrations/v1-to-v2.sh --auto

Migration script must:

Accept
```
--auto
```
flag
Skip confirmation prompts
Return exit code 0 on success
Log to
```
System/.migration-log
```

Manual Migration Required

If script doesn't support

--auto

⚠️ Manual step required

This update needs you to run a migration script.

Don't worry - it's one command and takes 30 seconds.

**In Cursor's terminal (bottom panel), run:**

./core/migrations/v1-to-v2.sh

**Then come back here when it's done.**

[I've run the migration — continue]
[Show me what the migration does]
[Cancel update]

Alternative: ZIP Download Path

For users who can't/won't use Git, provide manual instructions:

📥 Manual Update Method

If automatic updates don't work, you can update manually:

1. **Download latest Dex:**
   https://github.com/davekilleen/dex/archive/refs/heads/main.zip

2. **Copy your data and custom blocks:**
   From OLD Dex folder, copy these to NEW Dex folder:
   
   ✓ System/user-profile.yaml
   ✓ System/pillars.yaml
   ✓ 00-Inbox/ (entire folder)
   ✓ 01-Quarter_Goals/ (entire folder)
   ✓ 02-Week_Priorities/ (entire folder)
   ✓ 03-Tasks/ (entire folder)
   ✓ 04-Projects/ (entire folder)
   ✓ 05-Areas/ (entire folder)
   ✓ 07-Archives/ (entire folder)
   ✓ .env (if it exists)
   ✓ Your `USER_EXTENSIONS` block from `CLAUDE.md`
   ✓ Any custom MCP entries named `custom-*` from `.mcp.json`
   ✓ Any custom skills ending with `-custom`

3. **DON'T copy:**
   ✗ .claude/skills/ (use new version)
   ✗ core/mcp/ (use new version)
   ✗ README.md (use new version)

4. **Open new folder in Cursor**

5. **Run /setup to verify**

[Download now]
[Copy step-by-step instructions to clipboard]

Settings

User can configure update behavior in

System/user-profile.yaml

updates:
  auto_check: true              # Check during /daily-plan
  check_interval_days: 7        # How often to check
  auto_update: false            # Never auto-update without asking
  backup_before_update: true    # Always create backup tag

Related Commands

```
/dex-whats-new
```
- Check what's new without updating
```
/dex-rollback
```
- Undo last update (if something went wrong)
```
/dex-update-settings
```
- Configure update preferences

Non-Technical User Experience

User sees in daily plan:

🎁 Dex v1.3.0 is available. Run /dex-whats-new for details.

User runs:

/dex-update

User sees:

✓ Git detected
✓ Updates downloaded
✓ No conflicts
✓ Dependencies updated
✅ Update complete! v1.2.0 → v1.3.0

Total clicks: 1 (just ran the command) Total time: 2 minutes Technical knowledge required: Zero

Philosophy

Automatic where possible:

Git commands run silently
Conflicts resolved automatically
Dependencies updated automatically
Migrations run automatically (when safe)

Interactive where necessary:

Breaking changes: confirm understanding
Manual migration: clear instructions
Errors: always offer restoration

Safe always:

Backup created before any changes
User data never at risk (gitignored)
One-command rollback if issues
Clear status at every step

No jargon:

Don't say "merge conflict" - say "overlapping changes"
Don't say "upstream" - say "main Dex repository"
Don't say "git fetch" - say "downloading updates"
Don't say "rebase" - just don't use rebase