@localsummer/incspec 0.1.0 → 0.1.2

package/README.md

@@ -4,6 +4,7 @@
 <p align="center">面向 AI 编程助手的增量规范驱动开发工具</p>
 <p align="center">
   <a href="https://github.com/localSummer/IncSpec"><img alt="GitHub" src="https://img.shields.io/badge/GitHub-localSummer%2FIncSpec-blue?style=flat-square&logo=github" /></a>
+  <a href="https://www.npmjs.com/package/@localsummer/incspec"><img alt="npm" src="https://img.shields.io/npm/v/@localsummer/incspec?style=flat-square&logo=npm" /></a>
   <a href="https://nodejs.org/"><img alt="node version" src="https://img.shields.io/node/v/@localsummer/incspec?style=flat-square" /></a>
   <a href="./LICENSE"><img alt="License: ISC" src="https://img.shields.io/badge/License-ISC-blue.svg?style=flat-square" /></a>
 </p>

package/commands/init.mjs

@@ -121,7 +121,7 @@ export async function initCommand(ctx) {
   print('');
   print(colorize('下一步:', colors.bold));
   print(colorize(`  1. 运行 'incspec status' 查看工作流状态`, colors.dim));
-  print(colorize(`  2. 运行 'incspec cursor-sync' 同步 Cursor 命令`, colors.dim));
+  print(colorize(`  2. 运行 'incspec sync' 同步 Cursor 命令`, colors.dim));
   print(colorize(`  3. 使用 /incspec/inc-analyze 开始第一个工作流`, colors.dim));
   print('');
 }

package/commands/sync.mjs

@@ -114,12 +114,12 @@ async function syncCursor(ctx) {
       {
         name: `当前目录 (${cwd}/.cursor/commands/incspec/)`,
         value: 'project',
-        description: '仅对当前目录生效',
+        description: colorize('仅对当前目录生效', colors.blue),
       },
       {
         name: '全局目录 (~/.cursor/commands/incspec/)',
         value: 'global',
-        description: '对所有项目生效',
+        description: colorize('对所有项目生效', colors.blue),
       },
     ];
 
@@ -182,12 +182,12 @@ async function syncClaude(ctx) {
       {
         name: `当前目录 (${cwd}/.claude/skills/inc-spec-skill/)`,
         value: 'project',
-        description: '仅对当前目录生效',
+        description: colorize('仅对当前目录生效', colors.blue),
       },
       {
         name: '全局目录 (~/.claude/skills/inc-spec-skill/)',
         value: 'global',
-        description: '对所有项目生效（推荐）',
+        description: colorize('对所有项目生效（推荐）', colors.blue),
       },
     ];
 

package/lib/cursor.mjs

