kiro-spec-engine 1.4.4 → 1.5.5

package/template/.kiro/README.md

@@ -1,288 +1,328 @@
-# Kiro Spec 驱动开发体系
+# kse - Kiro Spec Engine
 
-> **用途**: 新项目引导文档，解释 Spec 驱动开发体系的设计思想和使用方法
+> **AI Tools: Read this first!** This project uses kse (Kiro Spec Engine) for structured development.
 
 ---
 
-## 🎯 这是什么？
+## 🎯 What is kse?
 
-这是一套基于 Spec 驱动的 AI 辅助开发规范体系，包含：
-- **Steering 规范**：控制 AI 行为的规则和上下文
-- **Spec 工作流**：结构化的需求-设计-实施流程
-- **文件组织**：清晰的产物归档和知识沉淀
+**kse** is a CLI tool that provides structured, Spec-driven development workflows for AI-assisted coding.
+
+**Key concepts:**
+- **Spec**: A structured feature definition with requirements, design, and tasks
+- **Context Export**: Generate AI-friendly documentation from Specs
+- **Task Tracking**: Monitor implementation progress
+- **Steering Rules**: AI behavior guidelines in `.kiro/steering/`
+
+**This project has adopted kse** - all development should follow the Spec-driven workflow
 
 ---
 
-## 💡 为什么需要这套体系？
+## 📦 kse Commands (For AI Tools)
 
-### 问题 1：AI Session Token 有限
+### Check Project Status
+```bash
+kse status
+```
+Shows all Specs and their progress.
 
-**挑战**：
-- AI session 启动时会加载所有 Steering 文档
-- 历史数据和详细内容会快速消耗 token
-- Token 耗尽导致无法继续执行任务
+### List All Specs
+```bash
+kse workflows
+```
+Lists all available Specs in `.kiro/specs/`.
 
-**解决方案**：
-- **分层管理**：稳定规则（CORE_PRINCIPLES）+ 动态场景（CURRENT_CONTEXT）
-- **精简原则**：Steering 只保留核心信息，详细内容放到 Spec 目录
-- **主动管控**：每个 Spec 完成后及时更新 CURRENT_CONTEXT
+### Export Spec Context
+```bash
+kse context export <spec-name>
+```
+Generates AI-friendly context from a Spec (requirements + design + tasks).
 
-### 问题 2：规范一致性难以保持
+**Example:**
+```bash
+kse context export 01-00-user-login
+# Creates: .kiro/specs/01-00-user-login/context-export.md
+```
 
-**挑战**：
-- 不同 Spec 使用不同的开发流程
-- 产物散落在项目各处，难以查找
-- 缺乏上下文，不知道为什么要这样做
+### Generate Task Prompt
+```bash
+kse prompt generate <spec-name> <task-id>
+```
+Creates a focused prompt for a specific task.
 
-**解决方案**：
-- **Spec 驱动**：所有工作基于 Spec 推进
-- **统一规范**：CORE_PRINCIPLES 适用于所有 Spec
-- **产物归档**：所有产物归档到对应的 Spec 目录
+**Example:**
+```bash
+kse prompt generate 01-00-user-login 1.1
+# Generates prompt for task 1.1 only
+```
 
----
+### Claim a Task
+```bash
+kse task claim <spec-name> <task-id>
+```
+Mark a task as "in progress" and assign it to yourself.
 
-## 📚 文件组织
+**Example:**
+```bash
+kse task claim 01-00-user-login 1.1
+```
 
-### Steering 目录（AI 每次启动时加载）
+### Check Adoption Status
+```bash
+kse doctor
+```
+Verifies kse is properly configured in the project.
 
-| 文件 | 职责 | Token 影响 | 更新频率 |
-|------|------|-----------|---------|
-| **RULES_GUIDE.md** | 索引和快速参考 | 低 | 很少 |
-| **CORE_PRINCIPLES.md** | 核心开发规范 | 中 | 很少 |
-| **ENVIRONMENT.md** | 环境配置 | 低 | 很少 |
-| **CURRENT_CONTEXT.md** | 当前 Spec 场景 | **高** ⚠️ | 每个 Spec |
+---
+
+## 🤖 AI Workflow Guide
 
-### Specs 目录（按需加载）
+### When User Asks to Implement a Feature
 
+**Step 1: Check if Spec exists**
+```bash
+kse workflows
 ```
-.kiro/specs/
-├── SPEC_WORKFLOW_GUIDE.md    # Spec 工作流指南
-└── {spec-name}/               # 具体的 Spec
-    ├── requirements.md        # 需求文档
-    ├── design.md              # 设计文档（可选）
-    ├── tasks.md               # 任务列表（可选）
-    ├── scripts/               # 脚本
-    ├── diagnostics/           # 诊断文档
-    └── results/               # 执行结果
+
+**Step 2: Export Spec context**
+```bash
+kse context export <spec-name>
 ```
 
