kiro-spec-engine 1.4.0 → 1.4.1

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.1] - 2026-01-23
+
+### Fixed - Documentation Clarity 🎯
+
+**Corrected Integration Flow**:
+- **Fixed sequence diagrams** - Now correctly show "User ↔ AI Tool ↔ kse" instead of "User → kse → AI Tool"
+- **Emphasized AI-driven workflow** - AI tools call kse directly, users stay in their familiar interface
+- **Clarified positioning** - kse works behind the scenes, users don't "switch tools"
+
+**Updated Documentation**:
+- `README.md` - Rewrote Step 4 to emphasize AI tool calls kse automatically
+- `README.zh.md` - Chinese version updated to match
+- `docs/integration-modes.md` - Fixed sequence diagrams and workflow descriptions
+
+**Key Message**:
+- ✅ Users continue using their preferred AI tool (Cursor, Claude, Windsurf, etc.)
+- ✅ AI tool calls kse commands during conversation
+- ✅ No "tool switching" - seamless integration
+- ✅ kse is the "context provider" working behind the scenes
+
+### Why This Matters
+
+Users are already comfortable with their AI tools. kse enhances their existing workflow by providing structured context, not by replacing their tools. This patch clarifies that positioning.
+
 ## [1.4.0] - 2026-01-23
 
 ### Added - User Onboarding and Documentation Overhaul 📚

package/README.md

@@ -116,31 +116,38 @@ This creates three files in `.kiro/specs/01-00-user-login/`:
 - [ ] 1.5 Write unit tests
 ```
 
-### Step 4: Export Context for Your AI Tool (1 minute)
+### Step 4: Let Your AI Tool Use the Spec (1 minute)
 
-```bash
-kse context export 01-00-user-login
-```
+Now your AI tool can access the Spec to generate better code.
 
-This generates `.kiro/specs/01-00-user-login/context-export.md` with all your Spec information formatted for AI tools.
+**For AI tools with command execution (Cursor, Windsurf, Claude Desktop):**
 
-**Using with different AI tools:**
+Just tell your AI:
+```
+"I have a Spec at 01-00-user-login. Please implement task 1.1"
+```
 
-**Claude Code / ChatGPT:**
-1. Open `context-export.md`
-2. Copy the entire content
-3. Paste into your AI conversation
-4. Say: "Please implement task 1.1"
+The AI will:
+1. Execute `kse context export 01-00-user-login`
+2. Read the Spec (requirements, design, tasks)
+3. Generate code that follows your design
+4. Update task status automatically
+
+**For web-based AI tools (ChatGPT, Claude web):**
 
-**Cursor:**
 ```bash
-kse prompt generate 01-00-user-login 1.1
+# Export context once
+kse context export 01-00-user-login
+
+# Copy to clipboard
+cat .kiro/specs/01-00-user-login/context-export.md | pbcopy  # macOS
+type .kiro\specs\01-00-user-login\context-export.md | clip  # Windows
+
+# Paste into AI tool and say:
+"Here's my Spec. Please implement task 1.1"
 ```
-Copy the generated prompt into Cursor Composer (Cmd+K)
 
-**Windsurf / Cline:**
-Just tell the AI: "Use kse to check the spec for user-login and implement task 1.1"
-(These tools can execute kse commands directly!)
+**The key insight:** You stay in your AI tool. The AI reads the Spec and generates code that matches your design.
 
 ### Step 5: Next Steps (30 seconds)
 

package/docs/integration-modes.md

@@ -88,27 +88,29 @@ Kiro AI:
 ## Mode 2: Manual Export
 
 **Best for:** Claude Code, ChatGPT, Cursor, VS Code + Copilot  
-**Automation Level:** Semi-Manual  
+**Automation Level:** AI-Driven (for tools with command execution) or Semi-Manual (for web tools)  
 **Setup Complexity:** Low
 
 ### How It Works
 
-You manually export context from kse and provide it to your AI tool. The AI tool doesn't directly access kse.
+The AI tool can directly call kse commands during your conversation. You stay in your familiar AI tool interface - the AI handles kse interaction automatically.
 
 ```mermaid
 sequenceDiagram
     participant User
