@localsummer/incspec 0.2.6 → 0.3.1

package/README.md

@@ -142,9 +142,36 @@ AI 编程助手在处理复杂前端代码库时常常力不从心，因为 API
 └────────────────────┘
 ```
 
+### 极简模式 (3步)
+
+适用于紧急修复、单文件小改动、不需要新基线的变更。
+
+```
+┌────────────────────┐
+│ 1. 分析            │  分析现有代码流程
+│    代码流程        │  生成基线快照
+└────────┬───────────┘
+         │
+         ▼
+┌────────────────────┐
+│ 5. 应用            │  基于口头需求
+│    变更            │  直接实现代码变更
+└────────┬───────────┘
+         │
+         ▼
+┌────────────────────┐
+│ 7. 归档            │  归档本轮产出
+│    产出            │  清空工作区
+└────────────────────┘
+```
+
 **模式选择建议:**
 - **完整模式**: 复杂 UI 功能、多组件交互、需要详细设计审查
 - **快速模式**: Bug 修复、简单功能、不涉及 UI 依赖变更
+- **极简模式**: 紧急修复、单文件小改动、无需生成新基线
+
+**模式升级:**
+支持从宽松模式升级到严格模式（`minimal → quick → full`），使用 `incspec upgrade <mode>` 补齐缺失步骤。
 
 > **提示**: 如果已有基准报告，可使用 `incspec analyze --baseline=<file>` 直接跳过分析步骤，快速进入后续工作流。
 
@@ -218,7 +245,7 @@ incspec init
 
 同步到 Cursor 或 Claude Code：
 ```bash
-incspec sync              # 交互式选择
+incspec sync              # 交互式选择（默认不预选）
 incspec sync --cursor     # 仅 Cursor
 incspec sync --claude     # 仅 Claude Code
 incspec sync --all        # 全部
@@ -260,6 +287,14 @@ $ incspec analyze src/views/Home --quick      # 启动快速模式工作流
 ```
 快速模式跳过步骤 3 (UI依赖采集) 和步骤 4 (增量设计)，直接从需求进入代码应用。
 
+**启动极简模式** (3步流程):
+
+适用于紧急修复或单文件小改动：
+```bash
+$ incspec analyze src/views/Home --minimal    # 启动极简模式工作流
+```
+极简模式跳过步骤 2、3、4、6，仅保留分析 → 应用 → 归档；如需补齐步骤可使用 `incspec upgrade <mode>`。
+
 **使用现有基准报告** (跳过分析):
 
 如果已有基准报告文件，可直接使用，跳过分析步骤：
@@ -462,7 +497,7 @@ incspec reset -t 3         # 短选项形式
 
 **回退行为:** 保留目标步骤及之前状态，重置后续步骤为 pending，被重置步骤的产出自动归档。
 
-**限制:** 目标步骤必须已完成（1-6），快速模式下不能回退到被跳过的步骤（3、4）。
+**限制:** 目标步骤必须已完成（1-6），快速模式下不能回退到被跳过的步骤（3、4），极简模式下不能回退到被跳过的步骤（2、3、4、6）。
 
 ## 目录结构
 
@@ -520,9 +555,10 @@ incspec help <command>    # 显示特定命令帮助
 
 ```bash
 # 步骤 1：分析代码流程
-incspec analyze <source-path> [--module=name] [--quick]  # 别名：a
+incspec analyze <source-path> [--module=name] [--quick|--minimal]  # 别名：a
 incspec a src/views/Home --module=home
 incspec analyze src/views/Home --quick                   # 启动快速模式
+incspec analyze src/views/Home --minimal                 # 启动极简模式
 incspec analyze src/views/Home --complete -o baselines/home-baseline-v1.md
 incspec analyze --baseline=home-baseline-v1.md  # 使用现有基准(自动从归档恢复)
 
@@ -530,23 +566,24 @@ incspec analyze --baseline=home-baseline-v1.md  # 使用现有基准(自动从
 incspec collect-req                             # 别名：cr
 incspec cr --complete
 
-# 步骤 3：收集 UI 依赖（快速模式跳过）
+# 步骤 3：收集 UI 依赖（快速/极简模式跳过）
 incspec collect-dep                             # 别名：cd
 incspec cd --complete
 