@@ -19,8 +19,8 @@ const GLOBAL_CURSOR_DIR = path.join(os.homedir(), '.cursor', 'commands', 'incspe
 /** Claude commands source directory (user local) */
 const CLAUDE_COMMANDS_DIR = path.join(os.homedir(), '.claude', 'commands', 'ai-increment');
 
-/** Built-in templates directory (fallback when Claude commands not installed) */
-const TEMPLATES_DIR = fileURLToPath(new URL('../templates/cursor-commands', import.meta.url));
+/** Built-in templates directory */
+const TEMPLATES_DIR = fileURLToPath(new URL('../templates/commands', import.meta.url));
 
 /**
  * Command mapping from Claude to Cursor

package/package.json

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

package/templates/AGENTS.md

@@ -19,7 +19,7 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
 - 检查状态: `incspec status`
 - 编号引用: `[S1]` 时序步骤, `[D1]` 依赖, `[C1]` 变更
 - 增量标记: `[N1]` 新增, `[S1-Modified]` 修改, `[S1-Deleted]` 删除
-- 继续前验证: `incspec validate --strict`
+- 验证时机: 步骤 1/4/6 完成后、归档前执行 `incspec validate`，出错时加 `--strict` 用于 CI
 
 ## 七步工作流
 
@@ -38,6 +38,8 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
 
 **交付物**: Mermaid 时序图 (`[S1]`-`[Sn]`)、依赖图 (`[D1]`-`[Dn]`)、依赖摘要 (`[R1.x]`-`[R3.x]`)
 
+**验证**: 完成后执行 `incspec validate` 检查基线格式（必含时序图和依赖图）
+
 ### 步骤 2: 收集结构化需求
 
 **命令**: `incspec collect-req` (别名: `cr`)
@@ -75,6 +77,8 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
 6. 潜在风险与副作用
 7. 建议的测试用例 (至少6个)
 
+**验证**: 完成后执行 `incspec validate` 检查增量格式（必含5个模块章节）
+
 ### 步骤 5: 应用代码变更
 
 **命令**: `incspec apply [increment-path]` (别名: `ap`)
@@ -93,12 +97,16 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
 
 **处理**: 移除增量标记 → 合并新节点 → 重新编号为干净序列 → 输出新基线 v{n+1}
 
+**验证**: 完成后执行 `incspec validate` 检查新基线完整性
+
 ### 步骤 7: 归档工作流产出
 
 **命令**: `incspec archive [--yes] [<file>] [--keep]`
 
 **目的**: 将已完成的工作流产出归档到 `incspec/archives/YYYY-MM/{module}/`
 
+**验证**: 归档前执行 `incspec validate` 确保项目健康，归档后再次验证确保文件移动正确
+
 ## 目录结构
 
 ```
@@ -141,7 +149,8 @@ incspec archive [--yes] [--keep]    # 步骤7
 # 验证与同步
 incspec validate / v [--strict]     # 验证完整性
 incspec sync [--cursor|--claude|--all] [--global|--project]  # IDE集成
-incspec reset [--to=<step>]         # 重置工作流（可选回退到指定步骤 1-6）
+incspec reset                       # 完全重置工作流（归档所有产出）
+incspec reset --to=<step>           # 部分回退到指定步骤（保留1-N，重置N+1至7）
 ```
 
 ## 文件格式示例
@@ -210,6 +219,10 @@ baseline: home-baseline-v1
 | No baseline found | 先完成步骤 1 (analyze) |
 | Previous step not completed | 运行 `incspec status` 检查进度 |
 | Validation failed | 检查文件格式和编号序列 |
-| 工作流卡住 | 运行 `incspec reset` 重置状态 |
+| 工作流卡住或状态异常 | `incspec reset` 完全重置，或 `incspec reset --to=N` 回退到步骤N |
+
+**工作流重置**:
+- 完全重置: `incspec reset` - 归档所有产出，回到初始状态
+- 部分回退: `incspec reset --to=N` - 保留步骤1-N，重置N+1至7（示例：`--to=3` 保留1-3，重置4-7）
 
 记住: **基线是真相，增量是提案**。通过工作流周期保持它们同步。

package/templates/inc-spec-skill/SKILL.md

@@ -100,8 +100,10 @@ description: 设计优先的前端功能增量编码工作流。适用于实现
 管理命令:
 - `incspec status` - 查看工作流状态
 - `incspec list` - 列出规范文件
-- `incspec validate` - 验证项目健康状态
-- `incspec reset [--to=<step>]` - 重置工作流（可选回退到指定步骤 1-6）
+- `incspec validate` - 验证项目健康状态（步骤1/4/6后、归档前执行）
+- `incspec validate --strict` - 严格模式，有错误时退出码为1（用于CI）
+- `incspec reset` - 重置工作流到初始状态
+- `incspec reset --to=N` - 回退到步骤N，保留1-N，重置N+1至7（示例：`--to=3` 保留1-3，重置4-7）
 
 ## 步骤详情
 
@@ -122,6 +124,8 @@ description: 设计优先的前端功能增量编码工作流。适用于实现
 - 组件/Store依赖关系图
 - 数据流摘要
 
+**验证:** 完成后执行 `incspec validate` 检查基线格式（必含时序图和依赖图）
+
 详见 [references/analyze-codeflow.md](references/analyze-codeflow.md)。
 
 ### 步骤2: 需求收集
@@ -164,6 +168,8 @@ description: 设计优先的前端功能增量编码工作流。适用于实现
 - 文件修改计划 (新增/修改/删除)
 - 分步实现指导
 
+**验证:** 完成后执行 `incspec validate` 检查增量格式（必含5个模块章节）
+
 详见 [references/analyze-increment-codeflow.md](references/analyze-increment-codeflow.md)。
 
 ### 步骤5: 代码应用
@@ -187,6 +193,8 @@ description: 设计优先的前端功能增量编码工作流。适用于实现
 
 **输出:** 代表当前系统状态的干净基线(无增量标记)
 
+**验证:** 完成后执行 `incspec validate` 检查新基线完整性
+
 详见 [references/merge-to-baseline.md](references/merge-to-baseline.md)。
 
 ### 步骤7: 归档
@@ -202,6 +210,8 @@ incspec archive <file> --yes       # 归档指定文件
 incspec archive <file> --keep      # 复制而非移动
 ```
 
+**验证:** 归档前执行 `incspec validate` 确保项目健康，归档后再次验证确保文件移动正确
+
 详见 [references/inc-archive.md](references/inc-archive.md)。
 
 ## 最佳实践
@@ -219,10 +229,16 @@ incspec archive <file> --keep      # 复制而非移动
 - 仅在变更范围明确、不涉及复杂依赖时使用快速模式
 
 **验证节点:**
+- 步骤1后: `incspec validate` 检查基线格式（必含时序图和依赖图）
 - 步骤2后: 需求中无模糊术语
-- 步骤4后 (完整模式): 编码前审查蓝图
+- 步骤4后 (完整模式): `incspec validate` 检查增量格式 + 编码前审查蓝图
 - 步骤5后: 验证所有文件已正确创建/修改
-- 步骤7后: 确认工作区已清理
+- 步骤6后: `incspec validate` 检查新基线完整性
+- 步骤7前后: 归档前后各执行 `incspec validate` 确保项目健康
+
+**工作流重置:**
+- 完全重置: `incspec reset` - 归档所有产出，回到初始状态
+- 部分回退: `incspec reset --to=N` - 保留步骤1-N，重置步骤N+1至7。示例：步骤5发现设计有误 → `--to=3` → 重做步骤4-7
 
 **人工确认点:**
 
@@ -241,14 +257,15 @@ incspec archive <file> --keep      # 复制而非移动
 
 ## 常见陷阱
 
-| 陷阱 | 后果 |
-|------|------|
-| 跳过代码流程分析 | 集成问题，返工 |
-| 接受模糊需求 | 编码时发现歧义 |
-| 遗漏依赖 | 导入错误，运行时失败 |
-| 编码先于设计 | 在不符合架构的实现上浪费精力 |
-| 跳过基线合并 | 对当前系统状态产生混淆 |
-| 忽略归档 | 工作区杂乱，历史丢失 |
+| 陷阱 | 后果 | 解决方案 |
+|------|------|----------|
+| 跳过代码流程分析 | 集成问题，返工 | 始终从步骤1开始，建立准确基线 |
+| 接受模糊需求 | 编码时发现歧义 | 步骤2必须确认，消除所有模糊术语 |
+| 遗漏依赖 | 导入错误，运行时失败 | 完整模式严格执行步骤3 |
+| 编码先于设计 | 在不符合架构的实现上浪费精力 | 完整模式严格执行步骤4，步骤4设计获批后才执行步骤5 |
+| 跳过基线合并 | 对当前系统状态产生混淆 | 每次增量后必须执行步骤6 |
+| 忽略归档 | 工作区杂乱，历史丢失 | 工作流完成后立即执行步骤7 |
+| 工作流状态不一致 | CLI命令执行失败 | 使用 `incspec status` 检查状态，必要时使用 `incspec reset` 修复 |
 
 ## 参考资源