sequant 1.12.0 → 1.13.0

package/README.md

@@ -194,7 +194,7 @@ npx sequant stats             # View local workflow analytics
 npx sequant dashboard         # Launch real-time workflow dashboard
 ```
 
-See [Run Command Options](docs/run-command.md), [State Command](docs/state-command.md), and [Analytics](docs/analytics.md) for details.
+See [Run Command Options](docs/reference/run-command.md), [State Command](docs/reference/state-command.md), and [Analytics](docs/reference/analytics.md) for details.
 
 ---
 
@@ -211,7 +211,7 @@ See [Run Command Options](docs/run-command.md), [State Command](docs/state-comma
 }
 ```
 
-See [Customization Guide](docs/customization.md) for all options.
+See [Customization Guide](docs/guides/customization.md) for all options.
 
 ---
 
@@ -228,13 +228,15 @@ See [Customization Guide](docs/customization.md) for all options.
 
 ## Documentation
 
+- [Quickstart](docs/guides/quickstart.md) — 5-minute guide
+- [Complete Workflow](docs/guides/workflow.md) — Full workflow including post-QA patterns
 - [Getting Started](docs/getting-started/installation.md)
-- [What We've Built](docs/what-weve-built.md) — Comprehensive project overview
+- [What We've Built](docs/internal/what-weve-built.md) — Comprehensive project overview
 - [Workflow Concepts](docs/concepts/workflow-phases.md)
-- [Run Command](docs/run-command.md)
-- [Feature Branch Workflows](docs/feature-branch-workflow.md)
-- [Customization](docs/customization.md)
-- [Plugin Updates & Versioning](docs/plugin-updates.md)
+- [Run Command](docs/reference/run-command.md)
+- [Git Workflows](docs/guides/git-workflows.md)
+- [Customization](docs/guides/customization.md)
+- [Plugin Updates & Versioning](docs/internal/plugin-updates.md)
 - [Troubleshooting](docs/troubleshooting.md)
 
 Stack guides: [Next.js](docs/stacks/nextjs.md) · [Rust](docs/stacks/rust.md) · [Python](docs/stacks/python.md) · [Go](docs/stacks/go.md)
@@ -268,7 +270,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
 
 ### Telemetry
 
-Sequant does not collect any usage telemetry. See [docs/telemetry.md](docs/telemetry.md) for details.
+Sequant does not collect any usage telemetry. See [docs/reference/telemetry.md](docs/reference/telemetry.md) for details.
 
 ---
 

package/dist/bin/cli.js

@@ -11,6 +11,8 @@ import { dirname, resolve } from "path";
 import { readFileSync } from "fs";
 import { initCommand } from "../src/commands/init.js";
 import { isLocalNodeModulesInstall } from "../src/lib/version-check.js";
+import { configureUI, banner } from "../src/lib/cli-ui.js";
+import { isCI, isStdoutTTY } from "../src/lib/tty.js";
 // Read version from package.json dynamically
 // Works from both source (bin/) and compiled (dist/bin/) locations
 function getVersion() {
@@ -46,6 +48,15 @@ const program = new Command();
 if (process.argv.includes("--no-color")) {
     process.env.FORCE_COLOR = "0";
 }
+// Configure UI early based on environment and flags
+configureUI({
+    noColor: process.argv.includes("--no-color") || !!process.env.NO_COLOR,
+    jsonMode: process.argv.includes("--json"),
+    verbose: process.argv.includes("--verbose") || process.argv.includes("-v"),
+    isTTY: isStdoutTTY(),
+    isCI: isCI(),
+    minimal: process.env.SEQUANT_MINIMAL === "1",
+});
 // Warn if running from local node_modules (not npx cache or global)
 // This helps users who accidentally have a stale local install
 if (!process.argv.includes("--quiet") && isLocalNodeModulesInstall()) {
@@ -176,14 +187,6 @@ stateCmd
 program.parse();
 // Show help if no command provided
 if (!process.argv.slice(2).length) {
-    console.log(chalk.green(`
-  ╔═══════════════════════════════════════════════════════════╗
-  ║                                                           ║
-  ║   ${chalk.bold("Sequant")} - Quantize your development workflow          ║
-  ║                                                           ║
-  ║   Sequential AI phases with quality gates                 ║
-  ║                                                           ║
-  ╚═══════════════════════════════════════════════════════════╝
-  `));
+    console.log(banner());
     program.help();
 }

package/dist/src/commands/doctor.js

@@ -3,6 +3,7 @@
  */
 import chalk from "chalk";
 import { execSync } from "child_process";
+import { ui, colors } from "../lib/cli-ui.js";
 import { fileExists, isExecutable } from "../lib/fs.js";
 import { getManifest } from "../lib/manifest.js";
 import { commandExists, isGhAuthenticated, isNativeWindows, isWSL, checkOptionalMcpServers, getMcpServersConfig, OPTIONAL_MCP_SERVERS, } from "../lib/system.js";
@@ -67,7 +68,8 @@ export function checkClosedIssues() {
     return missingCommitIssues;
 }
 export async function doctorCommand(options = {}) {
-    console.log(chalk.blue("\n🔍 Running health checks...\n"));
+    console.log(ui.headerBox("SEQUANT HEALTH CHECK"));
+    console.log();
     const checks = [];
     // Track gh availability and auth for conditional checks later
     let ghAvailable = false;
@@ -369,22 +371,22 @@ export async function doctorCommand(options = {}) {
             }
         }
     }
-    // Display results
+    // Display results with status icons
     let passCount = 0;
     let warnCount = 0;
     let failCount = 0;
     for (const check of checks) {
-        const icon = check.status === "pass"
-            ? chalk.green("✓")
+        const statusType = check.status === "pass"
+            ? "success"
             : check.status === "warn"
-                ? chalk.yellow("⚠")
-                : chalk.red("✗");
+                ? "warning"
+                : "error";
         const color = check.status === "pass"
-            ? chalk.green
+            ? colors.success
             : check.status === "warn"
-                ? chalk.yellow
-                : chalk.red;
-        console.log(`${icon} ${chalk.bold(check.name)}: ${color(check.message)}`);
+                ? colors.warning
+                : colors.error;
+        console.log(`  ${ui.statusIcon(statusType)} ${chalk.bold(check.name)}: ${color(check.message)}`);
         if (check.status === "pass")
             passCount++;
         else if (check.status === "warn")
@@ -392,21 +394,24 @@ export async function doctorCommand(options = {}) {
         else
             failCount++;
     }
-    // Summary
-    console.log(chalk.bold("\nSummary:"));
-    console.log(chalk.green(`  ✓ Passed: ${passCount}`));
-    if (warnCount > 0)
-        console.log(chalk.yellow(`  ⚠ Warnings: ${warnCount}`));
-    if (failCount > 0)
-        console.log(chalk.red(`  ✗ Failed: ${failCount}`));
+    // Summary with boxed output
+    const totalChecks = passCount + warnCount + failCount;
+    let summaryTitle;
+    let summaryMessage;
     if (failCount > 0) {
-        console.log(chalk.red("\n❌ Some checks failed. Run `sequant init` to fix."));
+        summaryTitle = `${failCount} check${failCount > 1 ? "s" : ""} failed`;
+        summaryMessage = `Passed: ${passCount}/${totalChecks}\nWarnings: ${warnCount}\nFailed: ${failCount}\n\nRun \`sequant init\` to fix issues.`;
+        console.log("\n" + ui.errorBox(summaryTitle, summaryMessage));
         process.exit(1);
     }
     else if (warnCount > 0) {
-        console.log(chalk.yellow("\n⚠️  Some warnings found but Sequant should work."));
+        summaryTitle = `All checks passed (${warnCount} warning${warnCount > 1 ? "s" : ""})`;
+        summaryMessage = `Passed: ${passCount}/${totalChecks}\nWarnings: ${warnCount}\n\nSequant should work correctly.`;
+        console.log("\n" + ui.warningBox(summaryTitle, summaryMessage));
     }
     else {
-        console.log(chalk.green("\n✅ All checks passed!"));
+        summaryTitle = `All ${totalChecks} checks passed!`;
+        summaryMessage = `Your Sequant installation is healthy.`;
+        console.log("\n" + ui.successBox(summaryTitle, summaryMessage));
     }
 }

package/dist/src/commands/init.js

@@ -3,7 +3,8 @@
  */
 import chalk from "chalk";
 import inquirer from "inquirer";
-import { detectStack, getStackConfig, detectPackageManager, getPackageManagerCommands, } from "../lib/stacks.js";
+import { ui, colors } from "../lib/cli-ui.js";
+import { detectStack, detectAllStacks, getStackConfig, detectPackageManager, getPackageManagerCommands, STACKS, } from "../lib/stacks.js";
 import { copyTemplates } from "../lib/templates.js";
 import { createManifest } from "../lib/manifest.js";
 import { saveConfig } from "../lib/config.js";
@@ -12,6 +13,7 @@ import { fileExists, ensureDir, readFile, writeFile } from "../lib/fs.js";
 import { commandExists, isGhAuthenticated, getInstallHint, } from "../lib/system.js";
 import { shouldUseInteractiveMode, getNonInteractiveReason, } from "../lib/tty.js";
 import { checkAllDependencies, displayDependencyStatus, runSetupWizard, shouldRunSetupWizard, } from "../lib/wizard.js";
+import { saveStackConfig } from "../lib/stack-config.js";
 /**
  * Check prerequisites and display warnings
  */
@@ -66,7 +68,9 @@ function logDefault(label, value) {
     console.log(chalk.blue(`📦 ${label}: ${value} (default)`));
 }
 export async function initCommand(options) {
-    console.log(chalk.green("\n🚀 Initializing Sequant...\n"));
+    // Show banner
+    console.log(ui.banner());
+    console.log(colors.success("\nInitializing Sequant...\n"));
     // Determine if we should use interactive mode
     const useInteractive = shouldUseInteractiveMode(options.interactive);
     const skipPrompts = options.yes || !useInteractive;
@@ -139,54 +143,116 @@ export async function initCommand(options) {
     }
     // Detect or prompt for stack
     let stack = options.stack;
+    let additionalStacks = [];
     if (!stack) {
-        const detected = await detectStack();
-        if (detected && skipPrompts) {
-            stack = detected;
-            logDefault("Detected stack", stack);
-        }
-        else if (detected && !skipPrompts) {
-            const { confirmedStack } = await inquirer.prompt([
+        // Check for multi-stack project in interactive mode
+        const allDetectedStacks = !skipPrompts ? await detectAllStacks() : [];
+        if (allDetectedStacks.length > 1 && !skipPrompts) {
+            // Multi-stack project detected - show checkbox selection
+            console.log(chalk.blue(`\n🔍 Detected ${allDetectedStacks.length} stacks in this project:`));
+            for (const ds of allDetectedStacks) {
+                const location = ds.path ? ` (${ds.path}/)` : " (root)";
+                console.log(chalk.gray(`   • ${STACKS[ds.stack]?.displayName || ds.stack}${location}`));
+            }
+            console.log();
+            // Multi-stack selection prompt
+            const { selectedStacks } = await inquirer.prompt([
                 {
-                    type: "list",
-                    name: "confirmedStack",
-                    message: `Detected ${detected} project. Is this correct?`,
-                    choices: [
-                        { name: `Yes, use ${detected}`, value: detected },
-                        { name: "No, let me choose", value: null },
-                    ],
+                    type: "checkbox",
+                    name: "selectedStacks",
+                    message: "Select stacks to include in your constitution:",
+                    choices: allDetectedStacks.map((ds) => ({
+                        name: `${STACKS[ds.stack]?.displayName || ds.stack}${ds.path ? ` (${ds.path}/)` : " (root)"}`,
+                        value: ds.stack,
+                        checked: true, // Pre-select all detected stacks
+                    })),
+                    validate: (answer) => {
+                        if (answer.length < 1) {
+                            return "You must select at least one stack.";
+                        }
+                        return true;
+                    },
                 },
             ]);
-            stack = confirmedStack;
-        }
-        if (!stack && skipPrompts) {
-            // No detection and skipping prompts: use generic as default
-            stack = "generic";
-            logDefault("Using stack", stack);
+            // First selected stack is the primary
+            if (selectedStacks.length > 0) {
+                stack = selectedStacks[0];
+                additionalStacks = selectedStacks.slice(1);
+            }
+            // Confirm or change primary stack if multiple selected
+            if (selectedStacks.length > 1) {
+                const { primaryStack } = await inquirer.prompt([
+                    {
+                        type: "list",
+                        name: "primaryStack",
+                        message: "Which stack should be the primary? (determines dev URL and commands)",
+                        choices: selectedStacks.map((s) => ({
+                            name: STACKS[s]?.displayName || s,
+                            value: s,
+                        })),
+                    },
+                ]);
+                stack = primaryStack;
+                additionalStacks = selectedStacks.filter((s) => s !== primaryStack);
+            }
         }
-        else if (!stack) {
-            const { selectedStack } = await inquirer.prompt([
-                {
-                    type: "list",
-                    name: "selectedStack",
-                    message: "Select your project stack:",
-                    choices: [
-                        { name: "Next.js / React", value: "nextjs" },
-                        { name: "Astro", value: "astro" },
-                        { name: "SvelteKit", value: "sveltekit" },
-                        { name: "Remix", value: "remix" },
-                        { name: "Nuxt", value: "nuxt" },
-                        { name: "Rust", value: "rust" },
-                        { name: "Python", value: "python" },
-                        { name: "Go", value: "go" },
-                        { name: "Generic (no stack-specific config)", value: "generic" },
-                    ],
-                },
-            ]);
-            stack = selectedStack;
+        else {
+            // Single stack detection (original behavior)
+            const detected = await detectStack();
+            if (detected && skipPrompts) {
+                stack = detected;
+                logDefault("Detected stack", stack);
+            }
+            else if (detected && !skipPrompts) {
+                const { confirmedStack } = await inquirer.prompt([
+                    {
+                        type: "list",
+                        name: "confirmedStack",
+                        message: `Detected ${detected} project. Is this correct?`,
+                        choices: [
+                            { name: `Yes, use ${detected}`, value: detected },
+                            { name: "No, let me choose", value: null },
+                        ],
+                    },
+                ]);
+                stack = confirmedStack;
+            }
+            if (!stack && skipPrompts) {
+                // No detection and skipping prompts: use generic as default
+                stack = "generic";
+                logDefault("Using stack", stack);
+            }
+            else if (!stack) {
+                const { selectedStack } = await inquirer.prompt([
+                    {
+                        type: "list",
+                        name: "selectedStack",
+                        message: "Select your project stack:",
+                        choices: [
+                            { name: "Next.js / React", value: "nextjs" },
+                            { name: "Astro", value: "astro" },
+                            { name: "SvelteKit", value: "sveltekit" },
+                            { name: "Remix", value: "remix" },
+                            { name: "Nuxt", value: "nuxt" },
+                            { name: "Rust", value: "rust" },
+                            { name: "Python", value: "python" },
+                            { name: "Go", value: "go" },
+                            { name: "Generic (no stack-specific config)", value: "generic" },
+                        ],
+                    },
+                ]);
+                stack = selectedStack;
+            }
         }
     }
-    console.log(chalk.blue(`\n📋 Stack: ${stack}`));
+    // Display selected stacks
+    if (additionalStacks.length > 0) {
+        console.log(chalk.blue(`\n📋 Primary Stack: ${stack}`));
+        console.log(chalk.blue(`   Additional: ${additionalStacks.join(", ")}`));
+    }
+    else {
+        console.log(chalk.blue(`\n📋 Stack: ${stack}`));
+    }
     // Detect package manager
     const packageManager = await detectPackageManager();
     if (packageManager) {
@@ -236,21 +302,24 @@ export async function initCommand(options) {
             return;
         }
     }
-    // Create directories
-    console.log(chalk.blue("\n📁 Creating directories..."));
+    // Create directories with spinner
+    const dirSpinner = ui.spinner("Creating directories...");
+    dirSpinner.start();
     await ensureDir(".claude/skills");
     await ensureDir(".claude/hooks");
     await ensureDir(".claude/memory");
     await ensureDir(".claude/.sequant");
     await ensureDir(".sequant/logs");
     await ensureDir("scripts/dev");
+    dirSpinner.succeed("Created directories");
     // Update .gitignore
     const gitignoreUpdated = await updateGitignore();
     if (gitignoreUpdated) {
-        console.log(chalk.blue("📝 Updated .gitignore with Sequant entries"));
+        ui.printStatus("success", "Updated .gitignore with Sequant entries");
     }
     // Save config with tokens
-    console.log(chalk.blue("💾 Saving configuration..."));
+    const configSpinner = ui.spinner("Saving configuration...");
+    configSpinner.start();
     const pmConfig = packageManager
         ? getPackageManagerCommands(packageManager)
         : getPackageManagerCommands("npm");
@@ -263,18 +332,33 @@ export async function initCommand(options) {
         stack: stack,
         initialized: new Date().toISOString(),
     });
+    configSpinner.succeed("Saved configuration");
+    // Save multi-stack configuration if additional stacks selected
+    if (additionalStacks.length > 0) {
+        const stackConfig = {
+            primary: { name: stack },
+            additional: additionalStacks.map((name) => ({ name })),
+        };
+        await saveStackConfig(stackConfig);
+        console.log(chalk.blue("📋 Saved multi-stack configuration"));
+    }
     // Create default settings
-    console.log(chalk.blue("⚙️  Creating default settings..."));
+    const settingsSpinner = ui.spinner("Creating default settings...");
+    settingsSpinner.start();
     await createDefaultSettings();
+    settingsSpinner.succeed("Created default settings");
     // Copy templates (with symlinks for scripts unless --no-symlinks)
-    console.log(chalk.blue("📄 Copying templates..."));
+    const templatesSpinner = ui.spinner("Copying templates...");
+    templatesSpinner.start();
     const { scriptsSymlinked, symlinkResults } = await copyTemplates(stack, tokens, {
         noSymlinks: options.noSymlinks,
         force: options.force,
+        additionalStacks,
     });
+    templatesSpinner.succeed("Copied templates");
     // Report symlink status
     if (scriptsSymlinked) {
-        console.log(chalk.blue("🔗 Created symlinks for scripts/dev/"));
+        ui.printStatus("success", "Created symlinks for scripts/dev/");
     }
     else if (!options.noSymlinks && symlinkResults) {
         // Some symlinks may have fallen back to copies
@@ -294,8 +378,10 @@ export async function initCommand(options) {
         }
     }
     // Create manifest
-    console.log(chalk.blue("📋 Creating manifest..."));
+    const manifestSpinner = ui.spinner("Creating manifest...");
+    manifestSpinner.start();
     await createManifest(stack, packageManager ?? undefined);
+    manifestSpinner.succeed("Created manifest");
     // Build optional suggestions section
     const optionalSuggestions = suggestions.filter((s) => s.startsWith("Optional"));
     const optionalSection = optionalSuggestions.length > 0
@@ -306,19 +392,20 @@ export async function initCommand(options) {
     const prereqReminder = hasRemainingIssues
         ? `\n${chalk.yellow("⚠️  Remember to install missing dependencies before using issue workflows.")}\n${chalk.gray("   Run 'sequant doctor' to verify your setup.\n")}`
         : "";
-    // Success message
-    console.log(chalk.green(`
-✅ Sequant initialized successfully!
-${prereqReminder}
-${chalk.bold("Next steps:")}
-  1. Review .claude/memory/constitution.md and customize for your project
-  2. Start using workflow commands in Claude Code:
+    // Success message with boxed output
+    const nextStepsContent = `${chalk.bold("Next steps:")}
+  1. Review .claude/memory/constitution.md
+  2. Start using workflow commands:
 
-     ${chalk.cyan("/spec 123")}    - Plan implementation for issue #123
-     ${chalk.cyan("/exec 123")}    - Implement the feature
-     ${chalk.cyan("/qa 123")}      - Quality review
-${optionalSection}
-${chalk.bold("Documentation:")}
-  https://github.com/admarble/sequant#readme
-`));
+     ${chalk.cyan("/spec 123")}  - Plan implementation
+     ${chalk.cyan("/exec 123")}  - Implement the feature
+     ${chalk.cyan("/qa 123")}    - Quality review`;
+    console.log("\n" + ui.successBox("Sequant initialized successfully!", nextStepsContent));
+    if (prereqReminder) {
+        console.log(prereqReminder);
+    }
+    if (optionalSection) {
+        console.log(optionalSection);
+    }
+    console.log(chalk.gray("\nDocumentation: https://github.com/admarble/sequant#readme\n"));
 }

package/dist/src/commands/logs.js

@@ -7,6 +7,7 @@ import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
+import { ui, colors } from "../lib/cli-ui.js";
 import { RunLogSchema, LOG_PATHS, } from "../lib/workflow/run-log-schema.js";
 import { manualRotate, getLogStats, formatBytes, } from "../lib/workflow/log-rotation.js";
 import { getSettings } from "../lib/settings.js";
@@ -177,17 +178,17 @@ export async function logsCommand(options) {
         await handleRotation(logDir, options.dryRun ?? false);
         return;
     }
-    console.log(chalk.blue("\n📝 Sequant Run Logs\n"));
-    console.log(chalk.gray(`  Log directory: ${logDir}`));
+    console.log(ui.headerBox("SEQUANT RUN LOGS"));
+    console.log(colors.muted(`\n  Log directory: ${logDir}`));
     // List log files
     const logFiles = listLogFiles(logDir);
     if (logFiles.length === 0) {
-        console.log(chalk.yellow("\n  No logs found."));
-        console.log(chalk.gray("  Run `npx sequant run <issues>` to generate logs."));
+        console.log(colors.warning("\n  No logs found."));
+        console.log(colors.muted("  Run `npx sequant run <issues>` to generate logs."));
         console.log("");
         return;
     }
-    console.log(chalk.gray(`  Found ${logFiles.length} log file(s)\n`));
+    console.log(colors.muted(`  Found ${logFiles.length} log file(s)\n`));
     // Parse all logs
     const logs = logFiles
         .map((filename) => {
@@ -215,7 +216,7 @@ export async function logsCommand(options) {
             displayLogSummary(log, filename);
         }
         // Summary
-        console.log(chalk.blue("\n" + "━".repeat(50)));
+        console.log("\n" + ui.divider());
         const totalPassed = filteredLogs.reduce((sum, { log }) => sum + log.summary.passed, 0);
         const totalFailed = filteredLogs.reduce((sum, { log }) => sum + log.summary.failed, 0);
         const totalDuration = filteredLogs.reduce((sum, { log }) => sum + log.summary.totalDurationSeconds, 0);

package/dist/src/commands/run.d.ts

@@ -4,7 +4,19 @@
  * Runs the Sequant workflow (/spec → /exec → /qa) for one or more issues
  * using the Claude Agent SDK for proper skill invocation.
  */
-import { Phase } from "../lib/workflow/types.js";
+import { Phase, QaVerdict } from "../lib/workflow/types.js";
+/**
+ * Parse QA verdict from phase output
+ *
+ * Looks for verdict patterns in the QA output:
+ * - "### Verdict: READY_FOR_MERGE"
+ * - "**Verdict:** AC_NOT_MET"
+ * - "Verdict: AC_MET_BUT_NOT_A_PLUS"
+ *
+ * @param output - The captured output from QA phase
+ * @returns The parsed verdict or null if not found
+ */
+export declare function parseQaVerdict(output: string): QaVerdict | null;
 /**
  * List all active worktrees with their branches
  */