scene-capability-engine 3.0.0

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)

package/docs/spec-locking-guide.md

@@ -0,0 +1,225 @@
+# Spec Locking Guide
+
+This guide explains how to use the Spec locking mechanism for multi-user collaboration in kse projects.
+
+## Overview
+
+When multiple developers work on the same project, they may accidentally edit the same Spec simultaneously, leading to conflicts. The Spec locking mechanism prevents this by allowing developers to acquire exclusive locks on Specs before editing.
+
+## Quick Start
+
+```bash
+# Before editing a Spec, acquire a lock
+kse lock acquire my-feature --reason "Implementing user authentication"
+
+# Check who has locks on which Specs
+kse lock status
+
+# When done editing, release the lock
+kse unlock my-feature
+```
+
+## Commands
+
+### Acquire a Lock
+
+```bash
+kse lock acquire <spec-name> [options]
+```
+
+Options:
+- `--reason <reason>` - Document why you're locking the Spec
+- `--timeout <hours>` - Lock timeout in hours (default: 24)
+
+Example:
+```bash
+kse lock acquire 01-00-user-auth --reason "Adding OAuth support" --timeout 48
+```
+
+### Release a Lock
+
+```bash
+kse unlock <spec-name> [options]
+# or
+kse lock release <spec-name> [options]
+```
+
+Options:
+- `--force` - Release lock even if owned by another machine
+
+Example:
+```bash
+kse unlock 01-00-user-auth
+kse unlock 01-00-user-auth --force  # Override someone else's lock
+```
+
+### Check Lock Status
+
+```bash
+# View all locked Specs
+kse lock status
+
+# View specific Spec lock status
+kse lock status <spec-name>
+```
+
+Output includes:
+- Lock owner name
+- Machine hostname
+- Lock duration
+- Stale indicator (if lock exceeded timeout)
+- "you" indicator (if you own the lock)
+
+### Clean Up Stale Locks
+
+```bash
+kse lock cleanup
+```
+
+Removes all locks that have exceeded their timeout period. This is useful when:
+- A developer forgot to release their lock
+- A machine crashed while holding a lock
+- Someone left for vacation with an active lock
+
+### View Machine Identifier
+
+```bash
+kse lock whoami
+```
+
+Shows your machine's unique identifier, which is used to track lock ownership.
+
+## Integration with Status Command
+
+The `kse status` command now shows lock indicators for each Spec:
+
+```
+📁 Specs (5)
+
+  01-00-user-auth 🔒 (you)
+    Tasks: 3/10 completed (30%)
+
+  02-00-api-gateway 🔒 (john)
+    Tasks: 5/8 completed (62%)
+
+  03-00-dashboard
+    Tasks: 8/8 completed (100%)
+```
+
+Lock indicators:
+- 🔒 (you) - You own this lock
+- 🔒 (username) - Another user owns this lock
+- 🔒 [STALE] - Lock has exceeded timeout
+
+## Best Practices
+
+### 1. Always Lock Before Major Edits
+
+```bash
+# Good practice
+kse lock acquire my-feature --reason "Refactoring task structure"
+# ... make your changes ...
+kse unlock my-feature
+```
+
+### 2. Use Meaningful Reasons
+
+```bash
+# Good - explains what you're doing
+kse lock acquire api-spec --reason "Adding pagination to list endpoints"
+
+# Bad - no context
+kse lock acquire api-spec
+```
+
+### 3. Release Locks Promptly
+
+Don't hold locks longer than necessary. Release as soon as you're done editing.
+
+### 4. Check Status Before Starting Work
+
+```bash
+# Check if anyone is working on the Spec
+kse lock status my-feature
+
+# If unlocked, acquire and start working
+kse lock acquire my-feature
+```
+
+### 5. Communicate Before Force Unlocking
+
+If you need to force unlock someone else's lock:
+1. Try to contact them first
+2. Check if the lock is stale
+3. Use `--force` only when necessary
+
+```bash
+# Check if stale
+kse lock status their-spec
+
+# If stale or confirmed with owner
+kse unlock their-spec --force
+```
+
+## Configuration
+
+### Lock Timeout
+
+Default timeout is 24 hours. You can customize per-lock:
+
+```bash
+kse lock acquire my-spec --timeout 48  # 48 hours
+kse lock acquire quick-fix --timeout 2  # 2 hours
+```
+
+### Machine ID Storage
+
+Machine IDs are stored in `.kiro/config/machine-id.json` and are automatically generated on first use.
+
+## Troubleshooting
+
+### "Spec is already locked" Error
+
+Someone else is editing this Spec. Options:
+1. Wait for them to finish
+2. Contact them to coordinate
+3. Use `--force` if the lock is stale or abandoned
+
+### "Lock owned by different machine" Error
+
+You're trying to unlock a Spec locked by another machine. Options:
+1. Use `--force` to override
+2. Contact the lock owner
+
+### Stale Locks Accumulating
+
+Run periodic cleanup:
+```bash
+kse lock cleanup
+```
+
+Consider adding this to your CI/CD pipeline or team workflow.
+
+## File Format
+
+Lock files are stored as `.kiro/specs/<spec-name>/.lock` with JSON format:
+
+```json
+{
+  "owner": "John Doe",
+  "machineId": "DESKTOP-ABC123-uuid-here",
+  "hostname": "DESKTOP-ABC123",
+  "timestamp": "2026-02-05T10:30:00.000Z",
+  "reason": "Implementing feature X",
+  "timeout": 24,
+  "version": "1.0.0"
+}
+```
+
+Lock files are excluded from version control via `.gitignore`.
+
+## See Also
+
+- [Team Collaboration Guide](team-collaboration-guide.md)
+- [Spec Workflow](spec-workflow.md)
+- [Command Reference](command-reference.md)