kiro-spec-engine 1.2.3 → 1.4.0

package/docs/spec-workflow.md

@@ -0,0 +1,453 @@
+# Spec Workflow Guide
+
+> Understanding the Spec-driven development workflow in kse
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23  
+**Audience**: Intermediate  
+**Estimated Time**: 10 minutes
+
+---
+
+## Overview
+
+A **Spec** (specification) is the fundamental unit of work in kse. It's a structured description of a feature or component that guides both human developers and AI assistants through the implementation process.
+
+Every Spec follows a three-stage workflow: **Requirements → Design → Tasks**
+
+---
+
+## The Spec Creation Workflow
+
+```mermaid
+graph LR
+    A[Idea/Feature Request] --> B[Requirements]
+    B --> C[Design]
+    C --> D[Tasks]
+    D --> E[Implementation]
+    E --> F[Completion]
+    F --> G[Archive/Document]
+```
+
+### Stage Descriptions
+
+1. **Idea/Feature Request** - The initial concept or need
+2. **Requirements** - What you're building and why (user stories, acceptance criteria)
+3. **Design** - How you'll build it (architecture, APIs, components)
+4. **Tasks** - Step-by-step implementation plan
+5. **Implementation** - Actual coding (often AI-assisted)
+6. **Completion** - All tasks done, feature working
+7. **Archive/Document** - Spec serves as documentation
+
+---
+
+## Stage 1: Requirements
+
+**Purpose:** Define WHAT you're building and WHY
+
+**File:** `requirements.md`
+
+**Key Components:**
+- **Overview** - Brief description of the feature
+- **User Stories** - "As a... I want... So that..."
+- **Functional Requirements** - Specific capabilities the system must have
+- **Acceptance Criteria** - "WHEN... THEN..." statements
+- **Non-Functional Requirements** - Performance, security, usability
+
+**Example Structure:**
+
+```markdown
+# Feature Name
+
+## Overview
+Brief description of what this feature does
+
+## User Stories
+- As a [user type], I want to [action], so that [benefit]
+
+## Functional Requirements
+### FR-1: Requirement Name
+Description of what the system must do
+
+## Acceptance Criteria
+- WHEN [condition] THEN [expected result]
+
+## Non-Functional Requirements
+- Performance: Response time < 500ms
+- Security: Data encrypted at rest
+```
+
+**Best Practices:**
+- ✅ Write from user perspective
+- ✅ Be specific and measurable
+- ✅ Include edge cases
+- ✅ Consider security and performance
+- ❌ Don't include implementation details (that's for Design)
+
+---
+
+## Stage 2: Design
+
+**Purpose:** Define HOW you'll build it
+
+**File:** `design.md`
+
+**Key Components:**
+- **Architecture Overview** - High-level system structure
+- **Component Design** - Individual components and their responsibilities
+- **API Design** - Endpoints, request/response formats
+- **Data Models** - Database schemas, data structures
+- **Technology Stack** - Languages, frameworks, libraries
+- **Requirements Traceability** - Map requirements to design components
+
+**Example Structure:**
+
+```markdown
+# Feature Name - Design
+
+## Architecture
+
+```mermaid
+graph TD
+    A[Component A] --> B[Component B]
+    B --> C[Database]
+```
+
+## API Design
+### POST /api/endpoint
+Request: { ... }
+Response: { ... }
+
+## Component Design
+### ComponentName
+**Responsibility:** What it does
+**Methods:**
+- method1() - Description
+- method2() - Description
+
+## Data Models
+```javascript
+{
+  field1: type,
+  field2: type
+}
+```
+
+## Technology Stack
+- Backend: Node.js + Express
+- Database: PostgreSQL
+
+## Requirements Traceability
+| Requirement | Design Component |
+|-------------|------------------|
+| FR-1 | ComponentA.method1() |
+```
+
+**Best Practices:**
+- ✅ Use diagrams to visualize architecture
+- ✅ Define clear component responsibilities
+- ✅ Specify all APIs and data formats
+- ✅ Link back to requirements
+- ❌ Don't skip the traceability section
+
+---
+
+## Stage 3: Tasks
+
+**Purpose:** Break down implementation into actionable steps
+
+**File:** `tasks.md`
+
+**Key Components:**
+- **Task List** - Checkbox list of implementation steps
+- **Task Hierarchy** - Organized by phase or component
+- **Task IDs** - Numbered for easy reference (1.1, 1.2, 2.1, etc.)
+- **Dependencies** - Implicit through ordering
+
+**Example Structure:**
+
+```markdown
+# Feature Name - Tasks
+
+## Phase 1: Setup
+- [ ] 1.1 Set up project structure
+- [ ] 1.2 Install dependencies
+- [ ] 1.3 Configure environment
+
+## Phase 2: Core Implementation
+- [ ] 2.1 Implement ComponentA
+  - [ ] 2.1.1 Create class structure
+  - [ ] 2.1.2 Implement method1()
+  - [ ] 2.1.3 Write unit tests
+- [ ] 2.2 Implement ComponentB
+
+## Phase 3: Integration
+- [ ] 3.1 Connect components
+- [ ] 3.2 Integration testing
+- [ ] 3.3 End-to-end testing
+
+## Phase 4: Documentation
+- [ ] 4.1 API documentation
+- [ ] 4.2 User guide
+```
+
+**Best Practices:**
+- ✅ Break large tasks into subtasks
+- ✅ Order tasks logically (dependencies first)
+- ✅ Include testing tasks
+- ✅ Be specific enough for AI to understand
+- ❌ Don't make tasks too granular (not every line of code)
+
+---
+
+## The Complete Workflow in Action
+
+### Example: User Login Feature
+
+**1. Create the Spec:**
+```bash
+kse create-spec 01-00-user-login
+```
+
+**2. Write Requirements** (`.kiro/specs/01-00-user-login/requirements.md`):
+```markdown
+# User Login
+
+## User Stories
+- As a user, I want to log in with email and password
+
+## Acceptance Criteria
+- WHEN user enters valid credentials THEN they are logged in
+- WHEN user enters invalid credentials THEN they see an error
+```
+
+**3. Write Design** (`.kiro/specs/01-00-user-login/design.md`):
+```markdown
+# User Login - Design
+
+## API Design
+POST /api/auth/login
+Request: { email, password }
+Response: { token } or { error }
+
+## Components
+- AuthController - handles login requests
+- AuthService - validates credentials
+- UserRepository - database access
+```
+
+**4. Write Tasks** (`.kiro/specs/01-00-user-login/tasks.md`):
+```markdown
+- [ ] 1.1 Create AuthController
+- [ ] 1.2 Create AuthService
+- [ ] 1.3 Create UserRepository
+- [ ] 1.4 Implement login endpoint
+- [ ] 1.5 Write tests
+```
+
+**5. Export Context:**
+```bash
+kse context export 01-00-user-login
+```
+
+**6. Implement with AI:**
+- Provide context to your AI tool
+- AI implements tasks based on your Spec
+- Update task checkboxes as you complete them
+
+**7. Track Progress:**
+```bash
+kse status
+```
+
+---
+
+## Workflow Variations
+
+### Iterative Refinement
+
+You don't have to complete all three stages before starting implementation:
+
+```mermaid
+graph TD
+    A[Write Basic Requirements] --> B[Write Basic Design]
+    B --> C[Write First Tasks]
+    C --> D[Implement First Tasks]
+    D --> E{Need More Detail?}
+    E -->|Yes| F[Refine Requirements/Design]
+    F --> C
+    E -->|No| G[Continue Implementation]
+```
+
+**When to use:**
+- Exploring new features
+- Prototyping
+- Learning new technologies
+
+### Waterfall Approach
+
+Complete each stage fully before moving to the next:
+
+```mermaid
+graph TD
+    A[Complete Requirements] --> B[Review Requirements]
+    B --> C[Complete Design]
+    C --> D[Review Design]
+    D --> E[Complete Tasks]
+    E --> F[Begin Implementation]
+```
+
+**When to use:**
+- Well-understood features
+- Critical systems
+- Team collaboration (clear handoffs)
+
+---
+
+## Integration with AI Tools
+
+### Context Export Workflow
+
+```mermaid
+sequenceDiagram
+    participant Dev as Developer
+    participant kse as kse
+    participant AI as AI Tool
+    
+    Dev->>kse: Create Spec (requirements, design, tasks)
+    Dev->>kse: kse context export spec-name
+    kse->>Dev: context-export.md
+    Dev->>AI: Provide context
+    AI->>Dev: Generate code
+    Dev->>kse: Update task status
+    Dev->>kse: kse status (check progress)
+```
+
+### Automated Workflow (Windsurf/Cline)
+
+```mermaid
+sequenceDiagram
+    participant Dev as Developer
+    participant AI as AI Tool
+    participant kse as kse
+    
+    Dev->>AI: "Implement user login feature"
+    AI->>kse: kse context export 01-00-user-login
+    kse->>AI: Return context
+    AI->>AI: Generate code
+    AI->>kse: kse task claim 01-00-user-login 1.1
+    AI->>Dev: Code generated, task claimed
+```
+
+---
+
+## Best Practices
+
+### Requirements Stage
+1. **Start with user stories** - Understand the user's perspective
+2. **Use EARS format** for acceptance criteria (WHEN... THEN...)
+3. **Include non-functional requirements** - Don't forget performance, security
+4. **Think about edge cases** - What could go wrong?
+
+### Design Stage
+1. **Visualize with diagrams** - A picture is worth a thousand words
+2. **Define clear interfaces** - APIs, method signatures, data formats
+3. **Maintain traceability** - Link every design decision to a requirement
+4. **Choose appropriate technologies** - Document your tech stack
+
+### Tasks Stage
+1. **Break down logically** - Group related tasks into phases
+2. **Order by dependencies** - What needs to be done first?
+3. **Include testing** - Every feature needs tests
+4. **Be AI-friendly** - Tasks should be clear enough for AI to implement
+
+### Throughout
+1. **Keep it updated** - Specs are living documents
+2. **Use version control** - Commit Spec changes
+3. **Review regularly** - Ensure Spec matches implementation
+4. **Archive completed Specs** - They become documentation
+
+---
+
+## Common Pitfalls
+
+### ❌ Too Vague
+**Bad:**
+```markdown
+- [ ] Make login work
+```
+
+**Good:**
+```markdown
+- [ ] 1.1 Implement AuthController.login() method
+  - Accept email and password
+  - Validate inputs
+  - Return JWT token on success
+  - Return error message on failure
+```
+
+### ❌ Too Detailed
+**Bad:**
+```markdown
+- [ ] 1.1 Create variable named 'email'
+- [ ] 1.2 Create variable named 'password'
+- [ ] 1.3 Write if statement to check email
+```
+
+**Good:**
+```markdown
+- [ ] 1.1 Implement input validation
+  - Validate email format
+  - Validate password length
+  - Return validation errors
+```
+
+### ❌ Missing Traceability
+**Bad:** Design with no connection to requirements
+
+**Good:** Design with clear traceability table:
+```markdown
+| Requirement | Design Component |
+|-------------|------------------|
+| FR-1: User can log in | AuthController.login() |
+| FR-2: Validate inputs | ValidationService |
+```
+
+---
+
+## Related Documentation
+
+- **[Quick Start Guide](quick-start.md)** - Get started with your first Spec
+- **[Integration Modes](integration-modes.md)** - How to use Specs with AI tools
+- **[Command Reference](command-reference.md)** - All kse commands
+- **[Examples](examples/)** - Complete example Specs
+
+---
+
+## Summary
+
+The Spec workflow is:
+1. **Requirements** - Define WHAT and WHY
+2. **Design** - Define HOW
+3. **Tasks** - Define STEPS
+4. **Implementation** - Build it (with AI assistance)
+5. **Completion** - Verify and document
+
+**Key Benefits:**
+- ✅ Clear structure for features
+- ✅ Better AI assistance (AI understands your intent)
+- ✅ Built-in documentation
+- ✅ Progress tracking
+- ✅ Team collaboration
+
+**Start your next Spec:** 🚀
+```bash
+kse create-spec 02-00-your-feature
+```
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23

