kiro-spec-engine 1.5.2 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,78 @@ 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.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
+- AI-friendly `.kiro/README.md` template explaining kse commands and usage
+- Comprehensive kse command reference for AI tools (status, workflows, context export, etc.)
+- AI workflow guide with step-by-step instructions for common tasks
+- Spec structure documentation for AI understanding
+- Best practices section for AI tools using kse
+
+### Changed
+- Updated `.kiro/README.md` template to focus on kse CLI usage instead of Kiro Spec system philosophy
+- Simplified template file list in adoption strategy (removed obsolete files)
+- Fixed template path in adoption strategy to point to correct location (`template/.kiro`)
+
+### Fixed
+- AI tools can now understand what kse is and how to use it by reading `.kiro/README.md`
+- Adoption command now correctly copies README from template
+
+## [1.5.4] - 2026-01-24
+
+### Fixed
+- Context exporter test to handle both possible error messages (tasks.md not found or Task not found)
+
+## [1.5.3] - 2026-01-24
+
+### Fixed
+- Context exporter test to match actual error message format
+
 ## [1.5.2] - 2026-01-24
 
 ### Fixed

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/adoption/adoption-strategy.js

@@ -41,14 +41,12 @@ class AdoptionStrategy {
   /**
    * Gets the path to template directory
    * This would be embedded in the kse package
-   * For now, we'll use a placeholder
    * 
    * @returns {string}
    */
   getTemplatePath() {
-    // In production, this would be: path.join(__dirname, '../../templates/kiro')
-    // For now, return a placeholder that can be configured
-    return path.join(__dirname, '../../templates/kiro');
+    // Template is at template/.kiro/ in the package
+    return path.join(__dirname, '../../template/.kiro');
   }
 
   /**
@@ -107,15 +105,12 @@ class AdoptionStrategy {
     
     // Define template structure
     const templateFiles = [
+      'README.md',
       'steering/CORE_PRINCIPLES.md',
       'steering/ENVIRONMENT.md',
       'steering/CURRENT_CONTEXT.md',
       'steering/RULES_GUIDE.md',
-      'tools/ultrawork_enhancer.py',
-      'README.md',
-      'ultrawork-application-guide.md',
-      'ultrawork-integration-summary.md',
-      'sisyphus-deep-dive.md'
+      'specs/SPEC_WORKFLOW_GUIDE.md'
     ];
     
     for (const file of templateFiles) {

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.2",
+  "version": "1.6.0",
   "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,288 +1,181 @@
-# Kiro Spec 驱动开发体系
+# Project Development Guide
 
-> **用途**: 新项目引导文档，解释 Spec 驱动开发体系的设计思想和使用方法
+> **AI Tools: Read this first!** This project follows Spec-driven development methodology.
 
 ---
 
-## 🎯 这是什么？
+## 🎯 How This Project Works
 
-这是一套基于 Spec 驱动的 AI 辅助开发规范体系，包含：
-- **Steering 规范**：控制 AI 行为的规则和上下文
-- **Spec 工作流**：结构化的需求-设计-实施流程
-- **文件组织**：清晰的产物归档和知识沉淀
+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
 
----
-
-## 💡 为什么需要这套体系？
-
-### 问题 1：AI Session Token 有限
-
-**挑战**：
-- AI session 启动时会加载所有 Steering 文档
-- 历史数据和详细内容会快速消耗 token
-- Token 耗尽导致无法继续执行任务
-
-**解决方案**：
-- **分层管理**：稳定规则（CORE_PRINCIPLES）+ 动态场景（CURRENT_CONTEXT）
-- **精简原则**：Steering 只保留核心信息，详细内容放到 Spec 目录
-- **主动管控**：每个 Spec 完成后及时更新 CURRENT_CONTEXT
-
-### 问题 2：规范一致性难以保持
+**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
 
-**挑战**：
-- 不同 Spec 使用不同的开发流程
-- 产物散落在项目各处，难以查找
-- 缺乏上下文，不知道为什么要这样做
-
-**解决方案**：
-- **Spec 驱动**：所有工作基于 Spec 推进
-- **统一规范**：CORE_PRINCIPLES 适用于所有 Spec
-- **产物归档**：所有产物归档到对应的 Spec 目录
+**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
 
 ---
 
-## 📚 文件组织
-
-### Steering 目录（AI 每次启动时加载）
-
-| 文件 | 职责 | Token 影响 | 更新频率 |
-|------|------|-----------|---------|
-| **RULES_GUIDE.md** | 索引和快速参考 | 低 | 很少 |
-| **CORE_PRINCIPLES.md** | 核心开发规范 | 中 | 很少 |
-| **ENVIRONMENT.md** | 环境配置 | 低 | 很少 |
-| **CURRENT_CONTEXT.md** | 当前 Spec 场景 | **高** ⚠️ | 每个 Spec |
+## 📋 Development Workflow
 
-### Specs 目录（按需加载）
+### When User Asks You to Implement a Feature
 
+**Step 1: Check if Spec exists**
 ```
-.kiro/specs/
-├── SPEC_WORKFLOW_GUIDE.md    # Spec 工作流指南
-└── {spec-name}/               # 具体的 Spec
-    ├── requirements.md        # 需求文档
-    ├── design.md              # 设计文档（可选）
-    ├── tasks.md               # 任务列表（可选）
-    ├── scripts/               # 脚本
-    ├── diagnostics/           # 诊断文档
-    └── results/               # 执行结果
+Look in .kiro/specs/ directory
 ```
 
----
-
-## 🔄 Steering 体系的核心思想
-
-### 1. 最小化 Token 消耗
-
-**原则**：
-- Steering 文档在每次 session 启动时**完全加载**
-- 必须保持精简，避免历史数据堆积
-- CURRENT_CONTEXT 需要随 Spec 推进及时更新
-
-**实践**：
-- ❌ 不要在 Steering 中保留详细的历史数据
-- ❌ 不要在 Steering 中保留详细的配置和命令
-- ✅ 历史数据归档到 Spec 目录
-- ✅ 详细配置放到 Spec 文档中
-
-### 2. 规范的可复用性
-
-**原则**：
-- CORE_PRINCIPLES 适用于所有 Spec
-- 新项目可以直接复制这套体系
-- 只需修正 ENVIRONMENT 和 CURRENT_CONTEXT
-
-**实践**：
-- ✅ CORE_PRINCIPLES 保持稳定，很少修改
-- ✅ ENVIRONMENT 记录项目特定的环境配置
-- ✅ CURRENT_CONTEXT 随 Spec 动态更新
-
-### 3. 上下文的聚焦性
-
-**原则**：
-- CURRENT_CONTEXT 只保留当前 Spec 的核心信息
-- 历史数据归档到 Spec 目录，不占用 Steering 空间
-- 每个 Spec 开始前必须更新 CURRENT_CONTEXT
-
-**实践**：
-- ✅ 每个新 Spec 开始前：更新 CURRENT_CONTEXT
-- ✅ Spec 推进中：及时精简已完成内容
-- ✅ Spec 完成后：清空 CURRENT_CONTEXT
-
----
-
-## 🚀 如何在新项目中使用？
-
-### 步骤 1：复制 Steering 模板
-
+**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 3: If no Spec exists**
+- Suggest creating a Spec first
+- Help user define requirements
+- Help design the solution
+- Break down into tasks
+- Then implement
+
+**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
-# 从模板项目复制
-cp -r template-project/.kiro/ new-project/.kiro/
+kse status
 ```
 
-### 步骤 2：修正 ENVIRONMENT.md
-
-更新为新项目的实际环境：
-- 服务器信息（如有）
-- 数据库配置
-- 部署方式
-- AI 权限范围
-
-### 步骤 3：清空 CURRENT_CONTEXT.md
-
-删除旧项目的场景信息，标记为"无活跃 Spec"。
+This shows all Specs and their progress.
 
-### 步骤 4：检查 CORE_PRINCIPLES.md
+### When You Need Context
 
-确认规范是否适用于新项目，必要时调整（但尽量保持稳定）。
-
-### 步骤 5：修正 SPEC_WORKFLOW_GUIDE.md
+If you need to understand a feature:
+```bash
+kse context export <spec-name>
+```
 
-更新项目特定的内容：
-- 项目名称
-- 技术栈
-- 示例
+This generates a summary of requirements, design, and tasks.
 
 ---
 
-## 📖 Spec 驱动开发工作流程
-
-### 标准流程
+## 📁 Project Structure
 
 ```
-1. 创建 Spec 目录
-   ↓
-2. 编写需求文档 (requirements.md)
-   ↓
-3. 编写设计文档 (design.md) - 可选
-   ↓
-4. 创建任务列表 (tasks.md) - 可选
-   ↓
-5. 执行任务（调研、分析、实现、测试）
-   ↓
-6. 所有产物归档到 Spec 目录
-   ↓
-7. 更新 CURRENT_CONTEXT 为下一个 Spec
+.kiro/
+├── README.md                  # This file - project development guide
+├── specs/                     # All Specs live here
+│   └── {spec-name}/           # Individual Spec
+│       ├── requirements.md    # What we're building
+│       ├── design.md          # How we'll build it
+│       ├── tasks.md           # Implementation steps
+│       └── ...                # Other artifacts
+├── steering/                  # Development rules
+│   ├── CORE_PRINCIPLES.md     # Core development principles
+│   ├── ENVIRONMENT.md         # Project environment
+│   └── CURRENT_CONTEXT.md     # Current work context
+└── tools/                     # Tool configurations
 ```
 
-### 为什么要用 Spec 驱动？
-
-**优点**：
-- ✅ 所有工作有明确的需求和设计支持
-- ✅ 产物有上下文，易于理解和维护
-- ✅ 可以追溯需求和设计决策
-- ✅ 团队协作更清晰
-- ✅ 知识沉淀在 Spec 中
-
-**不用 Spec 的问题**：
-- ❌ 脚本散落在项目各处，难以查找
-- ❌ 缺乏上下文，不知道为什么要这样做
-- ❌ 无法追溯需求来源
-- ❌ 临时文件堆积，项目混乱
-- ❌ 知识流失
+**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
 
 ---
 
-## 💡 最佳实践
-
-### 1. 主动管控 Token
-
-**时机**：
-- 每完成一组任务后：精简 tasks.md
-- 每完成一个阶段后：精简 CURRENT_CONTEXT
-- 发现 token 使用率 > 50% 时：立即精简
-- 阶段切换时：更新 CURRENT_CONTEXT 聚焦新阶段
-
-**策略**：
-- ❌ 删除：已完成阶段的详细配置、命令、表格
-- ❌ 删除：历史测试数据和性能对比表格
-- ❌ 删除：详细的问题排查流程和检查清单
-- ✅ 保留：当前阶段的核心信息和关键经验
-
-### 2. 保持 Steering 精简
+## 📖 What is a Spec?
 
-**原则**：
-- CURRENT_CONTEXT 只保留当前信息
-- 历史数据归档到 Spec 目录
-- 详细配置放到 Spec 文档中
+A Spec is a complete feature definition with three parts:
 
-**检查清单**：
-- [ ] CURRENT_CONTEXT 是否聚焦当前 Spec？
-- [ ] 历史阶段的详细内容是否已移除？
-- [ ] 详细数据是否已归档到 Spec 目录？
-- [ ] Token 使用率是否 < 50%？
+### 1. requirements.md - WHAT we're building
+- User stories
+- Functional requirements
+- Acceptance criteria
+- Non-functional requirements
 
-### 3. 规范的一致性
+### 2. design.md - HOW we'll build it
+- Architecture
+- Component design
+- API design
+- Technology choices
 
-**原则**：
-- 所有 Spec 遵循相同的规范
-- 不要在不同 Spec 中使用不同的流程
-- 发现问题及时更新 CORE_PRINCIPLES
+### 3. tasks.md - Implementation steps
+- Ordered task list
+- Task dependencies
+- Implementation notes
 
-**实践**：
-- ✅ 基于 Spec 推进所有工作
-- ✅ 产物归档到对应的 Spec 目录
-- ✅ 不要在根目录生成临时文件
-
-### 4. 知识的沉淀
-
-**原则**：
-- 通用经验沉淀到 CORE_PRINCIPLES
-- Spec 特定经验保留在 Spec 目录
-- 定期回顾和更新规范
-
-**时机**：
-- Spec 完成后：总结经验教训
-- 新 Spec 开始前：评估现有规则是否适用
-- 发现重复问题时：更新 CORE_PRINCIPLES
+**Task status:**
+- `- [ ]` Not started
+- `- [-]` In progress  
+- `- [x]` Completed
 
 ---
 
-## ⚠️ 常见错误
+## 💡 Working with This Project
 
-### 错误 1：CURRENT_CONTEXT 膨胀
+### 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
 
-**现象**：
-- session 启动后 token 使用率 > 50%
-- CURRENT_CONTEXT 包含大量历史数据
+### DON'T:
+- ❌ Start implementing without understanding requirements
+- ❌ Ignore the design document
+- ❌ Create files in wrong locations
+- ❌ Skip updating task status
 
-**解决**：
-- 立即精简 CURRENT_CONTEXT
-- 将详细数据归档到 Spec 目录
-- 只保留当前阶段的核心信息
+---
 
-### 错误 2：规范不一致
+## 🔍 Finding Information
 
-**现象**：
-- 不同 Spec 使用不同的开发流程
-- 文件组织混乱
+**Need to understand a feature?**
+→ Read `.kiro/specs/{spec-name}/requirements.md` and `design.md`
 
-**解决**：
-- 重新阅读 CORE_PRINCIPLES
-- 按照规范重新组织文件
-- 将散落的产物归档到 Spec 目录
+**Need to know what to work on?**
+→ Read `.kiro/specs/{spec-name}/tasks.md`
 
-### 错误 3：产物散落
+**Need project context?**
+→ Read `.kiro/steering/CURRENT_CONTEXT.md`
 
-**现象**：
-- 脚本、测试、报告散落在项目各处
-- 缺乏上下文，难以理解
+**Need development rules?**
+→ Read `.kiro/steering/CORE_PRINCIPLES.md`
 
-**解决**：
-- 所有产物归档到对应的 Spec 目录
-- 不要在根目录生成临时文件
-- 遵循 Spec 驱动开发原则
+**Need to check status?**
+→ Run `kse status`
 
 ---
 
-## 📚 相关文档
+## 🚀 Quick Start for AI
+
+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
 
-- **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`
+**Remember**: You're not just writing code, you're following a structured development process. The Spec is your guide.
 
 ---
 
-**版本**: v1.0  
-**创建**: 2025-01-22  
-**说明**: 这是新项目引导文档，日常开发时不需要加载
+**Project Type**: Spec-driven development  
+**Last Updated**: 2026-01-24  
+**Purpose**: Guide AI tools to work effectively with this project