----
+**Step 3: Read the exported context**
+```bash
+# Context is at: .kiro/specs/<spec-name>/context-export.md
+```
 
-## 🔄 Steering 体系的核心思想
+**Step 4: Implement according to the Spec**
+- Follow requirements in `requirements.md`
+- Follow design in `design.md`
+- Complete tasks from `tasks.md`
 
-### 1. 最小化 Token 消耗
+**Step 5: Update task status**
+- Mark tasks as complete: `- [x] 1.1 Task description`
+- Mark tasks in progress: `- [-] 1.1 Task description`
 
-**原则**：
-- Steering 文档在每次 session 启动时**完全加载**
-- 必须保持精简，避免历史数据堆积
-- CURRENT_CONTEXT 需要随 Spec 推进及时更新
+### When User Asks About Project Status
 
-**实践**：
-- ❌ 不要在 Steering 中保留详细的历史数据
-- ❌ 不要在 Steering 中保留详细的配置和命令
-- ✅ 历史数据归档到 Spec 目录
-- ✅ 详细配置放到 Spec 文档中
+```bash
+kse status
+```
 
-### 2. 规范的可复用性
+This shows:
+- All Specs in the project
+- Task completion progress
+- Current active Specs
 
-**原则**：
-- CORE_PRINCIPLES 适用于所有 Spec
-- 新项目可以直接复制这套体系
-- 只需修正 ENVIRONMENT 和 CURRENT_CONTEXT
+### When User Asks to Start a New Feature
 
-**实践**：
-- ✅ CORE_PRINCIPLES 保持稳定，很少修改
-- ✅ ENVIRONMENT 记录项目特定的环境配置
-- ✅ CURRENT_CONTEXT 随 Spec 动态更新
+**If no Spec exists:**
+```
+I notice there's no Spec for this feature yet. 
+Would you like me to create one? I can help you define:
+1. Requirements (what we're building)
+2. Design (how we'll build it)
+3. Tasks (implementation steps)
+```
 
-### 3. 上下文的聚焦性
+**If Spec exists:**
+```bash
+kse context export <spec-name>
+# Then read and implement according to the Spec
+```
 
-**原则**：
-- CURRENT_CONTEXT 只保留当前 Spec 的核心信息
-- 历史数据归档到 Spec 目录，不占用 Steering 空间
-- 每个 Spec 开始前必须更新 CURRENT_CONTEXT
+---
 
-**实践**：
-- ✅ 每个新 Spec 开始前：更新 CURRENT_CONTEXT
-- ✅ Spec 推进中：及时精简已完成内容
-- ✅ Spec 完成后：清空 CURRENT_CONTEXT
+## 📁 Directory Structure
 
----
+```
+.kiro/
+├── README.md                  # This file - kse usage guide
+├── specs/                     # All Specs live here
+│   ├── SPEC_WORKFLOW_GUIDE.md # Detailed Spec workflow
+│   └── {spec-name}/           # Individual Spec
+│       ├── requirements.md    # What we're building
+│       ├── design.md          # How we'll build it
+│       ├── tasks.md           # Implementation steps
+│       ├── context-export.md  # AI-friendly export (generated)
+│       ├── scripts/           # Spec-specific scripts
+│       ├── tests/             # Spec-specific tests
+│       └── results/           # Execution results
+├── steering/                  # AI behavior rules
+│   ├── RULES_GUIDE.md         # Quick reference
+│   ├── CORE_PRINCIPLES.md     # Core development rules
+│   ├── ENVIRONMENT.md         # Project environment
+│   └── CURRENT_CONTEXT.md     # Current Spec context
+└── tools/                     # Tool configurations
+```
 
-## 🚀 如何在新项目中使用？
+**Key files for AI:**
+- `.kiro/README.md` (this file) - kse command reference
+- `.kiro/steering/CORE_PRINCIPLES.md` - Development rules
+- `.kiro/steering/CURRENT_CONTEXT.md` - Current work context
+- `.kiro/specs/{spec-name}/context-export.md` - Spec context
 
-### 步骤 1：复制 Steering 模板
+---
 
-```bash
-# 从模板项目复制
-cp -r template-project/.kiro/ new-project/.kiro/
-```
+## 📖 Spec Structure
 
-### 步骤 2：修正 ENVIRONMENT.md
+Each Spec contains three core documents:
 
-更新为新项目的实际环境：
-- 服务器信息（如有）
-- 数据库配置
-- 部署方式
-- AI 权限范围
+### 1. requirements.md
+**Purpose:** Define WHAT we're building
 
