@localsummer/incspec 0.3.1 → 0.3.3

package/README.md

@@ -511,7 +511,7 @@ your-project/
 │   └── templates/               # Markdown 模板文件
 ├── incspec/
 │   ├── project.md               # 项目配置
-│   ├── WORKFLOW.md              # 当前工作流状态
+│   ├── workflow.json            # 当前工作流状态
 │   ├── AGENTS.md                # incspec 使用指南
 │   ├── baselines/               # 基线快照
 │   │   └── home-baseline-v1.md

package/package.json

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

package/src/CLAUDE.md

@@ -0,0 +1,7 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+*No recent activity*
+</claude-mem-context>

package/src/commands/CLAUDE.md

@@ -0,0 +1,14 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+### Jan 8, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #118 | 3:14 PM | 🔵 | 纠正对 IncSpec 工作流模式参数的错误理解 | ~113 |
+| #101 | 2:43 PM | 🔵 | 完成了 IncSpec 极简模式的深度分析 | ~95 |
+| #100 | " | 🔵 | 发现 IncSpec 三种工作流模式的完整实现 | ~110 |
+| #99 | " | 🔵 | 发现 IncSpec 极简模式的完整实现 | ~97 |
+</claude-mem-context>

package/src/commands/collect-req.mjs

@@ -13,6 +13,7 @@ import {
   updateStep,
   STATUS,
   isQuickMode,
+  isStepAllowed,
   getMissingPrereqs,
 } from '../lib/workflow.mjs';
 import {
@@ -46,6 +47,10 @@ export async function collectReqCommand(ctx) {
       printWarning('没有活跃的工作流，无法标记完成。');
       return;
     }
+    if (!isStepAllowed(STEP_NUMBER, workflow.mode)) {
+      printWarning('当前工作流模式不包含此步骤，无需标记完成。');
+      return;
+    }
     updateStep(projectRoot, STEP_NUMBER, STATUS.COMPLETED, OUTPUT_FILE);
     printSuccess(`步骤 ${STEP_NUMBER} 已标记为完成: ${OUTPUT_FILE}`);
 
@@ -63,6 +68,11 @@ export async function collectReqCommand(ctx) {
     return;
   }
 
+  if (!isStepAllowed(STEP_NUMBER, workflow.mode)) {
+    printWarning('当前工作流模式不包含此步骤（极简模式跳过需求收集）。');
+    return;
+  }
+
   const missingSteps = getMissingPrereqs(workflow, STEP_NUMBER);
   if (missingSteps && missingSteps.length > 0 && !options.force) {
     printWarning(`请先完成步骤 ${missingSteps.join(', ')} 后再继续。`);

package/src/commands/init.mjs

@@ -13,6 +13,12 @@ import {
 } from '../lib/config.mjs';
 import { initWorkflow } from '../lib/workflow.mjs';
 import { updateProjectAgentsFile } from '../lib/agents.mjs';
+import {
+  syncToProject,
+  syncToGlobal,
+  getSupportedIDEs,
+  getIDEConfig,
+} from '../lib/ide-sync.mjs';
 import {
   colors,
   colorize,
@@ -22,8 +28,82 @@ import {
   printInfo,
   prompt,
   confirm,
+  select,
 } from '../lib/terminal.mjs';
 
+/**
+ * Sync IDE commands helper
+ * @param {string} cwd - Current working directory
+ */
+async function syncIDECommands(cwd) {
+  print('');
+  print(colorize('IDE 命令同步', colors.bold, colors.cyan));
+  print(colorize('─────────────', colors.dim));
+  print('');
+
+  // Ask which IDE to sync
+  const ideChoice = await select({
+    message: '选择要同步的 IDE',
+    choices: [
+      { name: 'Cursor', value: 'cursor' },
+      { name: 'Claude Code', value: 'claude' },
+      { name: '全部 (Cursor + Claude Code)', value: 'all' },
+    ]
+  });
+
+  // Ask for sync scope
+  const scopeChoice = await select({
+    message: '选择同步范围',
+    choices: [
+      { name: '项目级 (仅当前项目)', value: 'project' },
+      { name: '全局级 (所有项目)', value: 'global' },
+    ]
+  });
+
+  const isGlobal = scopeChoice === 'global';
+
+  // Determine which IDEs to sync
+  const idesToSync = ideChoice === 'all' ? getSupportedIDEs() : [ideChoice];
+  let syncCount = 0;
+
+  for (const ide of idesToSync) {
+    const config = getIDEConfig(ide);
+    try {
+      let count;
+      if (isGlobal) {
+        count = syncToGlobal(ide);
+      } else {
+        count = syncToProject(ide, cwd);
+      }
+      
+      syncCount += count;
+      const targetDir = isGlobal ? config.globalDir : path.join(cwd, config.projectDir);
+      printInfo(`已同步 ${count} 个命令到 ${config.name}: ${targetDir}`);
+    } catch (error) {
+      printWarning(`同步 ${config.name} 命令失败: ${error.message}`);
+    }
+  }
+
+  print('');
+  printSuccess(`IDE 命令同步完成! 共同步 ${syncCount} 个命令文件`);
+  print('');
+  print(colorize('可用的 IDE 命令:', colors.bold));
+  print(colorize(`  /incspec/inc-analyze    - 步骤1: 分析代码流程`, colors.dim));
+  print(colorize(`  /incspec/inc-collect-req - 步骤2: 收集结构化需求`, colors.dim));
+  print(colorize(`  /incspec/inc-collect-dep - 步骤3: 采集UI依赖`, colors.dim));
+  print(colorize(`  /incspec/inc-design      - 步骤4: 增量设计`, colors.dim));
+  print(colorize(`  /incspec/inc-apply       - 步骤5: 应用代码变更`, colors.dim));
+  print(colorize(`  /incspec/inc-merge       - 步骤6: 合并到基线`, colors.dim));
+  print(colorize(`  /incspec/inc-archive     - 步骤7: 归档产出`, colors.dim));
+  print(colorize(`  /incspec/inc-status      - 查看工作流状态`, colors.dim));
+  print(colorize(`  /incspec/inc-help        - 显示帮助信息`, colors.dim));
+  print('');
+  print(colorize('下一步:', colors.bold));
+  print(colorize(`  1. 运行 'incspec status' 查看工作流状态`, colors.dim));
+  print(colorize(`  2. 使用 /incspec/inc-analyze 开始第一个工作流`, colors.dim));
+  print('');
+}
+
 /**
  * Execute init command
  * @param {Object} ctx - Command context
@@ -109,7 +189,7 @@ export async function initCommand(ctx) {
   print(colorize('创建的目录结构:', colors.bold));
   print(colorize(`  ${INCSPEC_DIR}/`, colors.cyan));
   print(colorize(`  ├── project.md`, colors.dim));
-  print(colorize(`  ├── WORKFLOW.md`, colors.dim));
+  print(colorize(`  ├── workflow.json`, colors.dim));
   print(colorize(`  ├── AGENTS.md`, colors.dim));
   print(colorize(`  ├── baselines/`, colors.dim));
   print(colorize(`  ├── requirements/`, colors.dim));
@@ -119,9 +199,18 @@ export async function initCommand(ctx) {
   print(colorize(`  AGENTS.md (项目根目录)`, colors.cyan));
   print(colorize(`  └── incspec 指令块已添加`, colors.dim));
   print('');
-  print(colorize('下一步:', colors.bold));
-  print(colorize(`  1. 运行 'incspec status' 查看工作流状态`, colors.dim));
-  print(colorize(`  2. 运行 'incspec sync' 同步 Cursor 命令`, colors.dim));
-  print(colorize(`  3. 使用 /incspec/inc-analyze 开始第一个工作流`, colors.dim));
-  print('');
+
+  // Ask user if they want to sync IDE commands
+  const shouldSync = await confirm('是否立即同步 IDE 命令?');
+
+  if (shouldSync) {
+    await syncIDECommands(cwd);
+  } else {
+    print('');
+    print(colorize('下一步:', colors.bold));
+    print(colorize(`  1. 运行 'incspec status' 查看工作流状态`, colors.dim));
+    print(colorize(`  2. 运行 'incspec sync' 同步 IDE 命令`, colors.dim));
+    print(colorize(`  3. 使用 /incspec/inc-analyze 开始第一个工作流`, colors.dim));
+    print('');
+  }
 }

package/src/commands/merge.mjs

@@ -14,6 +14,7 @@ import {
   updateStep,
   STATUS,
   isQuickMode,
+  isStepAllowed,
   getMissingPrereqs,
 } from '../lib/workflow.mjs';
 import { listSpecs, getNextVersion } from '../lib/spec.mjs';
@@ -61,6 +62,10 @@ export async function mergeCommand(ctx) {
       printWarning('没有活跃的工作流，无法标记完成。');
       return;
     }
+    if (!isStepAllowed(STEP_NUMBER, workflow.mode)) {
+      printWarning('当前工作流模式不包含此步骤，无需标记完成。');
+      return;
+    }
     const output = typeof options.output === 'string' ? options.output : null;
     if (!output) {
       printWarning('请通过 --output 指定输出文件名。');
@@ -76,6 +81,12 @@ export async function mergeCommand(ctx) {
     return;
   }
 
+  if (!isStepAllowed(STEP_NUMBER, workflow.mode)) {
+    printWarning('当前工作流模式不包含此步骤（极简模式跳过合并基线）。');
+    printInfo('极简模式下可在归档前使用 incspec upgrade quick 升级模式后执行合并。');
+    return;
+  }
+
   const quickMode = isQuickMode(workflow);
   const missingSteps = getMissingPrereqs(workflow, STEP_NUMBER);
   if (missingSteps && missingSteps.length > 0 && !options.force) {

package/src/commands/update.mjs

@@ -1,6 +1,6 @@
 /**
  * update command - Update template files to latest version
- * Updates AGENTS.md, WORKFLOW.md in incspec/ and managed block in project AGENTS.md
+ * Updates AGENTS.md, workflow.json in incspec/ and managed block in project AGENTS.md
  */
 
 import * as fs from 'fs';
@@ -53,19 +53,19 @@ function updateIncspecAgents(projectRoot) {
 }
 
 /**
- * Update incspec/WORKFLOW.md template structure while preserving user data
+ * Update incspec/workflow.json template structure while preserving user data
  * @param {string} projectRoot
  * @returns {{updated: boolean, path: string}}
  */
 function updateIncspecWorkflow(projectRoot) {
   const targetPath = path.join(getIncspecDir(projectRoot), FILES.workflow);
-  const templatePath = path.join(getTemplatesDir(), 'WORKFLOW.md');
+  const templatePath = path.join(getTemplatesDir(), 'workflow.json');
 
   if (!fs.existsSync(templatePath)) {
     return { updated: false, path: targetPath, error: '模板文件不存在' };
   }
 
-  // For WORKFLOW.md, we only update if file doesn't exist
+  // For workflow.json, we only update if file doesn't exist
   // Because it contains dynamic user data that we don't want to overwrite
   // The template is only used for initial structure
   if (fs.existsSync(targetPath)) {
@@ -104,7 +104,7 @@ export async function updateCommand(ctx) {
   // List what will be updated
   print(colorize('将更新以下模板文件:', colors.bold));
   print(colorize('  - incspec/AGENTS.md (incspec 使用指南)', colors.dim));
-  print(colorize('  - incspec/WORKFLOW.md (工作流模板，保留用户数据)', colors.dim));
+  print(colorize('  - incspec/workflow.json (工作流状态，保留用户数据)', colors.dim));
   print(colorize('  - AGENTS.md (项目根目录 incspec 指令块)', colors.dim));
   print('');
 
@@ -128,10 +128,10 @@ export async function updateCommand(ctx) {
     ...agentsResult,
   });
 
-  // Update incspec/WORKFLOW.md
+  // Update incspec/workflow.json
   const workflowResult = updateIncspecWorkflow(projectRoot);
   results.push({
-    file: 'incspec/WORKFLOW.md',
+    file: 'incspec/workflow.json',
     ...workflowResult,
   });
 

package/src/lib/CLAUDE.md

@@ -0,0 +1,7 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+*No recent activity*
+</claude-mem-context>

package/src/lib/config.mjs

@@ -24,7 +24,8 @@ export const DIRS = {
 /** Core files */
 export const FILES = {
   project: 'project.md',
-  workflow: 'WORKFLOW.md',
+  workflow: 'workflow.json',
+  workflowLegacy: 'WORKFLOW.md',
   agents: 'AGENTS.md',
 };
 

package/src/lib/ide-sync.mjs

@@ -9,6 +9,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { fileURLToPath } from 'url';
 import { INCSPEC_DIR } from './config.mjs';
+import { MODE_CONFIG, MODE_UPGRADE_ORDER } from './mode-utils.mjs';
 
 /** Built-in templates directory */
 const TEMPLATES_DIR = fileURLToPath(new URL('../templates/commands', import.meta.url));
@@ -114,35 +115,59 @@ function getSourcePath(fileName, fallbackDirs = []) {
 }
 
 /**
- * Generate utility commands content
- * @returns {Array<{name: string, content: string}>}
+ * Generate mode sections for help content
+ * Shows all 7 workflow steps with their mode indicators
+ * @returns {string}
  */
-function generateUtilityCommands() {
-  return [
-    {
-      name: 'inc-status.md',
-      content: `---
-description: [incspec] 查看当前工作流状态
----
+function generateModeSections() {
+  const lines = [];
+
+  // Step info: command, description, and which modes support it
+  const steps = [
+    { cmd: 'inc-analyze', desc: '分析代码流程,生成基线快照', modes: ['full', 'quick', 'minimal'] },
+    { cmd: 'inc-collect-req', desc: '收集结构化需求', modes: ['full', 'quick'] },
+    { cmd: 'inc-collect-dep', desc: '采集UI依赖', modes: ['full'] },
+    { cmd: 'inc-design', desc: '生成增量设计蓝图', modes: ['full'] },
+    { cmd: 'inc-apply', desc: '应用代码变更', modes: ['full', 'quick', 'minimal'] },
+    { cmd: 'inc-merge', desc: '合并到新基线', modes: ['full', 'quick'] },
+    { cmd: 'inc-archive', desc: '归档工作流产出', modes: ['full', 'quick', 'minimal'] }
+  ];
 
-# 查看工作流状态
+  // Generate all 7 steps with mode indicators
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const stepNum = i + 1;
 
-请运行以下命令查看当前工作流状态:
+    let cmdLine;
+    if (step.modes.length === 3) {
+      cmdLine = `\`/incspec/${step.cmd}\``;
+    } else if (step.modes.includes('full') && step.modes.includes('quick')) {
+      cmdLine = `\`/incspec/${step.cmd}\` (完整/快速)`;
+    } else {
+      cmdLine = `\`/incspec/${step.cmd}\` (完整)`;
+    }
 
-\`\`\`bash
-incspec status
-\`\`\`
+    lines.push(`${stepNum}. ${cmdLine} - ${step.desc}`);
+  }
 
-或直接读取状态文件:
+  return lines.join('\n');
+}
 
-\`\`\`bash
-cat ${INCSPEC_DIR}/WORKFLOW.md
-\`\`\`
-`,
-    },
-    {
-      name: 'inc-help.md',
-      content: `---
+/**
+ * Generate utility commands content
+ * @returns {Array<{name: string, content: string}>}
+ */
+function generateUtilityCommands() {
+  // Generate help content from template
+  const helpTemplatePath = path.join(TEMPLATES_DIR, 'inc-help.md');
+  let helpContent;
+
+  if (fs.existsSync(helpTemplatePath)) {
+    const template = fs.readFileSync(helpTemplatePath, 'utf-8');
+    helpContent = template.replace('<!-- MODE_SECTIONS -->', generateModeSections());
+  } else {
+    // Fallback: generate complete content inline
+    helpContent = `---
 description: [incspec] 显示帮助信息
 ---
 
@@ -150,22 +175,7 @@ description: [incspec] 显示帮助信息
 
 ## 工作流步骤
 
-**完整模式 (7步):**
-1. \`/incspec/inc-analyze\` - 分析代码流程,生成基线快照
-2. \`/incspec/inc-collect-req\` - 收集结构化需求
-3. \`/incspec/inc-collect-dep\` - 采集UI依赖
-4. \`/incspec/inc-design\` - 生成增量设计蓝图
-5. \`/incspec/inc-apply\` - 应用代码变更
-6. \`/incspec/inc-merge\` - 合并到新基线
-7. \`/incspec/inc-archive\` - 归档工作流产出
-
-**快速模式 (5步):**
-1. \`/incspec/inc-analyze --quick\` - 分析代码流程 (快速模式)
-2. \`/incspec/inc-collect-req\` - 收集结构化需求
-5. \`/incspec/inc-apply\` - 应用代码变更
-6. \`/incspec/inc-merge\` - 合并到新基线
-7. \`/incspec/inc-archive\` - 归档工作流产出
-
+${generateModeSections()}
 ## 辅助命令
 
 - \`/incspec/inc-status\` - 查看当前工作流状态
@@ -187,14 +197,41 @@ incspec help          # 显示帮助
 \`\`\`
 ${INCSPEC_DIR}/
 ├── project.md        # 项目配置
-├── WORKFLOW.md       # 工作流状态
+├── workflow.json     # 工作流状态
 ├── baselines/        # 基线快照
 ├── requirements/     # 需求文档
 ├── increments/       # 增量设计
 └── archives/         # 历史归档 (YYYY-MM/{module}/)
 \`\`\`
+`;
+  }
+
+  return [
+    {
+      name: 'inc-status.md',
+      content: `---
+description: [incspec] 查看当前工作流状态
+---
+
+# 查看工作流状态
+
+请运行以下命令查看当前工作流状态:
+
+\`\`\`bash
+incspec status
+\`\`\`
+
+或直接读取状态文件:
+
+\`\`\`bash
+cat ${INCSPEC_DIR}/workflow.json
+\`\`\`
 `,
     },
+    {
+      name: 'inc-help.md',
+      content: helpContent,
+    },
   ];
 }
 

package/src/lib/workflow.mjs

@@ -1,6 +1,6 @@
 /**
  * Workflow state management for incspec
- * - Read/write WORKFLOW.md
+ * - Read/write workflow.json
  * - Track current step
  * - Manage workflow history
  */
@@ -54,67 +54,8 @@ function normalizeOutputName(outputFile) {
   return parts[parts.length - 1] || outputFile;
 }
 
-function ensureTableSeparator(content, sectionTitle, headerLine, separatorLine) {
-  const sectionIndex = content.indexOf(sectionTitle);
-  if (sectionIndex === -1) {
-    return { content, updated: false };
-  }
-
-  const headerIndex = content.indexOf(headerLine, sectionIndex);
-  if (headerIndex === -1) {
-    return { content, updated: false };
-  }
-
-  const headerLineEnd = content.indexOf('\n', headerIndex);
-  if (headerLineEnd === -1) {
-    return { content, updated: false };
-  }
-
-  const nextLineStart = headerLineEnd + 1;
-  const nextLineEnd = content.indexOf('\n', nextLineStart);
-  const nextLine = content
-    .slice(nextLineStart, nextLineEnd === -1 ? content.length : nextLineEnd)
-    .replace(/\r$/, '');
-
-  if (nextLine.trim() === separatorLine.trim()) {
-    return { content, updated: false };
-  }
-
-  const updatedContent =
-    content.slice(0, nextLineStart) +
-    `${separatorLine}\n` +
-    content.slice(nextLineStart);
-
-  return { content: updatedContent, updated: true };
-}
-
-function normalizeWorkflowContent(content) {
-  let updated = false;
-  let normalized = content;
-
-  const stepsResult = ensureTableSeparator(
-    normalized,
-    '## 步骤进度',
-    '| 步骤 | 状态 | 输出文件 | 完成时间 |',
-    '|------|------|---------|---------|'
-  );
-  normalized = stepsResult.content;
-  updated = updated || stepsResult.updated;
-
-  const historyResult = ensureTableSeparator(
-    normalized,
-    '## 工作流历史',
-    '| 工作流 | 状态 | 开始时间 | 完成时间 |',
-    '|--------|------|---------|---------|'
-  );
-  normalized = historyResult.content;
-  updated = updated || historyResult.updated;
-
-  return { content: normalized, updated };
-}
-
 /**
- * Get workflow file path
+ * Get workflow file path (JSON format)
  * @param {string} projectRoot
  * @returns {string}
  */
@@ -123,11 +64,20 @@ export function getWorkflowPath(projectRoot) {
 }
 
 /**
- * Parse WORKFLOW.md content
+ * Get legacy workflow file path (Markdown format)
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+function getLegacyWorkflowPath(projectRoot) {
+  return path.join(projectRoot, INCSPEC_DIR, FILES.workflowLegacy);
+}
+
+/**
+ * Parse legacy WORKFLOW.md content (for migration)
  * @param {string} content
  * @returns {Object}
  */
-export function parseWorkflow(content) {
+function parseMarkdownWorkflow(content) {
   const workflow = {
     currentWorkflow: null,
     currentStep: null,
@@ -167,7 +117,8 @@ export function parseWorkflow(content) {
 
   const startMatch = content.match(/\*\*开始时间\*\*:\s*(.+)/);
   if (startMatch) {
-    workflow.startTime = startMatch[1].trim();
+    const value = startMatch[1].trim();
+    workflow.startTime = value === '-' ? null : value;
   }
 
   const updateMatch = content.match(/\*\*最后更新\*\*:\s*(.+)/);
@@ -179,11 +130,12 @@ export function parseWorkflow(content) {
   const stepsTableMatch = content.match(/## 步骤进度\n\n\|[^\n]+\n\|[^\n]+\n([\s\S]*?)(?=\n##|\n*$)/);
   if (stepsTableMatch) {
     const rows = stepsTableMatch[1].trim().split('\n').filter(r => r.trim());
-    workflow.steps = rows.map(row => {
+    workflow.steps = rows.map((row, index) => {
       const cells = row.split('|').map(c => c.trim()).filter(c => c);
       if (cells.length >= 4) {
         return {
-          step: cells[0],
+          id: index + 1,
+          name: STEPS[index]?.name || `step-${index + 1}`,
           status: cells[1],
           output: cells[2] === '-' ? null : cells[2],
           completedAt: cells[3] === '-' ? null : cells[3],
@@ -193,6 +145,18 @@ export function parseWorkflow(content) {
     }).filter(Boolean);
   }
 
+  // Ensure we have all 7 steps
+  while (workflow.steps.length < STEPS.length) {
+    const index = workflow.steps.length;
+    workflow.steps.push({
+      id: index + 1,
+      name: STEPS[index].name,
+      status: STATUS.PENDING,
+      output: null,
+      completedAt: null,
+    });
+  }
+
   // Parse history table
   const historyMatch = content.match(/## 工作流历史\n\n\|[^\n]+\n\|[^\n]+\n([\s\S]*?)(?=\n##|\n*$)/);
   if (historyMatch) {
@@ -214,12 +178,80 @@ export function parseWorkflow(content) {
   return workflow;
 }
 
+/**
+ * Migrate from WORKFLOW.md to workflow.json
+ * @param {string} projectRoot
+ * @returns {Object|null} Migrated workflow or null if no migration needed
+ */
+function migrateFromMarkdown(projectRoot) {
+  const legacyPath = getLegacyWorkflowPath(projectRoot);
+  const jsonPath = getWorkflowPath(projectRoot);
+
+  // Check if legacy file exists and JSON doesn't
+  if (!fs.existsSync(legacyPath)) {
+    return null;
+  }
+
+  if (fs.existsSync(jsonPath)) {
+    // JSON already exists, no migration needed
+    return null;
+  }
+
+  // Read and parse legacy file
+  const content = fs.readFileSync(legacyPath, 'utf-8');
+  const workflow = parseMarkdownWorkflow(content);
+
+  // Update lastUpdate
+  workflow.lastUpdate = formatLocalDateTime(new Date());
+
+  // Write new JSON file
+  const jsonContent = JSON.stringify(workflow, null, 2);
+  fs.writeFileSync(jsonPath, jsonContent, 'utf-8');
+
+  // Delete legacy file
+  fs.unlinkSync(legacyPath);
+
+  console.log(`已将 WORKFLOW.md 迁移到 workflow.json`);
+
+  return workflow;
+}
+
+/**
+ * Parse workflow.json content
+ * @param {string} content - JSON string
+ * @returns {Object}
+ */
+export function parseWorkflow(content) {
+  try {
+    const workflow = JSON.parse(content);
+
+    // Ensure all required fields exist with defaults
+    return {
+      currentWorkflow: workflow.currentWorkflow ?? null,
+      currentStep: workflow.currentStep ?? null,
+      mode: workflow.mode ?? MODE.FULL,
+      startTime: workflow.startTime ?? null,
+      lastUpdate: workflow.lastUpdate ?? null,
+      steps: workflow.steps ?? [],
+      history: workflow.history ?? [],
+    };
+  } catch (e) {
+    throw new Error(`解析 workflow.json 失败: ${e.message}`);
+  }
+}
+
 /**
  * Read workflow state
  * @param {string} projectRoot
  * @returns {Object|null}
  */
 export function readWorkflow(projectRoot) {
+  // Try migration first
+  const migrated = migrateFromMarkdown(projectRoot);
+  if (migrated) {
+    return migrated;
+  }
+
   const workflowPath = getWorkflowPath(projectRoot);
 
   if (!fs.existsSync(workflowPath)) {
@@ -227,12 +259,11 @@ export function readWorkflow(projectRoot) {
   }
 
   const content = fs.readFileSync(workflowPath, 'utf-8');
-  const normalized = normalizeWorkflowContent(content);
-  return parseWorkflow(normalized.content);
+  return parseWorkflow(content);
 }
 
 /**
- * Generate WORKFLOW.md content
+ * Generate workflow.json content
  * @param {Object} workflow
  * @returns {string}
  */
@@ -240,44 +271,29 @@ export function generateWorkflowContent(workflow) {
   const now = formatLocalDateTime(new Date());
   const mode = workflow.mode || MODE.FULL;
 
-  const lines = [
-    '# Workflow Status',
-    '',
-    `**当前工作流**: ${workflow.currentWorkflow || '-'}`,
-    `**当前步骤**: ${workflow.currentStep || '-'}`,
-    `**工作流模式**: ${mode}`,
-    `**开始时间**: ${workflow.startTime || '-'}`,
-    `**最后更新**: ${now}`,
-    '',
-    '## 步骤进度',
-    '',
-    '| 步骤 | 状态 | 输出文件 | 完成时间 |',
-    '|------|------|---------|---------|',
-  ];
-
-  // Generate steps
-  STEPS.forEach((step, index) => {
+  // Ensure steps have proper structure
+  const steps = STEPS.map((step, index) => {
     const stepData = workflow.steps[index] || {};
-    const status = stepData.status || STATUS.PENDING;
-    const output = stepData.output || '-';
-    const completedAt = stepData.completedAt || '-';
-    lines.push(`| ${step.id}. ${step.name} | ${status} | ${output} | ${completedAt} |`);
+    return {
+      id: step.id,
+      name: step.name,
+      status: stepData.status || STATUS.PENDING,
+      output: stepData.output || null,
+      completedAt: stepData.completedAt || null,
+    };
   });
 
-  lines.push('');
-  lines.push('## 工作流历史');
-  lines.push('');
-  lines.push('| 工作流 | 状态 | 开始时间 | 完成时间 |');
-  lines.push('|--------|------|---------|---------|');
-
-  // Generate history
-  if (workflow.history && workflow.history.length > 0) {
-    workflow.history.forEach(item => {
-      lines.push(`| ${item.name} | ${item.status} | ${item.startTime || '-'} | ${item.endTime || '-'} |`);
-    });
-  }
+  const data = {
+    currentWorkflow: workflow.currentWorkflow || null,
+    currentStep: workflow.currentStep || null,
+    mode: mode,
+    startTime: workflow.startTime || null,
+    lastUpdate: now,
+    steps: steps,
+    history: workflow.history || [],
+  };
 
-  return lines.join('\n');
+  return JSON.stringify(data, null, 2);
 }
 
 /**
@@ -297,45 +313,17 @@ export function writeWorkflow(projectRoot, workflow) {
  */
 export function initWorkflow(projectRoot) {
   const workflowPath = getWorkflowPath(projectRoot);
-  const content = generateInitialWorkflowContent();
-  fs.writeFileSync(workflowPath, content, 'utf-8');
-
-  return {
-    currentWorkflow: null,
-    currentStep: null,
-    mode: MODE.FULL,
-    startTime: null,
-    lastUpdate: null,
-    steps: STEPS.map(() => ({
-      status: STATUS.PENDING,
-      output: null,
-      completedAt: null,
-    })),
-    history: [],
-  };
-}
-
-/**
- * Generate initial WORKFLOW.md content from template
- * @returns {string}
- */
-function generateInitialWorkflowContent() {
-  const templatePath = path.join(getTemplatesDir(), 'WORKFLOW.md');
   const now = formatLocalDateTime(new Date());
 
-  if (fs.existsSync(templatePath)) {
-    let content = fs.readFileSync(templatePath, 'utf-8');
-    content = content.replace(/\{\{last_update\}\}/g, now);
-    return content;
-  }
-
-  // Fallback to generated content
   const workflow = {
     currentWorkflow: null,
     currentStep: null,
+    mode: MODE.FULL,
     startTime: null,
-    lastUpdate: null,
-    steps: STEPS.map(() => ({
+    lastUpdate: now,
+    steps: STEPS.map((step) => ({
+      id: step.id,
+      name: step.name,
       status: STATUS.PENDING,
       output: null,
       completedAt: null,
@@ -343,7 +331,10 @@ function generateInitialWorkflowContent() {
     history: [],
   };
 
-  return generateWorkflowContent(workflow);
+  const content = JSON.stringify(workflow, null, 2);
+  fs.writeFileSync(workflowPath, content, 'utf-8');
+
+  return workflow;
 }
 
 /**
@@ -391,12 +382,16 @@ export function startWorkflow(projectRoot, workflowName, options = {}) {
   workflow.steps = STEPS.map((step) => {
     if (skippedSteps.includes(step.id)) {
       return {
+        id: step.id,
+        name: step.name,
         status: STATUS.SKIPPED,
         output: null,
         completedAt: now,
       };
     }
     return {
+      id: step.id,
+      name: step.name,
       status: STATUS.PENDING,
       output: null,
       completedAt: null,
@@ -430,6 +425,8 @@ export function updateStep(projectRoot, stepNumber, status, outputFile = null) {
   const mode = workflow.mode || MODE.FULL;
 
   workflow.steps[index] = {
+    id: stepNumber,
+    name: STEPS[index].name,
     status,
     output: normalizedOutput,
     completedAt: status === STATUS.COMPLETED ? now : null,
@@ -494,14 +491,16 @@ export function archiveWorkflow(projectRoot) {
   workflow.history.unshift({
     name: workflow.currentWorkflow,
     status: 'archived',
-    startTime: workflow.startTime || '-',
+    startTime: workflow.startTime || null,
     endTime: now,
   });
 
   workflow.currentWorkflow = null;
   workflow.currentStep = null;
   workflow.startTime = null;
-  workflow.steps = STEPS.map(() => ({
+  workflow.steps = STEPS.map((step) => ({
+    id: step.id,
+    name: step.name,
     status: STATUS.PENDING,
     output: null,
     completedAt: null,
@@ -563,12 +562,16 @@ export function resetToStep(projectRoot, targetStep) {
     // Keep skipped steps as skipped based on mode
     if (skippedSteps.includes(stepNumber)) {
       workflow.steps[i] = {
+        id: stepNumber,
+        name: STEPS[i].name,
         status: STATUS.SKIPPED,
         output: null,
         completedAt: workflow.steps[i]?.completedAt || now,
       };
     } else {
       workflow.steps[i] = {
+        id: stepNumber,
+        name: STEPS[i].name,
         status: STATUS.PENDING,
         output: null,
         completedAt: null,
@@ -676,9 +679,12 @@ export function addToHistory(projectRoot, entry) {
     workflow = {
       currentWorkflow: null,
       currentStep: null,
+      mode: MODE.FULL,
       startTime: null,
       lastUpdate: null,
-      steps: STEPS.map(() => ({
+      steps: STEPS.map((step) => ({
+        id: step.id,
+        name: step.name,
         status: STATUS.PENDING,
         output: null,
         completedAt: null,
@@ -692,7 +698,7 @@ export function addToHistory(projectRoot, entry) {
   workflow.history.unshift({
     name: entry.name,
     status: entry.status,
-    startTime: entry.startTime || '-',
+    startTime: entry.startTime || null,
     endTime: entry.endTime || now,
   });
 

package/src/templates/AGENTS.md

@@ -1,5 +1,7 @@
 # IncSpec 使用指南
 
+> **核心定位**: CLI 工具仅用于工作流状态的跟踪记录和流程串联。**每个步骤的具体执行内容**（如代码分析、需求收集、UI依赖收集、增量设计、应用代码等）**应由用户指定的 Agent（Cursor、Claude Code） 根据对应指令完成**。
+
 AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
 
 ## 快速检查清单
@@ -154,7 +156,7 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
 ```
 incspec/
 ├── project.md              # 项目配置
-├── WORKFLOW.md             # 工作流状态
+├── workflow.json           # 工作流状态
 ├── AGENTS.md               # 本指南
 ├── baselines/              # 基线快照 (版本控制)
 ├── requirements/           # 需求与依赖

package/src/templates/CLAUDE.md

@@ -0,0 +1,12 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+### Jan 8, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #105 | 2:48 PM | 🔵 | 发现模板文件目录结构 | ~96 |
+| #94 | 2:40 PM | 🔵 | 发现 IncSpec 模板文件结构 | ~62 |
+</claude-mem-context>

package/src/templates/commands/CLAUDE.md

@@ -0,0 +1,11 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+### Jan 8, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #106 | 3:07 PM | 🔵 | 完成对 inc-help.md 写入机制的深度分析 | ~130 |
+</claude-mem-context>

package/src/templates/commands/inc-archive.md

@@ -145,11 +145,10 @@ ls -la incspec/archives/2025-12/  # 当月目录
 ### 4.2 检查工作流历史
 
 ```bash
-cat incspec/WORKFLOW.md
+cat incspec/workflow.json
 ```
 
 确认工作流历史已更新，包含工作流级别的归档记录（不是文件级别）。
-如果仅归档部分文件且本工作流尚未全部归档，工作流历史不应新增记录。
 
 ### 4.3 运行验证
 
@@ -265,7 +264,7 @@ incspec archive --workflow --yes
 1. **完成后归档**: 在完成工作流后及时归档，保持工作目录整洁
 2. **默认移动模式**: 默认会删除原文件，保持工作流干净；如需保留原文件使用 `--keep`
 3. **批量归档**: 工作流完成后，一次性归档所有相关文件
-4. **检查历史**: 归档后检查 WORKFLOW.md 确认记录正确
+4. **检查历史**: 归档后检查 workflow.json 确认记录正确
 
 # 错误处理
 

package/src/templates/commands/inc-help.md

@@ -0,0 +1,37 @@
+---
+description: [incspec] 显示帮助信息
+---
+
+# incspec 帮助
+
+## 工作流步骤
+
+<!-- MODE_SECTIONS -->
+
+## 辅助命令
+
+- `/incspec/inc-status` - 查看当前工作流状态
+- `/incspec/inc-help` - 显示帮助信息
+
+## CLI 命令
+
+```bash
+incspec init          # 初始化项目
+incspec status        # 查看工作流状态
+incspec list          # 列出规范文件
+incspec validate      # 验证规范完整性
+incspec sync          # 同步 IDE 命令
+incspec help          # 显示帮助
+```
+
+## 目录结构
+
+```
+incspec/
+├── project.md        # 项目配置
+├── workflow.json     # 工作流状态
+├── baselines/        # 基线快照
+├── requirements/     # 需求文档
+├── increments/       # 增量设计
+└── archives/         # 历史归档 (YYYY-MM/{module}/)
+```

package/src/templates/commands/inc-upgrade.md

@@ -67,10 +67,10 @@ incspec upgrade <target-mode>
 incspec status
 ```
 
-或直接读取 WORKFLOW.md:
+或直接读取 workflow.json:
 
 ```bash
-cat incspec/WORKFLOW.md
+cat incspec/workflow.json
 ```
 
 检查:
@@ -112,10 +112,10 @@ cat incspec/WORKFLOW.md
 
 ### 3.1 检查当前工作流进度
 
-读取 WORKFLOW.md 检查哪些步骤已完成:
+读取 workflow.json 检查哪些步骤已完成:
 
 ```bash
-cat incspec/WORKFLOW.md | grep -A 20 "## 当前工作流"
+cat incspec/workflow.json
 ```
 
 ### 3.2 按顺序引导补充步骤
@@ -214,7 +214,7 @@ incspec upgrade <target-mode>
 
 CLI 会:
 1. 验证所有必需步骤已完成
-2. 更新 WORKFLOW.md 中的模式标记
+2. 更新 workflow.json 中的模式标记
 3. 输出升级成功确认
 
 ## 步骤 5: 验证结果

package/src/templates/workflow.json

@@ -0,0 +1,59 @@
+{
+  "currentWorkflow": null,
+  "currentStep": null,
+  "mode": "full",
+  "startTime": null,
+  "lastUpdate": "{{last_update}}",
+  "steps": [
+    {
+      "id": 1,
+      "name": "analyze-codeflow",
+      "status": "pending",
+      "output": null,
+      "completedAt": null
+    },
+    {
+      "id": 2,
+      "name": "collect-requirements",
+      "status": "pending",
+      "output": null,
+      "completedAt": null
+    },
+    {
+      "id": 3,
+      "name": "collect-dependencies",
+      "status": "pending",
+      "output": null,
+      "completedAt": null
+    },
+    {
+      "id": 4,
+      "name": "design-increment",
+      "status": "pending",
+      "output": null,
+      "completedAt": null
+    },
+    {
+      "id": 5,
+      "name": "apply-code",
+      "status": "pending",
+      "output": null,
+      "completedAt": null
+    },
+    {
+      "id": 6,
+      "name": "merge-baseline",
+      "status": "pending",
+      "output": null,
+      "completedAt": null
+    },
+    {
+      "id": 7,
+      "name": "archive-workflow",
+      "status": "pending",
+      "output": null,
+      "completedAt": null
+    }
+  ],
+  "history": []
+}

package/src/templates/WORKFLOW.md

@@ -1,31 +0,0 @@
-# Workflow Status
-
-**当前工作流**: -
-**当前步骤**: -
-**工作流模式**: full
-**开始时间**: -
-**最后更新**: {{last_update}}
-
-<!-- 
-工作流模式说明:
-- full: 完整模式 (7步) - 适合复杂功能开发
-- quick: 快速模式 (5步) - 跳过步骤3,4，适合Bug修复和简单功能
-- minimal: 极简模式 (3步) - 跳过步骤2,3,4,6，适合紧急修复或单文件小改动
--->
-
-## 步骤进度
-
-| 步骤 | 状态 | 输出文件 | 完成时间 |
-|------|------|---------|---------|
-| 1. analyze-codeflow | pending | - | - |
-| 2. collect-requirements | pending | - | - |
-| 3. collect-dependencies | pending | - | - |
-| 4. design-increment | pending | - | - |
-| 5. apply-code | pending | - | - |
-| 6. merge-baseline | pending | - | - |
-| 7. archive-workflow | pending | - | - |
-
-## 工作流历史
-
-| 工作流 | 状态 | 开始时间 | 完成时间 |
-|--------|------|---------|---------|