specweave 0.16.7 → 0.16.12

package/dist/plugins/specweave-release/lib/dora-tracker.js

@@ -0,0 +1,279 @@
+/**
+ * DORA Metrics Persistent Tracking
+ *
+ * Stores DORA metrics in append-only JSONL format for historical tracking and trending
+ *
+ * Features:
+ * - Append-only JSONL storage (.specweave/metrics/dora-history.jsonl)
+ * - Trend calculation (7-day, 30-day, 90-day rolling averages)
+ * - Degradation detection (alert if metrics worsen >20%)
+ * - Living docs integration (auto-update dashboard)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+// ============================================================================
+// Constants
+// ============================================================================
+const SPECWEAVE_ROOT = process.cwd();
+const METRICS_DIR = path.join(SPECWEAVE_ROOT, '.specweave', 'metrics');
+const HISTORY_FILE = path.join(METRICS_DIR, 'dora-history.jsonl');
+const DEGRADATION_THRESHOLD = 20; // 20% worsening triggers alert
+// ============================================================================
+// Core Functions
+// ============================================================================
+/**
+ * Append DORA snapshot to history file (JSONL format)
+ *
+ * @param snapshot - DORA metrics snapshot
+ */
+export function appendSnapshot(snapshot) {
+    // Ensure metrics directory exists
+    if (!fs.existsSync(METRICS_DIR)) {
+        fs.mkdirSync(METRICS_DIR, { recursive: true });
+    }
+    // Append as single line (JSONL format)
+    const line = JSON.stringify(snapshot) + '\n';
+    fs.appendFileSync(HISTORY_FILE, line, 'utf-8');
+    console.log(`✓ Appended DORA snapshot to ${HISTORY_FILE}`);
+}
+/**
+ * Read all DORA snapshots from history file
+ *
+ * @returns Array of DORA snapshots (oldest first)
+ */
+export function readHistory() {
+    if (!fs.existsSync(HISTORY_FILE)) {
+        return [];
+    }
+    const content = fs.readFileSync(HISTORY_FILE, 'utf-8');
+    const lines = content.trim().split('\n').filter(line => line.length > 0);
+    return lines.map(line => JSON.parse(line));
+}
+/**
+ * Calculate rolling average for a metric over a time window
+ *
+ * @param snapshots - Historical snapshots (oldest first)
+ * @param metricExtractor - Function to extract metric value from snapshot
+ * @param windowDays - Time window in days (7, 30, 90)
+ * @returns Average value over window, or NaN if insufficient data
+ */
+function calculateRollingAverage(snapshots, metricExtractor, windowDays) {
+    const now = new Date();
+    const windowStart = new Date(now.getTime() - windowDays * 24 * 60 * 60 * 1000);
+    // Filter snapshots within window
+    const windowSnapshots = snapshots.filter(snapshot => {
+        const snapshotDate = new Date(snapshot.timestamp);
+        return snapshotDate >= windowStart && snapshotDate <= now;
+    });
+    if (windowSnapshots.length === 0) {
+        return NaN;
+    }
+    // Calculate average
+    const sum = windowSnapshots.reduce((acc, snapshot) => acc + metricExtractor(snapshot), 0);
+    return sum / windowSnapshots.length;
+}
+/**
+ * Calculate trend data for a specific metric
+ *
+ * @param metricName - Name of metric ('deploymentFrequency', 'leadTime', etc.)
+ * @returns Trend data with current, 7-day, 30-day, 90-day averages and changes
+ */
+export function calculateTrend(metricName) {
+    const snapshots = readHistory();
+    if (snapshots.length === 0) {
+        return null;
+    }
+    // Metric extractor based on metric name
+    const extractors = {
+        deploymentFrequency: (s) => s.deploymentFrequency.value,
+        leadTime: (s) => s.leadTime.value,
+        changeFailureRate: (s) => s.changeFailureRate.value,
+        mttr: (s) => s.mttr.value,
+    };
+    const extractor = extractors[metricName];
+    if (!extractor) {
+        throw new Error(`Unknown metric: ${metricName}`);
+    }
+    // Current value (latest snapshot)
+    const current = extractor(snapshots[snapshots.length - 1]);
+    // Rolling averages
+    const sevenDay = calculateRollingAverage(snapshots, extractor, 7);
+    const thirtyDay = calculateRollingAverage(snapshots, extractor, 30);
+    const ninetyDay = calculateRollingAverage(snapshots, extractor, 90);
+    // Percentage changes (vs rolling averages)
+    const calculateChange = (average) => {
+        if (isNaN(average) || average === 0)
+            return 0;
+        return ((current - average) / average) * 100;
+    };
+    return {
+        current,
+        sevenDay: isNaN(sevenDay) ? current : sevenDay,
+        thirtyDay: isNaN(thirtyDay) ? current : thirtyDay,
+        ninetyDay: isNaN(ninetyDay) ? current : ninetyDay,
+        sevenDayChange: calculateChange(sevenDay),
+        thirtyDayChange: calculateChange(thirtyDay),
+        ninetyDayChange: calculateChange(ninetyDay),
+    };
+}
+/**
+ * Detect metric degradation (>20% worsening)
+ *
+ * @returns Array of degradation alerts (empty if no degradation detected)
+ */
+export function detectDegradation() {
+    const alerts = [];
+    const snapshots = readHistory();
+    if (snapshots.length < 2) {
+        return alerts; // Insufficient data
+    }
+    const latest = snapshots[snapshots.length - 1];
+    const metrics = [
+        'deploymentFrequency',
+        'leadTime',
+        'changeFailureRate',
+        'mttr',
+    ];
+    metrics.forEach(metricName => {
+        const trend = calculateTrend(metricName);
+        if (!trend)
+            return;
+        const { current, thirtyDay, thirtyDayChange } = trend;
+        // For leadTime, changeFailureRate, mttr: LOWER is better (so INCREASE is degradation)
+        // For deploymentFrequency: HIGHER is better (so DECREASE is degradation)
+        let isDegradation = false;
+        let severity = 'warning';
+        if (metricName === 'deploymentFrequency') {
+            // Deployment frequency DECREASE is degradation
+            if (thirtyDayChange < -DEGRADATION_THRESHOLD) {
+                isDegradation = true;
+                severity = thirtyDayChange < -40 ? 'critical' : 'warning';
+            }
+        }
+        else {
+            // Lead time, change failure rate, MTTR INCREASE is degradation
+            if (thirtyDayChange > DEGRADATION_THRESHOLD) {
+                isDegradation = true;
+                severity = thirtyDayChange > 40 ? 'critical' : 'warning';
+            }
+        }
+        if (isDegradation) {
+            alerts.push({
+                metric: metricName,
+                currentValue: current,
+                previousValue: thirtyDay,
+                percentageChange: thirtyDayChange,
+                severity,
+                message: `${metricName} has degraded by ${Math.abs(thirtyDayChange).toFixed(1)}% (30-day average)`,
+            });
+        }
+    });
+    return alerts;
+}
+/**
+ * Get latest DORA snapshot
+ *
+ * @returns Latest snapshot, or null if no history
+ */
+export function getLatestSnapshot() {
+    const snapshots = readHistory();
+    return snapshots.length > 0 ? snapshots[snapshots.length - 1] : null;
+}
+/**
+ * Get snapshot count
+ *
+ * @returns Number of snapshots in history
+ */
+export function getSnapshotCount() {
+    return readHistory().length;
+}
+/**
+ * Clear history (use with caution!)
+ */
+export function clearHistory() {
+    if (fs.existsSync(HISTORY_FILE)) {
+        fs.unlinkSync(HISTORY_FILE);
+        console.log(`✓ Cleared DORA history: ${HISTORY_FILE}`);
+    }
+}
+// ============================================================================
+// CLI Entry Point
+// ============================================================================
+/**
+ * CLI tool for DORA tracking operations
+ *
+ * Usage:
+ *   npm run dora:track append      # Append latest metrics to history
+ *   npm run dora:track trends      # Show trend analysis
+ *   npm run dora:track degradation # Check for degradation
+ */
+async function main() {
+    const command = process.argv[2];
+    switch (command) {
+        case 'append': {
+            // Read latest metrics from dora-latest.json
+            const latestFile = path.join(METRICS_DIR, 'dora-latest.json');
+            if (!fs.existsSync(latestFile)) {
+                console.error('❌ No latest metrics found. Run: npm run metrics:dora');
+                process.exit(1);
+            }
+            const latest = JSON.parse(fs.readFileSync(latestFile, 'utf-8'));
+            appendSnapshot(latest);
+            console.log('✅ Snapshot appended to history');
+            break;
+        }
+        case 'trends': {
+            const metrics = [
+                'deploymentFrequency',
+                'leadTime',
+                'changeFailureRate',
+                'mttr',
+            ];
+            console.log('\n📊 DORA Metrics Trends\n');
+            metrics.forEach(metric => {
+                const trend = calculateTrend(metric);
+                if (!trend) {
+                    console.log(`${metric}: Insufficient data`);
+                    return;
+                }
+                console.log(`\n${metric}:`);
+                console.log(`  Current: ${trend.current}`);
+                console.log(`  7-day avg: ${trend.sevenDay.toFixed(2)} (${trend.sevenDayChange >= 0 ? '+' : ''}${trend.sevenDayChange.toFixed(1)}%)`);
+                console.log(`  30-day avg: ${trend.thirtyDay.toFixed(2)} (${trend.thirtyDayChange >= 0 ? '+' : ''}${trend.thirtyDayChange.toFixed(1)}%)`);
+                console.log(`  90-day avg: ${trend.ninetyDay.toFixed(2)} (${trend.ninetyDayChange >= 0 ? '+' : ''}${trend.ninetyDayChange.toFixed(1)}%)`);
+            });
+            break;
+        }
+        case 'degradation': {
+            const alerts = detectDegradation();
+            if (alerts.length === 0) {
+                console.log('✅ No degradation detected. Metrics are stable or improving.');
+            }
+            else {
+                console.log('⚠️  Degradation Detected:\n');
+                alerts.forEach(alert => {
+                    const icon = alert.severity === 'critical' ? '🔴' : '🟠';
+                    console.log(`${icon} ${alert.message}`);
+                    console.log(`   Previous: ${alert.previousValue.toFixed(2)}`);
+                    console.log(`   Current: ${alert.currentValue.toFixed(2)}`);
+                    console.log(`   Change: ${alert.percentageChange.toFixed(1)}%`);
+                    console.log('');
+                });
+            }
+            break;
+        }
+        case 'count': {
+            const count = getSnapshotCount();
+            console.log(`📊 ${count} snapshots in history`);
+            break;
+        }
+        default:
+            console.log('Usage: npm run dora:track [append|trends|degradation|count]');
+            process.exit(1);
+    }
+}
+// Run CLI if executed directly
+if (require.main === module) {
+    main().catch(console.error);
+}
+//# sourceMappingURL=dora-tracker.js.map

