kiro-spec-engine 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,97 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-01-23
+
+### Added - Watch Mode Automation System 🤖
+
+**Core Components** (2150+ lines of code, 172 tests):
+- **FileWatcher**: Cross-platform file monitoring with chokidar
+  - Glob pattern matching with minimatch
+  - Configurable ignored patterns
+  - Event emission for file changes
+  - Error recovery and health monitoring
+- **EventDebouncer**: Smart event management
+  - Debounce and throttle logic
+  - Event queue with duplicate prevention
+  - Configurable delays per pattern
+- **ActionExecutor**: Command execution engine
+  - Shell command execution with context interpolation
+  - Retry logic with exponential/linear backoff
+  - Timeout handling and process management
+  - Command validation and security
+- **ExecutionLogger**: Complete audit trail
+  - Log rotation by size
+  - Metrics tracking (executions, time saved, success rates)
+  - Export to JSON/CSV
+  - Configurable log levels
+- **WatchManager**: Central coordinator
+  - Lifecycle management (start/stop/restart)
+  - Configuration loading and validation
+  - Status reporting and metrics
+
+**CLI Commands** (7 commands):
+- `kse watch init` - Initialize watch configuration
+- `kse watch start/stop` - Control watch mode
+- `kse watch status` - Show current status
+- `kse watch logs` - View execution logs (with tail/follow)
+- `kse watch metrics` - Display automation metrics
+- `kse watch presets` - List available presets
+- `kse watch install <preset>` - Install automation preset
+
+**Automation Presets** (4 presets):
+- `auto-sync` - Automatically sync workspace when tasks.md changes
+- `prompt-regen` - Regenerate prompts when requirements/design change
+- `context-export` - Export context when tasks complete
+- `test-runner` - Run tests when source files change
+
+**Tool Detection & Auto-Configuration**:
+- Automatic IDE detection (Kiro IDE, VS Code, Cursor)
+- Tool-specific automation recommendations
+- Auto-configuration during project adoption
+- Confidence-based suggestions
+
+**Manual Workflows** (6 workflows):
+- Complete workflow guide (300+ lines)
+- `kse workflows` command for workflow management
+- Step-by-step instructions with time estimates
+- Interactive checklists for common tasks
+- Workflows: task-sync, context-export, prompt-generation, daily, task-completion, spec-creation
+
+### Enhanced
+- **README.md**: Added comprehensive automation section
+- **Project Adoption**: Integrated tool detection with automation setup
+- **Documentation**: Complete manual workflows guide
+
+### Testing
+- 289 tests passing (100% pass rate)
+- 279 unit tests
+- 10 integration tests
+- Full coverage of all watch mode components
+
+### Performance
+- Efficient file watching with debouncing
+- Configurable retry logic
+- Log rotation to prevent disk space issues
+- Metrics tracking for optimization
+
+## [1.2.3] - 2026-01-23
+
+### Added
+- **Developer Documentation**: Comprehensive guides for contributors and extenders
+  - `docs/developer-guide.md`: Complete developer guide with API documentation
+  - `docs/architecture.md`: Detailed architecture diagrams and data flow documentation
+  - Migration script interface documentation with examples
+  - Extension points for custom strategies and validators
+  - Testing guidelines for unit, property-based, and integration tests
+  - Contributing guidelines and development setup
+
+### Enhanced
+- Improved documentation structure for developers
+- Added detailed API documentation for all core classes
+- Added architecture diagrams for system understanding
+- Added data flow diagrams for adoption, upgrade, and backup processes
+
 ## [1.2.2] - 2026-01-23
 
 ### Added

package/README.md

@@ -25,6 +25,11 @@ At its heart, KSE is a **rules engine** that operates on **specs**:
 
 - ✅ **Spec-Driven Development**: Structured Requirements → Design → Tasks workflow
 - ✅ **Steering Rules System**: Control AI behavior with project-specific rules
