kiro-spec-engine 1.2.3 → 1.3.0

package/docs/manual-workflows-guide.md

@@ -0,0 +1,417 @@
+# Manual Workflows Guide
+
+> Complete guide for manual workflows when automation is not available
+
+---
+
+## Overview
+
+This guide provides step-by-step instructions for common workflows when using kiro-spec-engine without automation (watch mode or agent hooks). These workflows are designed to be efficient and easy to follow.
+
+**When to use manual workflows:**
+- When automation is not set up
+- When working in environments without watch mode support
+- When you prefer manual control over automation
+- For one-off tasks or testing
+
+---
+
+## Table of Contents
+
+1. [Task Sync Workflow](#task-sync-workflow)
+2. [Context Export Workflow](#context-export-workflow)
+3. [Prompt Generation Workflow](#prompt-generation-workflow)
+4. [Workflow Checklists](#workflow-checklists)
+
+---
+
+## Task Sync Workflow
+
+### Purpose
+Keep your workspace synchronized with task progress across multiple users or tools.
+
+### Time Estimate
+- Initial sync: 2-3 minutes
+- Subsequent syncs: 30-60 seconds
+
+### Prerequisites
+- Project adopted with kiro-spec-engine
+- Active spec with tasks.md file
+- Write access to .kiro/specs/ directory
+
+### Step-by-Step Instructions
+
+#### 1. Check Current Status
+```bash
+kse status
+```
+
+**What to look for:**
+- Current spec name
+- Number of tasks (total, completed, in progress)
+- Last sync timestamp
+
+**Time:** ~5 seconds
+
+---
+
+#### 2. Review Task Changes
+Open your spec's `tasks.md` file and review:
+- Tasks you've completed (mark with `[x]`)
+- Tasks you're working on (mark with `[-]`)
+- Tasks you've queued (mark with `[~]`)
+
+**Example:**
+```markdown
+- [x] 1.1 Completed task
+- [-] 1.2 In progress task
+- [~] 1.3 Queued task
+- [ ] 1.4 Not started task
+```
+
+**Time:** ~30-60 seconds
+
+---
+
+#### 3. Sync Workspace
+```bash
+kse workspace sync
+```
+
+**What this does:**
+- Updates workspace metadata
+- Synchronizes task status
+- Detects conflicts
+- Updates timestamps
+
+**Time:** ~10-15 seconds
+
+---
+
+#### 4. Verify Sync
+```bash
+kse status
+```
+
+**Verify:**
+- Task counts are updated
+- Sync timestamp is current
+- No conflicts reported
+
+**Time:** ~5 seconds
+
+---
+
+### Best Practices
+
+1. **Sync Frequency**
+   - Before starting work: Always sync first
+   - After completing tasks: Sync immediately
+   - During long sessions: Sync every 30-60 minutes
+
+2. **Conflict Resolution**
+   - If conflicts detected, review both versions
+   - Keep the most recent accurate state
+   - Document resolution in commit message
+
+3. **Team Coordination**
+   - Communicate task claims in team chat
+   - Use task claiming feature: `kse task claim <spec> <task-id>`
+   - Check for claimed tasks before starting work
+
+---
+
+## Context Export Workflow
+
+### Purpose
+Export spec context for sharing with AI assistants or team members.
+
+### Time Estimate
+- Single spec export: 15-30 seconds
+- With steering rules: 30-45 seconds
+
+### Prerequisites
+- Active spec with requirements, design, and tasks
+- Optional: Steering rules configured
+
+### Step-by-Step Instructions
+
+#### 1. Identify Spec to Export
+```bash
+kse status
+```
+
+Note the spec name you want to export.
+
+**Time:** ~5 seconds
+
+---
+
+#### 2. Export Context
+```bash
+kse context export <spec-name>
+```
+
+**Options:**
+- `--include-steering`: Include steering rules
+- `--steering-files <files>`: Specific steering files (comma-separated)
+- `--output <path>`: Custom output path
+
+**Example:**
+```bash
+kse context export my-feature --include-steering --steering-files CORE_PRINCIPLES.md,ENVIRONMENT.md
+```
+
+**Time:** ~10-20 seconds
+
+---
+
+#### 3. Locate Export File
+The export is saved to:
+```
+.kiro/specs/<spec-name>/context-export.md
+```
+
+**Time:** ~5 seconds
+
+---
+
+#### 4. Use Exported Context
+- Copy content to AI assistant
+- Share with team members
+- Use as documentation reference
+- Include in project handoff
+
+**Time:** Varies by use case
+
+---
+
+### Best Practices
+
+1. **When to Export**
+   - Before starting a new task
+   - When asking for AI assistance
+   - For project documentation
+   - During team handoffs
+
+2. **What to Include**
+   - Always: requirements, design, tasks
+   - Usually: core steering rules
+   - Sometimes: environment-specific rules
+   - Rarely: all steering rules (too verbose)
+
+3. **Export Management**
+   - Exports are regenerated each time
+   - Old exports are overwritten
+   - Consider versioning important exports
+   - Clean up old exports periodically
+
+---
+
+## Prompt Generation Workflow
+
+### Purpose
+Generate AI prompts for specific tasks with relevant context.
+
+### Time Estimate
+- Single task prompt: 20-30 seconds
+- Batch generation: 1-2 minutes per 10 tasks
+
+### Prerequisites
+- Active spec with tasks
+- Task IDs identified
+- Requirements and design documents complete
+
+### Step-by-Step Instructions
+
+#### 1. Identify Task
+Review tasks.md and note the task ID:
+```bash
+cat .kiro/specs/<spec-name>/tasks.md
+```
+
+**Example task ID:** `1.2` or `3.1.1`
+
+**Time:** ~10-15 seconds
+
+---
+
+#### 2. Generate Prompt
+```bash
+kse prompt generate <spec-name> <task-id>
+```
+
+**Options:**
+- `--target <tool>`: Target tool (kiro, vscode, cursor, other)
+- `--output <path>`: Custom output path
+
+**Example:**
+```bash
+kse prompt generate my-feature 1.2 --target vscode
+```
+
+**Time:** ~10-15 seconds
+
+---
+
+#### 3. Locate Generated Prompt
+The prompt is saved to:
+```
+.kiro/specs/<spec-name>/prompts/task-<task-id>.md
+```
+
+**Time:** ~5 seconds
+
+---
+
+#### 4. Use Generated Prompt
+- Copy to AI assistant
+- Review for accuracy
+- Customize if needed
+- Execute task based on prompt
+
+**Time:** Varies by task complexity
+
+---
+
+### Batch Operations
+
+For multiple tasks:
+
+```bash
+# Generate prompts for all incomplete tasks
+for task in 1.1 1.2 1.3; do
+  kse prompt generate my-feature $task
+done
+```
+
+**Time:** ~20-30 seconds per task
+
+---
+
+### Best Practices
+
+1. **Prompt Quality**
+   - Review generated prompts before use
+   - Customize for specific context
+   - Add tool-specific instructions
+   - Include relevant examples
+
+2. **Prompt Organization**
+   - Keep prompts in spec directory
+   - Use consistent naming
+   - Version control prompts
+   - Clean up after task completion
+
+3. **Optimization Tips**
+   - Generate prompts in batches
+   - Reuse prompts for similar tasks
+   - Template common patterns
+   - Document customizations
+
+---
+
+## Workflow Checklists
+
+### Daily Workflow Checklist
+
+**Morning (Start of Work)**
+- [ ] Sync workspace: `kse workspace sync`
+- [ ] Check status: `kse status`
+- [ ] Review task list
+- [ ] Claim tasks you'll work on
+- [ ] Export context for active tasks
+
+**During Work**
+- [ ] Update task status as you progress
+- [ ] Sync every 30-60 minutes
+- [ ] Export context when asking for help
+- [ ] Generate prompts for new tasks
+
+**End of Day**
+- [ ] Mark completed tasks
+- [ ] Update in-progress tasks
+- [ ] Final sync: `kse workspace sync`
+- [ ] Commit changes to version control
+
+---
+
+### Task Completion Checklist
+
+- [ ] Review task requirements
+- [ ] Generate task prompt
+- [ ] Export context if needed
+- [ ] Complete implementation
+- [ ] Run tests
+- [ ] Update task status to completed
+- [ ] Sync workspace
+- [ ] Commit changes
+
+---
+
+### Spec Creation Checklist
+
+- [ ] Create spec: `kse create-spec <name>`
+- [ ] Write requirements.md
+- [ ] Write design.md
+- [ ] Generate tasks.md
+- [ ] Export initial context
+- [ ] Generate prompts for first tasks
+- [ ] Sync workspace
+- [ ] Begin implementation
+
+---
+
+## Time Estimates Summary
+
+| Workflow | Time Estimate |
+|----------|---------------|
+| Task Sync | 30-60 seconds |
+| Context Export | 15-45 seconds |
+| Prompt Generation | 20-30 seconds |
+| Daily Sync Routine | 2-3 minutes |
+| Full Spec Setup | 10-15 minutes |
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue: Sync conflicts**
+- **Solution:** Review both versions, keep most recent
+- **Prevention:** Sync more frequently
+
+**Issue: Export fails**
+- **Solution:** Check spec exists, files are readable
+- **Prevention:** Verify spec structure before export
+
+**Issue: Prompt generation incomplete**
+- **Solution:** Ensure requirements and design are complete
+- **Prevention:** Complete docs before generating prompts
+
+---
+
+## Next Steps
+
+1. **Set Up Automation:** Consider using watch mode for automatic workflows
+   ```bash
+   kse watch init
+   kse watch install auto-sync
+   ```
+
+2. **Learn More:**
+   - [Watch Mode Guide](./watch-mode-guide.md)
+   - [Cross-Tool Guide](./cross-tool-guide.md)
+   - [Architecture](./architecture.md)
+
+3. **Get Help:**
+   - Run `kse --help` for command reference
+   - Check [GitHub Issues](https://github.com/heguangyong/kiro-spec-engine/issues)
+   - Review [Contributing Guide](../CONTRIBUTING.md)
+
+---
+
+**Version:** 1.0  
+**Last Updated:** 2026-01-23  
+**Spec:** 05-00-agent-hooks-and-automation

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

package/lib/adoption/detection-engine.js

@@ -11,6 +11,7 @@ const {
   listFiles,
   readJSON
 } = require('../utils/fs-utils');
+const SteeringManager = require('../steering/steering-manager');
 
 class DetectionEngine {
   constructor() {
@@ -19,6 +20,7 @@ class DetectionEngine {
     this.specsDir = 'specs';
     this.steeringDir = 'steering';
     this.toolsDir = 'tools';
+    this.steeringManager = new SteeringManager();
   }
 
   /**
@@ -37,6 +39,7 @@ class DetectionEngine {
       let hasSteering = false;
       let hasTools = false;
       let existingVersion = null;
+      let steeringDetection = null;
       
       if (hasKiroDir) {
         // Check for version.json
@@ -57,9 +60,9 @@ class DetectionEngine {
         const specsPath = path.join(kiroPath, this.specsDir);
         hasSpecs = await pathExists(specsPath);
         
-        // Check for steering/
-        const steeringPath = path.join(kiroPath, this.steeringDir);
-        hasSteering = await pathExists(steeringPath);
+        // Check for steering/ using SteeringManager
+        steeringDetection = await this.steeringManager.detectSteering(projectPath);
+        hasSteering = steeringDetection.hasExistingSteering;
         
         // Check for tools/
         const toolsPath = path.join(kiroPath, this.toolsDir);
@@ -80,7 +83,8 @@ class DetectionEngine {
         hasTools,
         projectType,
         existingVersion,
-        conflicts
+        conflicts,
+        steeringDetection // Add steering detection details
       };
     } catch (error) {
       throw new Error(`Failed to analyze project: ${error.message}`);
@@ -225,6 +229,12 @@ class DetectionEngine {
       }
       lines.push(`  specs/: ${result.hasSpecs ? 'Yes' : 'No'}`);
       lines.push(`  steering/: ${result.hasSteering ? 'Yes' : 'No'}`);
+      
+      // Show steering details if available
+      if (result.steeringDetection && result.steeringDetection.hasExistingSteering) {
+        lines.push(`    Files: ${result.steeringDetection.count} file(s)`);
+      }
+      
       lines.push(`  tools/: ${result.hasTools ? 'Yes' : 'No'}`);
       
       if (result.conflicts.length > 0) {