kiro-spec-engine 1.3.0 → 1.4.0

package/README.zh.md

@@ -1,330 +0,0 @@
-# kiro-spec-engine
-
-[![npm version](https://badge.fury.io/js/kiro-spec-engine.svg)](https://badge.fury.io/js/kiro-spec-engine)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-**Kiro Spec Engine** - 基于 Spec 的驱动规则引擎，融入 Ultrawork 精神的质量增强工具。
-
-> 🔥 用结构化的 Spec、Steering 规则和不懈的质量追求，改变你的开发工作流。
-
-[English](README.md) | 简体中文
-
-## 🎯 什么是 Kiro Spec Engine？
-
-Kiro Spec Engine (KSE) 是一个 **基于 Spec 的驱动规则引擎**，为你的开发过程带来结构、质量和 **Ultrawork 精神**。它不仅仅是一个工具——更是一种以清晰和卓越构建软件的方法论。
-
-### 核心概念：Spec 驱动规则引擎
-
-KSE 的核心是一个基于 **Specs** 运作的**规则引擎**：
-
-- **Specs** 定义你要构建什么（Requirements → Design → Tasks）
-- **Steering 规则** 指导 AI 助手如何帮助你构建
-- **Ultrawork 精神** 确保每个阶段的专业级质量
-
-### 核心特性
-
-- ✅ **Spec 驱动开发**: 结构化的 Requirements → Design → Tasks 工作流
-- ✅ **Steering 规则系统**: 用项目特定规则控制 AI 行为
-- ✅ **质量评估**: 自动文档质量评分（0-10 分制）
-- ✅ **智能增强**: 通过 Ultrawork 自动识别和应用改进
-- ✅ **专业标准**: 确保生产就绪的文档
-- ✅ **多语言支持**: 支持中文和英文界面
-- ✅ **CLI 接口**: 易用的命令行工具
-
-## 🚀 快速开始
-
-### 安装
-
-通过 npm 全局安装：
-
-```bash
-npm install -g kiro-spec-engine
-```
-
-或使用短别名：
-
-```bash
-npm install -g kiro-spec-engine
-# 创建 'kiro-spec-engine' 和 'kse' 两个命令
-```
-
-### 初始化项目
-
-```bash
-# 在当前目录初始化
-kiro-spec-engine init
-
-# 或指定项目名称
-kiro-spec-engine init "我的超棒项目"
-
-# 使用中文界面
-kiro-spec-engine --lang zh init
-
-# 使用短别名
-kse init
-```
-
-### 创建并增强你的第一个 Spec
-
-```bash
-# 创建新 Spec
-kse create-spec 01-00-user-authentication
-
-# 编写基础 requirements.md 文件
-# 然后使用 Ultrawork 增强
-kse enhance requirements .kiro/specs/01-00-user-authentication/requirements.md
-```
-
-## 📋 命令
-
-### 项目管理
-
-```bash
-# 初始化项目
-kse init [项目名称]
-
-# 接管现有项目
-kse adopt                    # 交互式接管
-kse adopt --auto             # 跳过确认
-kse adopt --dry-run          # 显示将要改变的内容
-kse adopt --mode fresh       # 强制指定模式
-
-# 升级项目版本
-kse upgrade                  # 交互式升级
-kse upgrade --auto           # 跳过确认
-kse upgrade --dry-run        # 显示升级计划
-kse upgrade --to 1.2.0       # 升级到指定版本
-
-# 回滚到之前的状态
-kse rollback                 # 交互式回滚
-kse rollback --auto          # 跳过确认
-kse rollback --backup <id>   # 恢复指定备份
-
-# 检查项目状态
-kse status
-
-# 创建新 Spec
-kse create-spec <spec-名称>
-
-# 系统诊断
-kse doctor
-
-# 设置语言
-kse --lang zh <命令>  # 中文
-kse --lang en <命令>  # 英文
-```
-
-### 文档增强
-
-```bash
-# 增强需求文档
-kse enhance requirements <文件>
-
-# 增强设计文档（需要需求文件）
-kse enhance design <设计文件> --requirements <需求文件>
-
-# 检查任务完成情况
-kse enhance tasks <任务文件>
-```
-
-### 示例
-
-```bash
-# 完整工作流示例
-kse init "电商平台"
-kse create-spec 01-00-user-auth
-# 编辑 .kiro/specs/01-00-user-auth/requirements.md
-kse enhance requirements .kiro/specs/01-00-user-auth/requirements.md
-# 编辑 .kiro/specs/01-00-user-auth/design.md  
-kse enhance design .kiro/specs/01-00-user-auth/design.md --requirements .kiro/specs/01-00-user-auth/requirements.md
-```
-
-## 📊 质量标准
-
-### Requirements 阶段（0-10 评分）
-- **基础结构**（2分）：概述、用户故事、功能需求、非功能需求
-- **EARS 格式**（2分）：WHEN...THEN 验收标准
-- **用户故事**（2分）："作为...我希望...以便" 格式
-- **验收标准**（2分）：完整的验收标准定义
-- **非功能需求**（1分）：性能、安全、可用性等
-- **约束条件**（1分）：技术约束、资源约束等
-
-### Design 阶段（0-10 评分）
-- **基础结构**（2分）：系统概述、架构设计、组件设计、接口设计
-- **需求追溯**（2分）：需求到设计的双向追溯
-- **架构图**（1.5分）：Mermaid 图或其他设计图
-- **技术选型**（1.5分）：技术栈选择和理由
-- **非功能设计**（1.5分）：性能设计、安全设计、可扩展性
-- **接口定义**（1.5分）：API 设计、数据结构定义
-
-### Tasks 阶段
-- **完成率分析**：统计已完成、进行中、未开始任务
-- **优先级识别**：基于关键词和任务编号识别优先级
-- **Ultrawork 激励**：提供 Sisyphus 精神激励和建议
-- **下一步指导**：建议具体的执行策略
-
-## � 项目接管和升级
-
-### 接管现有项目
-
-KSE 可以智能接管现有项目，支持三种模式：
-
-**全新接管**（无 `.kiro/` 目录）：
-```bash
-kse adopt
-# 从头创建完整的 .kiro/ 结构
-```
-
-**部分接管**（`.kiro/` 存在但不完整）：
-```bash
-kse adopt
-# 保留现有的 specs/ 和 steering/
-# 添加缺失的组件
-```
-
-**完整接管**（来自旧版本的完整 `.kiro/`）：
-```bash
-kse adopt
-# 将组件升级到当前版本
-# 保留所有用户内容
-# 更改前创建备份
-```
-
-### 升级到新版本
-
-当 KSE 发布新版本时：
-
-```bash
-# 检查当前版本
-kse --version
-
-# 升级到最新版本
-kse upgrade
-
-# 升级到指定版本
-kse upgrade --to 1.2.0
-
-# 预览升级计划
-kse upgrade --dry-run
-```
-
-**渐进式升级**：KSE 自动处理版本差距，通过中间版本升级（例如 1.0.0 → 1.1.0 → 1.2.0）。
-
-### 回滚和安全性
-
-所有破坏性操作都会自动创建备份：
-
-```bash
-# 列出可用备份
-kse rollback
-
-# 从指定备份恢复
-kse rollback --backup adopt-2026-01-23-100000
-
-# 快速回滚（交互式）
-kse rollback
-```
-
-**安全特性**：
-- ✅ 接管/升级前自动备份
-- ✅ 备份验证和完整性检查
-- ✅ 轻松回滚到之前的状态
-- ✅ 预览模式查看更改
-
-## 🛠️ 项目结构
-
-初始化后，你的项目将包含：
-
-```
-your-project/
-├── .kiro/                          # Kiro 核心目录
-│   ├── specs/                      # Spec 存储
-│   │   └── SPEC_WORKFLOW_GUIDE.md
-│   ├── steering/                   # AI 行为规则（"规则引擎"）
-│   │   ├── CORE_PRINCIPLES.md      # 核心原则 + Ultrawork 精神
-│   │   ├── ENVIRONMENT.md          # 环境配置
-│   │   ├── CURRENT_CONTEXT.md      # 当前上下文
-│   │   └── RULES_GUIDE.md          # 规则索引
-│   ├── tools/                      # Ultrawork 工具
-│   │   └── ultrawork_enhancer.py   # 核心增强工具
-│   └── README.md                   # Kiro 系统文档
-└── README.md                       # 项目文档
-```
-
-## 🔥 Ultrawork 精神
-
-> 受希腊神话中西西弗斯的启发，他被判永远推石上山，每次快到山顶时石头就会滚下来。
-
-Ultrawork 精神体现：
-
-- **不懈努力**：面对挑战永不放弃
-- **持续改进**：始终追求更好的质量
-- **专业标准**：在每个细节上追求卓越（9.0/10 目标）
-- **坚持执行**：持续推进直到完成
-
-Ultrawork 是 Kiro Spec Engine 中的**质量增强哲学**——它驱动引擎产出专业级结果。
-
-## 🌍 多语言支持
-
-Kiro Spec Engine 支持多种语言：
-
-### 设置语言
-
-```bash
-# 使用命令行参数
-kse --lang zh init
-
-# 使用环境变量
-export KIRO_LANG=zh
-kse init
-
-# Windows
-set KIRO_LANG=zh
-kse init
-```
-
-### 支持的语言
-
-- 🇺🇸 English (en) - 默认
-- 🇨🇳 简体中文 (zh)
-
-工具会自动检测你的系统语言并默认使用。你可以通过 `--lang` 选项或 `KIRO_LANG` 环境变量覆盖默认设置。
-
-## 🤝 贡献
-
-我们欢迎贡献！请查看我们的[贡献指南](CONTRIBUTING.md)了解详情。
-
-### 开发设置
-
-```bash
-git clone https://github.com/yourusername/kiro-spec-engine.git
-cd kiro-spec-engine
-npm install
-npm link  # 用于本地开发
-```
-
-### 添加新语言
-
-1. 在 `locales/` 目录创建新的语言文件（如 `ja.json`）
-2. 复制 `en.json` 的结构并翻译所有文本
-3. 在 `lib/i18n.js` 中添加语言检测逻辑
-4. 更新 README 文档
-
-## 📄 许可证
-
-MIT License - 详见 [LICENSE](LICENSE) 文件。
-
-## 🙏 致谢
-
-- 受 **Sisyphus** 神话和高贵奋斗概念的启发
-- 基于 **Kiro** Spec 驱动开发的基础
-- 受 **oh-my-opencode** 和 Ultrawork Manifesto 的影响
-
----
-
-**今天就开始你的 Spec 驱动之旅！🔥**
-
-```bash
-npm install -g kiro-spec-engine
-kse --lang zh init
-```

package/docs/README.md

@@ -0,0 +1,223 @@
+# kse Documentation Index
+
+> Complete guide to kse (Kiro Spec Engine)
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23
+
+---
+
+## 🚀 Getting Started
+
+**New to kse?** Start here:
+
+- **[Quick Start Guide](quick-start.md)** - Get up and running in 5 minutes
+- **[FAQ](faq.md)** - Frequently asked questions
+- **[Troubleshooting](troubleshooting.md)** - Common issues and solutions
+
+---
+
+## 📖 Core Concepts
+
+Understand how kse works:
+
+- **[Spec Workflow](spec-workflow.md)** - Understanding the Spec-driven development process
+- **[Integration Modes](integration-modes.md)** - Three ways to integrate kse with AI tools
+- **[Command Reference](command-reference.md)** - Complete list of all kse commands
+
+---
+
+## 🛠️ Tool-Specific Guides
+
+Choose your AI tool and learn how to integrate:
+
+### Native Integration
+- **[Kiro IDE Guide](tools/kiro-guide.md)** - Fully automatic integration
+
+### Manual Export Integration
+- **[Cursor Guide](tools/cursor-guide.md)** - Using kse with Cursor IDE
+- **[Claude Code Guide](tools/claude-guide.md)** - Using kse with Claude Code
+- **[VS Code + Copilot Guide](tools/vscode-guide.md)** - Using kse with VS Code and GitHub Copilot
+
+### Watch Mode Integration
+- **[Windsurf Guide](tools/windsurf-guide.md)** - Using kse with Windsurf (supports watch mode)
+
+### Universal Integration
+- **[Generic AI Tools Guide](tools/generic-guide.md)** - Using kse with any AI tool
+
+---
+
+## 📚 Examples
+
+Learn by example with complete Spec demonstrations:
+
+### API Development
+- **[REST API Example](examples/add-rest-api/)** - Complete RESTful API with authentication
+  - Requirements, design, and tasks for a task management API
+  - JWT authentication, CRUD operations, error handling
+  - Node.js + Express + PostgreSQL
+
+### UI Development
+- **[User Dashboard Example](examples/add-user-dashboard/)** - React dashboard with data visualization
+  - Component hierarchy, state management, API integration
+  - Responsive design, charts, loading states
+  - React + Recharts
+
+### CLI Development
+- **[Export Command Example](examples/add-export-command/)** - Adding a new CLI command
+  - Command structure, argument parsing, file I/O
+  - Multiple output formats (JSON, Markdown, HTML)
+  - Node.js + Commander.js
+
+---
+
+## 🔧 Reference
+
+Detailed technical documentation:
+
+- **[Command Reference](command-reference.md)** - All kse commands with examples
+- **[Troubleshooting](troubleshooting.md)** - Solutions to common problems
+- **[FAQ](faq.md)** - Answers to frequently asked questions
+
+---
+
+## 📋 Additional Guides
+
+- **[Adoption Guide](adoption-guide.md)** - Adopting kse in existing projects
+- **[Upgrade Guide](upgrade-guide.md)** - Upgrading kse to newer versions
+- **[Developer Guide](developer-guide.md)** - Contributing to kse development
+- **[Architecture](architecture.md)** - kse system architecture
+
+---
+
+## 🌍 Language
+
+- **English** - You are here
+- **[中文 (Chinese)](zh/README.md)** - Chinese documentation
+
+---
+
+## 📊 Documentation by Audience
+
+### For Beginners
+1. [Quick Start Guide](quick-start.md) - Start here!
+2. [FAQ](faq.md) - Common questions
+3. [Tool-Specific Guide](tools/) - Pick your AI tool
+4. [Examples](examples/) - Learn by example
+
+### For Intermediate Users
+1. [Spec Workflow](spec-workflow.md) - Deep dive into Specs
+2. [Integration Modes](integration-modes.md) - Choose the right mode
+3. [Command Reference](command-reference.md) - Master all commands
+4. [Troubleshooting](troubleshooting.md) - Solve problems
+
+### For Advanced Users
+1. [Developer Guide](developer-guide.md) - Contribute to kse
+2. [Architecture](architecture.md) - Understand internals
+3. [Manual Workflows Guide](manual-workflows-guide.md) - Advanced workflows
+
+---
+
+## 📊 Documentation by Task
+
+### Setting Up
+- [Quick Start Guide](quick-start.md) - First-time setup
+- [Adoption Guide](adoption-guide.md) - Add to existing project
+- [Tool-Specific Guides](tools/) - Configure your AI tool
+
+### Creating Specs
+- [Spec Workflow](spec-workflow.md) - How to create Specs
+- [Examples](examples/) - See complete examples
+- [Quick Start Guide](quick-start.md) - Your first Spec
+
+### Using with AI Tools
+- [Integration Modes](integration-modes.md) - Choose integration mode
+- [Tool-Specific Guides](tools/) - Tool-specific instructions
+- [Command Reference](command-reference.md) - Export context commands
+
+### Troubleshooting
+- [Troubleshooting](troubleshooting.md) - Common issues
+- [FAQ](faq.md) - Quick answers
+- [GitHub Issues](https://github.com/kiro-spec-engine/kse/issues) - Report bugs
+
+---
+
+## 🎯 Quick Links by Feature
+
+### Spec Management
+- [Creating Specs](spec-workflow.md#stage-1-requirements)
+- [Spec Structure](spec-workflow.md#the-spec-creation-workflow)
+- [Example Specs](examples/)
+
+### Context Export
+- [Manual Export Mode](integration-modes.md#mode-2-manual-export)
+- [Export Commands](command-reference.md#context--prompts)
+- [Using Exported Context](tools/)
+
+### Watch Mode
+- [Watch Mode Guide](integration-modes.md#mode-3-watch-mode)
+- [Watch Commands](command-reference.md#watch-mode)
+- [Windsurf Integration](tools/windsurf-guide.md)
+
+### Task Management
+- [Task Commands](command-reference.md#task-management)
+- [Task Workflow](spec-workflow.md#stage-3-tasks)
+- [Team Collaboration](workspace-info.md)
+
+---
+
+## 💡 Tips for Using This Documentation
+
+**Finding Information:**
+- Use your browser's search (Ctrl+F / Cmd+F) to find specific topics
+- Check the [FAQ](faq.md) first for quick answers
+- Browse [Examples](examples/) to learn by doing
+
+**Learning Path:**
+1. **Day 1:** [Quick Start Guide](quick-start.md) + [Your Tool Guide](tools/)
+2. **Week 1:** [Spec Workflow](spec-workflow.md) + [Examples](examples/)
+3. **Month 1:** [Integration Modes](integration-modes.md) + [Advanced Features](command-reference.md)
+
+**Getting Help:**
+- **Quick answers:** [FAQ](faq.md)
+- **Problems:** [Troubleshooting](troubleshooting.md)
+- **Community:** [GitHub Discussions](https://github.com/kiro-spec-engine/kse/discussions)
+- **Bugs:** [GitHub Issues](https://github.com/kiro-spec-engine/kse/issues)
+
+---
+
+## 📝 Documentation Status
+
+| Document | Status | Last Updated |
+|----------|--------|--------------|
+| Quick Start | ✅ Complete | 2026-01-23 |
+| Spec Workflow | ✅ Complete | 2026-01-23 |
+| Integration Modes | ✅ Complete | 2026-01-23 |
+| Tool Guides (6) | ✅ Complete | 2026-01-23 |
+| Examples (3) | ✅ Complete | 2026-01-23 |
+| FAQ | ✅ Complete | 2026-01-23 |
+| Troubleshooting | ✅ Complete | 2026-01-23 |
+| Command Reference | ✅ Complete | 2026-01-23 |
+
+---
+
+## 🤝 Contributing to Documentation
+
+Found an error? Want to improve the docs?
+
+1. **Report issues:** [GitHub Issues](https://github.com/kiro-spec-engine/kse/issues)
+2. **Suggest improvements:** [GitHub Discussions](https://github.com/kiro-spec-engine/kse/discussions)
+3. **Submit changes:** [Contributing Guide](../CONTRIBUTING.md)
+
+---
+
+## 📄 License
+
+Documentation is licensed under [MIT License](../LICENSE).
+
+---
+
+**Happy Spec-ing!** 🚀
+