kiro-spec-engine 1.3.0 → 1.4.0

package/docs/integration-philosophy.md

@@ -0,0 +1,313 @@
+# kse 集成哲学
+
+> kse 如何与 AI 编码工具配合工作
+
+---
+
+## 核心定位
+
+**kse 不是替代 AI 工具，而是增强 AI 工具**
+
+```
+┌─────────────────────────────────────┐
+│         AI 编码工具                  │
+│    (Codex/Claude/Cursor/Windsurf)   │
+│                                      │
+│  用户主要工作界面 ← 这里写代码        │
+└──────────────┬──────────────────────┘
+               │
+               │ 读取上下文
+               ▼
+┌─────────────────────────────────────┐
+│            kse                       │
+│                                      │
+│  Spec 管理 + 上下文生成               │
+│  (后台运行，提供结构化信息)            │
+└─────────────────────────────────────┘
+```
+
+---
+
+## 三种集成模式
+
+### 模式 1：AI 主动调用 kse（最佳）⭐
+
+**适用工具**：Windsurf、Cline、Aider（可执行命令的 AI）
+
+**工作流**：
+```
+用户 → AI 工具 → AI 自动执行 kse 命令 → 获取上下文 → 生成代码
+```
+
+**示例对话**：
+```
+用户：我要实现用户登录功能
+
+AI：好的，让我先查看项目的 Spec
+    [自动执行] kse context export 01-00-user-login
+    [读取文件] .kiro/specs/01-00-user-login/context-export.md
+    
+    我看到设计文档中定义了 AuthController...
+    [生成代码]
+    
+    [自动执行] kse task claim 01-00-user-login 1.1
+    任务已认领，开始实现...
+```
+
+**配置方法**：
+
+在 AI 工具的系统提示中添加：
+```markdown
+你可以使用以下 kse 命令来管理项目：
+
+- `kse context export <spec-name>` - 导出 Spec 上下文
+- `kse prompt generate <spec-name> <task-id>` - 生成任务提示
+- `kse task claim <spec-name> <task-id>` - 认领任务
+- `kse status` - 查看项目状态
+
+在实现功能前，先用 kse 命令查看相关 Spec。
+```
+
+**优势**：
+- ✅ 完全自动化
+- ✅ 用户无需手动操作
+- ✅ AI 自动管理 Spec 生命周期
+
+---
+
+### 模式 2：手动导出 + AI 使用（当前）
+
+**适用工具**：Claude Code、ChatGPT、GitHub Copilot
+
+**工作流**：
+```
+用户 → 手动执行 kse 命令 → 复制上下文 → 粘贴到 AI → AI 生成代码
+```
+
+**示例流程**：
+```bash
+# 1. 用户手动导出
+kse context export 01-00-user-login
+
+# 2. 复制内容
+cat .kiro/specs/01-00-user-login/context-export.md | pbcopy
+
+# 3. 粘贴到 Claude/ChatGPT
+
+# 4. 对话
+用户：请实现任务 1.1
+AI：[生成代码]
+
+# 5. 手动更新任务状态
+# 编辑 tasks.md: - [x] 1.1 ...
+```
+
+**改进建议**：
+```bash
+# 添加快捷命令
+kse clip 01-00-user-login          # 自动复制到剪贴板
+kse clip 01-00-user-login 1.1      # 只复制任务 1.1 的上下文
+```
+
+**优势**：
+- ✅ 适用于所有 AI 工具
+- ✅ 用户完全控制
+
+**劣势**：
+- ❌ 需要手动操作
+- ❌ 步骤较多
+
+---
+
+### 模式 3：Watch Mode 自动化（进阶）
+
+**适用场景**：频繁修改 Spec 的项目
+
+**工作流**：
+```
+用户修改 Spec → kse 自动检测 → 自动重新导出 → AI 工具自动刷新
+```
+
+**配置**：
+```bash
+# 启动 Watch Mode
+kse watch init
+kse watch install auto-export
+kse watch start
+
+# 现在修改任何 Spec 文件，都会自动重新导出
+```
+
+**Watch 配置示例**：
+```json
+{
+  "patterns": [
+    ".kiro/specs/**/requirements.md",
+    ".kiro/specs/**/design.md",
+    ".kiro/specs/**/tasks.md"
+  ],
+  "actions": [
+    {
+      "name": "auto-export",
+      "command": "kse context export ${spec-name}"
+    }
+  ]
+}
+```
+
+**优势**：
+- ✅ 完全自动化
+- ✅ Spec 修改立即生效
+
+---
+
+## 推荐配置
+
+### 对于 Windsurf/Cline 用户（推荐）⭐
+
+**在 AI 系统提示中添加**：
+
+```markdown
+# Spec 管理规则
+
+项目使用 kse (Kiro Spec Engine) 管理需求和设计。
+
+## 工作流程
+
+1. **查看 Spec**：实现功能前，先执行 `kse context export <spec-name>` 查看设计
+2. **认领任务**：开始工作前，执行 `kse task claim <spec-name> <task-id>`
+3. **实现代码**：严格按照 Spec 中的设计实现
+4. **更新状态**：完成后，在 tasks.md 中标记任务为完成 `[x]`
+
+## 可用命令
+
+- `kse status` - 查看项目状态
+- `kse context export <spec-name>` - 导出 Spec 上下文
+- `kse task claim <spec-name> <task-id>` - 认领任务
+- `kse prompt generate <spec-name> <task-id>` - 生成任务提示
+
+## 示例
+
+用户说："实现用户登录"
+你应该：
+1. 执行 `kse context export 01-00-user-login`
+2. 读取导出的上下文
+3. 根据设计文档实现代码
+4. 执行 `kse task claim 01-00-user-login 1.1`
+```
+
+### 对于 Claude/ChatGPT 用户
+
+**创建快捷脚本**：
+
+```bash
+# ~/.bashrc 或 ~/.zshrc
+alias kse-clip='kse context export $1 && cat .kiro/specs/$1/context-export.md | pbcopy && echo "✅ 已复制到剪贴板"'
+
+# 使用
+kse-clip 01-00-user-login
+# 然后直接粘贴到 Claude
+```
+
+### 对于 Cursor 用户
+
+**使用 Cursor Rules**：
+
+创建 `.cursorrules` 文件：
+```markdown
+# Spec 驱动开发
+
+项目使用 kse 管理 Spec。实现功能前：
+
+1. 查看 `.kiro/specs/<spec-name>/design.md`
+2. 按照设计实现
+3. 更新 `.kiro/specs/<spec-name>/tasks.md`
+
+示例：
+- 设计文档：`.kiro/specs/01-00-user-login/design.md`
+- 任务列表：`.kiro/specs/01-00-user-login/tasks.md`
+```
+
+---
+
+## 未来改进方向
+
+### 1. MCP (Model Context Protocol) 集成
+
+让 AI 工具通过 MCP 直接访问 kse：
+
+```javascript
+// AI 工具可以直接调用
+const context = await mcp.call('kse.getContext', '01-00-user-login');
+const tasks = await mcp.call('kse.getTasks', '01-00-user-login');
+```
+
+### 2. IDE 插件
+
+为主流 IDE 提供插件：
+- VS Code Extension
+- Cursor Extension
+- JetBrains Plugin
+
+功能：
+- 右键菜单："导出到 AI 工具"
+- 状态栏显示当前 Spec
+- 快捷键快速导出
+
+### 3. Web Dashboard
+
+提供 Web 界面：
+```bash
+kse serve
+# 打开 http://localhost:3000
+# 可视化管理 Spec，一键复制上下文
+```
+
+---
+
+## 常见问题
+
+### Q: 为什么不把 kse 做成 AI 工具的插件？
+
+**A**: 
+- kse 是**通用工具**，支持所有 AI 工具
+- 做成插件会限制在特定工具
+- CLI 工具更灵活，可以被任何工具调用
+
+### Q: 能否让 AI 工具自动读取 .kiro/ 目录？
+
+**A**: 
+- 部分工具支持（Cursor、Copilot）
+- 但需要明确的上下文导出更可靠
+- kse 的价值在于**结构化和格式化**上下文
+
+### Q: 两套工具确实有点麻烦，有更简单的方案吗？
+
+**A**: 
+- **短期**：使用 Windsurf/Cline，让 AI 自动调用 kse
+- **中期**：使用快捷脚本（如 `kse-clip`）
+- **长期**：MCP 集成，完全无缝
+
+---
+
+## 总结
+
+**kse 的定位**：
+- ❌ 不是独立的开发工具
+- ❌ 不是 AI 工具的竞争对手
+- ✅ 是 AI 工具的**上下文提供者**
+- ✅ 是项目的**Spec 管理系统**
+
+**最佳实践**：
+1. **用 kse 管理 Spec**（需求、设计、任务）
+2. **用 AI 工具写代码**（主要工作界面）
+3. **让 AI 工具调用 kse**（自动化集成）
+
+**选择合适的模式**：
+- 能执行命令的 AI → 模式 1（AI 主动调用）⭐
+- 不能执行命令的 AI → 模式 2（手动导出）
+- 频繁修改 Spec → 模式 3（Watch Mode）
+
+---
+
+**记住**：kse 是幕后英雄，AI 工具是前台明星。两者配合，才能发挥最大价值！🚀

