Migrate from .kiro to spec-kit

[s-celles]

Hello,

Kiro IDE users who want to migrate to spec-kit currently face a manual, error-prone process of restructuring their specification files. This creates friction for teams considering the transition from Kiro's IDE to spec-kit's open, multi-AI approach.

📋 Current Kiro Structure

Kiro projects use a .kiro/ directory with the following structure:

.kiro/
├── specs/
│   └── [feature-name]/
│       ├── requirements.md    # User stories with EARS notation
│       ├── design.md          # Technical architecture, interfaces, sequence diagrams
│       └── tasks.md           # Implementation tasks with statuses [TODO]/[IN_PROGRESS]/[DONE]
├── steering/
│   ├── product.md            # Business context, product vision, goals
│   ├── structure.md          # Codebase architecture, folder organization
│   └── tech.md               # Tech stack, patterns, coding conventions
├── hooks/                     # Event-driven automations (on-save, pre-commit, etc.)
└── memory/                    # Historical decisions, context

Key characteristics:

• EARS (Easy Approach to Requirements Syntax) notation: Requirements use "WHEN [condition] THE SYSTEM SHALL [action]" format
• Mermaid diagrams: Design files contain sequence/architecture diagrams
• Task tracking: Tasks use checkbox-style statuses with requirement traceability
• Steering context: Project-wide guidance similar to spec-kit's constitution

💡 Proposed Solution

Add a specify import command to migrate Kiro projects:

specify import --from kiro --source /path/to/kiro-project

Mapping Strategy:

Kiro Location	spec-kit Location	Notes
.kiro/specs/[feature]/requirements.md	.specify/specs/[feature]/spec.md	Keep EARS notation intact
.kiro/specs/[feature]/design.md	.specify/specs/[feature]/plan.md	Preserve Mermaid diagrams
.kiro/specs/[feature]/tasks.md	.specify/specs/[feature]/tasks.md	Convert [TODO] → task format
.kiro/steering/	.specify/memory/constitution.md	Merge product.md + tech.md + structure.md
.kiro/memory/	.specify/memory/	Preserve historical context
.kiro/hooks/	.specify/scripts/	Convert to spec-kit script format

🔄 Import Process

# 1. Detect Kiro project
specify import --from kiro

# Interactive prompts:
# → Found .kiro directory with 3 features
# → Merge steering files into constitution? [Y/n]
# → Convert task statuses? [Y/n]
# → Preserve hooks as scripts? [Y/n]

# 2. Generate mapping report
specify import --from kiro --dry-run

# Output:
# ✓ 3 features detected
# ✓ 15 requirements (EARS notation preserved)
# ✓ 8 design documents (Mermaid diagrams intact)
# ✓ 42 tasks (25 completed, 17 pending)
# ⚠ 2 hooks require manual review
# 
# Continue? [Y/n]

# 3. Execute import
specify import --from kiro --execute

# Post-import validation
specify check

✨ Benefits

1. Lower migration barrier: Teams can try spec-kit without losing existing work
2. Multi-AI flexibility: Continue specs with Claude Code, Cursor, Copilot, etc.
3. Preserve EARS methodology: Maintain structured requirement practices
4. Git history intact: Import preserves existing version control
5. Gradual transition: Can import individual features incrementally

🧪 Example Use Case

# Current Kiro project
kiro-project/
├── .kiro/
│   ├── specs/
│   │   ├── 001-user-auth/
│   │   │   ├── requirements.md  # 12 EARS requirements
│   │   │   ├── design.md        # Architecture + 3 Mermaid diagrams
│   │   │   └── tasks.md         # 8 tasks (5 done, 3 pending)
│   │   └── 002-payment-system/
│   │       └── ...
│   └── steering/
│       ├── product.md           # Company context
│       └── tech.md              # FastAPI + React stack

# After import
specify import --from kiro

# Result
kiro-project/
├── .kiro/                       # Preserved for reference
└── .specify/
    ├── memory/
    │   └── constitution.md      # Merged from steering/
    ├── specs/
    │   ├── 001-user-auth/
    │   │   ├── spec.md          # Preserved EARS format
    │   │   ├── plan.md          # Preserved Mermaid diagrams
    │   │   └── tasks.md         # Converted task statuses
    │   └── 002-payment-system/
    │       └── ...
    └── scripts/
        └── [converted-hooks]/

# Continue with any AI assistant
specify check
# → ✓ Project ready for Claude Code, Cursor, Copilot, etc.

🔍 Implementation Considerations

File Format Compatibility

• EARS notation: Already compatible, preserve as-is
• Mermaid diagrams: Standard markdown, direct copy
• Task statuses: Map [TODO] → unchecked, [DONE] → checked
• Metadata: Extract feature IDs, timestamps

Edge Cases

• Multiple features with same name → append suffix
• Conflicting steering files → merge with markers
• Custom hook scripts → preserve with manual review flag
• Binary assets → copy to appropriate location

Validation

• Verify all requirements have valid EARS syntax
• Check Mermaid diagram rendering
• Validate task dependency chains
• Ensure constitution merge is coherent

📚 Documentation Needs

If implemented, would need:

• Migration guide: .kiro → .specify
• Comparison table: Kiro vs spec-kit concepts
• Troubleshooting: Common migration issues
• Video walkthrough: Import process demo

🎁 Additional Value

This feature would also benefit:

• Kiro users evaluating alternatives
• Teams wanting multi-AI flexibility
• Open-source adoption of spec-driven development
• Enterprise users avoiding vendor lock-in

🤝 Community Impact

From discussions in spec-driven development communities, there's significant interest in tool-agnostic workflows. This import feature could:

• Accelerate spec-kit adoption
• Validate spec-driven methodology across tools
• Establish spec-kit as migration-friendly
• Build bridges between SDD communities

💬 Alternative Approaches

If full import is complex, consider:

1. Manual migration guide: Step-by-step documentation
2. Conversion script: Community-maintained tool
3. Gradual import: Start with single feature support
4. Template matching: Map common Kiro patterns

📊 Success Metrics

• Number of successful migrations
• Time saved vs manual conversion
• Feature parity preservation rate
• User satisfaction scores

---

🛠️ Implementation Checklist (if accepted)

• Design CLI interface for specify import
• Create file mapping logic
• Implement EARS preservation
• Handle Mermaid diagram migration
• Build steering → constitution merger
• Add dry-run validation
• Write migration documentation
• Create test fixtures from sample Kiro projects
• Add error handling and rollback
• Generate migration report

---

🙋 Contribution Offer

I'd be happy to:

• Contribute to the migration documentation
• Share feedback from the migration experience

[PIMBA]

Any progress ?