package/docs/steering-strategy-guide.md

@@ -0,0 +1,196 @@
+# Steering Strategy Guide
+
+## Overview
+
+When adopting kiro-spec-engine (kse) into a project that already has steering files in `.kiro/steering/`, you must choose a steering strategy. This is because Kiro IDE loads all files in the steering directory, and having both kse steering rules and your project's custom steering rules can cause conflicts.
+
+## Why Steering Exclusivity?
+
+Kiro IDE automatically loads all Markdown files in `.kiro/steering/` as AI behavior rules. If you have both kse steering files and your project's custom steering files, the AI will try to follow both sets of rules, which can lead to:
+
+- Conflicting instructions
+- Unpredictable AI behavior
+- Confusion about which rules take precedence
+
+Therefore, you must choose **one** set of steering rules to use.
+
+## Steering Strategies
+
+### Strategy 1: Use kse Steering (Recommended for New Users)
+
+**When to choose:**
+- You're new to kse and want to use the recommended steering rules
+- You don't have critical custom steering rules
+- You want the full kse experience with optimized AI behavior
+
+**What happens:**
+1. Your existing steering files are backed up to `.kiro/backups/steering-{timestamp}/`
+2. kse steering template files are installed to `.kiro/steering/`
+3. The backup ID is saved in `.kiro/adoption-config.json`
+4. You can rollback if needed
+
+**Files installed:**
+- `CORE_PRINCIPLES.md` - Core development principles and Spec workflow
+- `ENVIRONMENT.md` - Project environment configuration
+- `CURRENT_CONTEXT.md` - Current Spec context (updated per Spec)
+- `RULES_GUIDE.md` - Index of steering rules
+
+### Strategy 2: Use Project Steering (Keep Existing)
+
+**When to choose:**
+- You have custom steering rules that are critical to your project
+- You want to integrate kse without changing your AI behavior rules
+- You're experienced with steering files and want full control
+
+**What happens:**
+1. Your existing steering files are preserved
+2. kse steering files are **not** installed
+3. The choice is documented in `.kiro/adoption-config.json`
+4. You can manually integrate kse steering concepts if desired
+
+**Trade-offs:**
+- You won't get kse's optimized AI behavior out of the box
+- You'll need to manually add kse-specific steering rules if needed
+- Spec workflow may not work as smoothly without kse steering
+
+## Adoption Flow
+
+```
+kse adopt
+    ↓
+Detect existing steering files
+    ↓
+    ├─ No steering files → Install kse steering (default)
+    │
+    └─ Steering files found → Prompt for strategy
+           ↓
+           ├─ use-kse → Backup existing → Install kse steering
+           │
+           └─ use-project → Keep existing → Skip kse steering
+```
+
+## Rollback
+
+If you chose "use-kse" and want to restore your original steering files:
+
+```bash
+# List available backups
+kse rollback --list
+
+# Restore from backup
+kse rollback {backup-id}
+```
+
+Or manually restore from `.kiro/backups/steering-{timestamp}/`.
+
+## Manual Integration
+
+If you chose "use-project" but want to incorporate kse steering concepts:
+
+1. Review kse steering templates in `template/.kiro/steering/`
+2. Identify useful concepts (Spec workflow, Ultrawork principles, etc.)
+3. Manually merge relevant sections into your steering files
+4. Test with a sample Spec to ensure compatibility
+
+## Configuration File
+
+Your steering strategy choice is saved in `.kiro/adoption-config.json`:
+
+```json
+{
+  "version": "1.0.0",
+  "adoptedAt": "2026-01-23T10:00:00.000Z",
+  "steeringStrategy": "use-kse",
+  "steeringBackupId": "steering-2026-01-23T10-00-00-000Z",
+  "multiUserMode": false,
+  "lastUpdated": "2026-01-23T10:00:00.000Z"
+}
+```
+
+## Best Practices
+
+### For New kse Users
+
+1. **Choose "use-kse"** to get the full experience
+2. Review the installed steering files to understand kse workflow
+3. Customize `ENVIRONMENT.md` for your project specifics
+4. Update `CURRENT_CONTEXT.md` as you work on different Specs
+
+### For Experienced Users
+
+1. **Choose "use-project"** if you have mature steering rules
+2. Review kse steering templates for useful patterns
+3. Consider creating a hybrid approach:
+   - Keep your core steering rules
+   - Add kse-specific rules in separate files
+   - Use file naming to control load order (e.g., `00-core.md`, `10-kse.md`)
+
+### For Teams
+
+1. **Discuss strategy** with your team before adoption
+2. **Document the choice** in your project README
+3. **Version control** your steering files (if using custom rules)
+4. **Share backups** if team members need to rollback
+
+## Troubleshooting
+
+### Problem: AI behavior is inconsistent after adoption
+
+**Solution:**
+- Check which steering strategy you chose: `cat .kiro/adoption-config.json`
+- If "use-kse", verify kse steering files are present
+- If "use-project", ensure your steering files are compatible with kse
+
+### Problem: Want to switch strategies after adoption
+
+**Solution:**
+1. If currently "use-kse":
+   ```bash
+   kse rollback {steering-backup-id}
+   ```
+
+2. If currently "use-project":
+   - Manually backup your steering files
+   - Copy kse templates from `template/.kiro/steering/`
+   - Update `.kiro/adoption-config.json`
+
+### Problem: Lost steering backup
+
+**Solution:**
+- Check `.kiro/backups/` for steering backups
+- Backups are named `steering-{timestamp}`
+- If no backup exists, you'll need to recreate your steering files
+
+## FAQ
+
+**Q: Can I use both kse and project steering files?**
+
+A: No, due to Kiro IDE's behavior. You must choose one set of rules.
+
+**Q: Will my Specs work without kse steering?**
+
+A: Yes, but the AI may not follow kse workflow conventions as closely.
+
+**Q: Can I modify kse steering files after installation?**
+
+A: Yes! kse steering files are templates. Customize them for your project.
+
+**Q: What if I don't have any steering files?**
+
+A: kse will automatically install its steering files (no choice needed).
+
+**Q: Can I switch strategies later?**
+
+A: Yes, but you'll need to manually manage the steering files and update the config.
+
+## Related Documentation
+
+- [Adoption Guide](./adoption-guide.md) - Complete adoption workflow
+- [Spec Workflow Guide](../.kiro/specs/SPEC_WORKFLOW_GUIDE.md) - How to use Specs
+- [Steering Files](../.kiro/steering/) - kse steering templates
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23  
+**Spec**: 03-00-multi-user-and-cross-tool-support