kiro-spec-engine 1.20.5 → 1.22.0

package/CHANGELOG.md

@@ -7,6 +7,84 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.22.0] - 2026-02-02
+
+### Added
+- **Spec-Level Collaboration System**: Enable multiple AI instances to work on different Specs in parallel
+  - **Master Spec and Sub-Specs**: Break down large features into manageable, independently developable modules
+  - **Dependency Management**: Define and track dependencies between Specs with automatic circular dependency detection
+  - **Interface Contracts**: Formal API definitions (JSON/TypeScript format) ensuring compatibility between Specs
+  - **Status Tracking**: Monitor progress, assignments, and blocking issues across all Specs
+  - **Integration Testing**: Run cross-Spec integration tests to verify modules work together correctly
+  - **Dependency Visualization**: View dependency graphs with critical path highlighting
+  - **CLI Commands**: Complete set of commands for collaboration management
+    - `kse collab init` - Initialize Master Spec with Sub-Specs
+    - `kse collab status` - Display collaboration status and dependency graph
+    - `kse collab assign` - Assign Specs to Kiro instances
+    - `kse collab verify` - Verify interface contract compliance
+    - `kse collab integrate` - Run integration tests across Specs
+    - `kse collab migrate` - Convert standalone Spec to collaborative mode
+  - **Backward Compatible**: Opt-in system that doesn't affect existing single-Spec workflows
+  - **Comprehensive Documentation**: Complete guide with examples and best practices
+
+### Technical Details
+- New collaboration managers: MetadataManager, DependencyManager, ContractManager, IntegrationManager, Visualizer
+- Collaboration metadata stored in `.kiro/specs/{spec-name}/collaboration.json`
+- Interface contracts stored in `.kiro/specs/{spec-name}/interfaces/{interface-name}.json`
+- Atomic metadata updates with file locking and retry logic
+- Graph-based dependency analysis with cycle detection
+- Automated interface verification for JavaScript/TypeScript
+- Integration test framework with dependency validation
+- Text and Mermaid format graph visualization
+
+## [1.21.1] - 2026-02-01
+
+### Fixed
+- **Test Suite Compatibility**: Fixed test failures introduced in v1.21.0
+  - Updated tests to reflect optional version field (now defaults to "1.0")
+  - Added `skipFilesystemValidation` option to `loadConfig()` for testing scenarios
+  - Mocked `_validateRepositoryPath` in handler tests to avoid filesystem dependency
+  - All 1697 tests now pass successfully
+
+### Technical Details
+- Modified `ConfigManager.loadConfig()` to accept optional `skipFilesystemValidation` parameter
+- Updated test expectations for optional version field validation
+- Enhanced test isolation by mocking filesystem validation in unit tests
+- No functional changes to production code behavior
+
+## [1.21.0] - 2026-02-01
+
+### Added
+- **Manual Configuration Support**: Users can now manually create and edit `.kiro/project-repos.json` without relying solely on auto-scan
+  - Version field is now optional (defaults to "1.0" if omitted)
+  - Only `name` and `path` are required for each repository entry
+  - All other fields (`remote`, `defaultBranch`, `description`, `tags`, `group`, `parent`) are optional
+  - Filesystem validation ensures paths exist and contain valid `.git` directories
+  - Clear, actionable error messages guide users in fixing configuration issues
+  - Comprehensive documentation in `docs/multi-repo-management-guide.md` with examples and troubleshooting
+
+### Changed
+- **Enhanced Validation**: Configuration validation now performs filesystem checks when loading from disk
+  - Validates that repository paths exist on the filesystem
+  - Verifies each path contains a `.git` directory (not file)
+  - Detects and rejects Git worktrees with helpful error messages
+  - Reports all validation errors together (not just the first one)
+  - Maintains backward compatibility with all v1.18.0+ configurations
+
+### Fixed
+- **Manual Configuration Rejection**: Fixed issue where manually-created configurations were rejected even when valid
+  - Users can now manually curate repository lists
+  - Users can remove false positives from auto-scan results
+  - Users can add repositories that weren't auto-detected
+  - Minimal configurations (name + path only) now pass validation
+  - User-reported issue: 8 real Git repositories rejected by validation
+
+### Documentation
+- Added comprehensive "Manual Configuration" section to multi-repo management guide
+- Documented minimal configuration format with examples
+- Added troubleshooting guide for common validation errors
+- Included step-by-step instructions for creating manual configurations
+
 ## [1.20.5] - 2026-02-01 🔥 HOTFIX
 
 ### Fixed

package/README.md

@@ -279,6 +279,17 @@ Structure your work with Requirements → Design → Tasks workflow
 - **Cross-Platform**: Consistent path handling across Windows/Linux/macOS
 - **Smart Exclusions**: Automatically skip common non-repository directories (node_modules, build, etc.)
 