-### 步骤 3：清空 CURRENT_CONTEXT.md
+**Contains:**
+- User stories
+- Functional requirements
+- Non-functional requirements
+- Acceptance criteria
 
-删除旧项目的场景信息，标记为"无活跃 Spec"。
+### 2. design.md
+**Purpose:** Define HOW we'll build it
 
-### 步骤 4：检查 CORE_PRINCIPLES.md
+**Contains:**
+- Architecture overview
+- Component design
+- API design
+- Data models
+- Technology choices
 
-确认规范是否适用于新项目，必要时调整（但尽量保持稳定）。
+### 3. tasks.md
+**Purpose:** Break down implementation
 
-### 步骤 5：修正 SPEC_WORKFLOW_GUIDE.md
+**Contains:**
+- Ordered task list
+- Task dependencies
+- Implementation notes
 
-更新项目特定的内容：
-- 项目名称
-- 技术栈
-- 示例
+**Task status markers:**
+- `- [ ]` Not started
+- `- [-]` In progress
+- `- [x]` Completed
 
 ---
 
-## 📖 Spec 驱动开发工作流程
-
-### 标准流程
+## 🎯 Spec-Driven Workflow
 
 ```
-1. 创建 Spec 目录
+1. User requests feature
    ↓
-2. 编写需求文档 (requirements.md)
+2. Check if Spec exists (kse workflows)
    ↓
-3. 编写设计文档 (design.md) - 可选
+3. If no Spec: Suggest creating one
+   If Spec exists: Export context (kse context export)
    ↓
-4. 创建任务列表 (tasks.md) - 可选
+4. Read requirements.md and design.md
    ↓
-5. 执行任务（调研、分析、实现、测试）
+5. Implement according to Spec
    ↓
-6. 所有产物归档到 Spec 目录
+6. Update tasks.md as you complete tasks
    ↓
-7. 更新 CURRENT_CONTEXT 为下一个 Spec
+7. Verify against acceptance criteria
 ```
 
-### 为什么要用 Spec 驱动？
-
-**优点**：
-- ✅ 所有工作有明确的需求和设计支持
-- ✅ 产物有上下文，易于理解和维护
-- ✅ 可以追溯需求和设计决策
-- ✅ 团队协作更清晰
-- ✅ 知识沉淀在 Spec 中
-
-**不用 Spec 的问题**：
-- ❌ 脚本散落在项目各处，难以查找
-- ❌ 缺乏上下文，不知道为什么要这样做
-- ❌ 无法追溯需求来源
-- ❌ 临时文件堆积，项目混乱
-- ❌ 知识流失
+**Why Spec-driven?**
+- ✅ Clear requirements before coding
+- ✅ Consistent architecture decisions
+- ✅ Trackable progress
+- ✅ Better AI understanding of context
+- ✅ Knowledge preserved in Specs
 
 ---
 
-## 💡 最佳实践
+## 🔧 Common AI Tasks
 
-### 1. 主动管控 Token
+### Task 1: Implement a Feature
 
-**时机**：
-- 每完成一组任务后：精简 tasks.md
-- 每完成一个阶段后：精简 CURRENT_CONTEXT
-- 发现 token 使用率 > 50% 时：立即精简
-- 阶段切换时：更新 CURRENT_CONTEXT 聚焦新阶段
+```bash
+# 1. Check what Specs exist
+kse workflows
 
-**策略**：
-- ❌ 删除：已完成阶段的详细配置、命令、表格
-- ❌ 删除：历史测试数据和性能对比表格
-- ❌ 删除：详细的问题排查流程和检查清单
-- ✅ 保留：当前阶段的核心信息和关键经验
+# 2. Export the Spec context
+kse context export 01-00-user-login
 
-### 2. 保持 Steering 精简
+# 3. Read the context
+# File: .kiro/specs/01-00-user-login/context-export.md
 
-**原则**：
-- CURRENT_CONTEXT 只保留当前信息
-- 历史数据归档到 Spec 目录
-- 详细配置放到 Spec 文档中
+# 4. Implement according to requirements and design
 
-**检查清单**：
-- [ ] CURRENT_CONTEXT 是否聚焦当前 Spec？
-- [ ] 历史阶段的详细内容是否已移除？
-- [ ] 详细数据是否已归档到 Spec 目录？
-- [ ] Token 使用率是否 < 50%？
+# 5. Update tasks.md to mark tasks complete
+```
 
-### 3. 规范的一致性
+### Task 2: Check Project Status
 
-**原则**：
-- 所有 Spec 遵循相同的规范
-- 不要在不同 Spec 中使用不同的流程
-- 发现问题及时更新 CORE_PRINCIPLES
+```bash
+kse status
+```
 
