kiro-spec-engine 1.6.1 → 1.6.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +39 -0
- package/README.md +52 -66
- package/README.zh.md +52 -66
- package/lib/commands/status.js +1 -1
- package/lib/governance/diagnostic-engine.js +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,45 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [1.6.3] - 2026-01-24
|
|
9
|
+
|
|
10
|
+
### Fixed
|
|
11
|
+
- **Fixed incorrect command recommendations in diagnostic tools** 🐛
|
|
12
|
+
- Updated `lib/governance/diagnostic-engine.js` to recommend `kse docs archive --spec <spec-name>` instead of `kse archive --spec <spec-name>`
|
|
13
|
+
- Updated `lib/commands/status.js` to show correct archive command in quick fix suggestions
|
|
14
|
+
- Fixed all related test expectations to match actual command structure
|
|
15
|
+
- **Impact**: Users will now see correct commands when `kse doctor --docs` or `kse status` detect misplaced artifacts
|
|
16
|
+
- **Root cause**: Documentation/functionality mismatch - the actual command is `kse docs archive`, not `kse archive`
|
|
17
|
+
|
|
18
|
+
**Discovered from real user feedback:**
|
|
19
|
+
> User's AI (Codex) tried to run `kse archive --spec 01-00-user-space-diagnosis`
|
|
20
|
+
> based on `kse doctor --docs` recommendation, but got `error: unknown command 'archive'`
|
|
21
|
+
|
|
22
|
+
**Why this matters:**
|
|
23
|
+
- Prevents user confusion when following system recommendations
|
|
24
|
+
- AI agents will now execute correct commands automatically
|
|
25
|
+
- Improves reliability of automated workflows
|
|
26
|
+
|
|
27
|
+
## [1.6.2] - 2026-01-24
|
|
28
|
+
|
|
29
|
+
### Changed
|
|
30
|
+
- **Simplified Quick Start based on real user feedback** 📝
|
|
31
|
+
- Added "The Simplest Way" section (30 seconds, one command to AI)
|
|
32
|
+
- Moved detailed steps into collapsible section
|
|
33
|
+
- Reflects actual user experience: "Just tell AI to install and use kse"
|
|
34
|
+
- AI handles everything automatically (install, adopt, read docs, start working)
|
|
35
|
+
- Updated both English and Chinese README files
|
|
36
|
+
|
|
37
|
+
**User feedback:**
|
|
38
|
+
> "I just told Codex to install kse, and it figured out how to use it.
|
|
39
|
+
> Then I just said 'use this mode to manage the project' and it worked."
|
|
40
|
+
|
|
41
|
+
**Why this matters:**
|
|
42
|
+
- Reduces perceived complexity from "5 minutes, 4 steps" to "30 seconds, 1 command"
|
|
43
|
+
- Matches real-world usage pattern
|
|
44
|
+
- Emphasizes AI autonomy rather than manual steps
|
|
45
|
+
- Makes kse feel even more like "invisible infrastructure"
|
|
46
|
+
|
|
8
47
|
## [1.6.1] - 2026-01-24
|
|
9
48
|
|
|
10
49
|
### Fixed
|
package/README.md
CHANGED
|
@@ -45,9 +45,32 @@ graph LR
|
|
|
45
45
|
|
|
46
46
|
---
|
|
47
47
|
|
|
48
|
-
## Quick Start
|
|
48
|
+
## Quick Start
|
|
49
49
|
|
|
50
|
-
###
|
|
50
|
+
### The Simplest Way (30 seconds) ⚡
|
|
51
|
+
|
|
52
|
+
**Just tell your AI:**
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
Install kse and use it to manage this project with Spec-driven development.
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**Your AI will:**
|
|
59
|
+
1. Install kse globally (`npm install -g kiro-spec-engine`)
|
|
60
|
+
2. Adopt it in your project (`kse adopt`)
|
|
61
|
+
3. Read the methodology guide (`.kiro/README.md`)
|
|
62
|
+
4. Start working according to Spec-driven approach
|
|
63
|
+
|
|
64
|
+
**That's it!** Your AI handles everything. No manual steps needed.
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
### Step-by-Step Guide (if you want details) 📋
|
|
69
|
+
|
|
70
|
+
<details>
|
|
71
|
+
<summary><b>Click to expand detailed steps</b></summary>
|
|
72
|
+
|
|
73
|
+
#### Step 1: Install kse (30 seconds)
|
|
51
74
|
|
|
52
75
|
```bash
|
|
53
76
|
npm install -g kiro-spec-engine
|
|
@@ -58,7 +81,7 @@ Verify installation:
|
|
|
58
81
|
kse --version
|
|
59
82
|
```
|
|
60
83
|
|
|
61
|
-
|
|
84
|
+
#### Step 2: Adopt kse in Your Project (30 seconds)
|
|
62
85
|
|
|
63
86
|
Navigate to your project directory and run:
|
|
64
87
|
|
|
@@ -68,86 +91,49 @@ kse adopt
|
|
|
68
91
|
```
|
|
69
92
|
|
|
70
93
|
This creates a `.kiro/` directory with:
|
|
94
|
+
- `README.md` - Project development guide for AI
|
|
71
95
|
- `specs/` - Where your Specs live
|
|
72
|
-
- `steering/` -
|
|
96
|
+
- `steering/` - Development rules (optional)
|
|
73
97
|
|
|
74
|
-
|
|
98
|
+
#### Step 3: Tell Your AI About the Methodology (30 seconds)
|
|
75
99
|
|
|
76
|
-
|
|
77
|
-
kse create-spec 01-00-user-login
|
|
78
|
-
```
|
|
100
|
+
**In your AI tool (Cursor, Claude, Windsurf, Kiro, etc.), say:**
|
|
79
101
|
|
|
80
|
-
This creates three files in `.kiro/specs/01-00-user-login/`:
|
|
81
|
-
|
|
82
|
-
**requirements.md** - What you're building:
|
|
83
|
-
```markdown
|
|
84
|
-
# User Login Feature
|
|
85
|
-
|
|
86
|
-
## User Stories
|
|
87
|
-
- As a user, I want to log in with email and password
|
|
88
|
-
- As a user, I want to see an error if credentials are wrong
|
|
89
|
-
|
|
90
|
-
## Acceptance Criteria
|
|
91
|
-
- WHEN user enters valid credentials THEN they are logged in
|
|
92
|
-
- WHEN user enters invalid credentials THEN they see an error message
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
**design.md** - How you'll build it:
|
|
96
|
-
```markdown
|
|
97
|
-
# Design
|
|
98
|
-
|
|
99
|
-
## API Design
|
|
100
|
-
- POST /api/auth/login
|
|
101
|
-
- Request: { email: string, password: string }
|
|
102
|
-
- Response: { token: string } or { error: string }
|
|
103
|
-
|
|
104
|
-
## Components
|
|
105
|
-
- AuthController - handles login logic
|
|
106
|
-
- validateEmail() - validates email format
|
|
107
|
-
- validatePassword() - checks password requirements
|
|
108
102
|
```
|
|
109
|
-
|
|
110
|
-
**tasks.md** - Step-by-step implementation:
|
|
111
|
-
```markdown
|
|
112
|
-
- [ ] 1.1 Create AuthController class
|
|
113
|
-
- [ ] 1.2 Implement email validation
|
|
114
|
-
- [ ] 1.3 Implement password validation
|
|
115
|
-
- [ ] 1.4 Implement login endpoint
|
|
116
|
-
- [ ] 1.5 Write unit tests
|
|
103
|
+
Please read .kiro/README.md to understand how this project works.
|
|
117
104
|
```
|
|
118
105
|
|
|
119
|
-
|
|
106
|
+
**Your AI will learn:**
|
|
107
|
+
- This project follows Spec-driven development
|
|
108
|
+
- Every feature starts with a Spec (requirements + design + tasks)
|
|
109
|
+
- How to work with this methodology
|
|
110
|
+
- When to use kse commands
|
|
120
111
|
|
|
121
|
-
|
|
112
|
+
#### Step 4: Start Building Features
|
|
122
113
|
|
|
123
|
-
**
|
|
114
|
+
**Just ask your AI to implement features naturally:**
|
|
124
115
|
|
|
125
|
-
Just tell your AI:
|
|
126
116
|
```
|
|
127
|
-
|
|
117
|
+
I need a user login feature with email and password.
|
|
128
118
|
```
|
|
129
119
|
|
|
130
|
-
|
|
131
|
-
1.
|
|
132
|
-
2.
|
|
133
|
-
3.
|
|
134
|
-
4.
|
|
135
|
-
|
|
136
|
-
**For web-based AI tools (ChatGPT, Claude web):**
|
|
120
|
+
**Your AI will automatically:**
|
|
121
|
+
1. Create a Spec with requirements, design, and tasks
|
|
122
|
+
2. Implement according to the Spec
|
|
123
|
+
3. Update task status as work progresses
|
|
124
|
+
4. Use kse commands internally (you don't need to run them)
|
|
137
125
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
126
|
+
**Example conversation:**
|
|
127
|
+
- **You**: "I need user login with email and password"
|
|
128
|
+
- **AI**: "I'll create a Spec for this. Let me define the requirements..."
|
|
129
|
+
- **AI**: "Here's the design... Now I'll implement task 1.1..."
|
|
130
|
+
- **AI**: "Task 1.1 complete. Moving to task 1.2..."
|
|
141
131
|
|
|
142
|
-
|
|
143
|
-
cat .kiro/specs/01-00-user-login/context-export.md | pbcopy # macOS
|
|
144
|
-
type .kiro\specs\01-00-user-login\context-export.md | clip # Windows
|
|
132
|
+
</details>
|
|
145
133
|
|
|
146
|
-
|
|
147
|
-
"Here's my Spec. Please implement task 1.1"
|
|
148
|
-
```
|
|
134
|
+
---
|
|
149
135
|
|
|
150
|
-
**
|
|
136
|
+
**Key insight:** You don't "use kse" - your project "follows Spec-driven methodology" and kse helps enforce it. The AI handles all the kse commands for you.
|
|
151
137
|
|
|
152
138
|
### Step 5: Next Steps (30 seconds)
|
|
153
139
|
|
package/README.zh.md
CHANGED
|
@@ -45,9 +45,32 @@ graph LR
|
|
|
45
45
|
|
|
46
46
|
---
|
|
47
47
|
|
|
48
|
-
##
|
|
48
|
+
## 快速开始
|
|
49
49
|
|
|
50
|
-
###
|
|
50
|
+
### 最简单的方式（30 秒）⚡
|
|
51
|
+
|
|
52
|
+
**只需告诉你的 AI：**
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
安装 kse 并用它以 Spec 驱动开发的方式管理这个项目。
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**你的 AI 会：**
|
|
59
|
+
1. 全局安装 kse（`npm install -g kiro-spec-engine`）
|
|
60
|
+
2. 在项目中采用它（`kse adopt`）
|
|
61
|
+
3. 阅读方法论指南（`.kiro/README.md`）
|
|
62
|
+
4. 按照 Spec 驱动方式开始工作
|
|
63
|
+
|
|
64
|
+
**就这样！** 你的 AI 处理一切。不需要手动步骤。
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
### 分步指南（如果你想了解细节）📋
|
|
69
|
+
|
|
70
|
+
<details>
|
|
71
|
+
<summary><b>点击展开详细步骤</b></summary>
|
|
72
|
+
|
|
73
|
+
#### 步骤 1：安装 kse（30 秒）
|
|
51
74
|
|
|
52
75
|
```bash
|
|
53
76
|
npm install -g kiro-spec-engine
|
|
@@ -58,7 +81,7 @@ npm install -g kiro-spec-engine
|
|
|
58
81
|
kse --version
|
|
59
82
|
```
|
|
60
83
|
|
|
61
|
-
|
|
84
|
+
#### 步骤 2：在项目中采用 kse（30 秒）
|
|
62
85
|
|
|
63
86
|
导航到项目目录并运行：
|
|
64
87
|
|
|
@@ -68,86 +91,49 @@ kse adopt
|
|
|
68
91
|
```
|
|
69
92
|
|
|
70
93
|
这会创建一个 `.kiro/` 目录，包含：
|
|
94
|
+
- `README.md` - 给 AI 的项目开发指南
|
|
71
95
|
- `specs/` - Spec 存放位置
|
|
72
|
-
- `steering/` -
|
|
73
|
-
|
|
74
|
-
### 步骤 3：创建第一个 Spec（2 分钟）
|
|
75
|
-
|
|
76
|
-
```bash
|
|
77
|
-
kse create-spec 01-00-user-login
|
|
78
|
-
```
|
|
96
|
+
- `steering/` - 开发规则（可选）
|
|
79
97
|
|
|
80
|
-
|
|
98
|
+
#### 步骤 3：告诉 AI 项目的开发方法（30 秒）
|
|
81
99
|
|
|
82
|
-
|
|
83
|
-
```markdown
|
|
84
|
-
# 用户登录功能
|
|
100
|
+
**在你的 AI 工具中（Cursor、Claude、Windsurf、Kiro 等），说：**
|
|
85
101
|
|
|
86
|
-
## 用户故事
|
|
87
|
-
- 作为用户，我想用邮箱和密码登录
|
|
88
|
-
- 作为用户，我想在凭据错误时看到错误提示
|
|
89
|
-
|
|
90
|
-
## 验收标准
|
|
91
|
-
- 当用户输入有效凭据时，则用户登录成功
|
|
92
|
-
- 当用户输入无效凭据时，则显示错误消息
|
|
93
102
|
```
|
|
94
|
-
|
|
95
|
-
**design.md** - 如何构建：
|
|
96
|
-
```markdown
|
|
97
|
-
# 设计
|
|
98
|
-
|
|
99
|
-
## API 设计
|
|
100
|
-
- POST /api/auth/login
|
|
101
|
-
- 请求：{ email: string, password: string }
|
|
102
|
-
- 响应：{ token: string } 或 { error: string }
|
|
103
|
-
|
|
104
|
-
## 组件
|
|
105
|
-
- AuthController - 处理登录逻辑
|
|
106
|
-
- validateEmail() - 验证邮箱格式
|
|
107
|
-
- validatePassword() - 检查密码要求
|
|
103
|
+
请阅读 .kiro/README.md 了解项目的开发方法。
|
|
108
104
|
```
|
|
109
105
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
-
|
|
113
|
-
-
|
|
114
|
-
-
|
|
115
|
-
- [ ] 1.4 实现登录端点
|
|
116
|
-
- [ ] 1.5 编写单元测试
|
|
117
|
-
```
|
|
106
|
+
**你的 AI 会学到：**
|
|
107
|
+
- 这个项目遵循 Spec 驱动开发
|
|
108
|
+
- 每个功能都从 Spec 开始（需求 + 设计 + 任务）
|
|
109
|
+
- 如何按照这个方法论工作
|
|
110
|
+
- 何时使用 kse 命令
|
|
118
111
|
|
|
119
|
-
|
|
112
|
+
#### 步骤 4：开始构建功能
|
|
120
113
|
|
|
121
|
-
|
|
114
|
+
**自然地让 AI 实现功能：**
|
|
122
115
|
|
|
123
|
-
**对于支持命令执行的 AI 工具（Cursor、Windsurf、Claude Desktop）：**
|
|
124
|
-
|
|
125
|
-
只需告诉你的 AI：
|
|
126
116
|
```
|
|
127
|
-
|
|
117
|
+
我需要一个用邮箱和密码登录的功能。
|
|
128
118
|
```
|
|
129
119
|
|
|
130
|
-
AI
|
|
131
|
-
1.
|
|
132
|
-
2.
|
|
133
|
-
3.
|
|
134
|
-
4.
|
|
135
|
-
|
|
136
|
-
**对于基于 Web 的 AI 工具（ChatGPT、Claude web）：**
|
|
120
|
+
**你的 AI 会自动：**
|
|
121
|
+
1. 创建包含需求、设计和任务的 Spec
|
|
122
|
+
2. 按照 Spec 实现
|
|
123
|
+
3. 随着工作进展更新任务状态
|
|
124
|
+
4. 内部使用 kse 命令（你不需要运行它们）
|
|
137
125
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
126
|
+
**示例对话：**
|
|
127
|
+
- **你**："我需要用邮箱和密码登录的功能"
|
|
128
|
+
- **AI**："我会为此创建一个 Spec。让我定义需求..."
|
|
129
|
+
- **AI**："这是设计... 现在我会实现任务 1.1..."
|
|
130
|
+
- **AI**："任务 1.1 完成。继续任务 1.2..."
|
|
141
131
|
|
|
142
|
-
|
|
143
|
-
cat .kiro/specs/01-00-user-login/context-export.md | pbcopy # macOS
|
|
144
|
-
type .kiro\specs\01-00-user-login\context-export.md | clip # Windows
|
|
132
|
+
</details>
|
|
145
133
|
|
|
146
|
-
|
|
147
|
-
"这是我的 Spec。请实现任务 1.1"
|
|
148
|
-
```
|
|
134
|
+
---
|
|
149
135
|
|
|
150
|
-
**关键洞察：**
|
|
136
|
+
**关键洞察：** 你不是"使用 kse" - 你的项目"遵循 Spec 驱动方法论"，kse 帮助执行它。AI 为你处理所有 kse 命令。
|
|
151
137
|
|
|
152
138
|
### 步骤 5：下一步（30 秒）
|
|
153
139
|
|
package/lib/commands/status.js
CHANGED
|
@@ -280,7 +280,7 @@ async function displayDocumentCompliance(projectPath) {
|
|
|
280
280
|
console.log(` ${chalk.gray('•')} Run diagnostics: ${chalk.cyan('kse doctor --docs')}`);
|
|
281
281
|
console.log(` ${chalk.gray('•')} Clean temporary files: ${chalk.cyan('kse cleanup')}`);
|
|
282
282
|
console.log(` ${chalk.gray('•')} Validate structure: ${chalk.cyan('kse validate --all')}`);
|
|
283
|
-
console.log(` ${chalk.gray('•')} Archive artifacts: ${chalk.cyan('kse archive --spec <name>')}`);
|
|
283
|
+
console.log(` ${chalk.gray('•')} Archive artifacts: ${chalk.cyan('kse docs archive --spec <name>')}`);
|
|
284
284
|
}
|
|
285
285
|
|
|
286
286
|
console.log();
|
|
@@ -229,7 +229,7 @@ class DiagnosticEngine {
|
|
|
229
229
|
|
|
230
230
|
// Misplaced artifacts
|
|
231
231
|
if (summary.byType.misplaced_artifact > 0) {
|
|
232
|
-
recommendations.push('Run `kse archive --spec <spec-name>` to organize artifacts into subdirectories');
|
|
232
|
+
recommendations.push('Run `kse docs archive --spec <spec-name>` to organize artifacts into subdirectories');
|
|
233
233
|
}
|
|
234
234
|
|
|
235
235
|
// Missing required files
|
package/package.json
CHANGED