+- ✅ **Multi-User Collaboration**: Personal workspaces, task claiming, team coordination
+- ✅ **Cross-Tool Compatibility**: Export context for Claude Code, Cursor, Codex, etc.
+- ✅ **Watch Mode Automation**: Automatic file monitoring and workflow execution
+- ✅ **Manual Workflows**: Step-by-step guides for common tasks
+- ✅ **Tool Detection**: Auto-detect IDE and suggest appropriate automation
 - ✅ **Quality Assessment**: Automatic document quality scoring (0-10 scale)
 - ✅ **Intelligent Enhancement**: Auto-identify and apply improvements with Ultrawork
 - ✅ **Professional Standards**: Ensure production-ready documentation
@@ -114,6 +119,98 @@ kse --lang zh <command>  # Chinese
 kse --lang en <command>  # English (default)
 ```
 
+### Multi-User Collaboration
+
+```bash
+# Initialize personal workspace
+kse workspace init
+kse workspace init --user=alice
+
+# Synchronize workspace with team
+kse workspace sync
+
+# List all workspaces
+kse workspace list
+
+# Claim a task
+kse task claim <spec-name> <task-id>
+kse task claim 01-00-user-auth 1.1 --force
+
+# Unclaim a task
+kse task unclaim <spec-name> <task-id>
+
+# List claimed tasks
+kse task list <spec-name>
+```
+
+### Cross-Tool Support
+
+```bash
+# Export spec context for AI tools
+kse context export <spec-name>
+kse context export 01-00-user-auth --steering --steering-files=CORE_PRINCIPLES.md
+
+# Generate task-specific prompt
+kse prompt generate <spec-name> <task-id>
+kse prompt generate 01-00-user-auth 1.1 --tool=claude-code
+kse prompt generate 01-00-user-auth 1.2 --tool=cursor --max-length=5000
+```
+
+### Watch Mode (Automation)
+
+```bash
+# Initialize watch configuration
+kse watch init
+kse watch init --force  # Overwrite existing config
+
+# Start watch mode
+kse watch start
+kse watch start --config custom-config.json
+kse watch start --patterns "**/*.md,**/*.js"
+
+# Stop watch mode
+kse watch stop
+
+# Check watch mode status
+kse watch status
+
+# View execution logs
+kse watch logs
+kse watch logs --tail 100
+kse watch logs --follow
+
+# View automation metrics
+kse watch metrics
+kse watch metrics --format json
+
+# List available presets
+kse watch presets
+
+# Install a preset
+kse watch install auto-sync
+kse watch install prompt-regen
+kse watch install context-export
+kse watch install test-runner
+```
+
+### Manual Workflows
+
+```bash
+# List available workflows
+kse workflows
+
+# Show workflow details
+kse workflows show task-sync
+kse workflows show context-export
+kse workflows show prompt-generation
+
+# Open full workflows guide
+kse workflows guide
+
+# Mark workflow as complete
+kse workflows complete task-sync
+```
+
 ### Document Enhancement
 
 ```bash
@@ -231,6 +328,81 @@ kse rollback
 - ✅ Easy rollback to previous states
 - ✅ Dry-run mode to preview changes
 
