cai-upgrade

name	cai-upgrade
description	Use when upgrading CAI to the latest version. Triggers: 'cai-upgrade', 'context upgrade', 'context 업그레이드', 'update CAI'

cai-upgrade — Upgrade CAI

Overview

Upgrades the CAI infrastructure in a project to the latest plugin version. Performs section-based merge to preserve project-specific customizations while updating tool-managed content.

When to Use

• A new version of the cai plugin is available.
• Developer says "upgrade CAI" or "cai-upgrade".
• After installing a plugin update.

Workflow

Step 1: Detect current version

Read .claude/rules/cai.md in the target project. This is the primary file for version detection. Also check if the project has the expected directory structure (context/, tools/drift-warning.js, .claude/agents/, .claude/skills/).

Read ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json to get the plugin version.

If the project does not appear to have CAI initialized, inform the developer and suggest running cai-init instead.

Step 2: Fetch latest from plugin

Read the latest templates from the plugin source:

• ${CLAUDE_PLUGIN_ROOT}/templates/rules/cai.md (latest rules)
• ${CLAUDE_PLUGIN_ROOT}/templates/tools/drift-warning.js (latest hook)
• ${CLAUDE_PLUGIN_ROOT}/templates/AGENTS.md (latest AGENTS.md)
• ${CLAUDE_PLUGIN_ROOT}/skills/ (latest skills)
• ${CLAUDE_PLUGIN_ROOT}/agents/ (latest agents)
• ${CLAUDE_PLUGIN_ROOT}/CHANGELOG.md (version history)

Read CHANGELOG.md and extract all entries after the project's current version. These will be shown to the developer in Step 6.

Step 3: Create backup

Create a timestamped backup of all files that will be modified:

.claude/backups/cai-{YYYY-MM-DD-HHmmss}/
  rules/cai.md
  tools/drift-warning.js
  AGENTS.md
  skills/   (all cai-* skill files)
  agents/   (all agent files)

Inform the developer of the backup location.

Step 4: Section-based merge for rules file

Parse .claude/rules/cai.md using section markers:

1. Extract PROJECT-SPECIFIC content: Find everything between <!-- PROJECT-SPECIFIC:START --> and <!-- PROJECT-SPECIFIC:END -->. Save this content.

2. Replace TOOL-MANAGED content: Take the new <!-- TOOL-MANAGED:START --> ... <!-- TOOL-MANAGED:END --> block from the plugin template.

3. Reattach PROJECT-SPECIFIC content: Append the preserved PROJECT-SPECIFIC block after the new TOOL-MANAGED block.

4. If the project file has content outside both markers (custom sections added by the developer), preserve that content at the end of the file.

Step 5: Update hook and AGENTS.md

• Replace tools/drift-warning.js with the latest version from the plugin.
• Replace AGENTS.md with the latest version from the plugin.

These files are fully tool-managed and contain no project-specific content.

Step 6: Show changelog and diff preview

First, present the CHANGELOG entries since the project's current version:

📋 Changelog (v0.2.0 → v0.3.0):

### Improved — Confidence Pipeline
- verification-agent now recommends confidence promotion based on verification results ...
...

### Upgrade Notes
- To benefit from confidence promotion, re-verify existing specs via cai-onboard --incremental

Then present a clear diff of all changes:

1. Rules file: Show what changed in the TOOL-MANAGED section. Confirm PROJECT-SPECIFIC section is preserved (show it).
2. Hook: Show if the hook script changed.
3. AGENTS.md: Show if AGENTS.md changed.
4. Skills: List new, updated, and unchanged skills.
5. Agents: List new, updated, and unchanged agents.

Format the diff so the developer can review each change.

Step 7: Developer approval

Ask the developer to approve the upgrade. Options:

• Apply all — apply every change.
• Selective — let the developer pick which files to update.
• Abort — cancel the upgrade (backup is kept).

Do not apply any changes without explicit approval.

Step 8: Apply changes and update skills/agents

After approval:

1. Write the merged rules file.
2. Write the updated hook and AGENTS.md.
3. For each skill in the plugin's skills/ directory:
   • If the skill exists in the project: overwrite with the latest version.
   • If the skill is new: ask "Add new skill {name}?"
4. For each agent in the plugin's agents/ directory:
   • If the agent exists in the project: overwrite with the latest version.
   • If the agent is new: ask "Add new agent {name}?"
5. Never delete skills or agents that exist in the project but not in the plugin (these are custom project additions).

Step 9: Post-upgrade summary

Report:

• Plugin version applied.
• Files updated.
• PROJECT-SPECIFIC content preserved.
• New skills/agents added (if any).
• Backup location for rollback.
• Upgrade Notes from CHANGELOG (if any) — especially post-upgrade actions like cai-onboard --incremental.

Output

Updated files in the target project. Backup in .claude/backups/.

Error Handling

• If section markers are missing in the existing rules file, treat the entire file as PROJECT-SPECIFIC and prepend the new TOOL-MANAGED section. Warn the developer.
• If backup creation fails, abort the upgrade.
• If any file write fails after approval, report the error and point to the backup for manual recovery.