kiro-spec-engine 1.2.3 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/CHANGELOG.md +135 -0
  2. package/README.md +239 -213
  3. package/README.zh.md +0 -330
  4. package/bin/kiro-spec-engine.js +62 -0
  5. package/docs/README.md +223 -0
  6. package/docs/agent-hooks-analysis.md +815 -0
  7. package/docs/command-reference.md +252 -0
  8. package/docs/cross-tool-guide.md +554 -0
  9. package/docs/examples/add-export-command/design.md +194 -0
  10. package/docs/examples/add-export-command/requirements.md +110 -0
  11. package/docs/examples/add-export-command/tasks.md +88 -0
  12. package/docs/examples/add-rest-api/design.md +855 -0
  13. package/docs/examples/add-rest-api/requirements.md +323 -0
  14. package/docs/examples/add-rest-api/tasks.md +355 -0
  15. package/docs/examples/add-user-dashboard/design.md +192 -0
  16. package/docs/examples/add-user-dashboard/requirements.md +143 -0
  17. package/docs/examples/add-user-dashboard/tasks.md +91 -0
  18. package/docs/faq.md +696 -0
  19. package/docs/integration-modes.md +525 -0
  20. package/docs/integration-philosophy.md +313 -0
  21. package/docs/manual-workflows-guide.md +417 -0
  22. package/docs/quick-start-with-ai-tools.md +374 -0
  23. package/docs/quick-start.md +711 -0
  24. package/docs/spec-workflow.md +453 -0
  25. package/docs/steering-strategy-guide.md +196 -0
  26. package/docs/tools/claude-guide.md +653 -0
  27. package/docs/tools/cursor-guide.md +705 -0
  28. package/docs/tools/generic-guide.md +445 -0
  29. package/docs/tools/kiro-guide.md +308 -0
  30. package/docs/tools/vscode-guide.md +444 -0
  31. package/docs/tools/windsurf-guide.md +390 -0
  32. package/docs/troubleshooting.md +795 -0
  33. package/docs/zh/README.md +275 -0
  34. package/docs/zh/quick-start.md +711 -0
  35. package/docs/zh/tools/claude-guide.md +348 -0
  36. package/docs/zh/tools/cursor-guide.md +280 -0
  37. package/docs/zh/tools/generic-guide.md +498 -0
  38. package/docs/zh/tools/kiro-guide.md +342 -0
  39. package/docs/zh/tools/vscode-guide.md +448 -0
  40. package/docs/zh/tools/windsurf-guide.md +377 -0
  41. package/lib/adoption/detection-engine.js +14 -4
  42. package/lib/commands/adopt.js +117 -3
  43. package/lib/commands/context.js +99 -0
  44. package/lib/commands/prompt.js +105 -0
  45. package/lib/commands/status.js +225 -0
  46. package/lib/commands/task.js +199 -0
  47. package/lib/commands/watch.js +569 -0
  48. package/lib/commands/workflows.js +240 -0
  49. package/lib/commands/workspace.js +189 -0
  50. package/lib/context/context-exporter.js +378 -0
  51. package/lib/context/prompt-generator.js +482 -0
  52. package/lib/steering/adoption-config.js +164 -0
  53. package/lib/steering/steering-manager.js +289 -0
  54. package/lib/task/task-claimer.js +430 -0
  55. package/lib/utils/tool-detector.js +383 -0
  56. package/lib/watch/action-executor.js +458 -0
  57. package/lib/watch/event-debouncer.js +323 -0
  58. package/lib/watch/execution-logger.js +550 -0
  59. package/lib/watch/file-watcher.js +499 -0
  60. package/lib/watch/presets.js +266 -0
  61. package/lib/watch/watch-manager.js +533 -0
  62. package/lib/workspace/workspace-manager.js +370 -0
  63. package/lib/workspace/workspace-sync.js +356 -0
  64. package/package.json +3 -1
  65. package/template/.kiro/tools/backup_manager.py +295 -0
  66. package/template/.kiro/tools/configuration_manager.py +218 -0
  67. package/template/.kiro/tools/document_evaluator.py +550 -0
  68. package/template/.kiro/tools/enhancement_logger.py +168 -0
  69. package/template/.kiro/tools/error_handler.py +335 -0
  70. package/template/.kiro/tools/improvement_identifier.py +444 -0
  71. package/template/.kiro/tools/modification_applicator.py +737 -0
  72. package/template/.kiro/tools/quality_gate_enforcer.py +207 -0
  73. package/template/.kiro/tools/quality_scorer.py +305 -0
  74. package/template/.kiro/tools/report_generator.py +154 -0
  75. package/template/.kiro/tools/ultrawork_enhancer_refactored.py +0 -0
  76. package/template/.kiro/tools/ultrawork_enhancer_v2.py +463 -0
  77. package/template/.kiro/tools/ultrawork_enhancer_v3.py +606 -0
  78. package/template/.kiro/tools/workflow_quality_gate.py +100 -0
