kiro-spec-engine 1.21.1 → 1.22.0

package/CHANGELOG.md

@@ -7,6 +7,36 @@ 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

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/spec-collaboration-guide.md

@@ -0,0 +1,369 @@
+# Spec-Level Collaboration Guide
+
+## Overview
+
+The Spec-level collaboration system enables multiple AI instances (Kiro) to work on different Specs in parallel within a large project. This guide explains how to use the collaboration features to coordinate parallel development efforts.
+
+## Key Concepts
+
+### Master Spec and Sub-Specs
+
+- **Master Spec**: A high-level Spec that defines the overall feature and breaks it down into multiple Sub-Specs
+- **Sub-Spec**: A child Spec that implements a specific module or component of the Master Spec
+
+### Dependencies
+
+Specs can depend on other Specs in three ways:
+
+- **requires-completion**: The dependent Spec must be fully completed before this Spec can start
+- **requires-interface**: The dependent Spec must have its interface defined (can be in-progress)
+- **optional**: The dependency is optional and doesn't block progress
+
+### Interface Contracts
+
+Interface contracts formally define the APIs, data structures, and behaviors that a Spec provides or consumes. They ensure compatibility between independently developed Specs.
+
+### Kiro Instances
+
+A Kiro instance is an AI assistant working on a specific Spec. You can assign Specs to different instances to enable parallel development.
+
+## Quick Start
+
+### 1. Initialize a Master Spec
+
+Create a Master Spec with Sub-Specs:
+
+```bash
+kse collab init user-management \
+  --sub-specs user-service auth-service session-manager \
+  --dependencies "auth-service:user-service" \
+  --dependencies "session-manager:auth-service"
+```
+
+This creates:
+- A Master Spec called `user-management`
+- Three Sub-Specs: `user-service`, `auth-service`, `session-manager`
+- Dependencies: `auth-service` depends on `user-service`, `session-manager` depends on `auth-service`
+
+### 2. Check Status
+
+View all Specs and their status:
+
+```bash
+kse collab status
+```
+
+View dependency graph:
+
+```bash
+kse collab status --graph
+```
+
+### 3. Assign Specs to Kiro Instances
+
+Assign Specs to different AI instances:
+
+```bash
+kse collab assign user-service kiro-1
+kse collab assign auth-service kiro-2
+kse collab assign session-manager kiro-3
+```
+
+### 4. Define Interface Contracts
+
+Create an interface contract for a Spec (in `.kiro/specs/{spec-name}/interfaces/`):
+
+```json
+{
+  "version": "1.0.0",
+  "spec": "user-service",
+  "interfaces": [
+    {
+      "name": "UserService",
+      "type": "class",
+      "exports": [
+        {
+          "name": "createUser",
+          "type": "function",
+          "signature": "(userData: UserData) => Promise<User>",
+          "required": true
+        },
+        {
+          "name": "getUser",
+          "type": "function",
+          "signature": "(userId: string) => Promise<User>",
+          "required": true
+        }
+      ]
+    }
+  ],
+  "types": [
+    {
+      "name": "UserData",
+      "definition": "{ name: string, email: string }"
+    },
+    {
+      "name": "User",
+      "definition": "{ id: string, name: string, email: string }"
+    }
+  ]
+}
+```
+
+### 5. Verify Contracts
+
+Verify that implementations match contracts:
+
+```bash
+kse collab verify user-service
+```
+
+### 6. Run Integration Tests
+
+Run integration tests across multiple Specs:
+
+```bash
+kse collab integrate user-service auth-service session-manager
+```
+
+## Workflow Example
+
+### Scenario: Building a User Management System
+
+**Step 1: Architect creates Master Spec**
+
+```bash
+kse collab init user-management \
+  --sub-specs database-layer user-service auth-service notification-service \
+  --dependencies "user-service:database-layer" \
+  --dependencies "auth-service:user-service" \
+  --dependencies "notification-service:user-service"
+```
+
+**Step 2: Check which Specs are ready**
+
+```bash
+kse collab status
+```
+
+Output:
+```
+Total Specs: 5
+Ready to Start: 1
+
+✓ user-management (unassigned)
+○ database-layer (unassigned)
+○ user-service (unassigned)
+○ auth-service (unassigned)
+○ notification-service (unassigned)
+
+Ready to start: database-layer
+```
+
+**Step 3: Assign and start development**
+
+```bash
+kse collab assign database-layer kiro-1
+kse collab assign user-service kiro-2
+kse collab assign auth-service kiro-3
+```
+
+**Step 4: Define interfaces**
+
+Each Kiro instance defines the interface contract for their Spec.
+
+**Step 5: Verify and integrate**
+
+```bash
+kse collab verify database-layer
+kse collab verify user-service
+kse collab integrate database-layer user-service
+```
+
+## Commands Reference
+
+### `kse collab init`
+
+Initialize a Master Spec with Sub-Specs.
+
+```bash
+kse collab init <master-spec> [options]
+```
+
+Options:
+- `-s, --sub-specs <specs...>`: Sub-spec names
+- `-d, --dependencies <deps...>`: Dependencies in format "spec:dep1,dep2"
+
+### `kse collab status`
+
+Display collaboration status.
+
+```bash
+kse collab status [spec-name] [options]
+```
+
+Options:
+- `-g, --graph`: Show dependency graph
+- `--critical-path`: Highlight critical path in graph
+
+### `kse collab assign`
+
+Assign a Spec to a Kiro instance.
+
+```bash
+kse collab assign <spec-name> <kiro-instance>
+```
+
+### `kse collab verify`
+
+Verify interface contracts for a Spec.
+
+```bash
+kse collab verify <spec-name>
+```
+
+### `kse collab integrate`
+
+Run integration tests across Specs.
+
+```bash
+kse collab integrate <spec-names...>
+```
+
+### `kse collab migrate`
+
+Convert a standalone Spec to collaborative mode.
+
+```bash
+kse collab migrate <spec-name>
+```
+
+## Best Practices
+
+### 1. Clear Interface Contracts
+
+Define clear, complete interface contracts before starting implementation. This prevents integration issues later.
+
+### 2. Minimal Dependencies
+
+Keep dependencies minimal and well-justified. Too many dependencies create bottlenecks.
+
+### 3. Regular Verification
+
+Run `kse collab verify` frequently to catch interface mismatches early.
+
+### 4. Integration Testing
+
+Write integration tests that span multiple Specs to verify they work together correctly.
+
+### 5. Status Updates
+
+Update Spec status regularly so other Kiro instances know when dependencies are ready.
+
+### 6. Critical Path Awareness
+
+Use `kse collab status --graph --critical-path` to identify bottlenecks and prioritize work.
+
+## Troubleshooting
+
+### Circular Dependency Detected
+
+**Error**: `Circular dependency detected: spec-a → spec-b → spec-c → spec-a`
+
+**Solution**: Remove one of the dependencies to break the cycle. Redesign the architecture if necessary.
+
+### Interface Mismatch
+
+**Error**: `Implementation does not match contract for 'UserService'`
+
+**Solution**: Update either the implementation or the contract to match. Run `kse collab verify` to see specific mismatches.
+
+### Spec Blocked
+
+**Error**: `Cannot assign blocked spec (reason: API key missing)`
+
+**Solution**: Resolve the blocking issue first, then reassign the Spec.
+
+## Advanced Topics
+
+### Hierarchical Structures
+
+You can create nested structures with Sub-Sub-Specs:
+
+```bash
+kse collab init backend-system --sub-specs api-layer business-logic data-layer
+kse collab init api-layer --sub-specs rest-api graphql-api
+```
+
+### Breaking Changes
+
+When you need to make breaking changes to an interface:
+
+1. Version the interface (e.g., `UserServiceV2.json`)
+2. Update consumers to use the new version
+3. Run `kse collab verify` to detect breaking changes
+4. Coordinate with affected Kiro instances
+
+### Custom Integration Tests
+
+Create integration tests in `.kiro/specs/{master-spec}/integration-tests/`:
+
+```javascript
+module.exports = {
+  name: 'User Authentication Flow',
+  specs: ['user-service', 'auth-service'],
+  async setup() {
+    // Setup test environment
+  },
+  async test() {
+    const userService = require('../../user-service/lib/user-service');
+    const authService = require('../../auth-service/lib/auth-service');
+    
+    // Test cross-spec functionality
+    const user = await userService.createUser({ name: 'Test', email: 'test@example.com' });
+    const token = await authService.login(user.email, 'password');
+    assert(token, 'Should receive auth token');
+  },
+  async teardown() {
+    // Cleanup
+  }
+};
+```
+
+## Metadata File Format
+
+Collaboration metadata is stored in `.kiro/specs/{spec-name}/collaboration.json`:
+
+```json
+{
+  "version": "1.0.0",
+  "type": "master" | "sub",
+  "masterSpec": "parent-spec-name",
+  "subSpecs": ["child-1", "child-2"],
+  "dependencies": [
+    {
+      "spec": "other-spec",
+      "type": "requires-completion",
+      "reason": "Needs database schema"
+    }
+  ],
+  "assignment": {
+    "kiroInstance": "kiro-1",
+    "assignedAt": "2026-02-01T10:00:00Z"
+  },
+  "status": {
+    "current": "in-progress",
+    "updatedAt": "2026-02-01T10:00:00Z"
+  },
+  "interfaces": {
+    "provides": ["UserService.json"],
+    "consumes": ["other-spec/interfaces/DatabaseService.json"]
+  }
+}
+```
+
+## See Also
+
+- [Spec Workflow Guide](../README.md)
+- [Multi-Repository Management](multi-repo-management-guide.md)
+- [Environment Management](environment-management-guide.md)