scene-capability-engine 3.0.0

package/docs/adoption-guide.md

@@ -0,0 +1,616 @@
+# Project Adoption Guide
+
+This guide explains how to adopt existing projects into Kiro Spec Engine (KSE) using the new **zero-interaction smart adoption system**.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Quick Start](#quick-start)
+- [How It Works](#how-it-works)
+- [Adoption Modes](#adoption-modes)
+- [Command Options](#command-options)
+- [Common Scenarios](#common-scenarios)
+- [Troubleshooting](#troubleshooting)
+- [Migration from Interactive Mode](#migration-from-interactive-mode)
+
+---
+
+## Overview
+
+The `kse adopt` command now features **smart, zero-interaction adoption** that automatically handles project integration without asking any questions.
+
+**Key Features**:
+- ✅ **Zero Questions** - No user input required
+- ✅ **Smart Detection** - Automatically detects project state
+- ✅ **Automatic Decisions** - Intelligently resolves all conflicts
+- ✅ **Mandatory Backup** - Always creates verified backups
+- ✅ **Clear Feedback** - Shows exactly what happened
+- ✅ **Easy Rollback** - Simple undo with one command
+
+**Philosophy**: The system makes intelligent decisions automatically while maintaining complete safety through mandatory backups and clear communication.
+
+---
+
+## Quick Start
+
+### For New Users
+
+Simply run:
+```bash
+cd your-project
+kse adopt
+```
+
+That's it! The system will:
+1. Analyze your project
+2. Choose the best strategy
+3. Create a backup
+4. Apply changes
+5. Show you a summary
+
+**Example Output**:
+```
+🔥 Kiro Spec Engine - Project Adoption
+
+📦 Analyzing project structure... ✅
+📋 Creating adoption plan... ✅
+
+Adoption Plan:
+  Mode: Smart Update
+  Files to update: 5
+  Files to preserve: 8
+  Backup required: Yes
+
+🚀 Starting adoption...
+📦 Creating backup... ✅ backup-20260128-143022
+✓ Validating backup... ✅ 5 files verified
+📝 Updating files...
+  ✅ .kiro/steering/CORE_PRINCIPLES.md
+  ✅ .kiro/steering/ENVIRONMENT.md
+  ✅ .kiro/tools/ultrawork_enhancer.py
+  ⏭️  .kiro/specs/ (preserved)
+✅ Adoption completed successfully!
+
+📊 Summary:
+  Backup: backup-20260128-143022
+  Updated: 5 files
+  Preserved: 3 specs, 2 custom files
+  
+💡 Your original files are safely backed up.
+   To restore: kse rollback backup-20260128-143022
+```
+
+### Preview Changes First
+
+Want to see what would happen without making changes?
+```bash
+kse adopt --dry-run
+```
+
+---
+
+## How It Works
+
+### Automatic Detection
+
+The system automatically detects your project state:
+- Checks for existing `.kiro/` directory
+- Reads version information
+- Identifies user content (specs, custom files)
+- Detects potential conflicts
+
+### Smart Mode Selection
+
+Based on detection, it chooses the optimal mode:
+
+| Project State | Selected Mode | What Happens |
+|--------------|---------------|--------------|
+| No `.kiro/` | **Fresh** | Creates complete structure |
+| `.kiro/` + same version | **Skip** | Already up-to-date |
+| `.kiro/` + older version | **Smart Update** | Updates templates only |
+| `.kiro/` + newer version | **Warning** | Version mismatch alert |
+| `.kiro/` + no version | **Smart Adopt** | Full adoption with backup |
+
+### Automatic Conflict Resolution
+
+The system automatically resolves file conflicts using smart rules:
+
+| File Type | Resolution Strategy |
+|-----------|-------------------|
+| **Template files** (steering/, tools/) | Backup + Update to latest |
+| **User content** (specs/, custom/) | Always preserve |
+| **Config files** (version.json) | Backup + Update |
+| **Special** (CURRENT_CONTEXT.md) | Always preserve |
+
+### Mandatory Backup
+
+Before any modifications:
+1. Creates selective backup (only files that will change)
+2. Validates backup integrity
+3. Aborts if backup fails
+4. Provides rollback command
+
+---
+
+## Adoption Modes
+
+### 1. Fresh Adoption
+
+**When**: No `.kiro/` directory exists
+
+**Actions**:
+- Creates complete `.kiro/` structure
+- Copies all template files
+- Creates `version.json`
+- No conflicts, no backup needed
+
+**Example**:
+```bash
+$ kse adopt
+
+Mode: Fresh
+Actions:
+  - Create .kiro/ directory structure
+  - Copy template files
+  - Create version.json
+
+✅ Adoption completed successfully!
+```
+
+### 2. Skip Mode
+
+**When**: Already at latest version
+
+**Actions**:
+- No changes made
+- Displays current version info
+- Suggests next steps
+
+**Example**:
+```bash
+$ kse adopt
+
+✅ Project already adopted with latest version (v1.9.0)
+No changes needed.
+
+💡 Next steps:
+   - Create a spec: kse spec bootstrap --name 01-00-my-feature --non-interactive
+   - Check status: kse status
+```
+
+### 3. Smart Update
+
+**When**: Existing `.kiro/` with older version
+
+**Actions**:
+- Backs up files that will change
+- Updates template files to latest version
+- Preserves all user content (specs, CURRENT_CONTEXT.md)
+- Updates version.json
+
+**Example**:
+```bash
+$ kse adopt
+
+Mode: Smart Update (v1.8.0 → v1.9.0)
+Backup: backup-20260128-143022
+Updated: 5 template files
+Preserved: 3 specs, CURRENT_CONTEXT.md
+
+✅ Adoption completed successfully!
+```
+
+### 4. Smart Adopt
+
+**When**: `.kiro/` exists but no version info
+
+**Actions**:
+- Backs up entire `.kiro/` directory
+- Adopts with full structure
+- Preserves user content
+- Creates version.json
+
+**Example**:
+```bash
+$ kse adopt
+
+Mode: Smart Adopt
+Backup: backup-20260128-143022
+Updated: 8 files
+Preserved: 5 specs, 3 custom files
+
+✅ Adoption completed successfully!
+```
+
+### 5. Warning Mode
+
+**When**: Local version is newer than KSE version
+
+**Actions**:
+- Displays warning message
+- No changes made
+- Suggests upgrading KSE
+
+**Example**:
+```bash
+$ kse adopt
+
+⚠️  Warning: Project version (v2.0.0) is newer than KSE version (v1.9.0)
+
+Possible causes:
+  - You downgraded KSE
+  - Project was adopted with newer KSE version
+
+Solutions:
+  1. Upgrade KSE: npm install -g kiro-spec-engine@latest
+  2. Force adopt: kse adopt --force (not recommended)
+
+No changes made.
+```
+
+---
+
+## Command Options
+
+### Basic Options
+
+```bash
+# Default: Smart, automatic, safe
+kse adopt
+
+# Preview changes without executing
+kse adopt --dry-run
+
+# Show detailed logs
+kse adopt --verbose
+
+# Force overwrite (with backup)
+kse adopt --force
+```
+
+### Advanced Options
+
+```bash
+# Skip backup (dangerous, not recommended)
+kse adopt --no-backup
+
+# Skip template updates
+kse adopt --skip-update
+
+# Enable interactive mode (legacy behavior)
+kse adopt --interactive
+```
+
+### Option Details
+
+| Option | Description | Safety |
+|--------|-------------|--------|
+| `--dry-run` | Preview without executing | ✅ Safe |
+| `--verbose` | Show detailed logs | ✅ Safe |
+| `--force` | Force overwrite with backup | ⚠️ Use with caution |
+| `--no-backup` | Skip backup creation | ❌ Dangerous |
+| `--skip-update` | Don't update templates | ⚠️ May cause inconsistency |
+| `--interactive` | Enable legacy interactive mode | ✅ Safe |
+
+---
+
+## Common Scenarios
+
+### Scenario 1: First Time User
+
+**Situation**: You just installed KSE and want to adopt your project.
+
+**Solution**:
+```bash
+cd your-project
+kse adopt
+```
+
+**What happens**: Fresh adoption creates complete structure, no questions asked.
+
+---
+
+### Scenario 2: Upgrading KSE Version
+
+**Situation**: You upgraded KSE from v1.8.0 to v1.9.0.
+
+**Solution**:
+```bash
+kse adopt
+```
+
+**What happens**: Smart Update backs up and updates template files, preserves your specs.
+
+---
+
+### Scenario 3: Want to Preview First
+
+**Situation**: You want to see what would change before committing.
+
+**Solution**:
+```bash
+kse adopt --dry-run
+```
+
+**What happens**: Shows detailed plan without making any changes.
+
+---
+
+### Scenario 4: Need Detailed Information
+
+**Situation**: You want to see exactly what's happening.
+
+**Solution**:
+```bash
+kse adopt --verbose
+```
+
+**What happens**: Shows detailed logs of every operation.
+
+---
+
+### Scenario 5: Undo Adoption
+
+**Situation**: You want to revert the adoption.
+
+**Solution**:
+```bash
+kse rollback backup-20260128-143022
+```
+
+**What happens**: Restores all files from backup.
+
+---
+
+### Scenario 6: Multiple Projects
+
+**Situation**: You want to adopt multiple projects.
+
+**Solution**:
+```bash
+# Bash script
+for dir in project1 project2 project3; do
+  cd $dir
+  kse adopt
+  cd ..
+done
+```
+
+**What happens**: Each project is adopted automatically without interaction.
+
+---
+
+## Troubleshooting
+
+### Problem: Backup Creation Failed
+
+**Error**:
+```
+❌ Error: Backup Creation Failed
+
+Problem: Unable to create backup of existing files
+
+Possible causes:
+  - Insufficient disk space
+  - Permission denied for .kiro/backups/
+  - File system error
+```
+
+**Solutions**:
+1. Free up disk space (need ~50MB)
+2. Check file permissions: `ls -la .kiro/`
+3. Try running with elevated permissions (if appropriate)
+
+---
+
+### Problem: Permission Denied
+
+**Error**:
+```
+❌ Error: Permission Denied
+
+Problem: Cannot write to .kiro/ directory
+```
+
+**Solutions**:
+```bash
+# Check permissions
+ls -la .kiro/
+
+# Fix permissions (Unix/Mac)
+chmod -R u+w .kiro/
+
+# Windows: Right-click .kiro/ → Properties → Security → Edit
+```
+
+---
+
+### Problem: Version Mismatch Warning
+
+**Error**:
+```
+⚠️  Warning: Project version (v2.0.0) is newer than KSE version (v1.9.0)
+```
+
+**Solutions**:
+```bash
+# Upgrade KSE to latest
+npm install -g kiro-spec-engine@latest
+
+# Then adopt again
+kse adopt
+```
+
+---
+
+### Problem: Want to Keep Old Behavior
+
+**Situation**: You prefer the interactive mode.
+
+**Solution**:
+```bash
+kse adopt --interactive
+```
+
+**What happens**: Enables legacy interactive mode with prompts.
+
+---
+
+## Migration from Interactive Mode
+
+### What Changed
+
+**Old Behavior** (v1.8.0 and earlier):
+- Asked multiple questions
+- Required user decisions
+- Manual conflict resolution
+- Optional backup
+
+**New Behavior** (v1.9.0+):
+- Zero questions
+- Automatic decisions
+- Smart conflict resolution
+- Mandatory backup
+
+### Comparison
+
+| Aspect | Old (Interactive) | New (Smart) |
+|--------|------------------|-------------|
+| User Input | Multiple prompts | None |
+| Conflict Resolution | Manual selection | Automatic |
+| Backup | Optional | Mandatory |
+| Speed | Slow (waits for input) | Fast (automatic) |
+| Safety | Depends on user choices | Always safe |
+
+### Using Legacy Mode
+
+If you prefer the old interactive behavior:
+```bash
+kse adopt --interactive
+```
+
+This enables:
+- All the old prompts
+- Manual conflict resolution
+- Step-by-step confirmation
+
+### Recommended Approach
+
+For most users, the new smart mode is recommended:
+- Faster and easier
+- Safer (mandatory backups)
+- No learning curve
+- Can always rollback
+
+---
+
+## Best Practices
+
+### 1. Preview First (Optional)
+
+For peace of mind:
+```bash
+kse adopt --dry-run
+kse adopt
+```
+
+### 2. Commit Before Adoption
+
+If using version control:
+```bash
+git add -A
+git commit -m "Before KSE adoption"
+kse adopt
+```
+
+### 3. Verify After Adoption
+
+Check everything is correct:
+```bash
+kse status
+kse version-info
+```
+
+### 4. Keep Backups
+
+Don't delete automatic backups immediately:
+```bash
+# Backups are in .kiro/backups/
+ls .kiro/backups/
+```
+
+### 5. Use Verbose for Debugging
+
+If something seems wrong:
+```bash
+kse adopt --verbose
+```
+
+---
+
+## What Gets Created
+
+After adoption, your project will have:
+
+```
+your-project/
+├── .kiro/                          # KSE core directory
+│   ├── version.json                # Version tracking
+│   ├── specs/                      # Spec storage
+│   ├── steering/                   # AI behavior rules
+│   │   ├── CORE_PRINCIPLES.md
+│   │   ├── ENVIRONMENT.md
+│   │   ├── CURRENT_CONTEXT.md
+│   │   └── RULES_GUIDE.md
+│   ├── tools/                      # Ultrawork tools
+│   │   └── ultrawork_enhancer.py
+│   ├── backups/                    # Automatic backups
+│   │   └── adopt-{timestamp}/
+│   └── README.md
+└── (your existing files)           # All preserved
+```
+
+---
+
+## Next Steps
+
+After successful adoption:
+
+1. **Verify .gitignore configuration**:
+   The adoption process automatically checks and fixes your `.gitignore` for team collaboration. If you see a warning about .gitignore, you can manually fix it:
+   ```bash
+   kse doctor --fix-gitignore
+   ```
+   Learn more: [Team Collaboration Guide](./team-collaboration-guide.md)
+
+2. **Create your first spec**:
+   ```bash
+   kse spec bootstrap --name 01-00-my-feature --non-interactive
+   ```
+
+3. **Check project status**:
+   ```bash
+   kse status
+   ```
+
+4. **Read the spec workflow guide**:
+   - See `.kiro/specs/SPEC_WORKFLOW_GUIDE.md`
+
+5. **Explore Ultrawork**:
+   ```bash
+   kse enhance requirements .kiro/specs/01-00-my-feature/requirements.md
+   ```
+
+---
+
+## Getting Help
+
+- **Documentation**: Check README.md in your `.kiro/` directory
+- **System Check**: `kse doctor`
+- **Version Info**: `kse version-info`
+- **Issues**: https://github.com/heguangyong/scene-capability-engine/issues
+
+---
+
+**Happy adopting! 🔥**
+