package/docs/examples/add-export-command/design.md ADDED
@@ -0,0 +1,194 @@
1
+ # Export Command - Design
2
+
3
+ > Technical design for kse export command
4
+
5
+ ---
6
+
7
+ **Version**: 1.0.0
8
+ **Last Updated**: 2026-01-23
9
+
10
+ ---
11
+
12
+ ## Architecture
13
+
14
+ **Pattern:** Command Pattern
15
+ **CLI Framework:** Commander.js
16
+ **Markdown Processing:** marked library
17
+ **File I/O:** Node.js fs/promises
18
+
19
+ ---
20
+
21
+ ## Component Design
22
+
23
+ ### ExportCommand
24
+ **File:** `lib/commands/export.command.js`
25
+
26
+ **Responsibilities:**
27
+ - Parse command arguments
28
+ - Validate inputs
29
+ - Orchestrate export process
30
+ - Display results
31
+
32
+ **Methods:**
33
+ ```javascript
34
+ class ExportCommand {
35
+ async execute(specName, options) {
36
+ // 1. Validate Spec exists
37
+ // 2. Load Spec data
38
+ // 3. Format based on options.format
39
+ // 4. Write to file
40
+ // 5. Display success message
41
+ }
42
+ }
43
+ ```
44
+
45
+ ---
46
+
47
+ ### ExportService
48
+ **File:** `lib/services/export.service.js`
49
+
50
+ **Responsibilities:**
51
+ - Load Spec files
52
+ - Format data for export
53
+ - Generate output files
54
+
55
+ **Methods:**
56
+ ```javascript
57
+ class ExportService {
58
+ async loadSpec(specName) {
59
+ // Read requirements.md, design.md, tasks.md
60
+ // Return { requirements, design, tasks, metadata }
61
+ }
62
+
63
+ async exportAsJSON(specData, outputPath) {
64
+ // Format as JSON
65
+ // Write to file
66
+ }
67
+
68
+ async exportAsMarkdown(specData, outputPath) {
69
+ // Combine all documents
70
+ // Add TOC
71
+ // Write to file
72
+ }
73
+
74
+ async exportAsHTML(specData, outputPath) {
75
+ // Convert Markdown to HTML
76
+ // Add styling
77
+ // Write to file
78
+ }
79
+ }
80
+ ```
81
+
82
+ ---
83
+
84
+ ## Command Registration
85
+
86
+ **File:** `bin/kiro-spec-engine.js`
87
+
88
+ ```javascript
89
+ program
90
+ .command('export <spec-name>')
91
+ .description('Export Spec in various formats')
92
+ .option('-f, --format <format>', 'Output format (json|md|html)', 'md')
93
+ .option('-o, --output <path>', 'Output file path')
94
+ .option('--include-meta', 'Include metadata', true)
95
+ .action(async (specName, options) => {
96
+ const command = new ExportCommand();
97
+ await command.execute(specName, options);
98
+ });
99
+ ```
100
+
101
+ ---
102
+
103
+ ## Output Formats
104
+
105
+ ### JSON Format
106
+ ```json
107
+ {
108
+ "name": "01-00-feature-name",
109
+ "metadata": {
110
+ "created": "2026-01-23T10:00:00Z",
111
+ "version": "1.0.0"
112
+ },
113
+ "requirements": "# Requirements\n...",
114
+ "design": "# Design\n...",
115
+ "tasks": "# Tasks\n..."
116
+ }
117
+ ```
118
+
119
+ ### Markdown Format
120
+ ```markdown
121
+ # Spec: 01-00-feature-name
122
+
123
+ **Exported:** 2026-01-23
124
+ **Version:** 1.0.0
125
+
126
+ ## Table of Contents
127
+ - [Requirements](#requirements)
128
+ - [Design](#design)
129
+ - [Tasks](#tasks)
130
+
131
+ ---
132
+
133
+ ## Requirements
134
+ [Content from requirements.md]
135
+
136
+ ---
137
+
138
+ ## Design
139
+ [Content from design.md]
140
+
141
+ ---
142
+
143
+ ## Tasks
144
+ [Content from tasks.md]
145
+ ```
146
+
147
+ ### HTML Format
148
+ ```html
149
+ <!DOCTYPE html>
150
+ <html>
151
+ <head>
152
+ <title>Spec: 01-00-feature-name</title>
153
+ <style>/* Styling */</style>
154
+ </head>
155
+ <body>
156
+ <h1>Spec: 01-00-feature-name</h1>
157
+ <!-- Converted Markdown content -->
158
+ </body>
159
+ </html>
160
+ ```
161
+
162
+ ---
163
+
164
+ ## Error Handling
165
+
166
+ ```javascript
167
+ // Spec not found
168
+ throw new Error(`Spec "${specName}" not found in .kiro/specs/`);
169
+
170
+ // Invalid format
171
+ throw new Error(`Invalid format "${format}". Use: json, md, or html`);
172
+
173
+ // File write error
174
+ throw new Error(`Failed to write export file: ${error.message}`);
175
+ ```
176
+
177
+ ---
178
+
179
+ ## Requirements Traceability
180
+
181
+ | Requirement | Component | Method |
182
+ |-------------|-----------|--------|
183
+ | US-1 | ExportService | exportAsJSON() |
184
+ | US-2 | ExportService | exportAsMarkdown() |
185
+ | US-3 | ExportService | exportAsHTML() |
186
+ | FR-1 | ExportCommand | execute() |
187
+ | FR-2 | ExportService | exportAsJSON() |
188
+ | FR-3 | ExportService | exportAsMarkdown() |
189
+ | FR-4 | ExportService | exportAsHTML() |
190
+
191
+ ---
192
+
193
+ **Version**: 1.0.0
194
+ **Last Updated**: 2026-01-23
package/docs/examples/add-export-command/requirements.md ADDED
@@ -0,0 +1,110 @@
1
+ # Export Command - Requirements
2
+
3
+ > Example Spec demonstrating CLI command development
4
+
5
+ ---
6
+
7
+ **Version**: 1.0.0
8
+ **Last Updated**: 2026-01-23
9
+ **Spec Type**: Example - CLI Feature
10
+
11
+ ---
12
+
13
+ ## Overview
14
+
15
+ 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).
16
+
17
+ **Learning Points:**
18
+ - CLI command structure
19
+ - Argument parsing
20
+ - File I/O operations
21
+ - Output formatting
22
+ - Error handling in CLI
23
+
24
+ ---
25
+
26
+ ## User Stories
27
+
28
+ ### US-1: Export Spec as JSON
29
+ **As a** developer
30
+ **I want to** export a Spec as JSON
31
+ **So that** I can process it programmatically
32
+
33
+ **Acceptance Criteria:**
34
+ - WHEN I run `kse export 01-00-feature --format json` THEN I get a JSON file
35
+ - WHEN export succeeds THEN I see success message with file path
36
+ - WHEN Spec doesn't exist THEN I see error message
37
+
38
+ ### US-2: Export Spec as Markdown
39
+ **As a** developer
40
+ **I want to** export a Spec as single Markdown file
41
+ **So that** I can share it easily
42
+
43
+ **Acceptance Criteria:**
44
+ - WHEN I run `kse export 01-00-feature --format md` THEN I get a Markdown file
45
+ - WHEN I don't specify format THEN Markdown is default
46
+ - WHEN export succeeds THEN file contains all three Spec documents
47
+
48
+ ### US-3: Export Spec as HTML
49
+ **As a** developer
50
+ **I want to** export a Spec as HTML
51
+ **So that** I can view it in a browser
52
+
53
+ **Acceptance Criteria:**
54
+ - WHEN I run `kse export 01-00-feature --format html` THEN I get an HTML file
55
+ - WHEN I open HTML THEN it has proper styling
56
+ - WHEN HTML includes code blocks THEN they have syntax highlighting
57
+
58
+ ---
59
+
60
+ ## Functional Requirements
61
+
62
+ ### FR-1: Command Interface
63
+ ```bash
64
+ kse export <spec-name> [options]
65
+
66
+ Options:
67
+ --format, -f Output format (json|md|html) [default: md]
68
+ --output, -o Output file path [default: auto-generated]
69
+ --include-meta Include metadata in export [default: true]
70
+ ```
71
+
72
+ ### FR-2: JSON Export
73
+ - Export structure: `{ name, requirements, design, tasks, metadata }`
74
+ - Include file paths and timestamps
75
+ - Pretty-print JSON (2-space indentation)
76
+
77
+ ### FR-3: Markdown Export
78
+ - Combine requirements.md, design.md, tasks.md
79
+ - Add table of contents
80
+ - Add metadata header
81
+ - Preserve formatting
82
+
83
+ ### FR-4: HTML Export
84
+ - Convert Markdown to HTML
85
+ - Add CSS styling
86
+ - Add syntax highlighting for code blocks
87
+ - Make it printable
88
+
89
+ ---
90
+
91
+ ## Non-Functional Requirements
92
+
93
+ ### NFR-1: Performance
94
+ - Export completes in < 1 second for typical Spec
95
+ - Handle large Specs (> 10MB) gracefully
96
+
97
+ ### NFR-2: Error Handling
98
+ - Clear error messages for missing Specs
99
+ - Validate format option
100
+ - Handle file write errors
101
+
102
+ ### NFR-3: Usability
103
+ - Intuitive command syntax
104
+ - Helpful error messages
105
+ - Progress indicator for large exports
106
+
107
+ ---
108
+
109
+ **Version**: 1.0.0
110
+ **Last Updated**: 2026-01-23
package/docs/examples/add-export-command/tasks.md ADDED
@@ -0,0 +1,88 @@
1
+ # Export Command - Tasks
2
+
3
+ > Implementation plan for kse export command
4
+
5
+ ---
6
+
7
+ **Version**: 1.0.0
8
+ **Last Updated**: 2026-01-23
9
+
10
+ ---
11
+
12
+ ## Phase 1: Core Infrastructure
13
+
14
+ - [ ] 1.1 Create ExportService class
15
+ - Implement loadSpec() method
16
+ - Add error handling for missing files
17
+ - Write unit tests
18
+
19
+ - [ ] 1.2 Create ExportCommand class
20
+ - Implement execute() method
21
+ - Add input validation
22
+ - Write unit tests
23
+
24
+ ---
25
+
26
+ ## Phase 2: Format Implementations
27
+
28
+ - [ ] 2.1 Implement JSON export
29
+ - Create exportAsJSON() method
30
+ - Format Spec data as JSON
31
+ - Add pretty-printing
32
+ - Write unit tests
33
+
34
+ - [ ] 2.2 Implement Markdown export
35
+ - Create exportAsMarkdown() method
36
+ - Combine all Spec documents
37
+ - Generate table of contents
38
+ - Write unit tests
39
+
40
+ - [ ] 2.3 Implement HTML export
41
+ - Install marked library
42
+ - Create exportAsHTML() method
43
+ - Convert Markdown to HTML
44
+ - Add CSS styling
45
+ - Add syntax highlighting
46
+ - Write unit tests
47
+
48
+ ---
49
+
50
+ ## Phase 3: CLI Integration
51
+
52
+ - [ ] 3.1 Register command in CLI
53
+ - Add command to bin/kiro-spec-engine.js
54
+ - Define options and arguments
55
+ - Wire up to ExportCommand
56
+
57
+ - [ ] 3.2 Add output path handling
58
+ - Generate default output paths
59
+ - Validate custom output paths
60
+ - Create output directories if needed
61
+
62
+ - [ ] 3.3 Add user feedback
63
+ - Show progress spinner
64
+ - Display success message with file path
65
+ - Show helpful error messages
66
+
67
+ ---
68
+
69
+ ## Phase 4: Testing
70
+
71
+ - [ ] 4.1 Unit tests for ExportService
72
+ - [ ] 4.2 Unit tests for ExportCommand
73
+ - [ ] 4.3 Integration tests for CLI command
74
+ - [ ] 4.4 Test all three export formats
75
+ - [ ] 4.5 Test error scenarios
76
+
77
+ ---
78
+
79
+ ## Phase 5: Documentation
80
+
81
+ - [ ] 5.1 Update command reference
82
+ - [ ] 5.2 Add usage examples
83
+ - [ ] 5.3 Update CHANGELOG
84
+
85
+ ---
86
+
87
+ **Version**: 1.0.0
88
+ **Last Updated**: 2026-01-23