@leanspec/ui 0.2.7-dev.20251128020042 → 0.2.8

package/.next/standalone/packages/ui/dist/standalone/specs/063-migration-from-existing-tools/DESIGN.md

@@ -0,0 +1,338 @@
+# Design: Migration Command
+
+Technical design for `lean-spec migrate` command.
+
+## Command Interface
+
+```bash
+# Show generic migration instructions
+lean-spec migrate <input-path>
+lean-spec migrate ./docs/adr/
+lean-spec migrate ./docs/rfcs/
+lean-spec migrate ./specs/linear-export/
+
+# AI-assisted migration (AI figures out the format)
+lean-spec migrate <input-path> --with copilot
+lean-spec migrate <input-path> --with claude
+lean-spec migrate <input-path> --with gemini
+
+# Options
+lean-spec migrate <input-path> --dry-run          # Preview without changes
+lean-spec migrate <input-path> --batch-size 10    # Process N docs at a time
+lean-spec migrate <input-path> --skip-validation  # Don't validate after
+lean-spec migrate <input-path> --backfill         # Auto-run backfill after migration
+
+# After migration: Backfill metadata from git history
+lean-spec backfill                # Timestamps only
+lean-spec backfill --assignee     # Include assignee from git author
+lean-spec backfill --all          # All available metadata
+lean-spec backfill --dry-run      # Preview what would be backfilled
+```
+
+## Supported Sources
+
+**Primary Sources** (mainstream SDD tools):
+
+1. **[OpenSpec](https://github.com/Fission-AI/OpenSpec)**
+   - **Source path**: `openspec/specs/` (current state) + `openspec/changes/archive/` (completed changes)
+   - **Folder structure**: Separate directories for specs and changes
+   - **Migration challenge**: Merge specs + completed changes into single `specs/` directory
+   - **File organization**: Each capability in separate folder with spec.md
+
+2. **[GitHub spec-kit](https://github.com/github/spec-kit)**
+   - **Source path**: `.specify/specs/` (note the dot-prefix!)
+   - **Folder structure**: `###-feature-name/` (numbered features)
+   - **Migration challenge**: Already numbered, but has multiple files per feature (spec.md, plan.md, tasks.md, etc.)
+   - **File organization**: Multi-file per feature, consolidate or preserve as sub-specs
+
+3. **Document Collections** - Various folder-based specs
+   - **Source path**: Varies (e.g., `docs/adr/`, `rfcs/`, etc.)
+   - **Folder structure**: Varies widely (ADR: `docs/adr/####-title.md`, RFC: `rfcs/0042-name.md`)
+   - **Migration challenge**: Flat folders → structured `specs/###-name/` hierarchy
+   - **File organization**: Single files → folder-based organization
+
+**External Systems** (cautious approach):
+- **Linear, Jira, Confluence, Notion**: Support **exported documents only**
+- **Rationale**: API integration requires authentication, API keys, rate limiting, and ongoing maintenance
+- **Migration path**: Export to markdown/JSON, then migrate those files
+- **No direct API integration**: Keeps tool simple, secure, and maintenance-free
+
+**Key Migration Tasks:**
+1. **Frontmatter generation** (PRIMARY CHALLENGE): Use `lean-spec backfill` to extract:
+   - `status` - from git history or document content
+   - `priority` - infer from labels/tags or set default
+   - `tags` - extract from existing metadata or directory structure
+   - `created_at`, `updated_at`, `completed_at` - from git commits
+   - `assignee` - from git author with `--assignee` flag
+2. **Folder reorganization** (VARIES BY SOURCE):
+   - **spec-kit**: Already compatible! Keep `specs/###-name/` as-is
+   - **OpenSpec**: Merge `openspec/specs/` + `openspec/changes/archive/` → `specs/###-name/`
+   - **ADR/RFC**: Flat files → folder hierarchy with renumbering
+3. **Content preservation**: Keep as-is (LeanSpec doesn't enforce format)
+4. **System prompts**: Optionally migrate AGENTS.md, .cursorrules for AI continuity
+
+## Migration Modes
+
+### Mode 1: Instruction-Based (Default)
+
+Outputs generic migration prompt for user to copy to any AI tool:
+
+```markdown
+# LeanSpec Migration Instructions
+
+## Source Location
+./docs/adr/ (23 documents found)
+
+## Migration Prompt
+Copy this prompt to your AI assistant (Copilot, Claude, ChatGPT, etc.):
+
+---
+
+You are helping migrate specification documents to LeanSpec format.
+
+**Source:** ./docs/adr/
+
+**Your Task:**
+1. Analyze the source documents to understand their format and structure
+2. For each document, extract:
+   - Title/name
+   - Status (map to: planned, in-progress, complete, archived)
+   - Creation date
+   - Priority (if present)
+   - Main content sections
+   - Relationships to other documents
+
+3. Migrate each document by running these commands:
+   
+   # Create spec
+   lean-spec create <name>
+   
+   # Set metadata (NEVER edit frontmatter manually)
+   lean-spec update <name> --status <status>
+   lean-spec update <name> --priority <priority>
+   lean-spec update <name> --tags <tag1,tag2>
+   
+   # Edit content with your preferred tool
+   # Map original sections to LeanSpec structure:
+   # - Overview: Problem statement and context
+   # - Design: Technical approach and decisions
+   # - Plan: Implementation steps (if applicable)
+   # - Test: Validation criteria (if applicable)
+   # - Notes: Additional context, trade-offs, alternatives
+
+4. After migration, run:
+   
+   lean-spec validate  # Check for issues
+   lean-spec board     # Verify migration
+
+**Important Rules:**
+- Preserve decision rationale and context
+- Map status appropriately to LeanSpec states
+- Link related specs using `related` field (manual frontmatter edit)
+- Follow LeanSpec first principles: clarity over completeness
+- Keep specs under 400 lines (split if needed)
+
+---
+```
+
+### Mode 2: AI-Assisted Automation
+
+When `--with <provider>` specified, fully automated:
+
+**Pre-flight Checks:**
+```typescript
+interface AIToolCheck {
+  provider: 'copilot' | 'claude' | 'gemini';
+  cliCommand: string;
+  installed: boolean;
+  version?: string;
+  compatible: boolean;
+}
+
+async function verifyAITool(provider: string): Promise<AIToolCheck> {
+  const tools = {
+    copilot: 'github-copilot-cli',
+    claude: 'claude',
+    gemini: 'gemini-cli'
+  };
+  
+  const command = tools[provider];
+  const installed = await checkInstalled(command);
+  
+  if (!installed) {
+    throw new Error(
+      `${provider} CLI not found. Install: npm install -g ${command}`
+    );
+  }
+  
+  const version = await getVersion(command);
+  const compatible = checkCompatibility(version);
+  
+  return { provider, cliCommand: command, installed, version, compatible };
+}
+```
+
+**Migration Execution:**
+```typescript
+interface MigrationConfig {
+  inputPath: string;
+  aiProvider: 'copilot' | 'claude' | 'gemini';
+  dryRun?: boolean;
+  batchSize?: number;
+}
+
+async function migrateWithAI(config: MigrationConfig) {
+  // 1. Verify AI tool
+  const aiTool = await verifyAITool(config.aiProvider);
+  
+  // 2. Scan source documents (format-agnostic)
+  const docs = await scanDocuments(config.inputPath);
+  
+  // 3. Generate generic migration prompt
+  const batches = chunk(docs, config.batchSize || 10);
+  
+  for (const batch of batches) {
+    const prompt = generateMigrationPrompt(batch);
+    
+    // 4. Execute via AI CLI
+    await executeAICLI(aiTool.cliCommand, prompt);
+  }
+  
+  // 5. Validate results
+  await runValidation();
+  
+  // 6. Generate migration report
+  return generateReport();
+}
+
+function generateMigrationPrompt(docs: string[]): string {
+  return `
+Migrate these documents to LeanSpec format.
+
+SOURCE DOCUMENTS:
+${docs.map(d => d.content).join('\n---\n')}
+
+TASK:
+1. Analyze document format and structure
+2. Extract metadata (title, status, dates, priority)
+3. For each document, execute:
+   - lean-spec create <name>
+   - lean-spec update <name> --status <status>
+   - lean-spec update <name> --priority <priority>
+   - lean-spec update <name> --tags <tags>
+   - Edit content to match LeanSpec structure
+
+4. Preserve decision rationale and relationships
+5. Keep specs under 400 lines
+
+Execute migration commands now.
+  `;
+}
+```
+
+## AI Provider Integration
+
+**AI CLI Tool Registry:**
+```typescript
+interface AICliTool {
+  name: 'copilot' | 'claude' | 'gemini';
+  cliCommand: string;
+  installCmd: string;
+  versionCmd: string;
+  minVersion: string;
+  executePattern: (prompt: string) => string;
+}
+
+const AI_CLI_TOOLS: Record<string, AICliTool> = {
+  copilot: {
+    name: 'copilot',
+    cliCommand: 'github-copilot-cli',
+    installCmd: 'npm install -g @githubnext/github-copilot-cli',
+    versionCmd: 'github-copilot-cli --version',
+    minVersion: '0.1.0',
+    executePattern: (prompt) => `echo "${prompt}" | github-copilot-cli --execute`
+  },
+  claude: {
+    name: 'claude',
+    cliCommand: 'claude',
+    installCmd: 'pip install claude-cli',
+    versionCmd: 'claude --version',
+    minVersion: '1.0.0',
+    executePattern: (prompt) => `claude --prompt "${prompt}" --execute`
+  },
+  gemini: {
+    name: 'gemini',
+    cliCommand: 'gemini-cli',
+    installCmd: 'npm install -g @google/gemini-cli',
+    versionCmd: 'gemini-cli --version',
+    minVersion: '1.0.0',
+    executePattern: (prompt) => `gemini-cli --prompt "${prompt}" --auto`
+  }
+};
+```
+
+**Pre-flight Verification:**
+```typescript
+async function verifyAndExecute(provider: string, inputPath: string) {
+  const tool = AI_CLI_TOOLS[provider];
+  
+  // 1. Check if installed
+  const installed = await commandExists(tool.cliCommand);
+  if (!installed) {
+    console.error(`❌ ${tool.name} CLI not found`);
+    console.error(`   Install: ${tool.installCmd}`);
+    process.exit(1);
+  }
+  
+  // 2. Check version
+  const version = await getVersion(tool.versionCmd);
+  if (!satisfiesVersion(version, tool.minVersion)) {
+    console.error(`❌ ${tool.name} version ${version} too old`);
+    console.error(`   Required: >=${tool.minVersion}`);
+    process.exit(1);
+  }
+  
+  console.log(`✓ ${tool.name} CLI verified (v${version})`);
+  
+  // 3. Execute migration
+  await executeMigration(tool, inputPath);
+}
+```
+
+## Error Handling
+
+**Common Error Scenarios:**
+
+```bash
+# AI CLI not found
+$ lean-spec migrate ./docs/adr --with copilot
+❌ copilot CLI not found
+   Install: npm install -g @githubnext/github-copilot-cli
+   Or run without --with flag for manual instructions
+
+# AI CLI outdated
+$ lean-spec migrate ./docs/adr --with claude
+❌ claude version 0.5.0 too old
+   Required: >=1.0.0
+   Update: pip install --upgrade claude-cli
+
+# No documents found
+$ lean-spec migrate ./docs/empty --with gemini
+❌ No documents found in ./docs/empty
+   Check path and try again
+```
+
+**Error Handling Strategy:**
+- **Dry run first**: Preview changes before applying
+- **Validation**: Run `lean-spec validate` after migration
+- **Rollback**: Keep source docs unchanged
+- **Conflict resolution**: Detect duplicate names/IDs, prompt user
+- **Partial migration**: Continue on errors, report summary
+
+## Migration Examples
+
+See [EXAMPLES.md](./EXAMPLES.md) for detailed folder reorganization examples showing:
+- Source folder structure from each tool
+- Target LeanSpec folder structure
+- AI commands to reorganize files
+- What stays the same (content) vs what changes (organization)

package/.next/standalone/packages/ui/dist/standalone/specs/063-migration-from-existing-tools/EXAMPLES.md

@@ -0,0 +1,354 @@
+# Migration Examples: Metadata & Folder Organization
+
+The key migration challenges vary by source tool:
+1. **Metadata/Frontmatter** (ALL sources) - Use `lean-spec backfill`
+2. **Folder organization** (OpenSpec, ADR) - Reorganize into `specs/###-name/`
+3. **spec-kit** - Already compatible! Just needs frontmatter
+
+---
+
+## Example 1: spec-kit → LeanSpec (Easiest Migration)
+
+### Source Structure (spec-kit)
+
+**Source path**: `.specify/specs/` (not `specs/`!)
+
+```
+.specify/
+└── specs/
+    ├── 001-task-management/
+    │   ├── spec.md               # Feature specification
+    │   ├── plan.md               # Implementation plan
+    │   ├── tasks.md              # Task list
+    │   └── contracts/
+    │       └── api.yml
+    ├── 002-user-authentication/
+    │   ├── spec.md
+    │   └── plan.md
+    └── 003-notifications/
+        └── spec.md
+```
+
+### Target Structure (LeanSpec)
+
+```
+specs/
+├── 001-task-management/      # ✅ Already compatible!
+│   ├── README.md             # Rename: spec.md → README.md
+│   ├── plan.md               # ✅ Keep as-is (sub-spec)
+│   ├── tasks.md              # ✅ Keep as-is (sub-spec)
+│   └── contracts/            # ✅ Keep as-is
+│       └── api.yml
+├── 002-user-authentication/  # ✅ Already compatible!
+│   ├── README.md
+│   └── plan.md
+└── 003-notifications/        # ✅ Already compatible!
+    └── README.md
+```
+
+### Migration Process
+
+**Folder reorganization**: Move from `.specify/specs/` to `specs/` and rename spec.md → README.md
+
+```bash
+# Move and rename in one go
+mv .specify/specs specs/
+find specs -name 'spec.md' -execdir mv {} README.md \;
+```
+
+**Metadata generation** (PRIMARY CHALLENGE): Use `lean-spec backfill`
+
+```bash
+# Generate frontmatter from git history
+lean-spec backfill --assignee --all
+
+# This extracts:
+# - created_at: from first git commit
+# - updated_at: from last git commit
+# - completed_at: from status change to complete
+# - assignee: from git author
+# - status: inferred from git/content (defaults to 'planned')
+# - priority: defaults to 'medium' (can manually adjust after)
+# - tags: extracted from folder name or defaults (can manually adjust after)
+```
+
+**Result**: Each spec now has frontmatter:
+
+```yaml
+---
+status: complete
+created_at: '2024-03-15T10:23:45Z'
+updated_at: '2024-11-08T14:30:12Z'
+completed_at: '2024-03-20T16:45:00Z'
+assignee: Alice Chen
+priority: high
+tags:
+  - product
+  - mvp
+---
+```
+
+**Key Point**: spec-kit already has the right folder structure! Migration is mostly about metadata.
+
+### Source Structure (OpenSpec)
+
+```
+openspec/
+├── specs/              # Current state
+│   ├── auth/spec.md
+│   ├── api-gateway/spec.md
+│   └── user-management/spec.md
+└── changes/archive/    # Completed changes
+    └── 2024-11-15-oauth-integration/
+```
+
+### Target Structure (LeanSpec)
+
+```
+specs/
+├── 001-user-authentication/README.md
+├── 002-api-gateway/README.md
+└── 003-user-management/README.md
+```
+
+### Migration Process
+
+**Folder reorganization**: Merge specs/ + changes/archive/
+
+```bash
+# Copy specs, merge archived changes, renumber, rename spec.md → README.md
+cp -r openspec/specs/* specs/
+mv specs/auth specs/001-user-authentication
+mv specs/api-gateway specs/002-api-gateway
+find specs -name 'spec.md' -execdir mv {} README.md \;
+```
+
+**Metadata**: `lean-spec backfill --assignee --all`
+---
+
+## Example 2: OpenSpec → LeanSpec (Moderate Complexity)
+
+### Source Structure (spec-kit)
+
+```
+specs/
+├── 001-task-management/
+│   ├── spec.md               # Feature specification
+│   ├── plan.md               # Implementation plan
+│   ├── tasks.md              # Task list
+│   ├── research.md           # Technical research
+│   ├── data-model.md         # Data models
+│   └── contracts/            # API contracts
+│       ├── tasks-api.yml
+│       └── projects-api.yml
+├── 002-user-authentication/
+│   ├── spec.md
+│   ├── plan.md
+│   └── tasks.md
+└── 003-notifications/
+    ├── spec.md
+    └── plan.md
+```
+
+### Target Structure (LeanSpec)
+
+```
+specs/
+├── 001-task-management/
+│   ├── README.md             # Main spec (from spec.md)
+│   ├── IMPLEMENTATION.md     # Optional: from plan.md + tasks.md
+│   ├── DESIGN.md             # Optional: from data-model.md
+│   └── contracts/            # Preserved as-is
+│       ├── tasks-api.yml
+│       └── projects-api.yml
+├── 002-user-authentication/
+│   ├── README.md
+│   └── IMPLEMENTATION.md
+└── 003-notifications/
+    └── README.md
+```
+
+### Migration Process
+
+**AI Analysis:**
+- spec-kit already uses sequential numbering—preserve it
+- Multiple files per feature—decide: merge or keep as sub-specs
+- Contracts folder—preserve structure
+- Already has feature branches—extract metadata
+
+**AI Execution:**
+
+```bash
+# Option 1: Keep sub-specs (complex features)
+lean-spec create task-management
+# AI copies spec.md → README.md
+# AI copies plan.md + tasks.md → IMPLEMENTATION.md (merged)
+# AI copies data-model.md → DESIGN.md
+# AI preserves contracts/ folder
+lean-spec update task-management --status complete --tags product,mvp
+
+# Option 2: Single file (simple features)
+lean-spec create user-authentication
+# AI merges spec.md + plan.md into single README.md
+lean-spec update user-authentication --status complete --tags auth,security
+
+# Option 3: Minimal (very simple features)
+lean-spec create notifications
+# AI copies spec.md → README.md only
+lean-spec update notifications --status in-progress --tags product
+```
+
+**Key Points:**
+- Numbering preserved (001 → 001)
+- Multi-file decision: merge vs sub-specs depends on complexity
+- Content stays mostly intact
+- Frontmatter added for metadata
+
+---
+
+## Example 3: ADR Collection → LeanSpec
+
+### Source Structure (ADR)
+
+### Source Structure (ADR)
+
+```
+docs/
+└── adr/
+    ├── 0001-use-microservices.md
+    ├── 0042-event-sourcing-audit.md
+    ├── 0105-graphql-api.md
+    └── 0203-kubernetes-deployment.md
+```
+
+### Target Structure (LeanSpec)
+
+```
+specs/
+├── 001-use-microservices/
+│   └── README.md
+├── 002-event-sourcing-audit/
+│   └── README.md
+├── 003-graphql-api/
+│   └── README.md
+└── 004-kubernetes-deployment/
+    └── README.md
+```
+
+### Migration Process
+
+**Folder reorganization**: Flat → hierarchy with renumbering
+
+```bash
+# Create folder for each ADR, renumber sequentially
+mkdir -p specs/001-use-microservices
+mv docs/adr/0001-use-microservices.md specs/001-use-microservices/README.md
+
+mkdir -p specs/002-event-sourcing-audit
+mv docs/adr/0042-event-sourcing-audit.md specs/002-event-sourcing-audit/README.md
+# ... repeat for all ADRs
+```
+
+**Metadata**: `lean-spec backfill --assignee --all`
+
+---
+
+## Summary: Migration Complexity by Source
+
+### spec-kit (Easiest) ✅
+- **Folder structure**: Already compatible! Just rename spec.md → README.md
+- **Challenge**: Metadata/frontmatter only
+- **Solution**: `lean-spec backfill`
+- **Time**: < 5 minutes for 20 specs
+
+### OpenSpec (Moderate) ⚠️
+- **Folder structure**: Merge specs/ + changes/archive/ directories
+- **Challenge**: Folder merge + metadata
+- **Solution**: Manual merge + `lean-spec backfill`
+- **Time**: 15-30 minutes for 20 specs
+
+### ADR/RFC (Complex) 🔴
+- **Folder structure**: Flat files → folder hierarchy
+- **Challenge**: Complete reorganization + metadata
+- **Solution**: Reorganize + `lean-spec backfill`
+- **Time**: 30-60 minutes for 20 specs
+
+---
+
+## Real Migration Work: Metadata Is the Challenge
+
+### What Actually Needs Migration
+
+1. **Frontmatter (ALL sources - PRIMARY CHALLENGE)**:
+   - Extract timestamps from git: `lean-spec backfill`
+   - Infer status from content/history
+   - Set priority (defaults to 'medium')
+   - Extract/create tags
+   - Get assignee from git author
+
+2. **Folder structure (OpenSpec, ADR only)**:
+   - OpenSpec: Merge two directories
+   - ADR: Flat → hierarchy
+   - spec-kit: Already compatible!
+
+3. **Content (NEVER changes)**:
+   - LeanSpec is flexible about content format
+   - Keep existing writing style
+   - No format conversion needed
+
+### The `lean-spec backfill` Command
+
+This is the key tool for migration:
+
+```bash
+# Basic: Extract timestamps from git history
+lean-spec backfill
+
+# With assignee from git author
+lean-spec backfill --assignee
+
+# Full metadata extraction
+lean-spec backfill --all
+
+# Preview before applying
+lean-spec backfill --dry-run
+```
+
+**What it extracts from git**:
+- `created_at` - First commit timestamp
+- `updated_at` - Last commit timestamp
+- `completed_at` - When status changed to 'complete'
+- `assignee` - First commit author (with `--assignee`)
+- `transitions` - Full status change history (with `--transitions`)
+
+**What you set manually after**:
+- `priority` - Defaults to 'medium', adjust with `lean-spec update --priority`
+- `tags` - Defaults from folder names, adjust with `lean-spec update --tags`
+- `status` - Inferred from content/history, adjust if needed
+
+See [spec 047-git-backfill-timestamps](../047-git-backfill-timestamps/) for complete `backfill` documentation.
+
+---
+
+## System Prompts: AGENTS.md Migration
+
+Don't forget to migrate AI guidance files:
+
+```
+# Source tools often have:
+openspec/AGENTS.md
+.cursorrules
+.github/copilot-instructions.md
+
+# LeanSpec uses:
+AGENTS.md (in project root)
+```
+
+**Migration strategy**:
+1. Review existing AI guidance from source tool
+2. Preserve project-specific conventions
+3. Merge with LeanSpec AGENTS.md template
+4. Update commands (openspec → lean-spec)
+5. Keep team workflows intact
+
+This ensures AI agents maintain continuity during transition.