+### Spec-Level Collaboration 🚀 NEW in v1.22.0
+- **Parallel Development**: Enable multiple AI instances to work on different Specs simultaneously
+- **Dependency Management**: Define and track dependencies between Specs with circular dependency detection
+- **Interface Contracts**: Formal API definitions ensuring compatibility between independently developed Specs
+- **Status Tracking**: Monitor progress and assignments across all Specs in real-time
+- **Integration Testing**: Run cross-Spec integration tests to verify modules work together
+- **Dependency Visualization**: View dependency graphs with critical path highlighting
+- **Backward Compatible**: Opt-in system that doesn't affect existing single-Spec workflows
+
+[Learn more about Spec-Level Collaboration →](docs/spec-collaboration-guide.md)
+
 ### DevOps Integration Foundation 🚀
 - **Operations Spec Management**: Standardized operations documentation (deployment, monitoring, troubleshooting, etc.)
 - **Progressive AI Autonomy**: L1-L5 takeover levels for gradual AI operations control
@@ -348,6 +359,14 @@ kse repo init [--nested]           # Initialize repository configuration (nested
 kse repo init --no-nested          # Initialize without nested repository scanning
 kse repo status [--verbose]        # Show status of all repositories (including nested)
 kse repo exec "<command>"          # Execute command in all repositories
+
+# Spec-level collaboration (NEW in v1.22.0)
+kse collab init <master> [options] # Initialize Master Spec with Sub-Specs
+kse collab status [spec] [--graph] # Display collaboration status
+kse collab assign <spec> <kiro>    # Assign Spec to Kiro instance
+kse collab verify <spec>           # Verify interface contracts
+kse collab integrate <specs...>    # Run integration tests
+kse collab migrate <spec>          # Convert standalone Spec to collaborative
 kse repo health                    # Check repository health
 
 # DevOps operations

package/bin/kiro-spec-engine.js

@@ -13,6 +13,7 @@ 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 registerCollabCommands = require('../lib/commands/collab');
 const VersionChecker = require('../lib/version/version-checker');
 
 const i18n = getI18n();
@@ -551,6 +552,9 @@ repoCmd
     await repoCommand.healthRepo(options);
   });
 
+// Spec-level collaboration commands
+registerCollabCommands(program);
+
 // Template management commands
 const templatesCommand = require('../lib/commands/templates');
 

package/docs/multi-repo-management-guide.md