-    participant kse
     participant AI Tool
+    participant kse
     
-    User->>kse: kse context export spec-name
-    kse->>User: context-export.md
-    User->>User: Copy context
-    User->>AI Tool: Paste context
-    AI Tool->>User: Generate code
-    User->>kse: Update tasks.md manually
+    User->>AI Tool: "Implement user login feature"
+    AI Tool->>kse: kse context export user-login
+    kse->>AI Tool: context-export.md content
+    AI Tool->>AI Tool: Generate code based on Spec
+    AI Tool->>User: Here's the implementation
+    AI Tool->>kse: Update tasks.md
 ```
 
+**Note:** For AI tools without command execution (like ChatGPT web), you can manually export and paste as a fallback.
+
 ### Supported Tools
 
 - **Claude Code** - Large context window, excellent understanding
@@ -119,50 +121,52 @@ sequenceDiagram
 
 ### Workflow Example
 
-**Step 1: Export context**
-```bash
-kse context export 01-00-user-login
-```
-
-**Step 2: Copy context**
-```bash
-# macOS
-cat .kiro/specs/01-00-user-login/context-export.md | pbcopy
-
-# Windows
-type .kiro\specs\01-00-user-login\context-export.md | clip
+**With AI tools that can execute commands (Cursor, Windsurf, Claude Desktop):**
 
-# Linux
-cat .kiro/specs/01-00-user-login/context-export.md | xclip -selection clipboard
 ```
+You: "I have a Spec for user login at 01-00-user-login. 
+     Please implement task 1.1: Create AuthController"
 
-**Step 3: Paste into AI tool**
+AI Tool: 
+  [Executes: kse context export 01-00-user-login]
+  [Reads the exported context]
+  [Generates AuthController code]
+  [Updates tasks.md automatically]
+  
+  ✓ Created AuthController with login/logout methods
+  ✓ Updated task 1.1 to complete
 ```
-[Paste context into Claude/ChatGPT/Cursor]
 
-You: "Please implement task 1.1: Create AuthController"
+**With web-based AI tools (ChatGPT, Claude web):**
+
+```bash
+# You run this once
+kse context export 01-00-user-login
+cat .kiro/specs/01-00-user-login/context-export.md | pbcopy
+
+# Then paste into AI tool
+You: "Here's my Spec context: [paste]
+     Please implement task 1.1: Create AuthController"
 
 AI: [Generates code based on your Spec]
-```
 
-**Step 4: Update tasks**
-Edit `.kiro/specs/01-00-user-login/tasks.md`:
-```markdown
-- [x] 1.1 Create AuthController  ← Changed from [ ] to [x]
+# You update tasks manually
+# Edit .kiro/specs/01-00-user-login/tasks.md
 ```
 
 ### Advantages
 
 - ✅ **Works with any AI tool** - Universal compatibility
-- ✅ **Full control** - You decide what context to share
+- ✅ **AI can call kse directly** - For tools with command execution
+- ✅ **Fallback to manual** - Copy-paste for web-based tools
 - ✅ **Simple setup** - No configuration needed
-- ✅ **Reliable** - No dependencies on tool capabilities
+- ✅ **Reliable** - No dependencies on special integrations
 
 ### Limitations
 
-- ❌ **Manual steps** - Copy-paste required
-- ❌ **Context can be stale** - Need to re-export after Spec changes
-- ❌ **Manual task tracking** - You update tasks.md yourself
+- ❌ **Varies by tool** - Command execution depends on AI tool capabilities
+- ❌ **Manual fallback** - Web-based tools require copy-paste
+- ❌ **Context refresh** - May need to re-export after Spec changes (unless using Watch Mode)
 
 ### Optimization Tips
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-spec-engine",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Kiro Spec Engine - A spec-driven development engine with steering rules and quality enhancement powered by Ultrawork spirit",
   "main": "index.js",
   "bin": {