package/dist/plugins/specweave-release/lib/dora-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dora-tracker.js","sourceRoot":"","sources":["../../../../plugins/specweave-release/lib/dora-tracker.ts"],"names":[],"mappings":"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"}

package/dist/project-mapper.js

@@ -0,0 +1,272 @@
+/**
+ * Project Mapper - Intelligent User Story to Project Classification
+ *
+ * Analyzes user story content, tech stack mentions, and component architecture
+ * to intelligently map user stories to the correct projects (FE, BE, MOBILE, etc.)
+ *
+ * @module project-mapper
+ */
+/**
+ * Default project mapping rules
+ * These can be customized via .specweave/config.json
+ */
+export const DEFAULT_PROJECT_RULES = [
+    {
+        id: 'FE',
+        name: 'Frontend (Web)',
+        keywords: [
+            'ui', 'ux', 'web', 'browser', 'chart', 'graph', 'visualization',
+            'dashboard', 'button', 'form', 'input', 'page', 'view', 'screen',
+            'modal', 'dropdown', 'navigation', 'menu', 'search', 'filter',
+            'responsive', 'desktop', 'tablet', 'css', 'styling', 'theme',
+            'dark mode', 'light mode', 'component', 'state management'
+        ],
+        techStack: [
+            'react', 'vue', 'angular', 'next.js', 'gatsby', 'svelte',
+            'typescript', 'javascript', 'html', 'css', 'scss', 'tailwind',
+            'mui', 'material-ui', 'antd', 'chakra', 'redux', 'zustand',
+            'recharts', 'd3', 'chart.js', 'plotly'
+        ],
+        componentTypes: [
+            'component', 'hook', 'context', 'provider', 'hoc', 'page',
+            'layout', 'template', 'widget'
+        ]
+    },
+    {
+        id: 'BE',
+        name: 'Backend (API)',
+        keywords: [
+            'api', 'endpoint', 'rest', 'graphql', 'database', 'query',
+            'migration', 'schema', 'model', 'service', 'controller',
+            'authentication', 'authorization', 'jwt', 'session', 'token',
+            'validation', 'sanitization', 'rate limiting', 'caching',
+            'redis', 'queue', 'job', 'worker', 'webhook', 'integration',
+            'third-party', 'external api', 'data processing', 'batch',
+            'cron', 'scheduler', 'background'
+        ],
+        techStack: [
+            'node.js', 'express', 'fastify', 'nestjs', 'koa',
+            'python', 'fastapi', 'django', 'flask',
+            'java', 'spring boot',
+            '.net', 'asp.net',
+            'go', 'gin',
+            'rust', 'actix',
+            'postgresql', 'mysql', 'mongodb', 'redis',
+            'prisma', 'typeorm', 'sequelize', 'sqlalchemy'
+        ],
+        componentTypes: [
+            'controller', 'service', 'repository', 'middleware',
+            'route', 'handler', 'util', 'helper', 'validator'
+        ]
+    },
+    {
+        id: 'MOBILE',
+        name: 'Mobile (iOS/Android)',
+        keywords: [
+            'mobile', 'ios', 'android', 'app', 'native', 'cross-platform',
+            'push notification', 'offline', 'sync', 'device', 'camera',
+            'gps', 'location', 'gesture', 'touch', 'swipe', 'navigation',
+            'tab bar', 'bottom sheet', 'drawer', 'stack', 'screen transition',
+            'deep linking', 'universal link', 'app store', 'play store'
+        ],
+        techStack: [
+            'react native', 'expo', 'flutter', 'swift', 'swiftui',
+            'kotlin', 'jetpack compose', 'xamarin', 'cordova', 'ionic',
+            'react-navigation', 'react-native-reanimated', 'asyncstorage'
+        ],
+        componentTypes: [
+            'screen', 'navigator', 'modal', 'bottom-sheet', 'drawer'
+        ],
+        excludeKeywords: ['web']
+    },
+    {
+        id: 'INFRA',
+        name: 'Infrastructure',
+        keywords: [
+            'deployment', 'ci/cd', 'docker', 'kubernetes', 'helm',
+            'terraform', 'cloudformation', 'infrastructure', 'devops',
+            'monitoring', 'logging', 'metrics', 'alerting', 'slo', 'sli',
+            'scalability', 'load balancing', 'cdn', 'dns', 'ssl', 'tls',
+            'security', 'firewall', 'vpc', 'network', 'backup', 'disaster recovery'
+        ],
+        techStack: [
+            'aws', 'azure', 'gcp', 'kubernetes', 'docker', 'terraform',
+            'ansible', 'jenkins', 'github actions', 'gitlab ci', 'circleci',
+            'prometheus', 'grafana', 'datadog', 'new relic', 'sentry'
+        ],
+        componentTypes: [
+            'pipeline', 'manifest', 'helm chart', 'terraform module'
+        ]
+    }
+];
+/**
+ * Analyze user story content and map to projects
+ *
+ * @param userStory User story to analyze
+ * @param projectRules Project mapping rules (defaults to DEFAULT_PROJECT_RULES)
+ * @returns Array of project mappings sorted by confidence (highest first)
+ */
+export function mapUserStoryToProjects(userStory, projectRules = DEFAULT_PROJECT_RULES) {
+    const mappings = [];
+    // Combine all user story text for analysis
+    const fullText = [
+        userStory.title,
+        userStory.description,
+        ...userStory.acceptanceCriteria,
+        userStory.technicalContext || ''
+    ].join(' ').toLowerCase();
+    for (const rule of projectRules) {
+        const reasoning = [];
+        let score = 0;
+        let maxScore = 0;
+        // Keyword matching (40% weight)
+        const keywordMatches = rule.keywords.filter(keyword => fullText.includes(keyword.toLowerCase()));
+        const keywordScore = keywordMatches.length * 0.4;
+        score += keywordScore;
+        maxScore += rule.keywords.length * 0.4;
+        if (keywordMatches.length > 0) {
+            reasoning.push(`Keywords: ${keywordMatches.slice(0, 5).join(', ')}`);
+        }
+        // Tech stack matching (40% weight)
+        const techStackMatches = rule.techStack.filter(tech => fullText.includes(tech.toLowerCase()));
+        const techScore = techStackMatches.length * 0.4;
+        score += techScore;
+        maxScore += rule.techStack.length * 0.4;
+        if (techStackMatches.length > 0) {
+            reasoning.push(`Tech stack: ${techStackMatches.slice(0, 5).join(', ')}`);
+        }
+        // Component type matching (20% weight)
+        const componentMatches = rule.componentTypes.filter(component => fullText.includes(component.toLowerCase()));
+        const componentScore = componentMatches.length * 0.2;
+        score += componentScore;
+        maxScore += rule.componentTypes.length * 0.2;
+        if (componentMatches.length > 0) {
+            reasoning.push(`Components: ${componentMatches.slice(0, 3).join(', ')}`);
+        }
+        // Exclude keywords (penalty)
+        if (rule.excludeKeywords) {
+            const excludeMatches = rule.excludeKeywords.filter(keyword => fullText.includes(keyword.toLowerCase()));
+            if (excludeMatches.length > 0) {
+                score *= 0.5; // 50% penalty
+                reasoning.push(`Penalty: ${excludeMatches.join(', ')} (not primary focus)`);
+            }
+        }
+        // Normalize confidence (0.0-1.0)
+        const confidence = maxScore > 0 ? Math.min(score / (maxScore * 0.3), 1.0) : 0;
+        // Only include mappings with confidence > 0.1
+        if (confidence > 0.1) {
+            mappings.push({
+                projectId: rule.id,
+                confidence,
+                reasoning
+            });
+        }
+    }
+    // Sort by confidence (highest first)
+    mappings.sort((a, b) => b.confidence - a.confidence);
+    return mappings;
+}
+/**
+ * Determine primary project for a user story
+ * (highest confidence mapping)
+ *
+ * @param userStory User story to analyze
+ * @param projectRules Project mapping rules
+ * @returns Primary project mapping or null if no confident match
+ */
+export function getPrimaryProject(userStory, projectRules = DEFAULT_PROJECT_RULES) {
+    const mappings = mapUserStoryToProjects(userStory, projectRules);
+    // Require at least 30% confidence for primary project
+    return mappings.length > 0 && mappings[0].confidence >= 0.3
+        ? mappings[0]
+        : null;
+}
+/**
+ * Split spec into project-specific specs based on user story mappings
+ *
+ * @param userStories Array of user stories
+ * @param projectRules Project mapping rules
+ * @returns Map of projectId → user stories
+ */
+export function splitSpecByProject(userStories, projectRules = DEFAULT_PROJECT_RULES) {
+    const projectSpecs = new Map();
+    for (const userStory of userStories) {
+        const primaryProject = getPrimaryProject(userStory, projectRules);
+        if (primaryProject) {
+            const existing = projectSpecs.get(primaryProject.projectId) || [];
+            existing.push(userStory);
+            projectSpecs.set(primaryProject.projectId, existing);
+        }
+        else {
+            // No confident match - assign to "SHARED" or primary project
+            const shared = projectSpecs.get('SHARED') || [];
+            shared.push(userStory);
+            projectSpecs.set('SHARED', shared);
+        }
+    }
+    return projectSpecs;
+}
+/**
+ * Suggest JIRA item type hierarchy based on user story scope
+ *
+ * @param userStory User story to analyze
+ * @returns Suggested JIRA item type (Epic, Story, Task, Subtask)
+ */
+export function suggestJiraItemType(userStory) {
+    const storyPoints = estimateStoryPoints(userStory);
+    // Epic: > 13 story points (large feature area)
+    if (storyPoints > 13) {
+        return 'Epic';
+    }
+    // Story: 3-13 story points (standard user story)
+    if (storyPoints >= 3) {
+        return 'Story';
+    }
+    // Task: 1-2 story points (small implementation task)
+    if (storyPoints >= 1) {
+        return 'Task';
+    }
+    // Subtask: < 1 story point (granular work)
+    return 'Subtask';
+}
+/**
+ * Estimate story points based on acceptance criteria count and complexity
+ *
+ * @param userStory User story to estimate
+ * @returns Estimated story points (1-21)
+ */
+function estimateStoryPoints(userStory) {
+    const acCount = userStory.acceptanceCriteria.length;
+    // Simple heuristic: 1 AC ≈ 1 story point, max 21
+    return Math.min(acCount, 21);
+}
+/**
+ * Format project mapping report (for display to user)
+ *
+ * @param userStory User story
+ * @param mappings Project mappings
+ * @returns Formatted markdown report
+ */
+export function formatProjectMappingReport(userStory, mappings) {
+    const lines = [];
+    lines.push(`## ${userStory.id}: ${userStory.title}`);
+    lines.push('');
+    if (mappings.length === 0) {
+        lines.push('❌ **No project match** (assign to SHARED)');
+        return lines.join('\n');
+    }
+    lines.push(`✅ **Primary Project**: ${mappings[0].projectId} (${(mappings[0].confidence * 100).toFixed(0)}% confidence)`);
+    lines.push('');
+    lines.push('**Reasoning**:');
+    for (const reason of mappings[0].reasoning) {
+        lines.push(`- ${reason}`);
+    }
+    if (mappings.length > 1) {
+        lines.push('');
+        lines.push('**Secondary Matches**:');
+        for (const mapping of mappings.slice(1, 3)) {
+            lines.push(`- ${mapping.projectId} (${(mapping.confidence * 100).toFixed(0)}%)`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/scripts/split-spec-by-project.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+/**
+ * Split Monolithic Spec into Project-Specific Files
+ *
+ * Usage: node dist/scripts/split-spec-by-project.js <spec-path> <output-dir>
+ */
+
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import {
+  parseSpecFile,
+  splitSpecIntoProjects,
+  createMultiProjectFolderStructure
+} from '../utils/spec-splitter.js';
+import {
+  mapUserStoryToProjects,
+  formatProjectMappingReport
+} from '../utils/project-mapper.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length < 2) {
+    console.error('Usage: node dist/scripts/split-spec-by-project.js <spec-path> <output-dir>');
+    process.exit(1);
+  }
+
+  const [specPath, outputDir] = args;
+
+  console.log('🔍 Analyzing spec file...\n');
+
+  // Parse spec
+  const parsedSpec = await parseSpecFile(specPath);
+
+  console.log(`✓ Parsed spec: ${parsedSpec.metadata.title}`);
+  console.log(`  User stories: ${parsedSpec.userStories.length}`);
+  console.log('');
+
+  // Analyze user stories
+  console.log('📊 Classifying user stories by project...\n');
+
+  const projectStats = new Map();
+
+  for (const userStory of parsedSpec.userStories) {
+    const mappings = mapUserStoryToProjects(userStory);
+
+    if (mappings.length > 0) {
+      const primary = mappings[0];
+      console.log(formatProjectMappingReport(userStory, mappings));
+      console.log('');
+
+      projectStats.set(primary.projectId, (projectStats.get(primary.projectId) || 0) + 1);
+    } else {
+      console.log(`❌ ${userStory.id}: ${userStory.title} → NO MATCH (assign to SHARED)`);
+      console.log('');
+      projectStats.set('SHARED', (projectStats.get('SHARED') || 0) + 1);
+    }
+  }
+
+  // Print summary
+  console.log('📈 Project Distribution:\n');
+  const totalStories = parsedSpec.userStories.length;
+
+  for (const [projectId, count] of projectStats.entries()) {
+    const percentage = ((count / totalStories) * 100).toFixed(0);
+    console.log(`  ${projectId}: ${count} user stories (${percentage}%)`);
+  }
+
+  console.log('');
+
+  // Create folder structure
+  console.log('📁 Creating multi-project folder structure...\n');
+
+  const allProjectIds = [...projectStats.keys()];
+  await createMultiProjectFolderStructure(outputDir, allProjectIds);
+
+  console.log('✓ Folder structure created\n');
+
+  // Split spec
+  console.log('✂️  Splitting spec into project-specific files...\n');
+
+  const outputMap = await splitSpecIntoProjects(specPath, outputDir);
+
+  for (const [projectId, filePath] of outputMap.entries()) {
+    console.log(`✓ ${projectId}: ${filePath}`);
+  }
+
+  console.log('');
+  console.log('✅ Spec splitting complete!');
+  console.log('');
+  console.log('Next steps:');
+  console.log('1. Review project-specific specs in:', outputDir);
+  console.log('2. Configure JIRA sync for each project');
+  console.log('3. Run /specweave-jira:sync to create JIRA items');
+}
+
+main().catch((error) => {
+  console.error('❌ Error:', error.message);
+  console.error(error.stack);
+  process.exit(1);
+});