-# 步骤 4：生成增量设计（快速模式跳过）
+# 步骤 4：生成增量设计（快速/极简模式跳过）
 incspec design [--feature=name]                 # 别名：d
 incspec d --feature=user-auth --complete -o increments/auth-increment-v1.md
 
 # 步骤 5：应用代码变更
 incspec apply [increment-path]                  # 别名：ap
 incspec ap --source-dir=src/ --complete
-# 快速模式下自动使用 requirements/structured-requirements.md 作为输入
+# 快速/极简模式下自动使用 requirements/structured-requirements.md 作为输入
 
 # 步骤 6：合并到基线
 incspec merge [increment-path]                  # 别名：m
 incspec m --complete -o baselines/home-baseline-v2.md
 # 快速模式下重新分析代码生成新基线
+# 极简模式默认跳过步骤 6（需升级模式后执行）
 ```
 
 </details>
@@ -572,6 +609,10 @@ incspec archive -y             # 跳过确认提示
 incspec reset                  # 重置当前工作流（别名：rs）
 incspec reset --to=3           # 回退到步骤 3，保留步骤 1-3 的状态
 incspec reset -t 3             # 同上，短选项形式
+
+incspec upgrade <mode>         # 升级工作流模式（别名：ug）
+incspec upgrade quick          # minimal → quick
+incspec upgrade full           # quick/minimal → full
 ```
 
 </details>
@@ -594,6 +635,7 @@ incspec reset -t 3             # 同上，短选项形式
 | `sync` | `s` | 同步 |
 | `update` | `up` | 更新 |
 | `reset` | `rs` | 重置/回退 |
+| `upgrade` | `ug` | 模式升级 |
 | `help` | `h` | 帮助 |
 
 </details>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localsummer/incspec",
