kiro-spec-engine 1.3.0 → 1.4.1

package/docs/command-reference.md

@@ -0,0 +1,252 @@
+# Command Reference
+
+> Quick reference for all kse commands
+
+**Version**: 1.3.0  
+**Last Updated**: 2026-01-23
+
+---
+
+## Command Naming
+
+The package provides two command aliases:
+- `kse` - **Recommended short alias** (use this in all documentation)
+- `kiro-spec-engine` - Full command name (legacy, not recommended)
+
+**Always use `kse` in examples and documentation for consistency.**
+
+---
+
+## Installation
+
+```bash
+npm install -g kiro-spec-engine
+```
+
+This creates the `kse` command globally.
+
+---
+
+## Core Commands
+
+### Project Setup
+
+```bash
+# Initialize new project
+kse init [project-name]
+
+# Adopt existing project
+kse adopt
+
+# Check project status
+kse status
+
+# Run system diagnostics
+kse doctor
+```
+
+### Spec Management
+
+```bash
+# Create new spec (interactive)
+kse create-spec
+
+# Create spec with name
+kse create-spec 01-00-feature-name
+
+# List all specs
+kse list-specs
+```
+
+### Task Management
+
+```bash
+# Claim a task
+kse task claim <spec-name> <task-id>
+
+# Unclaim a task
+kse task unclaim <spec-name> <task-id>
+
+# Show task status
+kse task status <spec-name>
+```
+
+### Context & Prompts
+
+```bash
+# Export spec context
+kse context export <spec-name>
+
+# Export with steering rules
+kse context export <spec-name> --steering
+
+# Generate task prompt
+kse prompt generate <spec-name> <task-id>
+
+# Generate for specific tool
+kse prompt generate <spec-name> <task-id> --tool=claude-code
+```
+
+### Watch Mode
+
+```bash
+# Initialize watch configuration
+kse watch init
+
+# Start watch mode
+kse watch start
+
+# Stop watch mode
+kse watch stop
+
+# Check watch status
+kse watch status
+
+# View watch logs
+kse watch logs
+
+# Show automation metrics
+kse watch metrics
+
+# List available presets
+kse watch presets
+
+# Install a preset
+kse watch install <preset-name>
+```
+
+### Workflows
+
+```bash
+# List available workflows
+kse workflows
+
+# Show workflow details
+kse workflows show <workflow-name>
+
+# Open workflow guide
+kse workflows guide
+
+# Mark workflow as complete
+kse workflows complete <workflow-name>
+```
+
+### Workspace Management
+
+```bash
+# Sync workspace
+kse workspace sync
+
+# Show workspace info
+kse workspace info
+
+# List team members
+kse workspace team
+```
+
+### Version & Upgrade
+
+```bash
+# Show version info
+kse version-info
+
+# Check for upgrades
+kse upgrade check
+
+# Perform upgrade
+kse upgrade
+```
+
+---
+
+## Global Options
+
+```bash
+# Set language
+kse --lang zh <command>
+kse --lang en <command>
+
+# Show help
+kse --help
+kse <command> --help
+
+# Show version
+kse --version
+```
+
+---
+
+## Common Workflows
+
+### Starting a New Feature
+
+```bash
+# 1. Create spec
+kse create-spec 01-00-my-feature
+
+# 2. Export context
+kse context export 01-00-my-feature
+
+# 3. Work on tasks...
+
+# 4. Sync progress
+kse workspace sync
+```
+
+### Setting Up Automation
+
+```bash
+# 1. Initialize watch mode
+kse watch init
+
+# 2. Install presets
+kse watch install auto-sync
+kse watch install test-runner
+
+# 3. Start watching
+kse watch start
+
+# 4. Check status
+kse watch status
+```
+
+### Working with Team
+
+```bash
+# 1. Check team status
+kse workspace team
+
+# 2. Claim a task
+kse task claim 01-00-feature 1.1
+
+# 3. Work on task...
+
+# 4. Sync when done
+kse workspace sync
+```
+
+---
+
+## Tips
+
+1. **Use `kse` not `kiro-spec-engine`** - Shorter and easier to type
+2. **Add `--help` to any command** - Get detailed usage information
+3. **Use tab completion** - Most shells support command completion
+4. **Check `kse doctor`** - Diagnose issues quickly
+5. **Use watch mode** - Automate repetitive tasks
+
+---
+
+## See Also
+
+- [Manual Workflows Guide](./manual-workflows-guide.md)
+- [Cross-Tool Guide](./cross-tool-guide.md)
+- [Adoption Guide](./adoption-guide.md)
+- [Developer Guide](./developer-guide.md)
+
+---
+
+**Need Help?**
+- Run `kse --help` for command reference
+- Check [GitHub Issues](https://github.com/heguangyong/kiro-spec-engine/issues)
+- Review [Documentation](../README.md)

package/docs/examples/add-export-command/design.md

@@ -0,0 +1,194 @@
+# Export Command - Design
+
+> Technical design for kse export command
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23
+
+---
+
+## Architecture
+
+**Pattern:** Command Pattern  
+**CLI Framework:** Commander.js  
+**Markdown Processing:** marked library  
+**File I/O:** Node.js fs/promises
+
+---
+
+## Component Design
+
+### ExportCommand
+**File:** `lib/commands/export.command.js`
+
+**Responsibilities:**
+- Parse command arguments
+- Validate inputs
+- Orchestrate export process
+- Display results
+
+**Methods:**
+```javascript
+class ExportCommand {
+  async execute(specName, options) {
+    // 1. Validate Spec exists
+    // 2. Load Spec data
+    // 3. Format based on options.format
+    // 4. Write to file
+    // 5. Display success message
+  }
+}
+```
+
+---
+
+### ExportService
+**File:** `lib/services/export.service.js`
+
+**Responsibilities:**
+- Load Spec files
+- Format data for export
+- Generate output files
+
+**Methods:**
+```javascript
+class ExportService {
+  async loadSpec(specName) {
+    // Read requirements.md, design.md, tasks.md
+    // Return { requirements, design, tasks, metadata }
+  }
+
+  async exportAsJSON(specData, outputPath) {
+    // Format as JSON
+    // Write to file
+  }
+
+  async exportAsMarkdown(specData, outputPath) {
+    // Combine all documents
+    // Add TOC
+    // Write to file
+  }
+
+  async exportAsHTML(specData, outputPath) {
+    // Convert Markdown to HTML
+    // Add styling
+    // Write to file
+  }
+}
+```
+
+---
+
+## Command Registration
+
+**File:** `bin/kiro-spec-engine.js`
+
+```javascript
+program
+  .command('export <spec-name>')
+  .description('Export Spec in various formats')
+  .option('-f, --format <format>', 'Output format (json|md|html)', 'md')
+  .option('-o, --output <path>', 'Output file path')
+  .option('--include-meta', 'Include metadata', true)
+  .action(async (specName, options) => {
+    const command = new ExportCommand();
+    await command.execute(specName, options);
+  });
+```
+
+---
+
+## Output Formats
+
+### JSON Format
+```json
+{
+  "name": "01-00-feature-name",
+  "metadata": {
+    "created": "2026-01-23T10:00:00Z",
+    "version": "1.0.0"
+  },
+  "requirements": "# Requirements\n...",
+  "design": "# Design\n...",
+  "tasks": "# Tasks\n..."
+}
+```
+
+### Markdown Format
+```markdown
+# Spec: 01-00-feature-name
+
+**Exported:** 2026-01-23  
+**Version:** 1.0.0
+
+## Table of Contents
+- [Requirements](#requirements)
+- [Design](#design)
+- [Tasks](#tasks)
+
+---
+
+## Requirements
+[Content from requirements.md]
+
+---
+
+## Design
+[Content from design.md]
+
+---
+
+## Tasks
+[Content from tasks.md]
+```
+
+### HTML Format
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Spec: 01-00-feature-name</title>
+  <style>/* Styling */</style>
+</head>
+<body>
+  <h1>Spec: 01-00-feature-name</h1>
+  <!-- Converted Markdown content -->
+</body>
+</html>
+```
+
+---
+
+## Error Handling
+
+```javascript
+// Spec not found
+throw new Error(`Spec "${specName}" not found in .kiro/specs/`);
+
+// Invalid format
+throw new Error(`Invalid format "${format}". Use: json, md, or html`);
+
+// File write error
+throw new Error(`Failed to write export file: ${error.message}`);
+```
+
+---
+
+## Requirements Traceability
+
+| Requirement | Component | Method |
+|-------------|-----------|--------|
+| US-1 | ExportService | exportAsJSON() |
+| US-2 | ExportService | exportAsMarkdown() |
+| US-3 | ExportService | exportAsHTML() |
+| FR-1 | ExportCommand | execute() |
+| FR-2 | ExportService | exportAsJSON() |
+| FR-3 | ExportService | exportAsMarkdown() |
+| FR-4 | ExportService | exportAsHTML() |
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23

package/docs/examples/add-export-command/requirements.md

@@ -0,0 +1,110 @@
+# Export Command - Requirements
+
+> Example Spec demonstrating CLI command development
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23  
+**Spec Type**: Example - CLI Feature
+
+---
+
+## Overview
+
+This Spec demonstrates how to add a new CLI command to kse. We'll implement `kse export` command that exports Spec data in various formats (JSON, Markdown, HTML).
+
+**Learning Points:**
+- CLI command structure
+- Argument parsing
+- File I/O operations
+- Output formatting
+- Error handling in CLI
+
+---
+
+## User Stories
+
+### US-1: Export Spec as JSON
+**As a** developer  
+**I want to** export a Spec as JSON  
+**So that** I can process it programmatically
+
+**Acceptance Criteria:**
+- WHEN I run `kse export 01-00-feature --format json` THEN I get a JSON file
+- WHEN export succeeds THEN I see success message with file path
+- WHEN Spec doesn't exist THEN I see error message
+
+### US-2: Export Spec as Markdown
+**As a** developer  
+**I want to** export a Spec as single Markdown file  
+**So that** I can share it easily
+
+**Acceptance Criteria:**
+- WHEN I run `kse export 01-00-feature --format md` THEN I get a Markdown file
+- WHEN I don't specify format THEN Markdown is default
+- WHEN export succeeds THEN file contains all three Spec documents
+
+### US-3: Export Spec as HTML
+**As a** developer  
+**I want to** export a Spec as HTML  
+**So that** I can view it in a browser
+
+**Acceptance Criteria:**
+- WHEN I run `kse export 01-00-feature --format html` THEN I get an HTML file
+- WHEN I open HTML THEN it has proper styling
+- WHEN HTML includes code blocks THEN they have syntax highlighting
+
+---
+
+## Functional Requirements
+
+### FR-1: Command Interface
+```bash
+kse export <spec-name> [options]
+
+Options:
+  --format, -f    Output format (json|md|html) [default: md]
+  --output, -o    Output file path [default: auto-generated]
+  --include-meta  Include metadata in export [default: true]
+```
+
+### FR-2: JSON Export
+- Export structure: `{ name, requirements, design, tasks, metadata }`
+- Include file paths and timestamps
+- Pretty-print JSON (2-space indentation)
+
+### FR-3: Markdown Export
+- Combine requirements.md, design.md, tasks.md
+- Add table of contents
+- Add metadata header
+- Preserve formatting
+
+### FR-4: HTML Export
+- Convert Markdown to HTML
+- Add CSS styling
+- Add syntax highlighting for code blocks
+- Make it printable
+
+---
+
+## Non-Functional Requirements
+
+### NFR-1: Performance
+- Export completes in < 1 second for typical Spec
+- Handle large Specs (> 10MB) gracefully
+
+### NFR-2: Error Handling
+- Clear error messages for missing Specs
+- Validate format option
+- Handle file write errors
+
+### NFR-3: Usability
+- Intuitive command syntax
+- Helpful error messages
+- Progress indicator for large exports
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23

package/docs/examples/add-export-command/tasks.md

@@ -0,0 +1,88 @@
+# Export Command - Tasks
+
+> Implementation plan for kse export command
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23
+
+---
+
+## Phase 1: Core Infrastructure
+
+- [ ] 1.1 Create ExportService class
+  - Implement loadSpec() method
+  - Add error handling for missing files
+  - Write unit tests
+
+- [ ] 1.2 Create ExportCommand class
+  - Implement execute() method
+  - Add input validation
+  - Write unit tests
+
+---
+
+## Phase 2: Format Implementations
+
+- [ ] 2.1 Implement JSON export
+  - Create exportAsJSON() method
+  - Format Spec data as JSON
+  - Add pretty-printing
+  - Write unit tests
+
+- [ ] 2.2 Implement Markdown export
+  - Create exportAsMarkdown() method
+  - Combine all Spec documents
+  - Generate table of contents
+  - Write unit tests
+
+- [ ] 2.3 Implement HTML export
+  - Install marked library
+  - Create exportAsHTML() method
+  - Convert Markdown to HTML
+  - Add CSS styling
+  - Add syntax highlighting
+  - Write unit tests
+
+---
+
+## Phase 3: CLI Integration
+
+- [ ] 3.1 Register command in CLI
+  - Add command to bin/kiro-spec-engine.js
+  - Define options and arguments
+  - Wire up to ExportCommand
+
+- [ ] 3.2 Add output path handling
+  - Generate default output paths
+  - Validate custom output paths
+  - Create output directories if needed
+
+- [ ] 3.3 Add user feedback
+  - Show progress spinner
+  - Display success message with file path
+  - Show helpful error messages
+
+---
+
+## Phase 4: Testing
+
+- [ ] 4.1 Unit tests for ExportService
+- [ ] 4.2 Unit tests for ExportCommand
+- [ ] 4.3 Integration tests for CLI command
+- [ ] 4.4 Test all three export formats
+- [ ] 4.5 Test error scenarios
+
+---
+
+## Phase 5: Documentation
+
+- [ ] 5.1 Update command reference
+- [ ] 5.2 Add usage examples
+- [ ] 5.3 Update CHANGELOG
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23