|
| 1 | +# PAI Update - Intelligent Sideloading System |
| 2 | + |
| 3 | +You are helping the user safely update their PAI installation while preserving their customizations. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The user has customized their PAI system (renamed their DA, added skills, modified hooks, changed settings). They want to pull updates from the upstream PAI repository without losing their work. |
| 8 | + |
| 9 | +## Your Task |
| 10 | + |
| 11 | +Execute this workflow step by step: |
| 12 | + |
| 13 | +### Phase 1: Fetch Upstream PAI |
| 14 | + |
| 15 | +1. **Check for staging directory**: Look for `.claude/pai_updates/` |
| 16 | + |
| 17 | +2. **Fetch latest PAI**: The user's project IS a clone of PAI. Use git to get upstream: |
| 18 | + |
| 19 | +```bash |
| 20 | +# Ensure we have the upstream remote |
| 21 | +git remote get-url upstream 2>/dev/null || git remote add upstream https://github.com/danielmiessler/PAI.git |
| 22 | + |
| 23 | +# Fetch latest from upstream (doesn't modify working directory) |
| 24 | +git fetch upstream main |
| 25 | + |
| 26 | +# Create staging directory |
| 27 | +rm -rf .claude/pai_updates |
| 28 | +mkdir -p .claude/pai_updates |
| 29 | + |
| 30 | +# Export upstream's .claude directory to staging (clean, no .git) |
| 31 | +git archive upstream/main -- .claude | tar -x -C .claude/pai_updates --strip-components=1 |
| 32 | +``` |
| 33 | + |
| 34 | +This gives us `.claude/pai_updates/` containing the pure upstream `.claude/` contents without affecting the user's working directory. |
| 35 | + |
| 36 | +3. **Record version info**: |
| 37 | +```bash |
| 38 | +upstream_commit=$(git rev-parse upstream/main) |
| 39 | +upstream_date=$(git log -1 --format=%ci upstream/main) |
| 40 | +echo "Upstream: $upstream_commit ($upstream_date)" |
| 41 | +``` |
| 42 | + |
| 43 | +4. **Check user's current sync state**: Look for `.claude/.pai-sync-history` to see when they last synced |
| 44 | + |
| 45 | +### Phase 2: Analyze Differences |
| 46 | + |
| 47 | +Compare the staging directory (`.claude/pai_updates/`) against the user's active directory (`.claude/`). |
| 48 | + |
| 49 | +For each file category: |
| 50 | + |
| 51 | +**Settings (`settings.json`)**: |
| 52 | +- Identify new keys added upstream |
| 53 | +- Identify keys the user has customized (especially `env.DA`, custom env vars) |
| 54 | +- Plan a smart merge that adds new keys while preserving user values |
| 55 | + |
| 56 | +**Skills (`.claude/skills/`)**: |
| 57 | +- New skills in upstream → Available to add |
| 58 | +- Modified skills → Compare if user has customized |
| 59 | +- User's custom skills → Never touch these |
| 60 | + |
| 61 | +**Hooks (`.claude/hooks/`)**: |
| 62 | +- Critical: hooks often contain custom logic |
| 63 | +- Check if user has modified vs. upstream version |
| 64 | +- Identify breaking changes |
| 65 | + |
| 66 | +**Agents (`.claude/agents/`)**: |
| 67 | +- New agents available |
| 68 | +- Modified agents (usually safe to update) |
| 69 | + |
| 70 | +**Commands (`.claude/commands/`)**: |
| 71 | +- Don't overwrite user's custom commands |
| 72 | +- Offer new commands from upstream |
| 73 | + |
| 74 | +### Phase 3: Generate Report |
| 75 | + |
| 76 | +Present a clear, organized report: |
| 77 | + |
| 78 | +``` |
| 79 | +╔═══════════════════════════════════════════════════════════════════╗ |
| 80 | +║ PAI UPDATE AVAILABLE ║ |
| 81 | +║ Upstream: [commit hash] ║ |
| 82 | +║ Your version: [last sync or "initial"] ║ |
| 83 | +╠═══════════════════════════════════════════════════════════════════╣ |
| 84 | +║ SUMMARY ║ |
| 85 | +║ • X new files available ║ |
| 86 | +║ • Y files updated upstream ║ |
| 87 | +║ • Z potential conflicts with your customizations ║ |
| 88 | +╠═══════════════════════════════════════════════════════════════════╣ |
| 89 | +``` |
| 90 | + |
| 91 | +Then organize by category: |
| 92 | + |
| 93 | +**🔴 REQUIRES ATTENTION** (conflicts with your customizations) |
| 94 | +- List files where both upstream changed AND user modified |
| 95 | +- Show what would be lost if blindly updated |
| 96 | +- Recommend merge strategy |
| 97 | + |
| 98 | +**🟢 SAFE TO AUTO-UPDATE** (you haven't modified these) |
| 99 | +- List files that can be updated without risk |
| 100 | +- These match your current upstream version |
| 101 | + |
| 102 | +**🆕 NEW FEATURES** (available to add) |
| 103 | +- New skills, agents, commands |
| 104 | +- Brief description of what each does |
| 105 | +- Recommendation based on user's apparent use case |
| 106 | + |
| 107 | +**📝 YOUR CUSTOMIZATIONS** (will be preserved) |
| 108 | +- List user's custom files that don't exist upstream |
| 109 | +- Confirm these are safe |
| 110 | + |
| 111 | +### Phase 4: Get User Decision |
| 112 | + |
| 113 | +Present clear options: |
| 114 | + |
| 115 | +``` |
| 116 | +What would you like to do? |
| 117 | +
|
| 118 | +[A] Apply all safe updates + add all new features (recommended for most users) |
| 119 | +[S] Step through each change individually |
| 120 | +[C] Conservative - only safe updates, skip new features |
| 121 | +[M] Manual - show me the diffs, I'll decide everything |
| 122 | +[N] Not now - keep staging for later review |
| 123 | +``` |
| 124 | + |
| 125 | +### Phase 5: Execute Updates |
| 126 | + |
| 127 | +For approved changes: |
| 128 | + |
| 129 | +1. **Create backup**: |
| 130 | + ```bash |
| 131 | + timestamp=$(date +%Y%m%d_%H%M%S) |
| 132 | + mkdir -p .claude/pai_backups |
| 133 | + cp -r .claude/skills .claude/pai_backups/skills_$timestamp |
| 134 | + cp -r .claude/hooks .claude/pai_backups/hooks_$timestamp |
| 135 | + cp .claude/settings.json .claude/pai_backups/settings_$timestamp.json |
| 136 | + ``` |
| 137 | + |
| 138 | +2. **Apply changes**: |
| 139 | + - Copy approved new files |
| 140 | + - For settings.json: perform intelligent merge (preserve user keys, add new ones) |
| 141 | + - For conflicts user approved: apply the merge strategy they chose |
| 142 | + |
| 143 | +3. **Update tracking**: |
| 144 | + ```bash |
| 145 | + echo "$(date -Iseconds) $(git rev-parse upstream/main)" >> .claude/.pai-sync-history |
| 146 | + ``` |
| 147 | + |
| 148 | +### Phase 6: Validate |
| 149 | + |
| 150 | +After applying updates: |
| 151 | +1. Check that settings.json is valid JSON |
| 152 | +2. Verify no syntax errors in key hooks |
| 153 | +3. Report success or any issues |
| 154 | + |
| 155 | +### Phase 7: Cleanup Option |
| 156 | + |
| 157 | +Ask if user wants to: |
| 158 | +- Keep `.claude/pai_updates/` for reference |
| 159 | +- Remove it to save space |
| 160 | + |
| 161 | +--- |
| 162 | + |
| 163 | +## Important Notes |
| 164 | + |
| 165 | +- **Never overwrite without asking** when user has customized a file |
| 166 | +- **Always backup** before modifying existing files |
| 167 | +- **Preserve user identity**: Their DA name, custom env vars, personal touches |
| 168 | +- **Be conservative**: When in doubt, ask rather than overwrite |
| 169 | +- **Explain clearly**: Users should understand what each change does |
| 170 | + |
| 171 | +## Handling Edge Cases |
| 172 | + |
| 173 | +**First time running `/paiupdate`**: |
| 174 | +- No sync history exists |
| 175 | +- Treat all current files as "user's version" (may be customized) |
| 176 | +- Be extra careful, ask more questions |
| 177 | + |
| 178 | +**User has diverged significantly**: |
| 179 | +- Many files modified |
| 180 | +- Recommend reviewing section by section |
| 181 | +- Offer to show detailed diffs |
| 182 | + |
| 183 | +**Upstream has breaking changes**: |
| 184 | +- Warn prominently |
| 185 | +- Explain what might break |
| 186 | +- Offer to defer those specific changes |
| 187 | + |
| 188 | +**Not a git repo (downloaded as ZIP)**: |
| 189 | +- If no `.git` directory exists, use alternative approach: |
| 190 | + ```bash |
| 191 | + mkdir -p .claude/pai_updates |
| 192 | + cd .claude/pai_updates |
| 193 | + curl -L https://github.com/danielmiessler/PAI/archive/refs/heads/main.tar.gz | tar -xz --strip-components=2 PAI-main/.claude |
| 194 | + ``` |
| 195 | +- Inform user they should consider using git for easier future updates |
| 196 | + |
| 197 | +**User forked PAI**: |
| 198 | +- Their `origin` is their fork, not upstream PAI |
| 199 | +- Check if `upstream` remote exists, add it if not |
| 200 | +- This is the expected setup for most users |
| 201 | + |
| 202 | +--- |
| 203 | + |
| 204 | +## Begin Now |
| 205 | + |
| 206 | +Start by checking for the staging directory and fetching the latest PAI. Then analyze and report. |
| 207 | + |
| 208 | +$ARGUMENTS |
0 commit comments