-**实践**：
-- ✅ 基于 Spec 推进所有工作
-- ✅ 产物归档到对应的 Spec 目录
-- ✅ 不要在根目录生成临时文件
+Shows all Specs and their completion progress.
 
-### 4. 知识的沉淀
+### Task 3: Work on Specific Task
 
-**原则**：
-- 通用经验沉淀到 CORE_PRINCIPLES
-- Spec 特定经验保留在 Spec 目录
-- 定期回顾和更新规范
+```bash
+# Generate focused prompt for one task
+kse prompt generate 01-00-user-login 1.1
 
-**时机**：
-- Spec 完成后：总结经验教训
-- 新 Spec 开始前：评估现有规则是否适用
-- 发现重复问题时：更新 CORE_PRINCIPLES
+# Claim the task
+kse task claim 01-00-user-login 1.1
 
----
+# Implement the task
 
-## ⚠️ 常见错误
+# Mark complete in tasks.md
+```
 
-### 错误 1：CURRENT_CONTEXT 膨胀
+### Task 4: Understand Project Context
 
-**现象**：
-- session 启动后 token 使用率 > 50%
-- CURRENT_CONTEXT 包含大量历史数据
+**Read these files in order:**
+1. `.kiro/README.md` (this file) - kse basics
+2. `.kiro/steering/CURRENT_CONTEXT.md` - Current work
+3. `.kiro/steering/CORE_PRINCIPLES.md` - Development rules
+4. `.kiro/specs/{spec-name}/requirements.md` - Feature requirements
+5. `.kiro/specs/{spec-name}/design.md` - Feature design
 
-**解决**：
-- 立即精简 CURRENT_CONTEXT
-- 将详细数据归档到 Spec 目录
-- 只保留当前阶段的核心信息
+---
 
-### 错误 2：规范不一致
+## 💡 Best Practices for AI
 
-**现象**：
-- 不同 Spec 使用不同的开发流程
-- 文件组织混乱
+### DO:
+- ✅ Always check `kse workflows` to see available Specs
+- ✅ Export context before implementing: `kse context export <spec>`
+- ✅ Follow requirements and design documents strictly
+- ✅ Update tasks.md as you complete work
+- ✅ Read steering rules in `.kiro/steering/`
+- ✅ Keep all Spec artifacts in the Spec directory
 
-**解决**：
-- 重新阅读 CORE_PRINCIPLES
-- 按照规范重新组织文件
-- 将散落的产物归档到 Spec 目录
+### DON'T:
+- ❌ Implement features without checking for Specs first
+- ❌ Ignore requirements or design documents
+- ❌ Create temporary files in project root
+- ❌ Skip updating task status
+- ❌ Deviate from architecture without discussion
 
-### 错误 3：产物散落
+---
 
-**现象**：
-- 脚本、测试、报告散落在项目各处
-- 缺乏上下文，难以理解
+## 🚀 Quick Reference
 
-**解决**：
-- 所有产物归档到对应的 Spec 目录
-- 不要在根目录生成临时文件
-- 遵循 Spec 驱动开发原则
+| Task | Command |
+|------|---------|
+| List all Specs | `kse workflows` |
+| Check status | `kse status` |
+| Export Spec | `kse context export <spec>` |
+| Generate task prompt | `kse prompt generate <spec> <task>` |
+| Claim task | `kse task claim <spec> <task>` |
+| Verify setup | `kse doctor` |
 
 ---
 
-## 📚 相关文档
+## 📚 Learn More
 
-- **Steering 索引**: `.kiro/steering/RULES_GUIDE.md`
-- **核心开发原则**: `.kiro/steering/CORE_PRINCIPLES.md`
-- **环境配置**: `.kiro/steering/ENVIRONMENT.md`
-- **当前场景**: `.kiro/steering/CURRENT_CONTEXT.md`
-- **Spec 工作流指南**: `.kiro/specs/SPEC_WORKFLOW_GUIDE.md`
+- **Spec Workflow Guide**: `.kiro/specs/SPEC_WORKFLOW_GUIDE.md`
+- **Core Principles**: `.kiro/steering/CORE_PRINCIPLES.md`
+- **Current Context**: `.kiro/steering/CURRENT_CONTEXT.md`
+- **Environment**: `.kiro/steering/ENVIRONMENT.md`
 
 ---
 
-**版本**: v1.0  
-**创建**: 2025-01-22  
-**说明**: 这是新项目引导文档，日常开发时不需要加载
+**kse Version**: 1.5.4  
+**Last Updated**: 2026-01-24  
+**Purpose**: AI tool reference for kse usage