package/docs/quick-start-with-ai-tools.md

@@ -0,0 +1,374 @@
+# 快速入门：配合 AI 工具使用 kse
+
+> 5分钟学会如何用 kse 配合 Claude、Cursor、Copilot 等 AI 工具
+
+---
+
+## ⚠️ 重要：kse 的定位
+
+**kse 不是独立开发工具，而是 AI 工具的增强器**
+
+```
+你的工作界面 = AI 工具（Codex/Claude/Cursor）
+kse 的角色 = 后台管理 Spec，为 AI 提供结构化上下文
+```
+
+**简单理解**：
+- ❌ kse 不是用来写代码的
+- ✅ kse 是用来**组织项目信息**，让 AI 更好地帮你写代码
+- ✅ 你主要在 AI 工具中工作，kse 在后台提供支持
+
+**三种使用模式**：
+1. **AI 主动调用 kse**（Windsurf/Cline）- 最佳，完全自动 ⭐
+2. **手动导出上下文**（Claude/ChatGPT）- 当前方式
+3. **Watch Mode 自动化**（所有工具）- 进阶用法
+
+**详细说明**：查看 [集成哲学文档](./integration-philosophy.md)
+
+---
+
+## 核心理念
+
+**kse 是什么？**
+- 一个 CLI 工具，帮你管理项目的 Spec（需求、设计、任务）
+- 生成结构化的上下文，让 AI 工具更好地理解你的项目
+
+**为什么需要 kse？**
+- AI 工具需要清晰的上下文才能生成高质量代码
+- kse 帮你组织和导出这些上下文
+- 让 AI 按照你的设计和规范工作
+
+---
+
+## 工作流程图
+
+```
+┌─────────────┐
+│  1. 用 kse  │
+│  创建 Spec  │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  2. 导出    │
+│  上下文     │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  3. 复制到  │
+│  AI 工具    │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  4. AI 帮你 │
+│  写代码     │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  5. 更新    │
+│  任务状态   │
+└─────────────┘
+```
+
+---
+
+## 5分钟快速开始
+
+### 步骤 1：安装 kse
+
+```bash
+npm install -g kiro-spec-engine
+```
+
+### 步骤 2：初始化项目
+
+```bash
+cd your-project
+kse adopt
+```
+
+这会在项目中创建 `.kiro/` 目录。
+
+### 步骤 3：创建你的第一个 Spec
+
+```bash
+kse create-spec 01-00-user-login
+```
+
+然后编辑生成的文件：
+- `.kiro/specs/01-00-user-login/requirements.md` - 写需求
+- `.kiro/specs/01-00-user-login/design.md` - 写设计
+- `.kiro/specs/01-00-user-login/tasks.md` - 列任务
+
+### 步骤 4：导出上下文
+
+```bash
+kse context export 01-00-user-login
+```
+
+这会生成：`.kiro/specs/01-00-user-login/context-export.md`
+
+### 步骤 5：使用 AI 工具
+
+#### 方式 A：Claude Code / ChatGPT
+
+1. 打开生成的 `context-export.md`
+2. 复制全部内容
+3. 粘贴到 Claude/ChatGPT 对话框
+4. 说："请帮我实现任务 1.1"
+
+#### 方式 B：Cursor
+
+1. 生成任务提示：
+   ```bash
+   kse prompt generate 01-00-user-login 1.1
+   ```
+
+2. 打开 Cursor Composer (Cmd+K)
+3. 粘贴生成的提示
+4. Cursor 会根据上下文生成代码
+
+#### 方式 C：GitHub Copilot
+
+1. 在代码文件中添加注释：
+   ```javascript
+   // Task 1.1: Implement user login
+   // See: .kiro/specs/01-00-user-login/design.md
+   ```
+
+2. Copilot 会根据 Spec 文件生成代码
+
+### 步骤 6：更新任务状态
+
+完成任务后，编辑 `tasks.md`：
+
+```markdown
+- [x] 1.1 实现用户登录功能  ← 改成 [x] 表示完成
+- [ ] 1.2 添加密码加密
+```
+
+---
+
+## 详细示例：用 Claude Code 实现登录功能
+
+### 1. 创建 Spec
+
+```bash
+kse create-spec 01-00-user-login
+```
+
+### 2. 编写需求（requirements.md）
+
+```markdown
+# 用户登录功能
+
+## 1. 功能需求
+
+### 1.1 用户可以用邮箱和密码登录
+- 输入：邮箱、密码
+- 输出：登录成功返回 token，失败返回错误信息
+- 验证：邮箱格式、密码长度 >= 6
+```
+
+### 3. 编写设计（design.md）
+
+```markdown
+# 设计方案
+
+## 1. API 设计
+
+### 1.1 登录接口
+- 路径：POST /api/auth/login
+- 请求体：{ email: string, password: string }
+- 响应：{ token: string } 或 { error: string }
+
+## 2. 实现方案
+
+### 2.1 AuthController
+- validateEmail() - 验证邮箱格式
+- validatePassword() - 验证密码长度
+- login() - 处理登录逻辑
+```
+
+### 4. 列出任务（tasks.md）
+
+```markdown
+- [ ] 1.1 实现 AuthController 类
+- [ ] 1.2 实现邮箱验证
+- [ ] 1.3 实现密码验证
+- [ ] 1.4 实现登录逻辑
+- [ ] 1.5 编写单元测试
+```
+
+### 5. 导出上下文
+
+```bash
+kse context export 01-00-user-login
+```
+
+### 6. 在 Claude Code 中使用
+
+**对话示例**：
+
+```
+你：[粘贴 context-export.md 的全部内容]
+
+你：请帮我实现任务 1.1 "实现 AuthController 类"，
+    按照设计文档中的方案，用 TypeScript 实现。
+
+Claude：好的，我会根据设计文档实现 AuthController 类...
+[生成代码]
+
+你：很好！现在请为这个类编写单元测试。
+
+Claude：[生成测试代码]
+
+你：完美！请帮我更新 tasks.md，标记任务 1.1 为完成。
+
+[你手动更新 tasks.md：- [x] 1.1 实现 AuthController 类]
+```
+
+---
+
+## 不同 AI 工具的最佳实践
+
+### Claude Code / ChatGPT
+✅ **优势**：大上下文窗口，可以一次加载完整 Spec  
+📝 **用法**：复制 `context-export.md` 全部内容  
+💡 **技巧**：一次对话可以完成多个任务
+
+### Cursor
+✅ **优势**：IDE 集成，可以直接修改文件  
+📝 **用法**：用 `kse prompt generate` 生成任务提示  
+💡 **技巧**：使用 Composer 模式，让 Cursor 直接编辑文件
+
+### GitHub Copilot
+✅ **优势**：实时代码补全  
+📝 **用法**：在代码注释中引用 Spec 文件  
+💡 **技巧**：写详细的注释，Copilot 会根据 Spec 生成代码
+
+### Windsurf / Cline
+✅ **优势**：可以执行命令和修改文件  
+📝 **用法**：让 AI 直接运行 `kse` 命令  
+💡 **技巧**：AI 可以自动导出上下文和更新任务状态
+
+---
+
+## 常见问题
+
+### Q: 每次都要复制粘贴上下文吗？
+
+**A**: 取决于 AI 工具：
+- **Claude/ChatGPT**：是的，每次新对话需要重新加载
+- **Cursor**：可以在项目中持续使用，Cursor 会记住上下文
+- **Copilot**：不需要，它会自动读取项目文件
+
+### Q: 上下文太大怎么办？
+
+**A**: 使用任务级别的提示：
+```bash
+# 只导出特定任务的上下文
+kse prompt generate 01-00-user-login 1.1
+```
+
+### Q: AI 生成的代码不符合设计怎么办？
+
+**A**: 
+1. 检查 `design.md` 是否写得够详细
+2. 在提示中明确说："严格按照设计文档实现"
+3. 提供代码示例在设计文档中
+
+### Q: 如何让 AI 遵循项目规范？
+
+**A**: 使用 Steering Rules：
+```bash
+# 导出时包含规范
+kse context export 01-00-user-login --steering --steering-files=CORE_PRINCIPLES.md
+```
+
+### Q: 可以自动更新任务状态吗？
+
+**A**: 
+- **Kiro IDE**：支持自动更新
+- **其他工具**：需要手动更新 `tasks.md`
+- **未来**：计划支持更多工具的自动更新
+
+---
+
+## 进阶技巧
+
+### 1. 使用 Steering Rules 控制 AI 行为
+
+创建 `.kiro/steering/CODING_STANDARDS.md`：
+
+```markdown
+# 编码规范
+
+- 使用 TypeScript
+- 所有函数必须有 JSDoc 注释
+- 使用 async/await 而不是 Promise.then
+- 错误处理使用 try-catch
+```
+
+导出时包含：
+```bash
+kse context export 01-00-user-login --steering
+```
+
+### 2. 为不同工具生成不同格式的提示
+
+```bash
+# 为 Claude 生成
+kse prompt generate 01-00-user-login 1.1 --tool=claude-code
+
+# 为 Cursor 生成
+kse prompt generate 01-00-user-login 1.1 --tool=cursor
+
+# 通用格式
+kse prompt generate 01-00-user-login 1.1
+```
+
+### 3. 批量导出多个任务
+
+```bash
+# 导出整个 Spec
+kse context export 01-00-user-login
+
+# 然后在 AI 工具中说：
+# "请按顺序实现任务 1.1 到 1.5"
+```
+
+---
+
+## 总结
+
+**kse 的价值**：
+1. ✅ 结构化管理项目需求和设计
+2. ✅ 生成 AI 友好的上下文
+3. ✅ 让 AI 按照你的规范工作
+4. ✅ 跟踪任务进度
+
+**配合 AI 工具的流程**：
+1. 用 kse 写 Spec（需求、设计、任务）
+2. 导出上下文
+3. 复制给 AI 工具
+4. AI 帮你写代码
+5. 更新任务状态
+
+**下一步**：
+- 查看 [完整跨工具指南](./cross-tool-guide.md)
+- 查看 [命令参考](./command-reference.md)
+- 查看 [手动工作流指南](./manual-workflows-guide.md)
+
+---
+
+**开始使用！** 🚀
+
+```bash
+npm install -g kiro-spec-engine
+kse adopt
+kse create-spec 01-00-my-feature
+```