+## 🤖 Automation and Workflows
+
+### Watch Mode
+
+Watch mode provides automatic file monitoring and workflow execution:
+
+**Features**:
+- 📁 **File Monitoring**: Automatically detect file changes
+- ⚡ **Debouncing**: Prevent duplicate executions
+- 🔄 **Retry Logic**: Automatic retry with exponential backoff
+- 📊 **Metrics Tracking**: Track executions, time saved, success rates
+- 📝 **Execution Logging**: Complete audit trail with log rotation
+
+**Quick Start**:
+```bash
+# Initialize watch configuration
+kse watch init
+
+# Install a preset (auto-sync, prompt-regen, context-export, test-runner)
+kse watch install auto-sync
+
+# Start watching
+kse watch start
+
+# Check status
+kse watch status
+
+# View metrics
+kse watch metrics
+```
+
+**Presets**:
+- `auto-sync`: Automatically sync workspace when tasks.md changes
+- `prompt-regen`: Regenerate prompts when requirements/design change
+- `context-export`: Export context when tasks complete
+- `test-runner`: Run tests when source files change
+
+### Tool Detection
+
+KSE automatically detects your development environment and suggests appropriate automation:
+
+```bash
+# During adoption, KSE detects:
+kse adopt
+
+# Detected: Kiro IDE → Suggests native agent hooks
+# Detected: VS Code/Cursor → Suggests watch mode
+# Detected: Other → Suggests manual workflows
+```
+
+### Manual Workflows
+
+For environments without automation, KSE provides step-by-step workflow guides:
+
+```bash
+# List available workflows
+kse workflows
+
+# View workflow details
+kse workflows show task-sync        # 30-60 seconds
+kse workflows show context-export   # 15-45 seconds
+kse workflows show prompt-generation # 20-30 seconds
+
+# Open complete guide
+kse workflows guide
+```
+
+**Available Workflows**:
+- **Task Sync**: Keep workspace synchronized with task progress
+- **Context Export**: Export spec context for AI assistants
+- **Prompt Generation**: Generate task-specific prompts
+- **Daily Checklist**: Complete daily workflow routine
+- **Task Completion**: Checklist for completing tasks
+- **Spec Creation**: Checklist for creating new specs
+
 ## 🛠️ Project Structure
 
 After initialization, your project will have:

package/bin/kiro-spec-engine.js

@@ -11,6 +11,8 @@ const doctorCommand = require('../lib/commands/doctor');
 const adoptCommand = require('../lib/commands/adopt');
 const upgradeCommand = require('../lib/commands/upgrade');
 const rollbackCommand = require('../lib/commands/rollback');
+const watchCommands = require('../lib/commands/watch');
+const workflowsCommand = require('../lib/commands/workflows');
 const VersionChecker = require('../lib/version/version-checker');
 
 const i18n = getI18n();
@@ -264,6 +266,66 @@ program
     await versionChecker.displayVersionInfo(projectPath);
   });
 
+// Watch mode commands
+const watchCmd = program
+  .command('watch')
+  .description('Manage watch mode for automated file monitoring');
+
+watchCmd
+  .command('start')
+  .description('Start watch mode')
+  .option('-c, --config <path>', 'Custom config file path')
+  .option('-p, --patterns <patterns>', 'Override patterns (comma-separated)')
+  .action(watchCommands.startWatch);
+
+watchCmd
+  .command('stop')
+  .description('Stop watch mode')
+  .action(watchCommands.stopWatch);
+
+watchCmd
+  .command('status')
+  .description('Show watch mode status')
+  .action(watchCommands.statusWatch);
+
+watchCmd
+  .command('logs')
+  .description('Display execution logs')
+  .option('-t, --tail <lines>', 'Number of lines to show', '50')
+  .option('-f, --follow', 'Follow mode (tail -f)')
+  .action(watchCommands.logsWatch);
+
+watchCmd
+  .command('metrics')
+  .description('Display automation metrics')
+  .option('--format <format>', 'Output format (text/json)', 'text')
+  .action(watchCommands.metricsWatch);
+
+watchCmd
+  .command('init')
+  .description('Initialize watch configuration')
+  .option('-f, --force', 'Overwrite existing config')
+  .action(watchCommands.initWatch);
+
+watchCmd
+  .command('presets')
+  .description('List available watch presets')
+  .action(watchCommands.listPresetsWatch);
+
+watchCmd
+  .command('install <preset>')
+  .description('Install a watch preset')
+  .option('-f, --force', 'Overwrite existing actions')
+  .action(watchCommands.installPresetWatch);
+
+// Workflows commands
+const workflowsCmd = program
+  .command('workflows [action] [workflow-id]')
+  .description('Manage manual workflows and checklists')
+  .action(async (action, workflowId) => {
+    await workflowsCommand(action, workflowId);
+  });
+
 // 更新项目配置的辅助函数
 async function updateProjectConfig(projectName) {
   const envPath = path.join(process.cwd(), '.kiro/steering/ENVIRONMENT.md');