/import-external

description: AUTO-EXECUTE import of external work items (GitHub/JIRA/ADO) since last import. NO PROMPTS - immediately runs with defaults. Creates READ-ONLY references in living docs. Options available but NOT required.
disable-model-invocation: true

Import External Work Items (Reference Import)

Import work items from GitHub (issues/milestones), JIRA (epics/stories), or Azure DevOps (work items) into SpecWeave living docs **as read-only references**.

> **Important**: This command creates a **reference catalog**, NOT increments. Imported items have E-suffix IDs (US-001E, FS-042E). To implement an imported item, you must **manually create an increment** that references it.

CRITICAL: Default Behavior (NO PROMPTS!)

**When user runs `sw:import-external` with NO arguments:** 1. **IMMEDIATELY execute** with default settings - DO NOT show menus or ask questions 2. **Default = "since last import"** - auto-detects from `.specweave/sync-metadata.json` 3. **If first import ever** - defaults to last 1 month 4. **Import from ALL configured platforms** (GitHub, JIRA, ADO - whichever are configured)

**WRONG behavior** (DO NOT DO THIS):

❌ "What would you like to import?"
❌ "Which option would you like?"
❌ "Should I run a dry run first?"
❌ Showing a menu of options

**CORRECT behavior**:

✅ Immediately start importing
✅ Show progress: "🔄 Importing from GitHub... [25/150]"
✅ Show summary when done

What This Does

1. **Detects configured external tools** (GitHub, JIRA, ADO) from environment/config 2. **Fetches work items** based on time range filter (since last import by default) 3. **Assigns IDs with E suffix and validation**

• IDs have E suffix to indicate external origin (US-001E, T-001E, FS-042E)
• **Validates FS (Feature) IDs** to avoid conflicts:

     import { validateIncrementNumber, logValidationResult } from './src/core/increment-validator.js';

     // Get all existing feature IDs (including E-suffix ones)
     const existingFeatures = [
       ...fs.readdirSync('.specweave/docs/internal/specs/'),
       ...fs.readdirSync('.specweave/increments/').map(parseFeatureId),
     ].filter(f => /^FS-\d{3}E?$/.test(f));

     // For external feature FS-042E, validate base number 042
     const baseNumber = featureId.replace('E', '').replace('FS-', '');
     const result = validateIncrementNumber(baseNumber, existingFeatures);

     // Log warnings if non-sequential
     if (result.warnings.length > 0) {
       console.log('ℹ️  External feature ID validation:');
       logValidationResult(result);
       console.log('   This is normal for external imports (IDs from external system)');
     }

• Note: External IDs may be non-sequential (they come from external systems)
• Validation ensures awareness of gaps, not enforcement

4. **Creates living docs files** in `.specweave/docs/internal/specs/FS-XXXE/` 5. **Updates sync metadata** (`.specweave/sync-metadata.json`) with import timestamp 6. **Skips duplicates** automatically (checks existing external IDs) 7. **Shows progress** indicator and summary report

Usage

sw:import-external [options]

Options (ALL OPTIONAL - defaults work without them)

• `--since=<range>` - Time range filter (default: since last import)
• `last` - Since last import (uses sync metadata) **← DEFAULT**
• `1m`, `3m`, `6m` - Last 1/3/6 months
• `all` - All items (no time filter)
• Custom: `2025-01-01` - Since specific date (ISO format)
• `--github-only` - Import from GitHub only
• `--jira-only` - Import from JIRA only
• `--ado-only` - Import from Azure DevOps only
• `--dry-run` - Preview what would be imported without creating files

Examples

Example 1: Import New Items (Default - NO PROMPTS!)

sw:import-external

# IMMEDIATELY executes with defaults:
# - Since last import (or 1 month if first import)
# - All configured platforms

# Output (NO QUESTIONS ASKED):
# 📥 Import External Work Items
#
# 📋 Import Configuration:
#   Platforms: GITHUB
#   Time range: last
#   Dry run: No
#
# 🔗 Imported from GITHUB: 15 items
#
# 📊 Import Summary:
#    Total imported: 15 items
#    🔗 GITHUB: 15 items
# ✅ Import complete!

Example 2: GitHub Only (Last 3 Months)

sw:import-external --github-only --since=3m

# Imports only from GitHub
# Items created in last 3 months

Example 3: Dry Run (Preview)

sw:import-external --dry-run --since=1m

# Shows what would be imported without creating files
# Useful for checking item counts before actual import

# Result:
# 🔍 Dry run - no files will be created
# 📊 Preview:
#    GitHub: 25 items (5 duplicates skipped)
#    JIRA: 10 items (2 duplicates skipped)
#    Total: 35 new items, 7 existing
# ⚠️  Remove --dry-run to perform actual import

Example 4: JIRA Only (All Items)

sw:import-external --jira-only --since=all

# Imports all JIRA items (no time filter)
# ⚠️  Warning shown if > 100 items detected

Time Range Filters

Since Last Import (Default)

sw:import-external

# Reads last import timestamp from:
# .specweave/sync-metadata.json
# {
#   "github": { "lastImport": "2025-11-15T10:30:00Z" },
#   "jira": { "lastImport": "2025-11-10T14:20:00Z" }
# }
#
# GitHub: imports items created after 2025-11-15T10:30:00Z
# JIRA: imports items created after 2025-11-10T14:20:00Z

Relative Time Ranges

--since=1m   # Last 1 month
--since=3m   # Last 3 months
--since=6m   # Last 6 months

Absolute Date

--since=2025-01-01   # Since January 1, 2025 (ISO format: YYYY-MM-DD)

All Items

--since=all   # Import all items (no time filter)
# ⚠️  Warning: May import hundreds of items

Configured Platforms

The command auto-detects configured platforms from:

GitHub

• **Detection**: `.git/config` remote URL
• **Auth**: `GITHUB_TOKEN` environment variable
• **Format**: `github.com/{owner}/{repo}`

JIRA

• **Detection**: `JIRA_HOST` environmen