@lbruton/specflow 3.0.0

package/dist/index.js

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+import { SpecWorkflowMCPServer } from './server.js';
+import { MultiProjectDashboardServer } from './dashboard/multi-server.js';
+import { DashboardSessionManager } from './core/dashboard-session.js';
+import { homedir } from 'os';
+import { resolveGitRoot, resolveGitWorkspaceRoot } from './core/git-utils.js';
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { realpathSync } from 'fs';
+// Default dashboard port
+const DEFAULT_DASHBOARD_PORT = 5000;
+function showHelp() {
+    console.error(`
+SpecFlow — Spec-driven development with persistent project memory
+
+USAGE:
+  specflow [path] [options]
+
+ARGUMENTS:
+  path                    Project path (defaults to current directory)
+                         Supports ~ for home directory
+
+OPTIONS:
+  --help                  Show this help message
+  --dashboard             Run dashboard-only mode (no MCP server)
+  --port <number>         Specify dashboard port (1024-65535)
+                         Default: 5000
+                         Only use if port 5000 is unavailable
+  --no-open               Don't automatically open browser when starting dashboard
+                         Useful in restricted environments where browser launch is blocked
+  --no-shared-worktree-specs
+                         Disable shared .spec-workflow in git worktrees
+                         Use workspace-local .spec-workflow instead of main repo
+
+IMPORTANT:
+  Only ONE dashboard instance runs at a time. All MCP servers connect to the
+  same dashboard. The dashboard runs on port 5000 by default.
+
+MODES OF OPERATION:
+
+1. MCP Server Only (default):
+   specflow
+   specflow ~/my-project
+
+   Starts MCP server without dashboard. Dashboard can be started separately.
+
+2. Dashboard Only Mode:
+   specflow --dashboard
+   specflow --dashboard --port 8080
+   specflow --dashboard --no-open
+
+   Runs only the web dashboard without MCP server (default port: 5000).
+   Projects will automatically appear in the dashboard as MCP servers register.
+   Only one dashboard instance is needed for all your projects.
+   Use --no-open to prevent automatic browser launch (useful in restricted environments).
+
+EXAMPLES:
+  # Start MCP server in current directory (no dashboard)
+  specflow
+
+  # Start MCP server in a specific project directory
+  specflow ~/projects/my-app
+
+  # Run dashboard (default port 5000) - START THIS FIRST
+  specflow --dashboard
+
+  # Run dashboard on custom port (if 5000 is unavailable)
+  specflow --dashboard --port 8080
+
+TYPICAL WORKFLOW:
+  1. Start the dashboard once:
+     specflow --dashboard
+
+  2. Start MCP servers for your projects (in separate terminals):
+     specflow ~/project1
+     specflow ~/project2
+     specflow ~/project3
+
+  All projects will appear in the same dashboard at http://localhost:5000
+
+PARAMETER FORMATS:
+  --port 3456             Space-separated format
+  --port=3456             Equals format
+
+For more information, visit: https://github.com/lbruton/specflow
+`);
+}
+function expandTildePath(path) {
+    if (path.startsWith('~/') || path === '~') {
+        return path.replace('~', homedir());
+    }
+    return path;
+}
+export function parseArguments(args) {
+    const isDashboardMode = args.includes('--dashboard');
+    const noOpen = args.includes('--no-open');
+    const noSharedWorktreeSpecs = args.includes('--no-shared-worktree-specs');
+    let customPort;
+    // Check for invalid flags
+    const validFlags = ['--dashboard', '--port', '--help', '-h', '--no-open', '--no-shared-worktree-specs'];
+    for (const arg of args) {
+        if (arg.startsWith('--') && !arg.includes('=')) {
+            if (!validFlags.includes(arg)) {
+                throw new Error(`Unknown option: ${arg}\nUse --help to see available options.`);
+            }
+        }
+        else if (arg.startsWith('--') && arg.includes('=')) {
+            const flagName = arg.split('=')[0];
+            if (!validFlags.includes(flagName)) {
+                throw new Error(`Unknown option: ${flagName}\nUse --help to see available options.`);
+            }
+        }
+    }
+    // Parse --port parameter (supports --port 3000 and --port=3000 formats)
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith('--port=')) {
+            // Handle --port=3000 format
+            const portStr = arg.split('=')[1];
+            if (portStr) {
+                const parsed = parseInt(portStr, 10);
+                if (isNaN(parsed)) {
+                    throw new Error(`Invalid port number: ${portStr}. Port must be a number.`);
+                }
+                if (parsed < 1024 || parsed > 65535) {
+                    throw new Error(`Port ${parsed} is out of range. Port must be between 1024 and 65535.`);
+                }
+                customPort = parsed;
+            }
+            else {
+                throw new Error('--port parameter requires a value (e.g., --port=3000)');
+            }
+        }
+        else if (arg === '--port' && i + 1 < args.length) {
+            // Handle --port 3000 format
+            const portStr = args[i + 1];
+            const parsed = parseInt(portStr, 10);
+            if (isNaN(parsed)) {
+                throw new Error(`Invalid port number: ${portStr}. Port must be a number.`);
+            }
+            if (parsed < 1024 || parsed > 65535) {
+                throw new Error(`Port ${parsed} is out of range. Port must be between 1024 and 65535.`);
+            }
+            customPort = parsed;
+            i++; // Skip the next argument as it's the port value
+        }
+        else if (arg === '--port') {
+            throw new Error('--port parameter requires a value (e.g., --port 3000)');
+        }
+    }
+    // Get project path (filter out flags and their values)
+    const filteredArgs = args.filter((arg, index) => {
+        if (arg === '--dashboard')
+            return false;
+        if (arg.startsWith('--port='))
+            return false;
+        if (arg === '--port')
+            return false;
+        if (arg === '--no-open')
+            return false;
+        if (arg === '--no-shared-worktree-specs')
+            return false;
+        // Check if this arg is a value following --port
+        if (index > 0 && args[index - 1] === '--port')
+            return false;
+        return true;
+    });
+    // For dashboard-only mode, use cwd as default (dashboard doesn't need it)
+    const rawProjectPath = filteredArgs[0] || process.cwd();
+    const expandedPath = expandTildePath(rawProjectPath);
+    const workspacePath = resolveGitWorkspaceRoot(expandedPath);
+    const workflowRootPath = noSharedWorktreeSpecs ? workspacePath : resolveGitRoot(workspacePath);
+    // Warn if no explicit path was provided and we're using cwd (but only for MCP server mode)
+    if (!filteredArgs[0] && !isDashboardMode) {
+        console.warn(`Warning: No project path specified, using current directory: ${workspacePath}`);
+        console.warn('Consider specifying an explicit path for better clarity.');
+    }
+    return {
+        workspacePath,
+        workflowRootPath,
+        expandedPath,
+        isDashboardMode,
+        noSharedWorktreeSpecs,
+        port: customPort,
+        lang: undefined,
+        noOpen
+    };
+}
+async function main() {
+    try {
+        const args = process.argv.slice(2);
+        // Check for help flag
+        if (args.includes('--help') || args.includes('-h')) {
+            showHelp();
+            process.exit(0);
+        }
+        // Parse command-line arguments
+        const cliArgs = parseArguments(args);
+        const workspacePath = cliArgs.workspacePath;
+        const workflowRootPath = cliArgs.workflowRootPath;
+        const noSharedWorktreeSpecs = cliArgs.noSharedWorktreeSpecs;
+        // Log worktree details when workspace and shared workflow roots differ
+        if (workspacePath !== workflowRootPath) {
+            console.error('Git worktree detected.');
+            console.error(`workspacePath=${workspacePath}`);
+            console.error(`workflowRootPath=${workflowRootPath}`);
+        }
+        else if (noSharedWorktreeSpecs) {
+            console.error('Shared worktree specs disabled. Using workspace-local .spec-workflow.');
+            console.error(`workspacePath=${workspacePath}`);
+        }
+        // Apply configuration from CLI args
+        const isDashboardMode = cliArgs.isDashboardMode || false;
+        const port = cliArgs.port;
+        const lang = cliArgs.lang;
+        const noOpen = cliArgs.noOpen || false;
+        if (isDashboardMode) {
+            // Check if a dashboard is already running (always check, regardless of port)
+            const sessionManager = new DashboardSessionManager();
+            const existingSession = await sessionManager.getDashboardSession();
+            if (existingSession) {
+                console.error(`Dashboard is already running at: ${existingSession.url}`);
+                console.error('');
+                console.error('You can:');
+                console.error(`  1. Use the existing dashboard at: ${existingSession.url}`);
+                console.error(`  2. Stop it first (Ctrl+C or kill ${existingSession.pid}), then start a new one`);
+                console.error('');
+                console.error('Note: Only one dashboard instance is needed for all your projects.');
+                process.exit(1);
+            }
+            // Use specified port or default
+            const dashboardPort = port || DEFAULT_DASHBOARD_PORT;
+            // Dashboard only mode - use new multi-project dashboard
+            console.error(`Starting Unified Multi-Project Dashboard`);
+            if (port) {
+                console.error(`Using custom port: ${port}`);
+            }
+            else {
+                console.error(`Using default port: ${DEFAULT_DASHBOARD_PORT}`);
+            }
+            if (noOpen) {
+                console.error(`Browser auto-open disabled (--no-open)`);
+            }
+            // Load configuration from environment variables
+            let bindAddress;
+            let allowExternalAccess;
+            const securityConfig = {};
+            // Network binding configuration
+            if (process.env.SPEC_WORKFLOW_BIND_ADDRESS) {
+                bindAddress = process.env.SPEC_WORKFLOW_BIND_ADDRESS;
+            }
+            // External access opt-in (only override if explicitly set to true or false)
+            if (process.env.SPEC_WORKFLOW_ALLOW_EXTERNAL_ACCESS !== undefined) {
+                const allowExternal = process.env.SPEC_WORKFLOW_ALLOW_EXTERNAL_ACCESS.toLowerCase();
+                if (allowExternal === 'true') {
+                    allowExternalAccess = true;
+                }
+                else if (allowExternal === 'false') {
+                    allowExternalAccess = false;
+                }
+                // If invalid value, ignore and use default
+            }
+            // Security features configuration
+            // Rate limiting toggle (only override if explicitly set to true or false)
+            if (process.env.SPEC_WORKFLOW_RATE_LIMIT_ENABLED !== undefined) {
+                const rateLimitEnabled = process.env.SPEC_WORKFLOW_RATE_LIMIT_ENABLED.toLowerCase();
+                if (rateLimitEnabled === 'true') {
+                    securityConfig.rateLimitEnabled = true;
+                }
+                else if (rateLimitEnabled === 'false') {
+                    securityConfig.rateLimitEnabled = false;
+                }
+                // If invalid value, ignore and use default
+            }
+            // CORS toggle (only override if explicitly set to true or false)
+            if (process.env.SPEC_WORKFLOW_CORS_ENABLED !== undefined) {
+                const corsEnabled = process.env.SPEC_WORKFLOW_CORS_ENABLED.toLowerCase();
+                if (corsEnabled === 'true') {
+                    securityConfig.corsEnabled = true;
+                }
+                else if (corsEnabled === 'false') {
+                    securityConfig.corsEnabled = false;
+                }
+                // If invalid value, ignore and use default
+            }
+            // Create dashboard server (network binding validation happens in constructor)
+            let dashboardServer;
+            try {
+                dashboardServer = new MultiProjectDashboardServer({
+                    autoOpen: !noOpen,
+                    port: dashboardPort,
+                    bindAddress,
+                    allowExternalAccess,
+                    security: securityConfig
+                });
+            }
+            catch (error) {
+                // Provide user-friendly error message with environment variable names
+                if (error.message.includes('SECURITY ERROR') || error.message.includes('non-localhost')) {
+                    console.error('');
+                    console.error('❌ Security Configuration Error:');
+                    console.error(error.message);
+                    console.error('');
+                    console.error('To fix this, either:');
+                    console.error('  1. Use localhost binding (secure):');
+                    console.error('     export SPEC_WORKFLOW_BIND_ADDRESS=127.0.0.1');
+                    console.error('');
+                    console.error('  2. Explicitly allow external access (insecure):');
+                    console.error('     export SPEC_WORKFLOW_ALLOW_EXTERNAL_ACCESS=true');
+                    console.error('');
+                    process.exit(1);
+                }
+                throw error; // Re-throw other errors
+            }
+            try {
+                const dashboardUrl = await dashboardServer.start();
+                console.error(`Dashboard started at: ${dashboardUrl}`);
+                console.error('Projects will automatically appear as MCP servers register.');
+                console.error('Press Ctrl+C to stop the dashboard');
+            }
+            catch (error) {
+                console.error(`Failed to start dashboard: ${error.message}`);
+                process.exit(1);
+            }
+            // Handle graceful shutdown
+            const shutdown = async () => {
+                console.error('\nShutting down dashboard...');
+                await dashboardServer.stop();
+                process.exit(0);
+            };
+            process.on('SIGINT', shutdown);
+            process.on('SIGTERM', shutdown);
+        }
+        else {
+            // MCP server mode
+            console.error(`Starting Spec Workflow MCP Server for project: ${workflowRootPath}`);
+            console.error(`Workspace path: ${workspacePath}`);
+            console.error(`Working directory: ${process.cwd()}`);
+            const server = new SpecWorkflowMCPServer();
+            await server.initialize(workflowRootPath, workspacePath, lang);
+            // Handle graceful shutdown
+            process.on('SIGINT', async () => {
+                await server.stop();
+                process.exit(0);
+            });
+            process.on('SIGTERM', async () => {
+                await server.stop();
+                process.exit(0);
+            });
+        }
+    }
+    catch (error) {
+        console.error('Error:', error.message);
+        // Provide additional context for common path-related issues
+        if (error.message.includes('ENOENT') || error.message.includes('path') || error.message.includes('directory')) {
+            console.error('\nProject path troubleshooting:');
+            console.error('- Verify the project path exists and is accessible');
+            console.error('- For Claude CLI users, ensure you used: claude mcp add spec-workflow npx -y @pimzino/spec-workflow-mcp@latest -- /path/to/your/project');
+            console.error('- Check that the path doesn\'t contain special characters that need escaping');
+            console.error(`- Current working directory: ${process.cwd()}`);
+        }
+        process.exit(1);
+    }
+}
+export function resolveEntrypoint(pathValue) {
+    if (!pathValue)
+        return undefined;
+    try {
+        return realpathSync(pathValue);
+    }
+    catch {
+        return resolve(pathValue);
+    }
+}
+const entrypoint = resolveEntrypoint(process.argv[1]);
+const currentFile = resolveEntrypoint(fileURLToPath(import.meta.url));
+if (entrypoint && currentFile && currentFile === entrypoint) {
+    main().catch(() => process.exit(1));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAElC,yBAAyB;AACzB,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAEpC,SAAS,QAAQ;IACf,OAAO,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyEf,CAAC,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,IAAY;IACnC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;QAC1C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAc;IAU3C,MAAM,eAAe,GAAG,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC1C,MAAM,qBAAqB,GAAG,IAAI,CAAC,QAAQ,CAAC,4BAA4B,CAAC,CAAC;IAC1E,IAAI,UAA8B,CAAC;IAEnC,0BAA0B;IAC1B,MAAM,UAAU,GAAG,CAAC,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,4BAA4B,CAAC,CAAC;IACxG,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC9B,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,wCAAwC,CAAC,CAAC;YAClF,CAAC;QACH,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACrD,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACnC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,KAAK,CAAC,mBAAmB,QAAQ,wCAAwC,CAAC,CAAC;YACvF,CAAC;QACH,CAAC;IACH,CAAC;IAED,wEAAwE;IACxE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAEpB,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,4BAA4B;YAC5B,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAClC,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;gBACrC,IAAI,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;oBAClB,MAAM,IAAI,KAAK,CAAC,wBAAwB,OAAO,0BAA0B,CAAC,CAAC;gBAC7E,CAAC;gBACD,IAAI,MAAM,GAAG,IAAI,IAAI,MAAM,GAAG,KAAK,EAAE,CAAC;oBACpC,MAAM,IAAI,KAAK,CAAC,QAAQ,MAAM,wDAAwD,CAAC,CAAC;gBAC1F,CAAC;gBACD,UAAU,GAAG,MAAM,CAAC;YACtB,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;YAC3E,CAAC;QACH,CAAC;aAAM,IAAI,GAAG,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACnD,4BAA4B;YAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC5B,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACrC,IAAI,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;gBAClB,MAAM,IAAI,KAAK,CAAC,wBAAwB,OAAO,0BAA0B,CAAC,CAAC;YAC7E,CAAC;YACD,IAAI,MAAM,GAAG,IAAI,IAAI,MAAM,GAAG,KAAK,EAAE,CAAC;gBACpC,MAAM,IAAI,KAAK,CAAC,QAAQ,MAAM,wDAAwD,CAAC,CAAC;YAC1F,CAAC;YACD,UAAU,GAAG,MAAM,CAAC;YACpB,CAAC,EAAE,CAAC,CAAC,gDAAgD;QACvD,CAAC;aAAM,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC3E,CAAC;IACH,CAAC;IAED,uDAAuD;IACvD,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QAC9C,IAAI,GAAG,KAAK,aAAa;YAAE,OAAO,KAAK,CAAC;QACxC,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,KAAK,CAAC;QAC5C,IAAI,GAAG,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QACnC,IAAI,GAAG,KAAK,WAAW;YAAE,OAAO,KAAK,CAAC;QACtC,IAAI,GAAG,KAAK,4BAA4B;YAAE,OAAO,KAAK,CAAC;QACvD,gDAAgD;QAChD,IAAI,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC5D,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IAEH,0EAA0E;IAC1E,MAAM,cAAc,GAAG,YAAY,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACxD,MAAM,YAAY,GAAG,eAAe,CAAC,cAAc,CAAC,CAAC;IACrD,MAAM,aAAa,GAAG,uBAAuB,CAAC,YAAY,CAAC,CAAC;IAC5D,MAAM,gBAAgB,GAAG,qBAAqB,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IAE/F,2FAA2F;IAC3F,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;QACzC,OAAO,CAAC,IAAI,CAAC,gEAAgE,aAAa,EAAE,CAAC,CAAC;QAC9F,OAAO,CAAC,IAAI,CAAC,0DAA0D,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO;QACL,aAAa;QACb,gBAAgB;QAChB,YAAY;QACZ,eAAe;QACf,qBAAqB;QACrB,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,SAAS;QACf,MAAM;KACP,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAEnC,sBAAsB;QACtB,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACnD,QAAQ,EAAE,CAAC;YACX,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,+BAA+B;QAC/B,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;QAC5C,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;QAClD,MAAM,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC;QAE5D,uEAAuE;QACvE,IAAI,aAAa,KAAK,gBAAgB,EAAE,CAAC;YACvC,OAAO,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;YACxC,OAAO,CAAC,KAAK,CAAC,iBAAiB,aAAa,EAAE,CAAC,CAAC;YAChD,OAAO,CAAC,KAAK,CAAC,oBAAoB,gBAAgB,EAAE,CAAC,CAAC;QACxD,CAAC;aAAM,IAAI,qBAAqB,EAAE,CAAC;YACjC,OAAO,CAAC,KAAK,CAAC,uEAAuE,CAAC,CAAC;YACvF,OAAO,CAAC,KAAK,CAAC,iBAAiB,aAAa,EAAE,CAAC,CAAC;QAClD,CAAC;QAED,oCAAoC;QACpC,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,KAAK,CAAC;QACzD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QAC1B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC;QAEvC,IAAI,eAAe,EAAE,CAAC;YACpB,6EAA6E;YAC7E,MAAM,cAAc,GAAG,IAAI,uBAAuB,EAAE,CAAC;YACrD,MAAM,eAAe,GAAG,MAAM,cAAc,CAAC,mBAAmB,EAAE,CAAC;YAEnE,IAAI,eAAe,EAAE,CAAC;gBACpB,OAAO,CAAC,KAAK,CAAC,oCAAoC,eAAe,CAAC,GAAG,EAAE,CAAC,CAAC;gBACzE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBAClB,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;gBAC1B,OAAO,CAAC,KAAK,CAAC,uCAAuC,eAAe,CAAC,GAAG,EAAE,CAAC,CAAC;gBAC5E,OAAO,CAAC,KAAK,CAAC,sCAAsC,eAAe,CAAC,GAAG,yBAAyB,CAAC,CAAC;gBAClG,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBAClB,OAAO,CAAC,KAAK,CAAC,oEAAoE,CAAC,CAAC;gBACpF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YAED,gCAAgC;YAChC,MAAM,aAAa,GAAG,IAAI,IAAI,sBAAsB,CAAC;YAErD,wDAAwD;YACxD,OAAO,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAC;YAC1D,IAAI,IAAI,EAAE,CAAC;gBACT,OAAO,CAAC,KAAK,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC;YAC9C,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,KAAK,CAAC,uBAAuB,sBAAsB,EAAE,CAAC,CAAC;YACjE,CAAC;YACD,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;YAC1D,CAAC;YAED,gDAAgD;YAChD,IAAI,WAA+B,CAAC;YACpC,IAAI,mBAAwC,CAAC;YAC7C,MAAM,cAAc,GAAQ,EAAE,CAAC;YAE/B,gCAAgC;YAChC,IAAI,OAAO,CAAC,GAAG,CAAC,0BAA0B,EAAE,CAAC;gBAC3C,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC;YACvD,CAAC;YAED,4EAA4E;YAC5E,IAAI,OAAO,CAAC,GAAG,CAAC,mCAAmC,KAAK,SAAS,EAAE,CAAC;gBAClE,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,WAAW,EAAE,CAAC;gBACpF,IAAI,aAAa,KAAK,MAAM,EAAE,CAAC;oBAC7B,mBAAmB,GAAG,IAAI,CAAC;gBAC7B,CAAC;qBAAM,IAAI,aAAa,KAAK,OAAO,EAAE,CAAC;oBACrC,mBAAmB,GAAG,KAAK,CAAC;gBAC9B,CAAC;gBACD,2CAA2C;YAC7C,CAAC;YAED,kCAAkC;YAElC,0EAA0E;YAC1E,IAAI,OAAO,CAAC,GAAG,CAAC,gCAAgC,KAAK,SAAS,EAAE,CAAC;gBAC/D,MAAM,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC,gCAAgC,CAAC,WAAW,EAAE,CAAC;gBACpF,IAAI,gBAAgB,KAAK,MAAM,EAAE,CAAC;oBAChC,cAAc,CAAC,gBAAgB,GAAG,IAAI,CAAC;gBACzC,CAAC;qBAAM,IAAI,gBAAgB,KAAK,OAAO,EAAE,CAAC;oBACxC,cAAc,CAAC,gBAAgB,GAAG,KAAK,CAAC;gBAC1C,CAAC;gBACD,2CAA2C;YAC7C,CAAC;YAED,iEAAiE;YACjE,IAAI,OAAO,CAAC,GAAG,CAAC,0BAA0B,KAAK,SAAS,EAAE,CAAC;gBACzD,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,WAAW,EAAE,CAAC;gBACzE,IAAI,WAAW,KAAK,MAAM,EAAE,CAAC;oBAC3B,cAAc,CAAC,WAAW,GAAG,IAAI,CAAC;gBACpC,CAAC;qBAAM,IAAI,WAAW,KAAK,OAAO,EAAE,CAAC;oBACnC,cAAc,CAAC,WAAW,GAAG,KAAK,CAAC;gBACrC,CAAC;gBACD,2CAA2C;YAC7C,CAAC;YAED,8EAA8E;YAC9E,IAAI,eAA4C,CAAC;YACjD,IAAI,CAAC;gBACH,eAAe,GAAG,IAAI,2BAA2B,CAAC;oBAChD,QAAQ,EAAE,CAAC,MAAM;oBACjB,IAAI,EAAE,aAAa;oBACnB,WAAW;oBACX,mBAAmB;oBACnB,QAAQ,EAAE,cAAc;iBACzB,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,KAAU,EAAE,CAAC;gBACpB,sEAAsE;gBACtE,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;oBACxF,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;oBAClB,OAAO,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;oBACjD,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;oBAC7B,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;oBAClB,OAAO,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;oBACtC,OAAO,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC;oBACtD,OAAO,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAC;oBAClE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;oBAClB,OAAO,CAAC,KAAK,CAAC,mDAAmD,CAAC,CAAC;oBACnE,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAC;oBACtE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;oBAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAClB,CAAC;gBACD,MAAM,KAAK,CAAC,CAAC,wBAAwB;YACvC,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,YAAY,GAAG,MAAM,eAAe,CAAC,KAAK,EAAE,CAAC;gBACnD,OAAO,CAAC,KAAK,CAAC,yBAAyB,YAAY,EAAE,CAAC,CAAC;gBACvD,OAAO,CAAC,KAAK,CAAC,6DAA6D,CAAC,CAAC;gBAC7E,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;YACtD,CAAC;YAAC,OAAO,KAAU,EAAE,CAAC;gBACpB,OAAO,CAAC,KAAK,CAAC,8BAA8B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YAED,2BAA2B;YAC3B,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;gBAC1B,OAAO,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;gBAC9C,MAAM,eAAe,CAAC,IAAI,EAAE,CAAC;gBAC7B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC,CAAC;YAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAElC,CAAC;aAAM,CAAC;YACN,kBAAkB;YAClB,OAAO,CAAC,KAAK,CAAC,kDAAkD,gBAAgB,EAAE,CAAC,CAAC;YACpF,OAAO,CAAC,KAAK,CAAC,mBAAmB,aAAa,EAAE,CAAC,CAAC;YAClD,OAAO,CAAC,KAAK,CAAC,sBAAsB,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YAErD,MAAM,MAAM,GAAG,IAAI,qBAAqB,EAAE,CAAC;YAE3C,MAAM,MAAM,CAAC,UAAU,CAAC,gBAAgB,EAAE,aAAa,EAAE,IAAI,CAAC,CAAC;YAE/D,2BAA2B;YAC3B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;gBAC9B,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;gBACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC,CAAC,CAAC;YAEH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;gBAC/B,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;gBACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC,CAAC,CAAC;QACL,CAAC;IAEH,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAEvC,4DAA4D;QAC5D,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;YAC9G,OAAO,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;YACjD,OAAO,CAAC,KAAK,CAAC,oDAAoD,CAAC,CAAC;YACpE,OAAO,CAAC,KAAK,CAAC,yIAAyI,CAAC,CAAC;YACzJ,OAAO,CAAC,KAAK,CAAC,8EAA8E,CAAC,CAAC;YAC9F,OAAO,CAAC,KAAK,CAAC,gCAAgC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACjE,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,SAA6B;IAC7D,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IAEjC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,SAAS,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC;IAC5B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,GAAG,iBAAiB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACtD,MAAM,WAAW,GAAG,iBAAiB,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAEtE,IAAI,UAAU,IAAI,WAAW,IAAI,WAAW,KAAK,UAAU,EAAE,CAAC;IAC5D,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACtC,CAAC"}

package/dist/markdown/templates/code-quality-reviewer-template.md

@@ -0,0 +1,76 @@
+# Code Quality Reviewer
+
+You are reviewing code changes for production readiness. Only dispatch this review AFTER spec compliance has passed.
+
+## What Was Implemented
+
+{DESCRIPTION}
+
+## Git Range to Review
+
+```bash
+git diff --stat {BASE_SHA}..{HEAD_SHA}
+git diff {BASE_SHA}..{HEAD_SHA}
+```
+
+## Review Checklist
+
+**Code Quality:**
+- Clean separation of concerns?
+- Proper error handling?
+- Type safety (if applicable)?
+- DRY principle followed?
+- Edge cases handled?
+
+**Architecture:**
+- Sound design decisions?
+- Scalability considerations?
+- Performance implications?
+- Security concerns?
+
+**Testing:**
+- Tests actually test logic (not just mocks)?
+- Edge cases covered?
+- Integration tests where needed?
+- All tests passing?
+- Test execution results logged in implementation artifacts? (name, status, pass/fail counts)
+- Tests linked to user stories from spec requirements?
+
+**Requirements:**
+- All plan requirements met?
+- Implementation matches spec?
+- No scope creep?
+- Breaking changes documented?
+
+**Production Readiness:**
+- Backward compatibility considered?
+- Documentation complete?
+- No obvious bugs?
+
+## Output Format
+
+### Strengths
+[What's well done? Be specific with file:line references.]
+
+### Issues
+
+#### Critical (Must Fix)
+[Bugs, security issues, data loss risks, broken functionality]
+
+#### Important (Should Fix)
+[Architecture problems, missing features, poor error handling, test gaps]
+
+#### Minor (Nice to Have)
+[Code style, optimization opportunities, documentation improvements]
+
+**For each issue:**
+- File:line reference
+- What's wrong
+- Why it matters
+- How to fix (if not obvious)
+
+### Assessment
+
+**Ready to proceed?** [Yes / No / With fixes]
+
+**Reasoning:** [1-2 sentence technical assessment]

package/dist/markdown/templates/design-template.md

@@ -0,0 +1,141 @@
+# Design Document
+
+## References
+
+- **Issue:** PROJ-XXX
+- **GitHub PR:** [#NNN](https://github.com/owner/repo/pull/NNN)
+- **Spec Path:** `.spec-workflow/specs/{spec-name}/`
+
+## Overview
+
+[High-level description of the feature and its place in the overall system]
+
+## Steering Document Alignment
+
+### Technical Standards (tech.md)
+[How the design follows documented technical patterns and standards]
+
+### Project Structure (structure.md)
+[How the implementation will follow project organization conventions]
+
+## Code Reuse Analysis
+[What existing code will be leveraged, extended, or integrated with this feature]
+
+### Existing Components to Leverage
+- **[Component/Utility Name]**: [How it will be used]
+- **[Service/Helper Name]**: [How it will be extended]
+
+### Integration Points
+- **[Existing System/API]**: [How the new feature will integrate]
+- **[Database/Storage]**: [How data will connect to existing schemas]
+
+## Architecture
+
+[Describe the overall architecture and design patterns used]
+
+### Modular Design Principles
+- **Single File Responsibility**: Each file should handle one specific concern or domain
+- **Component Isolation**: Create small, focused components rather than large monolithic files
+- **Service Layer Separation**: Separate data access, business logic, and presentation layers
+- **Utility Modularity**: Break utilities into focused, single-purpose modules
+
+```mermaid
+graph TD
+    A[Component A] --> B[Component B]
+    B --> C[Component C]
+```
+
+## Components and Interfaces
+
+### Component 1
+- **Purpose:** [What this component does]
+- **Interfaces:** [Public methods/APIs]
+- **Dependencies:** [What it depends on]
+- **Reuses:** [Existing components/utilities it builds upon]
+
+### Component 2
+- **Purpose:** [What this component does]
+- **Interfaces:** [Public methods/APIs]
+- **Dependencies:** [What it depends on]
+- **Reuses:** [Existing components/utilities it builds upon]
+
+## Data Models
+
+### Model 1
+```
+[Define the structure of Model1 in your language]
+- id: [unique identifier type]
+- name: [string/text type]
+- [Additional properties as needed]
+```
+
+### Model 2
+```
+[Define the structure of Model2 in your language]
+- id: [unique identifier type]
+- [Additional properties as needed]
+```
+
+## UI Impact Assessment
+
+### Has UI Changes: [Yes / No]
+
+_If **No**, skip this section entirely. If **Yes**, complete all fields below — this gates Phase 4._
+
+### Visual Scope
+- **Impact Level:** [New screen / New modal or panel / Redesign existing component / Minor element additions]
+- **Components Affected:** [List every UI component this spec creates or modifies]
+- **Prototype Required:** [Yes — if 3+ data elements, new layout, or uncertain visual hierarchy / No — single-element additions with clear analogues]
+
+### Prototype Artifacts
+- **Stitch Screen IDs:** [To be filled during prototype phase — leave blank in design doc]
+- **Playground File:** [To be filled during prototype phase — leave blank in design doc]
+- **Reference HTML/Mockup:** [Path to any existing prototype, mockup, or reference HTML provided with the spec]
+
+### Design Constraints
+- **Theme Compatibility:** [Must work in: light / dark / sepia / all]
+- **Existing Patterns to Match:** [Name specific existing components whose visual style this should follow]
+- **Responsive Behavior:** [How this renders on mobile / tablet / desktop]
+
+### Visual Approval Gate
+> **BLOCKING:** If `Prototype Required` is **Yes**, no UI implementation task may begin until:
+> 1. A Stitch mockup or equivalent visual is created and reviewed
+> 2. A Playground prototype (or reference HTML) is interactively approved by the user
+> 3. Both artifact paths are filled in above
+>
+> This gate is enforced in Phase 4 — the orchestrator MUST check this section before dispatching any task tagged with `ui:true`.
+
+## Open Questions
+
+> **GATE:** All blocking questions must be resolved before this document can be approved.
+> Questions carried from Requirements should be resolved here.
+
+### Blocking (must resolve before approval)
+
+- [ ] [Question — why it matters]
+
+### Resolved
+
+- [x] ~~[Question]~~ — [Answer, source]
+
+## Error Handling
+
+### Error Scenarios
+1. **Scenario 1:** [Description]
+   - **Handling:** [How to handle]
+   - **User Impact:** [What user sees]
+
+2. **Scenario 2:** [Description]
+   - **Handling:** [How to handle]
+   - **User Impact:** [What user sees]
+
+## Testing Strategy
+
+### Runbook E2E Tests (Primary)
+- Identify affected `tests/runbook/` section(s): [01-page-load, 02-crud, 03-backup-restore, 04-import-export, 05-market, 06-ui-ux, 07-activity-log, 08-spot-prices]
+- New test blocks to write (TDD — before implementation): [describe tests]
+- Run via `/bb-test sections=NN` against PR preview URL
+
+### Manual Verification
+- [Any flows that require manual testing, e.g., OAuth/Dropbox cloud sync at beta.staktrakr.com]
+- [Flows requiring API keys from Infisical]