kiro-spec-engine 1.2.3 → 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/manual-workflows-guide.md

@@ -0,0 +1,417 @@
+# Manual Workflows Guide
+
+> Complete guide for manual workflows when automation is not available
+
+---
+
+## Overview
+
+This guide provides step-by-step instructions for common workflows when using kiro-spec-engine without automation (watch mode or agent hooks). These workflows are designed to be efficient and easy to follow.
+
+**When to use manual workflows:**
+- When automation is not set up
+- When working in environments without watch mode support
+- When you prefer manual control over automation
+- For one-off tasks or testing
+
+---
+
+## Table of Contents
+
+1. [Task Sync Workflow](#task-sync-workflow)
+2. [Context Export Workflow](#context-export-workflow)
+3. [Prompt Generation Workflow](#prompt-generation-workflow)
+4. [Workflow Checklists](#workflow-checklists)
+
+---
+
+## Task Sync Workflow
+
+### Purpose
+Keep your workspace synchronized with task progress across multiple users or tools.
+
+### Time Estimate
+- Initial sync: 2-3 minutes
+- Subsequent syncs: 30-60 seconds
+
+### Prerequisites
+- Project adopted with kiro-spec-engine
+- Active spec with tasks.md file
+- Write access to .kiro/specs/ directory
+
+### Step-by-Step Instructions
+
+#### 1. Check Current Status
+```bash
+kse status
+```
+
+**What to look for:**
+- Current spec name
+- Number of tasks (total, completed, in progress)
+- Last sync timestamp
+
+**Time:** ~5 seconds
+
+---
+
+#### 2. Review Task Changes
+Open your spec's `tasks.md` file and review:
+- Tasks you've completed (mark with `[x]`)
+- Tasks you're working on (mark with `[-]`)
+- Tasks you've queued (mark with `[~]`)
+
+**Example:**
+```markdown
+- [x] 1.1 Completed task
+- [-] 1.2 In progress task
+- [~] 1.3 Queued task
+- [ ] 1.4 Not started task
+```
+
+**Time:** ~30-60 seconds
+
+---
+
+#### 3. Sync Workspace
+```bash
+kse workspace sync
+```
+
+**What this does:**
+- Updates workspace metadata
+- Synchronizes task status
+- Detects conflicts
+- Updates timestamps
+
+**Time:** ~10-15 seconds
+
+---
+
+#### 4. Verify Sync
+```bash
+kse status
+```
+
+**Verify:**
+- Task counts are updated
+- Sync timestamp is current
+- No conflicts reported
+
+**Time:** ~5 seconds
+
+---
+
+### Best Practices
+
+1. **Sync Frequency**
+   - Before starting work: Always sync first
+   - After completing tasks: Sync immediately
+   - During long sessions: Sync every 30-60 minutes
+
+2. **Conflict Resolution**
+   - If conflicts detected, review both versions
+   - Keep the most recent accurate state
+   - Document resolution in commit message
+
+3. **Team Coordination**
+   - Communicate task claims in team chat
+   - Use task claiming feature: `kse task claim <spec> <task-id>`
+   - Check for claimed tasks before starting work
+
+---
+
+## Context Export Workflow
+
+### Purpose
+Export spec context for sharing with AI assistants or team members.
+
+### Time Estimate
+- Single spec export: 15-30 seconds
+- With steering rules: 30-45 seconds
+
+### Prerequisites
+- Active spec with requirements, design, and tasks
+- Optional: Steering rules configured
+
+### Step-by-Step Instructions
+
+#### 1. Identify Spec to Export
+```bash
+kse status
+```
+
+Note the spec name you want to export.
+
+**Time:** ~5 seconds
+
+---
+
+#### 2. Export Context
+```bash
+kse context export <spec-name>
+```
+
+**Options:**
+- `--include-steering`: Include steering rules
+- `--steering-files <files>`: Specific steering files (comma-separated)
+- `--output <path>`: Custom output path
+
+**Example:**
+```bash
+kse context export my-feature --include-steering --steering-files CORE_PRINCIPLES.md,ENVIRONMENT.md
+```
+
+**Time:** ~10-20 seconds
+
+---
+
+#### 3. Locate Export File
+The export is saved to:
+```
+.kiro/specs/<spec-name>/context-export.md
+```
+
+**Time:** ~5 seconds
+
+---
+
+#### 4. Use Exported Context
+- Copy content to AI assistant
+- Share with team members
+- Use as documentation reference
+- Include in project handoff
+
+**Time:** Varies by use case
+
+---
+
+### Best Practices
+
+1. **When to Export**
+   - Before starting a new task
+   - When asking for AI assistance
+   - For project documentation
+   - During team handoffs
+
+2. **What to Include**
+   - Always: requirements, design, tasks
+   - Usually: core steering rules
+   - Sometimes: environment-specific rules
+   - Rarely: all steering rules (too verbose)
+
+3. **Export Management**
+   - Exports are regenerated each time
+   - Old exports are overwritten
+   - Consider versioning important exports
+   - Clean up old exports periodically
+
+---
+
+## Prompt Generation Workflow
+
+### Purpose
+Generate AI prompts for specific tasks with relevant context.
+
+### Time Estimate
+- Single task prompt: 20-30 seconds
+- Batch generation: 1-2 minutes per 10 tasks
+
+### Prerequisites
+- Active spec with tasks
+- Task IDs identified
+- Requirements and design documents complete
+
+### Step-by-Step Instructions
+
+#### 1. Identify Task
+Review tasks.md and note the task ID:
+```bash
+cat .kiro/specs/<spec-name>/tasks.md
+```
+
+**Example task ID:** `1.2` or `3.1.1`
+
+**Time:** ~10-15 seconds
+
+---
+
+#### 2. Generate Prompt
+```bash
+kse prompt generate <spec-name> <task-id>
+```
+
+**Options:**
+- `--target <tool>`: Target tool (kiro, vscode, cursor, other)
+- `--output <path>`: Custom output path
+
+**Example:**
+```bash
+kse prompt generate my-feature 1.2 --target vscode
+```
+
+**Time:** ~10-15 seconds
+
+---
+
+#### 3. Locate Generated Prompt
+The prompt is saved to:
+```
+.kiro/specs/<spec-name>/prompts/task-<task-id>.md
+```
+
+**Time:** ~5 seconds
+
+---
+
+#### 4. Use Generated Prompt
+- Copy to AI assistant
+- Review for accuracy
+- Customize if needed
+- Execute task based on prompt
+
+**Time:** Varies by task complexity
+
+---
+
+### Batch Operations
+
+For multiple tasks:
+
+```bash
+# Generate prompts for all incomplete tasks
+for task in 1.1 1.2 1.3; do
+  kse prompt generate my-feature $task
+done
+```
+
+**Time:** ~20-30 seconds per task
+
+---
+
+### Best Practices
+
+1. **Prompt Quality**
+   - Review generated prompts before use
+   - Customize for specific context
+   - Add tool-specific instructions
+   - Include relevant examples
+
+2. **Prompt Organization**
+   - Keep prompts in spec directory
+   - Use consistent naming
+   - Version control prompts
+   - Clean up after task completion
+
+3. **Optimization Tips**
+   - Generate prompts in batches
+   - Reuse prompts for similar tasks
+   - Template common patterns
+   - Document customizations
+
+---
+
+## Workflow Checklists
+
+### Daily Workflow Checklist
+
+**Morning (Start of Work)**
+- [ ] Sync workspace: `kse workspace sync`
+- [ ] Check status: `kse status`
+- [ ] Review task list
+- [ ] Claim tasks you'll work on
+- [ ] Export context for active tasks
+
+**During Work**
+- [ ] Update task status as you progress
+- [ ] Sync every 30-60 minutes
+- [ ] Export context when asking for help
+- [ ] Generate prompts for new tasks
+
+**End of Day**
+- [ ] Mark completed tasks
+- [ ] Update in-progress tasks
+- [ ] Final sync: `kse workspace sync`
+- [ ] Commit changes to version control
+
+---
+
+### Task Completion Checklist
+
+- [ ] Review task requirements
+- [ ] Generate task prompt
+- [ ] Export context if needed
+- [ ] Complete implementation
+- [ ] Run tests
+- [ ] Update task status to completed
+- [ ] Sync workspace
+- [ ] Commit changes
+
+---
+
+### Spec Creation Checklist
+
+- [ ] Create spec: `kse create-spec <name>`
+- [ ] Write requirements.md
+- [ ] Write design.md
+- [ ] Generate tasks.md
+- [ ] Export initial context
+- [ ] Generate prompts for first tasks
+- [ ] Sync workspace
+- [ ] Begin implementation
+
+---
+
+## Time Estimates Summary
+
+| Workflow | Time Estimate |
+|----------|---------------|
+| Task Sync | 30-60 seconds |
+| Context Export | 15-45 seconds |
+| Prompt Generation | 20-30 seconds |
+| Daily Sync Routine | 2-3 minutes |
+| Full Spec Setup | 10-15 minutes |
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue: Sync conflicts**
+- **Solution:** Review both versions, keep most recent
+- **Prevention:** Sync more frequently
+
+**Issue: Export fails**
+- **Solution:** Check spec exists, files are readable
+- **Prevention:** Verify spec structure before export
+
+**Issue: Prompt generation incomplete**
+- **Solution:** Ensure requirements and design are complete
+- **Prevention:** Complete docs before generating prompts
+
+---
+
+## Next Steps
+
+1. **Set Up Automation:** Consider using watch mode for automatic workflows
+   ```bash
+   kse watch init
+   kse watch install auto-sync
+   ```
+
+2. **Learn More:**
+   - [Watch Mode Guide](./watch-mode-guide.md)
+   - [Cross-Tool Guide](./cross-tool-guide.md)
+   - [Architecture](./architecture.md)
+
+3. **Get Help:**
+   - Run `kse --help` for command reference
+   - Check [GitHub Issues](https://github.com/heguangyong/kiro-spec-engine/issues)
+   - Review [Contributing Guide](../CONTRIBUTING.md)
+
+---
+
+**Version:** 1.0  
+**Last Updated:** 2026-01-23  
+**Spec:** 05-00-agent-hooks-and-automation