kiro-sync

Kiro Specification Sync

Synchronize specifications with AWS Kiro IDE format.

Kiro File Structure

AWS Kiro uses a specific file structure:

.kiro/
├── steering/
│   ├── requirements.md    # Project-wide requirements
│   ├── design.md          # Overall design
│   └── tasks.md           # Current tasks
├── specs/
│   └── {feature-name}/
│       ├── requirements.md
│       ├── design.md
│       └── tasks.md
└── kiro.json              # Configuration

Sync Directions

Direction	Description
import	Kiro → Canonical (read from Kiro)
export	Canonical → Kiro (write to Kiro)
bidirectional	Two-way sync with conflict detection

Workflow

1. Detect Structure

   • Check for existing .kiro/ directory
   • Identify canonical specifications
   • Determine sync direction

2. Execute Sync

   • Spawn spec-converter kiro agent
   • Compare content hashes
   • Identify changes

3. Handle Conflicts

   • If bidirectional and both changed:
     • Flag conflicts
     • Present diff
     • Prompt for resolution

4. Apply Changes

   • Write updated files
   • Preserve formatting
   • Update timestamps

5. Report

   • Show sync summary
   • List changes made
   • Note any conflicts

Arguments

• $1 - Specification file or .kiro/ directory
• --direction - Sync direction: import, export, bidirectional (default)
• --force - Overwrite without conflict check
• --dry-run - Show what would change without writing

Examples

# Export canonical to Kiro
/spec-driven-development:kiro-sync .specs/auth/spec.md --direction export

# Import from Kiro
/spec-driven-development:kiro-sync .kiro/specs/auth/ --direction import

# Bidirectional sync
/spec-driven-development:kiro-sync .specs/auth/spec.md

# Dry run to see changes
/spec-driven-development:kiro-sync .specs/auth/spec.md --dry-run

Mapping: Canonical ↔ Kiro

requirements.md

Canonical	Kiro
Problem Statement	Context
Scope	Context/Scope
FR-X	REQ-X
NFR-X	REQ-NX
AC-X.Y	AC-X.Y

design.md

Canonical	Kiro
Design Overview	Overview
Components	Components
Data Model	Data Model
API Design	API Design

tasks.md

Canonical	Kiro
Task List	Task List
TASK-X	TASK-X
Dependencies	Dependency graph

EARS Compatibility

Kiro uses EARS syntax natively, so requirements pass through unchanged:

Canonical:

## FR-1: User Login

WHEN the user submits valid credentials,
the system SHALL authenticate the user.

Kiro (requirements.md):

### REQ-1: User Login

WHEN the user submits valid credentials,
the system SHALL authenticate the user.

Only the ID prefix changes (FR-X → REQ-X).

Sync Report

# Kiro Sync Report

**Direction:** Bidirectional
**Timestamp:** 2024-01-15T10:30:00Z

## Summary

| Type | Added | Updated | Unchanged | Conflicts |
| --- | --- | --- | --- | --- |
| Requirements | 1 | 2 | 5 | 0 |
| Design | 0 | 1 | 0 | 0 |
| Tasks | 3 | 0 | 2 | 0 |

## Changes

### Added
- REQ-8 (new requirement in canonical)

### Updated
- REQ-2: Updated acceptance criteria
- REQ-5: Clarified EARS statement

## Generated Files

- .kiro/specs/auth/requirements.md (updated)
- .kiro/specs/auth/design.md (updated)
- .kiro/specs/auth/tasks.md (created)

Related Commands

• /spec-driven-development:convert - General format conversion
• /spec-driven-development:speckit-run - Full Spec Kit workflow
• /spec-driven-development:specify - Generate specification