-  "version": "0.2.6",
+  "version": "0.3.1",
   "description": "面向 AI 编程助手的增量规范驱动开发工具",
   "bin": {
     "incspec": "src/index.mjs"

package/src/commands/analyze.mjs

@@ -19,6 +19,7 @@ import {
   isWorkflowIncomplete,
   getWorkflowProgress,
 } from '../lib/workflow.mjs';
+import { getModeLabel, formatModeInfo } from '../lib/mode-utils.mjs';
 import { getNextVersion } from '../lib/spec.mjs';
 import {
   colors,
@@ -141,11 +142,12 @@ export async function analyzeCommand(ctx) {
 
     // Handle workflow state
     let workflow = readWorkflow(projectRoot);
-    const isQuick = options.quick || options.q;
+    const mode = options.minimal ? MODE.MINIMAL : 
+                 options.quick || options.q ? MODE.QUICK : MODE.FULL;
     if (!workflow?.currentWorkflow) {
       const workflowName = typeof options.workflow === 'string' ? options.workflow : `analyze-${moduleName}`;
-      workflow = startWorkflow(projectRoot, workflowName, { mode: isQuick ? MODE.QUICK : MODE.FULL });
-      const modeLabel = isQuick ? '(快速模式: 5步)' : '';
+      workflow = startWorkflow(projectRoot, workflowName, { mode });
+      const modeLabel = getModeLabel(mode);
       printSuccess(`已创建新工作流: ${workflowName} ${modeLabel}`);
     }
 
@@ -171,17 +173,18 @@ export async function analyzeCommand(ctx) {
 
   // Get workflow state
   let workflow = readWorkflow(projectRoot);
-  const isQuick = options.quick || options.q;
+  const mode = options.minimal ? MODE.MINIMAL : 
+               options.quick || options.q ? MODE.QUICK : MODE.FULL;
 
   // Check if starting new workflow
   if (!workflow?.currentWorkflow) {
     let workflowName = typeof options.workflow === 'string' ? options.workflow : '';
     if (!workflowName) {
-      const modeHint = isQuick ? '(快速模式)' : '';
-      workflowName = await prompt(`请输入工作流名称 ${modeHint}`, `analyze-${moduleName}`);
+      const modeLabel = getModeLabel(mode);
+      workflowName = await prompt(`请输入工作流名称 ${modeLabel}`, `analyze-${moduleName}`);
     }
-    workflow = startWorkflow(projectRoot, workflowName, { mode: isQuick ? MODE.QUICK : MODE.FULL });
-    const modeLabel = isQuick ? '(快速模式: 5步)' : '';
+    workflow = startWorkflow(projectRoot, workflowName, { mode });
+    const modeLabel = getModeLabel(mode);
     printSuccess(`已创建新工作流: ${workflowName} ${modeLabel}`);
   } else if (isWorkflowIncomplete(workflow)) {
     // Current workflow is incomplete, ask for confirmation
@@ -199,11 +202,11 @@ export async function analyzeCommand(ctx) {
     } else {
       let workflowName = typeof options.workflow === 'string' ? options.workflow : '';
       if (!workflowName) {
-        const modeHint = isQuick ? '(快速模式)' : '';
-        workflowName = await prompt(`请输入新工作流名称 ${modeHint}`, `analyze-${moduleName}`);
+        const modeLabel = getModeLabel(mode);
+        workflowName = await prompt(`请输入新工作流名称 ${modeLabel}`, `analyze-${moduleName}`);
       }
-      workflow = startWorkflow(projectRoot, workflowName, { mode: isQuick ? MODE.QUICK : MODE.FULL });
-      const modeLabel = isQuick ? '(快速模式: 5步)' : '';
+      workflow = startWorkflow(projectRoot, workflowName, { mode });
+      const modeLabel = getModeLabel(mode);
       printSuccess(`已归档旧工作流，创建新工作流: ${workflowName} ${modeLabel}`);
     }
   }
@@ -218,10 +221,9 @@ export async function analyzeCommand(ctx) {
   print(colorize('─────────────────────', colors.dim));
   print('');
 
-  // Show quick mode info
-  if (isQuick) {
-    print(colorize('快速模式流程: 分析 -> 需求收集 -> 应用代码 -> 合并基线', colors.yellow));
-    print(colorize('(跳过 UI依赖采集 和 增量设计)', colors.dim));
+  // Show mode info
+  if (mode !== MODE.FULL) {
+    print(colorize(formatModeInfo(mode), colors.yellow));
     print('');
   }
 

package/src/commands/apply.mjs

@@ -14,9 +14,15 @@ import {
   readWorkflow,
   updateStep,
   STATUS,
-  isQuickMode,
+  MODE,
   getMissingPrereqs,
 } from '../lib/workflow.mjs';
+import {
+  isMinimalMode,
+  isQuickMode,
+  isFullMode,
+  getApplyInputFile,
+} from '../lib/mode-utils.mjs';
 import { listSpecs } from '../lib/spec.mjs';
 import {
   colors,
@@ -73,7 +79,7 @@ export async function applyCommand(ctx) {
     return;
   }
 
-  const quickMode = isQuickMode(workflow);
+  const mode = workflow.mode || MODE.FULL;
   const missingSteps = getMissingPrereqs(workflow, STEP_NUMBER);
   if (missingSteps && missingSteps.length > 0 && !options.force) {
     printWarning(`请先完成步骤 ${missingSteps.join(', ')} 后再继续。`);
@@ -91,16 +97,7 @@ export async function applyCommand(ctx) {
   let inputPath;
   let inputType;
 
-  if (quickMode) {
-    // Quick mode: use requirements document
-    const reqFile = path.join(projectRoot, INCSPEC_DIR, DIRS.requirements, 'structured-requirements.md');
-    if (!fs.existsSync(reqFile)) {
-      printWarning('未找到需求文件。请先运行步骤 2 (collect-req)。');
-      return;
-    }
-    inputPath = path.join(INCSPEC_DIR, DIRS.requirements, 'structured-requirements.md');
-    inputType = 'requirements';
-  } else {
+  if (isFullMode(workflow)) {
     // Full mode: use increment design file
     let incrementPath = args[0];
     if (!incrementPath) {
@@ -128,12 +125,22 @@ export async function applyCommand(ctx) {
     }
     inputPath = incrementPath;
     inputType = 'increment';
+  } else {
+    // Quick/Minimal mode: use requirements document
+    const reqFile = path.join(projectRoot, INCSPEC_DIR, DIRS.requirements, 'structured-requirements.md');
+    if (!fs.existsSync(reqFile)) {
+      printWarning('未找到需求文件。请先运行步骤 2 (collect-req)。');
+      return;
+    }
+    inputPath = path.join(INCSPEC_DIR, DIRS.requirements, 'structured-requirements.md');
+    inputType = 'requirements';
   }
 
   print('');
   print(colorize('步骤 5: 应用代码变更', colors.bold, colors.cyan));
-  if (quickMode) {
-    print(colorize('(快速模式 - 基于需求文档)', colors.yellow));
+  if (mode !== MODE.FULL) {
+    const modeLabel = mode === MODE.MINIMAL ? '极简模式' : '快速模式';
+    print(colorize(`(${modeLabel} - 基于需求文档)`, colors.yellow));
   }
   print(colorize('────────────────────', colors.dim));
   print('');
@@ -149,9 +156,10 @@ export async function applyCommand(ctx) {
   print(colorize('使用说明:', colors.bold));
   print('');
 
-  if (quickMode) {
-    // Quick mode instructions
-    print(colorize('快速模式下，请直接根据需求文档实现代码变更:', colors.cyan));
+  if (mode !== MODE.FULL) {
+    // Quick/Minimal mode instructions
+    const modeLabel = mode === MODE.MINIMAL ? '极简模式' : '快速模式';
+    print(colorize(`${modeLabel}下，请直接根据需求文档实现代码变更:`, colors.cyan));
     print('');
     print(colorize('在 Cursor 中:', colors.dim));
     print(colorize(`  /incspec/inc-apply ${inputPath}`, colors.bold, colors.white));

package/src/commands/archive.mjs

@@ -10,7 +10,8 @@ import {
   DIRS,
 } from '../lib/config.mjs';
 import { archiveSpec, getSpecInfo } from '../lib/spec.mjs';
-import { archiveWorkflow, readWorkflow, updateStep, STATUS, isQuickMode, MODE } from '../lib/workflow.mjs';
+import { archiveWorkflow, readWorkflow, updateStep, STATUS, MODE } from '../lib/workflow.mjs';
+import { getArchivableStepsForMode } from '../lib/mode-utils.mjs';
 import {
   colors,
   colorize,
@@ -21,25 +22,6 @@ import {
   confirm,
 } from '../lib/terminal.mjs';
 
-// Full mode: archivable steps are 1, 2, 3, 4, 6 (0-based: 0, 1, 2, 3, 5)
-// Note: Step 5 (apply) has no file output, Step 7 (archive) is this command itself
-const FULL_MODE_ARCHIVABLE_INDEXES = [0, 1, 2, 3, 5];
-// Quick mode: archivable steps are 1, 2, 6 (0-based: 0, 1, 5)
-// Note: Steps 3, 4 are skipped in quick mode
-const QUICK_MODE_ARCHIVABLE_INDEXES = [0, 1, 5];
-
-/**
- * Get archivable step indexes based on workflow mode
- * @param {Object} workflow
- * @returns {number[]}
- */
-function getArchivableStepIndexes(workflow) {
-  if (isQuickMode(workflow)) {
-    return QUICK_MODE_ARCHIVABLE_INDEXES;
-  }
-  return FULL_MODE_ARCHIVABLE_INDEXES;
-}
-
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -64,7 +46,7 @@ function collectArchivedFiles(projectRoot) {
   }
 
   const files = [];
-  
+
   // Helper to collect .md files from a directory
   const collectMdFiles = (dir) => {
     const entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -75,7 +57,7 @@ function collectArchivedFiles(projectRoot) {
       }
     });
   };
-  
+
   // Traverse: archives/ -> YYYY-MM/ -> [module/] -> files
   const topEntries = fs.readdirSync(archiveRoot, { withFileTypes: true });
   topEntries.forEach(entry => {
@@ -132,7 +114,8 @@ function getArchivableOutputs(workflow) {
     return null;
   }
 
-  const archivableIndexes = getArchivableStepIndexes(workflow);
+  const mode = workflow.mode || MODE.FULL;
+  const archivableIndexes = getArchivableStepsForMode(mode);
   const outputs = [];
 
   for (const index of archivableIndexes) {
@@ -141,6 +124,11 @@ function getArchivableOutputs(workflow) {
       return null;
     }
 
+    // 步骤5 (apply) 的输出是"代码已应用"占位符，不是文件，跳过
+    if (index === 4 && step.output === '代码已应用') {
+      continue;
+    }
+
     const completedAt = parseWorkflowTime(step.completedAt);
     if (!completedAt) {
       return null;
@@ -254,6 +242,20 @@ export async function archiveCommand(ctx) {
       return;
     }
 
+    // 极简模式提醒
+    if (workflow.mode === MODE.MINIMAL && !skipConfirm) {
+      print(colorize('⚠️  极简模式提醒:', colors.yellow, colors.bold));
+      print(colorize('   极简模式跳过了步骤6（合并基线），当前归档的是初始基线和应用后的代码。', colors.dim));
+      print(colorize('   如需生成新基线快照，请先运行: incspec merge', colors.dim));
+      print('');
+      const shouldContinue = await confirm('是否继续归档当前文件?');
+      if (!shouldContinue) {
+        print(colorize('已取消。', colors.dim));
+        return;
+      }
+      print('');
+    }
+
     if (targets.length > 0) {
       print(colorize('将归档以下文件:', colors.dim));
       targets.forEach(target => print(colorize(`  - ${target.name}`, colors.dim)));

package/src/commands/status.mjs

@@ -11,9 +11,12 @@ import {
   STEPS,
   STATUS,
   MODE,
-  QUICK_MODE_SKIPPED,
   isQuickMode,
 } from '../lib/workflow.mjs';
+import {
+  getModeLabel,
+  getSkippedStepsForMode,
+} from '../lib/mode-utils.mjs';
 import {
   colors,
   colorize,
@@ -52,8 +55,9 @@ export async function statusCommand(ctx) {
 
   // Current workflow
   if (workflow?.currentWorkflow) {
-    const quickMode = isQuickMode(workflow);
-    const modeLabel = quickMode ? '快速模式 (5步)' : '完整模式 (7步)';
+    const mode = workflow.mode || MODE.FULL;
+    const modeLabel = getModeLabel(mode);
+    const skippedSteps = getSkippedStepsForMode(mode);
 
     print(colorize(`当前工作流: `, colors.bold) + colorize(workflow.currentWorkflow, colors.cyan));
     print(colorize(`工作流模式: ${modeLabel}`, colors.dim));
@@ -69,9 +73,9 @@ export async function statusCommand(ctx) {
       const stepData = workflow.steps[index] || {};
       let status = stepData.status || STATUS.PENDING;
       const isCurrent = workflow.currentStep === step.id;
-      const isSkipped = quickMode && QUICK_MODE_SKIPPED.includes(step.id);
+      const isSkipped = skippedSteps.includes(step.id);
 
-      // Quick mode: mark skipped steps
+      // Mark skipped steps
       if (isSkipped && status !== STATUS.SKIPPED) {
         status = STATUS.SKIPPED;
       }
@@ -100,8 +104,8 @@ export async function statusCommand(ctx) {
     // Next step hint
     const nextStepIndex = workflow.steps.findIndex((step, index) => {
       const stepNumber = index + 1;
-      // Skip excluded steps in quick mode
-      if (quickMode && QUICK_MODE_SKIPPED.includes(stepNumber)) {
+      // Skip excluded steps based on mode
+      if (skippedSteps.includes(stepNumber)) {
         return false;
       }
       return (step?.status || STATUS.PENDING) !== STATUS.COMPLETED;

package/src/commands/sync.mjs

@@ -61,8 +61,8 @@ export async function syncCommand(ctx) {
     targets = await checkbox({
       message: '选择要同步的目标:',
       choices: [
-        { ...SYNC_TARGETS.cursor, checked: true },
-        { ...SYNC_TARGETS.claude, checked: false },
+        { ...SYNC_TARGETS.cursor },
+        { ...SYNC_TARGETS.claude },
       ],
     });
 

package/src/commands/upgrade.mjs

@@ -0,0 +1,139 @@
+/**
+ * upgrade command - Upgrade workflow mode
+ */
+
+import {
+  ensureInitialized,
+} from '../lib/config.mjs';
+import {
+  readWorkflow,
+  writeWorkflow,
+  STATUS,
+  MODE,
+} from '../lib/workflow.mjs';
+import {
+  validateModeUpgrade,
+  getMissingStepsAfterUpgrade,
+  getModeLabel,
+  MODE_UPGRADE_ORDER,
+} from '../lib/mode-utils.mjs';
+import {
+  colors,
+  colorize,
+  print,
+  printSuccess,
+  printWarning,
+  printError,
+  printInfo,
+  confirm,
+} from '../lib/terminal.mjs';
+
+/**
+ * Execute upgrade command
+ * @param {Object} ctx - Command context
+ */
+export async function upgradeCommand(ctx) {
+  const { cwd, args, options } = ctx;
+
+  const targetMode = args[0]; // 目标模式：quick 或 full
+
+  // Validate target mode
+  if (!targetMode) {
+    printError('请指定目标模式');
+    print('');
+    print(colorize('用法:', colors.bold));
+    print(colorize('  incspec upgrade <mode>', colors.dim));
+    print('');
+    print(colorize('可用模式:', colors.bold));
+    print(colorize(`  ${MODE_UPGRADE_ORDER.join(' → ')}`, colors.cyan));
+    return;
+  }
+
+  if (!Object.values(MODE).includes(targetMode)) {
+    printError(`未知的目标模式: ${targetMode}`);
+    print('');
+    print(colorize('可用模式:', colors.bold));
+    print(colorize(`  ${MODE_UPGRADE_ORDER.join(', ')}`, colors.dim));
+    return;
+  }
+
+  // Ensure initialized
+  const projectRoot = ensureInitialized(cwd);
+
+  // Get workflow state
+  const workflow = readWorkflow(projectRoot);
+
+  if (!workflow?.currentWorkflow) {
+    printError('当前没有活跃的工作流');
+    printInfo('请先运行 incspec analyze 开始新工作流');
+    return;
+  }
+
+  const currentMode = workflow.mode || MODE.FULL;
+
+  // Validate upgrade
+  const validation = validateModeUpgrade(currentMode, targetMode);
+  if (!validation.valid) {
+    printError(`无法升级: ${validation.reason}`);
+    print('');
+    print(colorize('提示:', colors.bold));
+    print(colorize('  只能从宽松模式升级到严格模式', colors.dim));
+    print(colorize(`  升级路径: ${MODE_UPGRADE_ORDER.join(' → ')}`, colors.cyan));
+    return;
+  }
+
+  // Get missing steps
+  const missingSteps = getMissingStepsAfterUpgrade(currentMode, targetMode);
+
+  print('');
+  print(colorize('工作流模式升级', colors.bold, colors.cyan));
+  print(colorize('──────────────', colors.dim));
+  print('');
+  print(colorize(`当前模式: ${getModeLabel(currentMode)}`, colors.dim));
+  print(colorize(`目标模式: ${getModeLabel(targetMode)}`, colors.cyan));
+  print('');
+
+  if (missingSteps.length > 0) {
+    print(colorize('需要补充的步骤:', colors.bold));
+    missingSteps.forEach(stepId => {
+      print(colorize(`  - 步骤 ${stepId}`, colors.yellow));
+    });
+    print('');
+  } else {
+    print(colorize('无需补充额外步骤', colors.dim));
+    print('');
+  }
+
+  const confirmed = await confirm('确认升级工作流模式？');
+  if (!confirmed) {
+    print('');
+    printInfo('已取消升级');
+    return;
+  }
+
+  // Update workflow mode
+  workflow.mode = targetMode;
+
+  // Update skipped steps to pending (the steps that were skipped but now are needed)
+  missingSteps.forEach(stepId => {
+    const index = stepId - 1;
+    if (workflow.steps[index]) {
+      workflow.steps[index].status = STATUS.PENDING;
+      workflow.steps[index].output = null;
+      workflow.steps[index].completedAt = null;
+    }
+  });
+
+  // Write updated workflow
+  writeWorkflow(projectRoot, workflow);
+
+  print('');
+  printSuccess(`已升级到 ${getModeLabel(targetMode)}`);
+  
+  if (missingSteps.length > 0) {
+    print('');
+    printInfo(`请依次执行步骤: ${missingSteps.join(', ')}`);
+    print('');
+    print(colorize('提示: 运行 incspec status 查看详细进度', colors.dim));
+  }
+}

package/src/index.mjs

@@ -18,6 +18,7 @@ import { listCommand } from './commands/list.mjs';
 import { validateCommand } from './commands/validate.mjs';
 import { archiveCommand } from './commands/archive.mjs';
 import { resetCommand } from './commands/reset.mjs';
+import { upgradeCommand } from './commands/upgrade.mjs';
 import { syncCommand } from './commands/sync.mjs';
 import { helpCommand } from './commands/help.mjs';
 import { colors, colorize } from './lib/terminal.mjs';
@@ -211,6 +212,12 @@ async function main() {
         await resetCommand(commandContext);
         break;
 
+      // Upgrade workflow mode
+      case 'upgrade':
+      case 'ug':
+        await upgradeCommand(commandContext);
+        break;
+
       // Sync integrations
       case 'sync':
       case 's':