@@ -193,6 +193,260 @@ Paths can be specified as:
   "path": "packages/frontend"   // Unix/Mac
   ```
 
+## Manual Configuration
+
+### Overview
+
+Starting with v1.21.0, you can manually create and edit the `.kiro/project-repos.json` configuration file without relying solely on `kse repo init`. This is useful for:
+
+- Curating a specific list of repositories
+- Removing false positives from auto-scan
+- Adding repositories that weren't auto-detected
+- Creating configurations for repositories that don't exist yet
+
+### Minimal Configuration Format
+
+The simplest valid configuration requires only `name` and `path` for each repository:
+
+```json
+{
+  "repositories": [
+    {
+      "name": "my-repo",
+      "path": "./my-repo"
+    },
+    {
+      "name": "another-repo",
+      "path": "./another-repo"
+    }
+  ]
+}
+```
+
+**Key points:**
+- The `version` field is optional (defaults to "1.0")
+- Only `name` and `path` are required for each repository
+- All other fields (`remote`, `defaultBranch`, `description`, `tags`, `group`) are optional
+
+### Complete Configuration Example
+
+For more detailed configurations, you can include all optional fields:
+
+```json
+{
+  "version": "1.0",
+  "repositories": [
+    {
+      "name": "frontend",
+      "path": "./packages/frontend",
+      "remote": "https://github.com/user/frontend.git",
+      "defaultBranch": "main",
+      "description": "React frontend application",
+      "tags": ["ui", "react"],
+      "group": "client"
+    },
+    {
+      "name": "backend",
+      "path": "./packages/backend",
+      "remote": "https://github.com/user/backend.git",
+      "defaultBranch": "develop",
+      "description": "Node.js API server",
+      "tags": ["api", "nodejs"],
+      "group": "server"
+    },
+    {
+      "name": "local-only",
+      "path": "./local-repo"
+    }
+  ],
+  "groups": {
+    "client": {
+      "description": "Client-side applications"
+    },
+    "server": {
+      "description": "Server-side services"
+    }
+  }
+}
+```
+
+### Field Requirements
+
+#### Required Fields
+- **name**: Unique identifier for the repository
+  - Must contain only alphanumeric characters, hyphens, underscores, and dots
+  - Examples: `"frontend"`, `"my-repo"`, `"repo.1"`, `".github"`
+
+- **path**: Path to the repository directory
+  - Can be relative (e.g., `"./my-repo"`) or absolute (e.g., `"/home/user/my-repo"`)
+  - Must point to an existing directory containing a `.git` directory
+  - Cannot point to a Git worktree (`.git` file instead of directory)
+
+#### Optional Fields
+- **remote**: Git remote URL (can be omitted for local-only repositories)
+- **defaultBranch**: Default branch name (e.g., `"main"`, `"develop"`)
+- **description**: Human-readable description
+- **tags**: Array of tags for categorization
+- **group**: Group name for logical organization
+- **parent**: Parent repository path (for nested repositories)
+
+### Validation Rules
+
+When you manually create or edit the configuration, `kse` validates:
+
+1. **File Format**: Must be valid JSON
+2. **Structure**: Must have a `repositories` array
+3. **Required Fields**: Each repository must have `name` and `path`
+4. **Path Existence**: Each path must exist on the filesystem
+5. **Git Repository**: Each path must contain a `.git` directory (not file)
+6. **No Duplicates**: Repository names and paths must be unique
+7. **No Worktrees**: Paths cannot point to Git worktrees
+
+### Creating a Manual Configuration
+
+**Step 1: Create the directory structure**
+
+```bash
+mkdir -p .kiro
+```
+
+**Step 2: Create the configuration file**
+
+Create `.kiro/project-repos.json` with your repositories:
+
+```json
+{
+  "repositories": [
+    {
+      "name": "repo1",
+      "path": "./repo1"
+    },
+    {
+      "name": "repo2",
+      "path": "./repo2"
+    }
+  ]
+}
+```
+
+**Step 3: Verify the configuration**
+
+```bash
+kse repo status
+```
+
+If there are validation errors, `kse` will display clear error messages:
+
+```
+Error: Repository path validation failed
+  - Repository "repo1": path "./repo1" does not exist. Please check the path is correct.
+  - Repository "repo2": path "./repo2" is not a Git repository (no .git directory found). Please ensure this is a Git repository.
+```
+
+### Editing an Existing Configuration
+
+You can manually edit the auto-generated configuration to:
+
+**Remove repositories:**
+```json
+{
+  "repositories": [
+    // Remove unwanted entries from this array
+    {
+      "name": "keep-this",
+      "path": "./keep-this"
+    }
+    // Deleted: { "name": "remove-this", "path": "./remove-this" }
+  ]
+}
+```
+
+**Add new repositories:**
+```json
+{
+  "repositories": [
+    {
+      "name": "existing-repo",
+      "path": "./existing-repo"
+    },
+    {
+      "name": "new-repo",
+      "path": "./new-repo"
+    }
+  ]
+}
+```
+
+**Simplify to minimal format:**
+```json
+{
+  "repositories": [
+    {
+      "name": "repo1",
+      "path": "./repo1"
+      // Removed: remote, defaultBranch, description, tags, group
+    }
+  ]
+}
+```
+
+### Troubleshooting
+
+#### Error: "path does not exist"
+
+**Cause**: The specified path doesn't exist on the filesystem.
+
+**Solution**: Check the path is correct and the directory exists:
+```bash
+ls -la ./my-repo  # Unix/Mac
+dir .\my-repo     # Windows
+```
+
+#### Error: "is not a Git repository"
+
+**Cause**: The path exists but doesn't contain a `.git` directory.
+
+**Solution**: Initialize the directory as a Git repository:
+```bash
+cd ./my-repo
+git init
+```
+
+#### Error: "appears to be a Git worktree"
+
+**Cause**: The path contains a `.git` file instead of a directory (Git worktree).
+
+**Solution**: Use the main repository path instead of the worktree path:
+```json
+{
+  "name": "my-repo",
+  "path": "./main-repo"  // Use main repo, not worktree
+}
+```
+
+#### Error: "Duplicate repository name"
+
+**Cause**: Two repositories have the same name.
+
+**Solution**: Ensure each repository has a unique name:
+```json
+{
+  "repositories": [
+    { "name": "repo1", "path": "./path1" },
+    { "name": "repo2", "path": "./path2" }  // Changed from "repo1"
+  ]
+}
+```
+
+#### Error: "Configuration file contains invalid JSON"
+
+**Cause**: The JSON syntax is incorrect (missing comma, bracket, etc.).
+
+**Solution**: Validate your JSON using a JSON validator or IDE:
+- Check for missing commas between array elements
+- Ensure all brackets and braces are properly closed
+- Use a JSON formatter to identify syntax errors
+
 ## Nested Repository Support
 
 ### Overview