kiro-spec-engine 1.5.5 → 1.6.1

package/CHANGELOG.md

@@ -5,6 +5,65 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.1] - 2026-01-24
+
+### Fixed
+- **Cross-platform path handling in SelectiveBackup** 🐛
+  - Fixed path construction bug in `lib/backup/selective-backup.js`
+  - Changed from string replacement (`this.backupDir.replace('/backups', '')`) to proper path joining
+  - Now uses `path.join(projectPath, '.kiro', filePath)` for consistent cross-platform behavior
+  - Affects both `createSelectiveBackup()` and `restoreSelective()` methods
+  - Ensures backup/restore works correctly on Windows (backslash paths) and Unix (forward slash paths)
+
+**Why this matters:**
+- Previous code used string replacement which failed on Windows paths
+- Could cause backup creation to fail silently or create backups in wrong locations
+- Critical for `kse adopt --force` conflict resolution feature
+
+## [1.6.0] - 2026-01-24
+
+### Changed - BREAKING CONCEPTUAL CHANGE 🎯
+
+**Repositioned kse from "tool" to "methodology enforcer"**
+
+This is a fundamental shift in how kse should be understood and used:
+
+**Before (WRONG approach):**
+- `.kiro/README.md` was a "kse command manual"
+- Taught AI "how to use kse tool"
+- Listed 20+ commands with examples
+- Users had to "learn kse" before using it
+
+**After (CORRECT approach):**
+- `.kiro/README.md` is a "project development guide"
+- Explains project follows Spec-driven methodology
+- AI's role: follow the methodology, not learn the tool
+- kse commands are helpers used automatically when needed
+
+**Key insight from user feedback:**
+> "After installing kse, just tell AI to read .kiro/README.md. 
+> AI will understand the methodology and naturally use kse commands 
+> to solve problems, rather than memorizing command syntax."
+
+**What changed:**
+- `.kiro/README.md` - Completely rewritten as methodology guide (not tool manual)
+- `kse adopt` completion message - Now says "Tell AI to read README" instead of "Create your first spec"
+- `docs/quick-start.md` - Simplified from 5-minute tool tutorial to 2-minute methodology introduction
+- Removed detailed Spec creation examples (that's AI's job, not user's manual work)
+
+**Impact:**
+- Users don't need to "learn kse" anymore
+- AI tools understand project methodology by reading README
+- Natural workflow: User asks for feature → AI creates Spec → AI implements
+- kse becomes invisible infrastructure, not a tool to master
+
+**Migration:**
+- Existing projects: Run `kse adopt --force` to get new README
+- Tell your AI: "Please read .kiro/README.md to understand project methodology"
+- AI will automatically understand and follow Spec-driven approach
+
+This aligns kse with its true purpose: **enforcing development methodology**, not being a CLI tool to learn.
+
 ## [1.5.5] - 2026-01-24
 
 ### Added

package/docs/quick-start.md

@@ -1,711 +1,93 @@
 # Quick Start Guide
 
-> Get started with kse in 5 minutes - from installation to your first AI-assisted feature implementation
-
----
-
-**Version**: 1.0.0  
-**Last Updated**: 2026-01-23  
-**Estimated Time**: 5 minutes  
-**Audience**: Beginners
+> Get your project using Spec-driven development in 2 minutes
 
 ---
 
 ## What You'll Learn
 
-By the end of this guide, you will:
-- ✅ Install kse and set up your first project
-- ✅ Create a complete Spec (Requirements → Design → Tasks)
-- ✅ Export context for your AI tool
-- ✅ Use AI to implement features based on your Spec
-- ✅ Track task progress
-
----
-
-## Prerequisites
-
-Before starting, ensure you have:
-- **Node.js** 14 or higher ([Download](https://nodejs.org/))
-- **npm** 6 or higher (comes with Node.js)
-- Basic command-line knowledge
-- An AI coding tool (Claude, Cursor, Windsurf, Copilot, etc.)
-
-Check your versions:
-```bash
-node --version  # Should show v14.0.0 or higher
-npm --version   # Should show 6.0.0 or higher
-```
+- ✅ Install kse and adopt it in your project
+- ✅ Tell your AI about the methodology
+- ✅ Let AI work according to Spec-driven approach
 
 ---
 
 ## Step 1: Install kse (30 seconds)
 
-Install kse globally using npm:
-
 ```bash
 npm install -g kiro-spec-engine
 ```
 
-**Expected output:**
-```
-added 50 packages in 5s
-```
-
-**Verify installation:**
+Verify:
 ```bash
 kse --version
 ```
 
-**Expected output:**
-```
-1.3.0
-```
-
-**Troubleshooting:**
-- **"kse: command not found"** → Restart your terminal or check your PATH
-- **Permission errors on macOS/Linux** → Use `sudo npm install -g kiro-spec-engine`
-- **Windows permission errors** → Run terminal as Administrator
-
 ---
 
-## Step 2: Adopt kse in Your Project (1 minute)
-
-Navigate to your project directory (or create a new one):
+## Step 2: Adopt in Your Project (30 seconds)
 
 ```bash
-# For existing project
 cd your-project
-
-# Or create a new project
-mkdir my-awesome-app
-cd my-awesome-app
-git init  # kse works best with git projects
-```
-
-**Adopt kse:**
-```bash
 kse adopt
 ```
 
-**Expected output:**
-```
-✓ Detected project type: Node.js
-✓ Created .kiro/ directory
-✓ Created specs/ directory
-✓ Created steering/ directory
-✓ Generated CORE_PRINCIPLES.md
-✓ Generated ENVIRONMENT.md
-✓ Generated CURRENT_CONTEXT.md
-
-✅ Project successfully adopted kse!
-
-Next steps:
-  1. Create your first Spec: kse create-spec 01-00-my-feature
-  2. Read the guide: .kiro/README.md
-```
-
-**What was created:**
-```
-your-project/
-├── .kiro/
-│   ├── specs/              # Your Specs will live here
-│   ├── steering/           # AI behavior rules
-│   │   ├── CORE_PRINCIPLES.md
-│   │   ├── ENVIRONMENT.md
-│   │   └── CURRENT_CONTEXT.md
-│   └── README.md           # Kiro system documentation
-```
-
-**Verification:**
-```bash
-kse status
-```
-
-**Expected output:**
-```
-Project: my-awesome-app
-Specs: 0
-Status: Ready
-```
+This creates `.kiro/` directory with:
+- `README.md` - Project development guide
+- `steering/` - Development rules
+- `specs/` - Where Specs will live
 
 ---
 
-## Step 3: Create Your First Spec (2 minutes)
-
-Let's create a Spec for a user login feature:
-
-```bash
-kse create-spec 01-00-user-login
-```
-
-**Expected output:**
-```
-✓ Created spec: 01-00-user-login
-✓ Created requirements.md
-✓ Created design.md
-✓ Created tasks.md
-
-📝 Next steps:
-  1. Edit requirements.md to define what you're building
-  2. Edit design.md to define how you'll build it
-  3. Edit tasks.md to break down implementation steps
-```
-
-### 3.1 Write Requirements
-
-Open `.kiro/specs/01-00-user-login/requirements.md` and write:
-
-```markdown
-# User Login Feature
-
-## Overview
-Enable users to log in to the application using email and password.
+## Step 3: Tell Your AI (1 minute)
 
-## User Stories
+**In your AI tool (Cursor, Claude, Windsurf, etc.), say:**
 
-### US-1: User Login
-**As a** user  
-**I want to** log in with my email and password  
-**So that** I can access my account
-
-### US-2: Login Validation
-**As a** user  
-**I want to** see clear error messages when login fails  
-**So that** I know what went wrong
-
-## Functional Requirements
-
-### FR-1: Login Form
-The system shall provide a login form with:
-- Email input field
-- Password input field
-- Submit button
-
-### FR-2: Credential Validation
-**WHEN** user submits valid credentials  
-**THEN** system authenticates user and redirects to dashboard
-
-**WHEN** user submits invalid credentials  
-**THEN** system displays error message "Invalid email or password"
-
-### FR-3: Input Validation
-**WHEN** user submits empty email  
-**THEN** system displays error "Email is required"
-
-**WHEN** user submits invalid email format  
-**THEN** system displays error "Please enter a valid email"
-
-**WHEN** user submits password shorter than 6 characters  
-**THEN** system displays error "Password must be at least 6 characters"
-
-## Non-Functional Requirements
-
-### NFR-1: Security
-- Passwords must be hashed before storage
-- Use bcrypt with salt rounds >= 10
-- Implement rate limiting (max 5 attempts per minute)
-
-### NFR-2: Performance
-- Login response time < 500ms
-- Support 100 concurrent login requests
-
-### NFR-3: Usability
-- Clear error messages
-- Accessible form (WCAG 2.1 Level AA)
-
-## Acceptance Criteria
-
-- [ ] User can log in with valid email and password
-- [ ] User sees error message with invalid credentials
-- [ ] Email validation works correctly
-- [ ] Password validation works correctly
-- [ ] Passwords are hashed in database
-- [ ] Rate limiting prevents brute force attacks
-- [ ] Login response time is under 500ms
 ```
-
-### 3.2 Write Design
-
-Open `.kiro/specs/01-00-user-login/design.md` and write:
-
-```markdown
-# User Login - Design Document
-
-## Overview
-This design implements a secure user login system with email/password authentication, input validation, and rate limiting.
-
-## Architecture
-
-### System Components
-
-```mermaid
-graph TD
-    A[Login Form] --> B[AuthController]
-    B --> C[ValidationService]
-    B --> D[AuthService]
-    D --> E[UserRepository]
-    D --> F[TokenService]
-    E --> G[Database]
+Please read .kiro/README.md to understand how this project works.
 ```
 
-## API Design
-
-### POST /api/auth/login
-
-**Request:**
-```json
-{
-  "email": "user@example.com",
-  "password": "secret123"
-}
-```
-
-**Success Response (200):**
-```json
-{
-  "success": true,
-  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-  "user": {
-    "id": "123",
-    "email": "user@example.com",
-    "name": "John Doe"
-  }
-}
-```
-
-**Error Response (401):**
-```json
-{
-  "success": false,
-  "error": "Invalid email or password"
-}
-```
-
-**Error Response (429):**
-```json
-{
-  "success": false,
-  "error": "Too many login attempts. Please try again later."
-}
-```
-
-## Component Design
-
-### AuthController
-**Responsibility:** Handle HTTP requests for authentication
-
-**Methods:**
-- `login(req, res)` - Process login request
-- `validateRequest(req)` - Validate request format
-
-### ValidationService
-**Responsibility:** Validate user input
-
-**Methods:**
-- `validateEmail(email)` - Check email format
-- `validatePassword(password)` - Check password requirements
-- Returns: `{ valid: boolean, errors: string[] }`
-
-### AuthService
-**Responsibility:** Business logic for authentication
-
-**Methods:**
-- `authenticate(email, password)` - Verify credentials
-- `generateToken(user)` - Create JWT token
-- `hashPassword(password)` - Hash password with bcrypt
-
-### UserRepository
-**Responsibility:** Database operations for users
-
-**Methods:**
-- `findByEmail(email)` - Get user by email
-- `updateLastLogin(userId)` - Update last login timestamp
-
-### RateLimiter
-**Responsibility:** Prevent brute force attacks
-
-**Configuration:**
-- Max attempts: 5 per minute per IP
-- Block duration: 15 minutes after limit exceeded
-
-## Data Models
-
-### User
-```javascript
-{
-  id: string,
-  email: string,
-  passwordHash: string,
-  name: string,
-  createdAt: Date,
-  lastLoginAt: Date
-}
-```
-
-## Security Considerations
-
-1. **Password Hashing:** Use bcrypt with 10 salt rounds
-2. **JWT Tokens:** Sign with secret key, expire in 24 hours
-3. **Rate Limiting:** Implement per-IP rate limiting
-4. **Input Sanitization:** Sanitize all user inputs
-5. **HTTPS Only:** Enforce HTTPS in production
-
-## Error Handling
-
-| Error | HTTP Code | Message |
-|-------|-----------|---------|
-| Invalid credentials | 401 | "Invalid email or password" |
-| Missing email | 400 | "Email is required" |
-| Invalid email format | 400 | "Please enter a valid email" |
-| Missing password | 400 | "Password is required" |
-| Password too short | 400 | "Password must be at least 6 characters" |
-| Rate limit exceeded | 429 | "Too many login attempts. Please try again later." |
-| Server error | 500 | "An error occurred. Please try again." |
-
-## Technology Stack
-
-- **Backend:** Node.js + Express
-- **Database:** PostgreSQL
-- **Authentication:** JWT (jsonwebtoken)
-- **Password Hashing:** bcrypt
-- **Rate Limiting:** express-rate-limit
-- **Validation:** validator.js
-
-## Requirements Traceability
-
-| Requirement | Design Component |
-|-------------|------------------|
-| FR-1: Login Form | AuthController.login() |
-| FR-2: Credential Validation | AuthService.authenticate() |
-| FR-3: Input Validation | ValidationService |
-| NFR-1: Security | bcrypt, JWT, RateLimiter |
-| NFR-2: Performance | Indexed database queries |
-| NFR-3: Usability | Clear error messages in API responses |
-```
-
-### 3.3 Write Tasks
-
-Open `.kiro/specs/01-00-user-login/tasks.md` and write:
-
-```markdown
-# User Login - Implementation Tasks
-
-## Phase 1: Setup and Models
-
-- [ ] 1.1 Set up project dependencies
-  - Install express, bcrypt, jsonwebtoken, validator, express-rate-limit
-  - Configure TypeScript (if using)
-
-- [ ] 1.2 Create User model and database schema
-  - Define User interface/class
-  - Create database migration for users table
-  - Add indexes on email field
-
-## Phase 2: Core Services
-
-- [ ] 2.1 Implement ValidationService
-  - Create validateEmail() method
-  - Create validatePassword() method
-  - Write unit tests
-
-- [ ] 2.2 Implement AuthService
-  - Create hashPassword() method
-  - Create authenticate() method
-  - Create generateToken() method
-  - Write unit tests
-
-- [ ] 2.3 Implement UserRepository
-  - Create findByEmail() method
-  - Create updateLastLogin() method
-  - Write unit tests
-
-## Phase 3: API Implementation
-
-- [ ] 3.1 Implement AuthController
-  - Create login() endpoint handler
-  - Add request validation
-  - Add error handling
-  - Write integration tests
-
-- [ ] 3.2 Implement rate limiting
-  - Configure express-rate-limit
-  - Apply to login endpoint
-  - Test rate limiting behavior
-
-## Phase 4: Testing and Documentation
-
-- [ ] 4.1 Write comprehensive tests
-  - Unit tests for all services
-  - Integration tests for API endpoint
-  - Test error scenarios
-  - Test rate limiting
-
-- [ ] 4.2 Create API documentation
-  - Document request/response formats
-  - Add example requests
-  - Document error codes
-
-- [ ] 4.3 Manual testing
-  - Test with valid credentials
-  - Test with invalid credentials
-  - Test input validation
-  - Test rate limiting
-  - Test performance (response time < 500ms)
-
-## Phase 5: Deployment
-
-- [ ] 5.1 Environment configuration
-  - Set up environment variables
-  - Configure JWT secret
-  - Configure database connection
-
-- [ ] 5.2 Deploy to staging
-  - Deploy code
-  - Run smoke tests
-  - Verify functionality
-
-## Notes
-- All passwords must be hashed before storage
-- Use environment variables for secrets
-- Follow project coding standards
-- Write tests before marking tasks complete
-```
+**Your AI will learn:**
+- This project follows Spec-driven development
+- Every feature starts with a Spec (requirements + design + tasks)
+- How to work with this methodology
 
 ---
 
-## Step 4: Export Context for Your AI Tool (1 minute)
+## Step 4: Start Working
 
-Now that your Spec is complete, export it for your AI tool:
+**Just ask your AI to implement features:**
 
-```bash
-kse context export 01-00-user-login
-```
-
-**Expected output:**
 ```
-✓ Exported context to .kiro/specs/01-00-user-login/context-export.md
-✓ Context size: 3.2 KB
-✓ Ready to use with AI tools
+I need a user login feature with email and password.
 ```
 
-**What was created:**
-A file at `.kiro/specs/01-00-user-login/context-export.md` containing:
-- All requirements
-- Complete design
-- Task list
-- Project structure
-- Formatted for AI consumption
-
----
-
-## Step 5: Use Your AI Tool (1 minute)
-
-Now use your AI tool to implement the feature. Choose your tool:
-
-### Option A: Claude Code / ChatGPT
-
-1. **Open the context file:**
-   ```bash
-   # On macOS
-   cat .kiro/specs/01-00-user-login/context-export.md | pbcopy
-   
-   # On Windows
-   type .kiro\specs\01-00-user-login\context-export.md | clip
-   
-   # On Linux
-   cat .kiro/specs/01-00-user-login/context-export.md | xclip -selection clipboard
-   ```
-
-2. **Start a new conversation** with Claude or ChatGPT
-
-3. **Paste the context** and say:
-   ```
-   I've provided the complete Spec for a user login feature.
-   Please implement task 1.1: "Set up project dependencies"
-   ```
-
-4. **Claude/ChatGPT will:**
-   - Understand your requirements and design
-   - Generate the appropriate code
-   - Follow your architecture decisions
-
-### Option B: Cursor
-
-1. **Generate a task-specific prompt:**
-   ```bash
-   kse prompt generate 01-00-user-login 1.1
-   ```
-
-2. **Open Cursor Composer** (Cmd+K or Ctrl+K)
-
-3. **Paste the generated prompt**
-
-4. **Cursor will:**
-   - Read your Spec files
-   - Generate code matching your design
-   - Create or modify files directly
-
-### Option C: Windsurf / Cline
-
-1. **Simply tell the AI:**
-   ```
-   Use kse to check the spec for 01-00-user-login and implement task 1.1
-   ```
-
-2. **The AI will:**
-   - Automatically run `kse context export 01-00-user-login`
-   - Read the exported context
-   - Implement the task
-   - Update task status
-
-### Option D: VS Code + Copilot
-
-1. **Create a new file** (e.g., `src/auth/AuthController.js`)
+**Your AI will:**
+1. Suggest creating a Spec first
+2. Help you define requirements
+3. Design the solution
+4. Break down into tasks
+5. Implement according to the Spec
 
-2. **Add a comment referencing your Spec:**
-   ```javascript
-   // Task 1.1: Set up project dependencies
-   // See: .kiro/specs/01-00-user-login/design.md
-   // 
-   // Install: express, bcrypt, jsonwebtoken, validator, express-rate-limit
-   ```
-
-3. **Copilot will:**
-   - Suggest code based on your Spec
-   - Follow your design patterns
-   - Generate appropriate implementations
+**The AI uses kse commands automatically** - you don't need to learn them.
 
 ---
 
-## Step 6: Track Your Progress (30 seconds)
-
-As you complete tasks, update the task status:
-
-**Edit** `.kiro/specs/01-00-user-login/tasks.md`:
+## That's It!
 
-```markdown
-- [x] 1.1 Set up project dependencies  ← Changed from [ ] to [x]
-- [ ] 1.2 Create User model and database schema
-```
+You're now using Spec-driven development. Your AI understands the methodology and will follow it.
 
-**Check your progress:**
-```bash
-kse status
-```
-
-**Expected output:**
-```
-Project: my-awesome-app
-Specs: 1
-
-Spec: 01-00-user-login
-  Total tasks: 15
-  Completed: 1
-  In progress: 0
-  Not started: 14
-  Progress: 6.7%
-```
+**Key insight:** You don't "use kse" - your project "follows Spec-driven methodology" and kse helps enforce it.
 
 ---
 
 ## Next Steps
 
-Congratulations! You've completed the quick start. Here's what to do next:
-
-### Learn More About Integration
-
-Choose your AI tool for detailed guidance:
-- **[Cursor Guide](tools/cursor-guide.md)** - Deep dive into Cursor integration
-- **[Claude Guide](tools/claude-guide.md)** - Best practices for Claude Code
-- **[Windsurf Guide](tools/windsurf-guide.md)** - Automated workflows with Windsurf
-- **[Generic Guide](tools/generic-guide.md)** - Works with any AI tool
-
-### Explore Advanced Features
-
-- **[Integration Modes](integration-modes.md)** - Native, Manual, and Watch Mode
+- **[Integration Modes](integration-modes.md)** - Understand how AI tools work with kse
 - **[Spec Workflow](spec-workflow.md)** - Deep dive into Spec creation
-- **[Command Reference](command-reference.md)** - All kse commands
-
-### See Real Examples
-
-- **[API Feature Example](examples/add-rest-api/)** - Complete RESTful API Spec
-- **[UI Feature Example](examples/add-user-dashboard/)** - React dashboard Spec
-- **[CLI Feature Example](examples/add-export-command/)** - CLI command Spec
-
----
-
-## Troubleshooting
-
-### Issue: "kse: command not found"
-
-**Solution:**
-1. Restart your terminal
-2. Check if npm global bin is in PATH:
-   ```bash
-   npm config get prefix
-   ```
-3. Add to PATH if needed (macOS/Linux):
-   ```bash
-   export PATH="$(npm config get prefix)/bin:$PATH"
-   ```
-
-### Issue: Context file is too large for AI tool
-
-**Solution:** Generate task-specific prompts:
-```bash
-kse prompt generate 01-00-user-login 1.1
-```
-
-This creates a smaller, focused context for just that task.
-
-### Issue: AI doesn't follow my design
-
-**Solution:**
-1. Make your design.md more detailed
-2. Add code examples in design.md
-3. Be explicit in your prompt: "Strictly follow the design document"
-4. Include steering rules:
-   ```bash
-   kse context export 01-00-user-login --steering
-   ```
-
-### Issue: Can't find my Spec files
-
-**Solution:**
-All Specs are in `.kiro/specs/`:
-```bash
-ls .kiro/specs/
-```
-
-### More Help
-
-- 📖 **[Troubleshooting Guide](troubleshooting.md)** - Common issues and solutions
-- 🤔 **[FAQ](faq.md)** - Frequently asked questions
-- 💬 **[GitHub Discussions](https://github.com/yourusername/kiro-spec-engine/discussions)** - Community help
-
----
-
-## Summary
-
-You've learned how to:
-- ✅ Install and set up kse
-- ✅ Create structured Specs with requirements, design, and tasks
-- ✅ Export context for AI tools
-- ✅ Use AI to implement features based on Specs
-- ✅ Track implementation progress
-
-**The kse workflow:**
-```
-Create Spec → Export Context → AI Implements → Update Tasks → Repeat
-```
-
-**Ready to build your next feature?** 🚀
-
-```bash
-kse create-spec 02-00-your-next-feature
-```
+- **[Tool Guides](tools/)** - Tool-specific tips
 
 ---
 
-**Version**: 1.0.0  
-**Last Updated**: 2026-01-23
+**Version**: 2.0.0  
+**Last Updated**: 2026-01-24

package/lib/backup/selective-backup.js

@@ -53,7 +53,7 @@ class SelectiveBackup {
     
     // Backup each file
     for (const filePath of filePaths) {
-      const sourcePath = path.join(projectPath, this.backupDir.replace('/backups', ''), filePath);
+      const sourcePath = path.join(projectPath, '.kiro', filePath);
       const destPath = path.join(filesBackupPath, filePath);
       
       // Check if source file exists
@@ -138,7 +138,7 @@ class SelectiveBackup {
     for (const filePath of filesToRestore) {
       try {
         const sourcePath = path.join(backupPath, 'files', filePath);
-        const destPath = path.join(projectPath, this.backupDir.replace('/backups', ''), filePath);
+        const destPath = path.join(projectPath, '.kiro', filePath);
         
         // Check if backup file exists
         const sourceExists = await pathExists(sourcePath);

package/lib/commands/adopt.js

@@ -399,11 +399,11 @@ async function adoptCommand(options = {}) {
       
       console.log();
       console.log(chalk.blue('💡 Next steps:'));
-      console.log('  1. Review the .kiro/ directory structure');
-      console.log('  2. Create your first spec: ' + chalk.cyan('kse create-spec my-feature'));
-      console.log('  3. Check project status: ' + chalk.cyan('kse status'));
+      console.log('  1. Tell your AI: "Read .kiro/README.md to understand project methodology"');
+      console.log('  2. Start working: Ask AI to implement features following Spec-driven approach');
+      console.log('  3. Check progress: ' + chalk.cyan('kse status'));
       console.log();
-      console.log(chalk.red('🔥') + ' Ready to build with Kiro Spec Engine!');
+      console.log(chalk.red('🔥') + ' Project now follows Spec-driven development!');
     } else {
       console.log(chalk.red('❌ Adoption failed'));
       console.log();

package/package.json

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

package/template/.kiro/README.md

@@ -1,328 +1,181 @@
-# kse - Kiro Spec Engine
+# Project Development Guide
 
-> **AI Tools: Read this first!** This project uses kse (Kiro Spec Engine) for structured development.
+> **AI Tools: Read this first!** This project follows Spec-driven development methodology.
 
 ---
 
-## 🎯 What is kse?
+## 🎯 How This Project Works
 
-**kse** is a CLI tool that provides structured, Spec-driven development workflows for AI-assisted coding.
+This project uses **Spec-driven development** - a structured approach where:
+- Every feature starts with a **Spec** (requirements + design + tasks)
+- All work is tracked and documented
+- AI tools help implement features according to Specs
 
-**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/`
+**Your role as AI:**
+- When user requests a feature → Check if Spec exists, if not, help create one
+- When implementing → Follow the Spec's requirements and design
+- When stuck → Read the Spec documents for context
+- Track progress by updating task status
 
-**This project has adopted kse** - all development should follow the Spec-driven workflow
+**The tool `kse` helps you:**
+- Check project status: `kse status`
+- Find Specs: `kse workflows`
+- Get context: `kse context export <spec-name>`
+- But you don't need to memorize commands - use them when needed
 
 ---
 
-## 📦 kse Commands (For AI Tools)
+## 📋 Development Workflow
 
-### Check Project Status
-```bash
-kse status
-```
-Shows all Specs and their progress.
-
-### List All Specs
-```bash
-kse workflows
-```
-Lists all available Specs in `.kiro/specs/`.
-
-### Export Spec Context
-```bash
-kse context export <spec-name>
-```
-Generates AI-friendly context from a Spec (requirements + design + tasks).
-
-**Example:**
-```bash
-kse context export 01-00-user-login
-# Creates: .kiro/specs/01-00-user-login/context-export.md
-```
-
-### Generate Task Prompt
-```bash
-kse prompt generate <spec-name> <task-id>
-```
-Creates a focused prompt for a specific task.
-
-**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
-```
-
-### Check Adoption Status
-```bash
-kse doctor
-```
-Verifies kse is properly configured in the project.
-
----
-
-## 🤖 AI Workflow Guide
-
-### When User Asks to Implement a Feature
+### When User Asks You to Implement a Feature
 
 **Step 1: Check if Spec exists**
-```bash
-kse workflows
 ```
-
-**Step 2: Export Spec context**
-```bash
-kse context export <spec-name>
+Look in .kiro/specs/ directory
 ```
 
-**Step 3: Read the exported context**
-```bash
-# Context is at: .kiro/specs/<spec-name>/context-export.md
-```
+**Step 2: If Spec exists**
+- Read `requirements.md` - understand what to build
+- Read `design.md` - understand how to build it
+- Read `tasks.md` - see implementation steps
+- Implement according to the Spec
+- Update task status as you complete work
 
-**Step 4: Implement according to the Spec**
-- Follow requirements in `requirements.md`
-- Follow design in `design.md`
-- Complete tasks from `tasks.md`
+**Step 3: If no Spec exists**
+- Suggest creating a Spec first
+- Help user define requirements
+- Help design the solution
+- Break down into tasks
+- Then implement
 
-**Step 5: Update task status**
-- Mark tasks as complete: `- [x] 1.1 Task description`
-- Mark tasks in progress: `- [-] 1.1 Task description`
+**Why Spec-first?**
+- Clear requirements prevent misunderstandings
+- Design decisions are documented
+- Progress is trackable
+- Knowledge is preserved
 
 ### When User Asks About Project Status
 
+Check what's happening:
 ```bash
 kse status
 ```
 
-This shows:
-- All Specs in the project
-- Task completion progress
-- Current active Specs
-
-### When User Asks to Start a New Feature
+This shows all Specs and their progress.
 
-**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)
-```
+### When You Need Context
 
-**If Spec exists:**
+If you need to understand a feature:
 ```bash
 kse context export <spec-name>
-# Then read and implement according to the Spec
 ```
 
+This generates a summary of requirements, design, and tasks.
+
 ---
 
-## 📁 Directory Structure
+## 📁 Project Structure
 
 ```
 .kiro/
-├── README.md                  # This file - kse usage guide
+├── README.md                  # This file - project development 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
+│       └── ...                # Other artifacts
+├── steering/                  # Development rules
+│   ├── CORE_PRINCIPLES.md     # Core development principles
 │   ├── ENVIRONMENT.md         # Project environment
-│   └── CURRENT_CONTEXT.md     # Current Spec context
+│   └── CURRENT_CONTEXT.md     # Current work 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
+**Key files:**
+- `.kiro/steering/CORE_PRINCIPLES.md` - Development principles for this project
+- `.kiro/steering/CURRENT_CONTEXT.md` - What we're currently working on
+- `.kiro/specs/{spec-name}/` - Feature specifications
 
 ---
 
-## 📖 Spec Structure
-
-Each Spec contains three core documents:
+## 📖 What is a Spec?
 
-### 1. requirements.md
-**Purpose:** Define WHAT we're building
+A Spec is a complete feature definition with three parts:
 
-**Contains:**
+### 1. requirements.md - WHAT we're building
 - User stories
 - Functional requirements
-- Non-functional requirements
 - Acceptance criteria
+- Non-functional requirements
 
-### 2. design.md
-**Purpose:** Define HOW we'll build it
-
-**Contains:**
-- Architecture overview
+### 2. design.md - HOW we'll build it
+- Architecture
 - Component design
 - API design
-- Data models
 - Technology choices
 
-### 3. tasks.md
-**Purpose:** Break down implementation
-
-**Contains:**
+### 3. tasks.md - Implementation steps
 - Ordered task list
 - Task dependencies
 - Implementation notes
 
-**Task status markers:**
+**Task status:**
 - `- [ ]` Not started
-- `- [-]` In progress
+- `- [-]` In progress  
 - `- [x]` Completed
 
 ---
 
-## 🎯 Spec-Driven Workflow
+## 💡 Working with This Project
 
-```
-1. User requests feature
-   ↓
-2. Check if Spec exists (kse workflows)
-   ↓
-3. If no Spec: Suggest creating one
-   If Spec exists: Export context (kse context export)
-   ↓
-4. Read requirements.md and design.md
-   ↓
-5. Implement according to Spec
-   ↓
-6. Update tasks.md as you complete tasks
-   ↓
-7. Verify against acceptance criteria
-```
+### DO:
+- ✅ Check for existing Specs before starting work
+- ✅ Follow requirements and design in Specs
+- ✅ Update task status as you work
+- ✅ Read steering rules for project-specific guidelines
+- ✅ Ask user if requirements are unclear
 
-**Why Spec-driven?**
-- ✅ Clear requirements before coding
-- ✅ Consistent architecture decisions
-- ✅ Trackable progress
-- ✅ Better AI understanding of context
-- ✅ Knowledge preserved in Specs
+### DON'T:
+- ❌ Start implementing without understanding requirements
+- ❌ Ignore the design document
+- ❌ Create files in wrong locations
+- ❌ Skip updating task status
 
 ---
 
-## 🔧 Common AI Tasks
-
-### Task 1: Implement a Feature
-
-```bash
-# 1. Check what Specs exist
-kse workflows
-
-# 2. Export the Spec context
-kse context export 01-00-user-login
-
-# 3. Read the context
-# File: .kiro/specs/01-00-user-login/context-export.md
-
-# 4. Implement according to requirements and design
-
-# 5. Update tasks.md to mark tasks complete
-```
-
-### Task 2: Check Project Status
+## 🔍 Finding Information
 
-```bash
-kse status
-```
-
-Shows all Specs and their completion progress.
-
-### Task 3: Work on Specific Task
-
-```bash
-# Generate focused prompt for one task
-kse prompt generate 01-00-user-login 1.1
-
-# Claim the task
-kse task claim 01-00-user-login 1.1
-
-# Implement the task
-
-# Mark complete in tasks.md
-```
-
-### Task 4: Understand Project Context
+**Need to understand a feature?**
+→ Read `.kiro/specs/{spec-name}/requirements.md` and `design.md`
 
-**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
+**Need to know what to work on?**
+→ Read `.kiro/specs/{spec-name}/tasks.md`
 
----
+**Need project context?**
+→ Read `.kiro/steering/CURRENT_CONTEXT.md`
 
-## 💡 Best Practices for AI
-
-### 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
+**Need development rules?**
+→ Read `.kiro/steering/CORE_PRINCIPLES.md`
 
-### 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
+**Need to check status?**
+→ Run `kse status`
 
 ---
 
-## 🚀 Quick Reference
-
-| 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` |
-
----
+## 🚀 Quick Start for AI
 
-## 📚 Learn More
+1. **User asks you to implement something**
+2. **You check**: Does a Spec exist for this? (`kse workflows` or check `.kiro/specs/`)
+3. **If yes**: Read the Spec and implement according to it
+4. **If no**: Suggest creating a Spec first, help user define it
+5. **While working**: Update task status in `tasks.md`
+6. **When done**: Mark tasks complete
 
-- **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`
+**Remember**: You're not just writing code, you're following a structured development process. The Spec is your guide.
 
 ---
 
-**kse Version**: 1.5.4  
+**Project Type**: Spec-driven development  
 **Last Updated**: 2026-01-24  
-**Purpose**: AI tool reference for kse usage
+**Purpose**: Guide AI tools to work effectively with this project