sequant 1.1.2 → 1.2.0

package/dist/src/lib/tty.js

@@ -0,0 +1,81 @@
+/**
+ * TTY and CI detection utilities for non-interactive mode handling
+ */
+/**
+ * Check if stdin is a TTY (terminal)
+ */
+export function isStdinTTY() {
+    return Boolean(process.stdin.isTTY);
+}
+/**
+ * Check if stdout is a TTY (terminal)
+ */
+export function isStdoutTTY() {
+    return Boolean(process.stdout.isTTY);
+}
+/**
+ * Common CI environment variables that indicate non-interactive mode
+ */
+const CI_ENV_VARS = [
+    "CI",
+    "CONTINUOUS_INTEGRATION",
+    "GITHUB_ACTIONS",
+    "GITLAB_CI",
+    "CIRCLECI",
+    "TRAVIS",
+    "JENKINS_URL",
+    "BUILDKITE",
+    "DRONE",
+    "TEAMCITY_VERSION",
+    "TF_BUILD", // Azure DevOps
+    "CODEBUILD_BUILD_ID", // AWS CodeBuild
+];
+/**
+ * Check if running in a CI environment
+ */
+export function isCI() {
+    return CI_ENV_VARS.some((envVar) => Boolean(process.env[envVar]));
+}
+/**
+ * Determine if interactive mode should be used
+ *
+ * Interactive mode is used when:
+ * 1. --interactive flag is passed (forceInteractive = true)
+ * 2. OR (stdin is TTY AND stdout is TTY AND not in CI)
+ *
+ * @param forceInteractive - Whether --interactive flag was passed
+ * @returns true if interactive prompts should be shown
+ */
+export function shouldUseInteractiveMode(forceInteractive) {
+    if (forceInteractive) {
+        return true;
+    }
+    // Non-interactive if any of these conditions are met
+    if (!isStdinTTY() || !isStdoutTTY() || isCI()) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Get a human-readable reason for non-interactive mode
+ */
+export function getNonInteractiveReason() {
+    if (!isStdinTTY()) {
+        return "stdin is not a terminal (piped input detected)";
+    }
+    if (!isStdoutTTY()) {
+        return "stdout is not a terminal";
+    }
+    if (isCI()) {
+        // Find which CI environment
+        for (const envVar of CI_ENV_VARS) {
+            if (process.env[envVar]) {
+                const ciName = envVar.replace(/_/g, " ").toLowerCase();
+                return `running in CI environment (${ciName})`;
+            }
+        }
+        return "running in CI environment";
+    }
+    return null;
+}
+//# sourceMappingURL=tty.js.map

package/dist/src/lib/tty.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tty.js","sourceRoot":"","sources":["../../../src/lib/tty.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,WAAW,GAAG;IAClB,IAAI;IACJ,wBAAwB;IACxB,gBAAgB;IAChB,WAAW;IACX,UAAU;IACV,QAAQ;IACR,aAAa;IACb,WAAW;IACX,OAAO;IACP,kBAAkB;IAClB,UAAU,EAAE,eAAe;IAC3B,oBAAoB,EAAE,gBAAgB;CACvC,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,IAAI;IAClB,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CAAC,gBAA0B;IACjE,IAAI,gBAAgB,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,qDAAqD;IACrD,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;QAClB,OAAO,gDAAgD,CAAC;IAC1D,CAAC;IACD,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;QACnB,OAAO,0BAA0B,CAAC;IACpC,CAAC;IACD,IAAI,IAAI,EAAE,EAAE,CAAC;QACX,4BAA4B;QAC5B,KAAK,MAAM,MAAM,IAAI,WAAW,EAAE,CAAC;YACjC,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBACxB,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;gBACvD,OAAO,8BAA8B,MAAM,GAAG,CAAC;YACjD,CAAC;QACH,CAAC;QACD,OAAO,2BAA2B,CAAC;IACrC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/src/lib/tty.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tty.test.d.ts.map

package/dist/src/lib/tty.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tty.test.d.ts","sourceRoot":"","sources":["../../../src/lib/tty.test.ts"],"names":[],"mappings":""}

package/dist/src/lib/tty.test.js

@@ -0,0 +1,227 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { isStdinTTY, isStdoutTTY, isCI, shouldUseInteractiveMode, getNonInteractiveReason, } from "./tty.js";
+describe("tty utilities", () => {
+    const originalStdinIsTTY = process.stdin.isTTY;
+    const originalStdoutIsTTY = process.stdout.isTTY;
+    const originalEnv = { ...process.env };
+    beforeEach(() => {
+        // Reset environment
+        process.env = { ...originalEnv };
+        // Clear CI-related env vars
+        const ciVars = [
+            "CI",
+            "CONTINUOUS_INTEGRATION",
+            "GITHUB_ACTIONS",
+            "GITLAB_CI",
+            "CIRCLECI",
+            "TRAVIS",
+            "JENKINS_URL",
+            "BUILDKITE",
+            "DRONE",
+            "TEAMCITY_VERSION",
+            "TF_BUILD",
+            "CODEBUILD_BUILD_ID",
+        ];
+        for (const v of ciVars) {
+            delete process.env[v];
+        }
+    });
+    afterEach(() => {
+        // Restore original values
+        Object.defineProperty(process.stdin, "isTTY", {
+            value: originalStdinIsTTY,
+            writable: true,
+        });
+        Object.defineProperty(process.stdout, "isTTY", {
+            value: originalStdoutIsTTY,
+            writable: true,
+        });
+        process.env = originalEnv;
+    });
+    describe("isStdinTTY", () => {
+        it("returns true when stdin.isTTY is true", () => {
+            Object.defineProperty(process.stdin, "isTTY", {
+                value: true,
+                writable: true,
+            });
+            expect(isStdinTTY()).toBe(true);
+        });
+        it("returns false when stdin.isTTY is false", () => {
+            Object.defineProperty(process.stdin, "isTTY", {
+                value: false,
+                writable: true,
+            });
+            expect(isStdinTTY()).toBe(false);
+        });
+        it("returns false when stdin.isTTY is undefined", () => {
+            Object.defineProperty(process.stdin, "isTTY", {
+                value: undefined,
+                writable: true,
+            });
+            expect(isStdinTTY()).toBe(false);
+        });
+    });
+    describe("isStdoutTTY", () => {
+        it("returns true when stdout.isTTY is true", () => {
+            Object.defineProperty(process.stdout, "isTTY", {
+                value: true,
+                writable: true,
+            });
+            expect(isStdoutTTY()).toBe(true);
+        });
+        it("returns false when stdout.isTTY is false", () => {
+            Object.defineProperty(process.stdout, "isTTY", {
+                value: false,
+                writable: true,
+            });
+            expect(isStdoutTTY()).toBe(false);
+        });
+    });
+    describe("isCI", () => {
+        it("returns false when no CI env vars are set", () => {
+            expect(isCI()).toBe(false);
+        });
+        it("returns true when CI=true", () => {
+            process.env.CI = "true";
+            expect(isCI()).toBe(true);
+        });
+        it("returns true when GITHUB_ACTIONS is set", () => {
+            process.env.GITHUB_ACTIONS = "true";
+            expect(isCI()).toBe(true);
+        });
+        it("returns true when GITLAB_CI is set", () => {
+            process.env.GITLAB_CI = "true";
+            expect(isCI()).toBe(true);
+        });
+        it("returns true when CIRCLECI is set", () => {
+            process.env.CIRCLECI = "true";
+            expect(isCI()).toBe(true);
+        });
+        it("returns true when JENKINS_URL is set", () => {
+            process.env.JENKINS_URL = "http://jenkins.local";
+            expect(isCI()).toBe(true);
+        });
+    });
+    describe("shouldUseInteractiveMode", () => {
+        it("returns true when forceInteractive is true", () => {
+            // Even in non-TTY environment, forceInteractive should win
+            Object.defineProperty(process.stdin, "isTTY", {
+                value: false,
+                writable: true,
+            });
+            expect(shouldUseInteractiveMode(true)).toBe(true);
+        });
+        it("returns true when stdin and stdout are TTY and not in CI", () => {
+            Object.defineProperty(process.stdin, "isTTY", {
+                value: true,
+                writable: true,
+            });
+            Object.defineProperty(process.stdout, "isTTY", {
+                value: true,
+                writable: true,
+            });
+            expect(shouldUseInteractiveMode()).toBe(true);
+        });
+        it("returns false when stdin is not TTY", () => {
+            Object.defineProperty(process.stdin, "isTTY", {
+                value: false,
+                writable: true,
+            });
+            Object.defineProperty(process.stdout, "isTTY", {
+                value: true,
+                writable: true,
+            });
+            expect(shouldUseInteractiveMode()).toBe(false);
+        });
+        it("returns false when stdout is not TTY", () => {
+            Object.defineProperty(process.stdin, "isTTY", {
+                value: true,
+                writable: true,
+            });
+            Object.defineProperty(process.stdout, "isTTY", {
+                value: false,
+                writable: true,
+            });
+            expect(shouldUseInteractiveMode()).toBe(false);
+        });
+        it("returns false when in CI environment", () => {
+            Object.defineProperty(process.stdin, "isTTY", {
+                value: true,
+                writable: true,
+            });
+            Object.defineProperty(process.stdout, "isTTY", {
+                value: true,
+                writable: true,
+            });
+            process.env.CI = "true";
+            expect(shouldUseInteractiveMode()).toBe(false);
+        });
+        it("returns false when forceInteractive is explicitly false and in non-TTY", () => {
+            Object.defineProperty(process.stdin, "isTTY", {
+                value: false,
+                writable: true,
+            });
+            expect(shouldUseInteractiveMode(false)).toBe(false);
+        });
+    });
+    describe("getNonInteractiveReason", () => {
+        it("returns null when in interactive mode", () => {
+            Object.defineProperty(process.stdin, "isTTY", {
+                value: true,
+                writable: true,
+            });
+            Object.defineProperty(process.stdout, "isTTY", {
+                value: true,
+                writable: true,
+            });
+            expect(getNonInteractiveReason()).toBeNull();
+        });
+        it("returns stdin reason when stdin is not TTY", () => {
+            Object.defineProperty(process.stdin, "isTTY", {
+                value: false,
+                writable: true,
+            });
+            Object.defineProperty(process.stdout, "isTTY", {
+                value: true,
+                writable: true,
+            });
+            expect(getNonInteractiveReason()).toBe("stdin is not a terminal (piped input detected)");
+        });
+        it("returns stdout reason when stdout is not TTY", () => {
+            Object.defineProperty(process.stdin, "isTTY", {
+                value: true,
+                writable: true,
+            });
+            Object.defineProperty(process.stdout, "isTTY", {
+                value: false,
+                writable: true,
+            });
+            expect(getNonInteractiveReason()).toBe("stdout is not a terminal");
+        });
+        it("returns CI reason with env var name when in GitHub Actions", () => {
+            Object.defineProperty(process.stdin, "isTTY", {
+                value: true,
+                writable: true,
+            });
+            Object.defineProperty(process.stdout, "isTTY", {
+                value: true,
+                writable: true,
+            });
+            process.env.GITHUB_ACTIONS = "true";
+            expect(getNonInteractiveReason()).toBe("running in CI environment (github actions)");
+        });
+        it("returns CI reason with env var name when in GitLab CI", () => {
+            Object.defineProperty(process.stdin, "isTTY", {
+                value: true,
+                writable: true,
+            });
+            Object.defineProperty(process.stdout, "isTTY", {
+                value: true,
+                writable: true,
+            });
+            process.env.GITLAB_CI = "true";
+            expect(getNonInteractiveReason()).toBe("running in CI environment (gitlab ci)");
+        });
+    });
+});
+//# sourceMappingURL=tty.test.js.map

package/dist/src/lib/tty.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tty.test.js","sourceRoot":"","sources":["../../../src/lib/tty.test.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/workflow/types.d.ts

@@ -46,6 +46,8 @@ export interface PhaseResult {
     success: boolean;
     durationSeconds?: number;
     error?: string;
+    /** Captured output from the phase (used for parsing spec recommendations) */
+    output?: string;
 }
 /**
  * Result of executing all phases for an issue

package/dist/src/lib/workflow/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/lib/workflow/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;AAEzE;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,KAAK,EAA2B,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,mCAAmC;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,WAAW,EAAE,OAAO,CAAC;IACrB,sCAAsC;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,mCAAmC;IACnC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,8BAA8B;IAC9B,UAAU,EAAE,OAAO,CAAC;IACpB,4CAA4C;IAC5C,aAAa,EAAE,OAAO,CAAC;IACvB,qBAAqB;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,mCAAmC;IACnC,YAAY,EAAE,OAAO,CAAC;IACtB,4CAA4C;IAC5C,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,eAW5B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;CAClB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/lib/workflow/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;AAEzE;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,KAAK,EAA2B,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,mCAAmC;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,WAAW,EAAE,OAAO,CAAC;IACrB,sCAAsC;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,mCAAmC;IACnC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,8BAA8B;IAC9B,UAAU,EAAE,OAAO,CAAC;IACpB,4CAA4C;IAC5C,aAAa,EAAE,OAAO,CAAC;IACvB,qBAAqB;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,mCAAmC;IACnC,YAAY,EAAE,OAAO,CAAC;IACtB,4CAA4C;IAC5C,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,eAW5B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;CAClB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Quantize your development workflow - Sequential AI phases with quality gates",
   "type": "module",
   "bin": {

package/templates/hooks/post-tool.sh

@@ -190,14 +190,16 @@ if [[ "$TOOL_NAME" == "Bash" ]]; then
 fi
 
 # === DETECT TEST FAILURES ===
-if [[ "$TOOL_NAME" == "Bash" ]] && echo "$TOOL_INPUT" | grep -qE 'npm (test|run test)'; then
+# Supports: npm, bun, yarn, pnpm
+if [[ "$TOOL_NAME" == "Bash" ]] && echo "$TOOL_INPUT" | grep -qE '(npm (test|run test)|bun (test|run test)|yarn (test|run test)|pnpm (test|run test))'; then
     if echo "$TOOL_OUTPUT" | grep -qE '(FAIL|failed|Error:)'; then
         echo "$(date +%H:%M:%S) TEST_FAILURE detected" >> "$QUALITY_LOG"
     fi
 fi
 
 # === DETECT BUILD FAILURES ===
-if [[ "$TOOL_NAME" == "Bash" ]] && echo "$TOOL_INPUT" | grep -qE 'npm run build'; then
+# Supports: npm, bun, yarn, pnpm
+if [[ "$TOOL_NAME" == "Bash" ]] && echo "$TOOL_INPUT" | grep -qE '(npm run build|bun run build|yarn build|yarn run build|pnpm run build)'; then
     if echo "$TOOL_OUTPUT" | grep -qE '(error TS|Build failed|Error:)'; then
         echo "$(date +%H:%M:%S) BUILD_FAILURE detected" >> "$QUALITY_LOG"
     fi

package/templates/scripts/new-feature.sh

@@ -1,8 +1,9 @@
 #!/bin/bash
 
 # Create a new feature worktree from a GitHub issue
-# Usage: ./scripts/new-feature.sh <issue-number>
+# Usage: ./scripts/new-feature.sh <issue-number> [--stash]
 # Example: ./scripts/new-feature.sh 4
+# Example: ./scripts/new-feature.sh 4 --stash  # Auto-stash uncommitted changes
 
 set -e
 
@@ -13,16 +14,33 @@ BLUE='\033[0;34m'
 YELLOW='\033[1;33m'
 NC='\033[0m' # No Color
 
+# Parse arguments (flexible position for --stash flag)
+STASH_FLAG=false
+ISSUE_NUMBER=""
+
+for arg in "$@"; do
+    case $arg in
+        --stash)
+            STASH_FLAG=true
+            ;;
+        *)
+            # First non-flag argument is the issue number
+            if [ -z "$ISSUE_NUMBER" ]; then
+                ISSUE_NUMBER=$arg
+            fi
+            ;;
+    esac
+done
+
 # Check if issue number is provided
-if [ -z "$1" ]; then
+if [ -z "$ISSUE_NUMBER" ]; then
     echo -e "${RED}❌ Error: Issue number required${NC}"
-    echo "Usage: ./scripts/new-feature.sh <issue-number>"
+    echo "Usage: ./scripts/new-feature.sh <issue-number> [--stash]"
     echo "Example: ./scripts/new-feature.sh 4"
+    echo "Example: ./scripts/new-feature.sh 4 --stash"
     exit 1
 fi
 
-ISSUE_NUMBER=$1
-
 # Check if gh CLI is installed
 if ! command -v gh &> /dev/null; then
     echo -e "${RED}❌ GitHub CLI not found. Install from: https://cli.github.com${NC}"
@@ -82,10 +100,16 @@ echo ""
 
 # Check for uncommitted changes before switching branches
 if ! git diff-index --quiet HEAD -- 2>/dev/null; then
-    echo -e "${RED}❌ Working tree has uncommitted changes${NC}"
-    echo -e "${YELLOW}   Commit or stash your changes first:${NC}"
-    echo -e "   git stash push -m 'WIP before issue #${ISSUE_NUMBER}'"
-    exit 1
+    if [ "$STASH_FLAG" = true ]; then
+        echo -e "${YELLOW}📦 Stashing uncommitted changes...${NC}"
+        git stash push --include-untracked -m "WIP before issue #${ISSUE_NUMBER}"
+        echo -e "${GREEN}   Changes stashed successfully${NC}"
+    else
+        echo -e "${RED}❌ Working tree has uncommitted changes${NC}"
+        echo -e "${YELLOW}   Use --stash to auto-stash, or manually:${NC}"
+        echo -e "   git stash push -m 'WIP before issue #${ISSUE_NUMBER}'"
+        exit 1
+    fi
 fi
 
 # Check if branch already exists

package/templates/skills/solve/SKILL.md

@@ -58,7 +58,7 @@ Provide a clear, actionable response with:
 
 2. **Recommended Commands** in order
 
-3. **CLI Command** - ALWAYS include `sequant run <issue>` for terminal/CI usage
+3. **CLI Command** - ALWAYS include `npx sequant run <issue>` for terminal/CI usage
 
 4. **Explanation** of why this workflow was chosen
 
@@ -102,10 +102,12 @@ For comprehensive quality with automatic fix iterations:
 
 Run from terminal (useful for automation/CI):
 ```bash
-sequant run 152        # Single issue
-sequant run 152 153    # Multiple issues
+npx sequant run 152        # Single issue
+npx sequant run 152 153    # Multiple issues
 ```
 
+> **Tip:** For frequent use, install globally with `npm install -g sequant` to run `sequant` directly without `npx`.
+
 ### Notes
 - Issue #152 requires UI testing due to `ui` label
 - Issue #153 is a bug fix - simpler workflow recommended
@@ -114,6 +116,16 @@ sequant run 152 153    # Multiple issues
 
 ## Workflow Selection Logic
 
+**Note:** `npx sequant run` now uses **spec-driven phase detection**. It runs `/spec` first, which analyzes the issue and outputs a `## Recommended Workflow` section. The CLI then parses this to determine subsequent phases.
+
+### How It Works
+
+1. **Bug fixes** (labels: `bug`, `fix`) → Skip spec, run `exec → qa` directly
+2. **All other issues** → Run `/spec` first, which recommends phases based on:
+   - UI/frontend changes → Add `test` phase
+   - Complex refactors → Enable quality loop
+   - Security-sensitive → Add `security-review` phase
+
 ### Standard Workflow (Most Issues)
 ```
 /spec → /exec → /qa
@@ -148,25 +160,27 @@ Runs complete workflow with automatic fix iterations.
 
 ## CLI Alternative
 
-Use `sequant run` for batch execution from the command line:
+Use `npx sequant run` for batch execution from the command line:
 
 ```bash
 # Run workflow for single issue
-sequant run 152
+npx sequant run 152
 
 # Multiple issues in parallel
-sequant run 152 153 154
+npx sequant run 152 153 154
 
 # Sequential execution (respects dependencies)
-sequant run 152 153 --sequential
+npx sequant run 152 153 --sequential
 
 # Custom phases
-sequant run 152 --phases spec,exec,qa
+npx sequant run 152 --phases spec,exec,qa
 
 # Dry run (shows what would execute)
-sequant run 152 --dry-run
+npx sequant run 152 --dry-run
 ```
 
+> **Tip:** Install globally with `npm install -g sequant` to omit the `npx` prefix.
+
 ## Edge Cases
 
 ### Multiple Issues with Different Types
@@ -203,7 +217,7 @@ If issues depend on each other:
 
 - [ ] **Issue Summary Table** - Table with Issue, Title, Labels, Workflow columns
 - [ ] **Recommended Workflow** - Slash commands in order for each issue
-- [ ] **CLI Command** - `sequant run <issue-numbers>` command (REQUIRED)
+- [ ] **CLI Command** - `npx sequant run <issue-numbers>` command (REQUIRED)
 - [ ] **Explanation** - Brief notes explaining workflow choices
 
 **DO NOT respond until all items are verified.**
@@ -232,9 +246,11 @@ You MUST use this exact structure:
 
 Run from terminal (useful for automation/CI):
 \`\`\`bash
-sequant run <ISSUE_NUMBERS>
+npx sequant run <ISSUE_NUMBERS>
 \`\`\`
 
+> **Tip:** Install globally with `npm install -g sequant` to omit the `npx` prefix.
+
 ### Notes
 <!-- FILL: explanation of workflow choices -->
 ```

package/templates/skills/spec/SKILL.md

@@ -143,7 +143,26 @@ Ask the user to confirm or adjust:
 
 **Do NOT start implementation** - this is planning-only.
 
-### 4. Issue Comment Draft
+### 4. Recommended Workflow
+
+Analyze the issue and recommend the optimal workflow phases:
+
+```markdown
+## Recommended Workflow
+
+**Phases:** spec → exec → qa
+**Quality Loop:** disabled
+**Reasoning:** [Brief explanation of why these phases were chosen]
+```
+
+**Phase Selection Logic:**
+- **UI/Frontend changes** → Add `test` phase (browser testing)
+- **Bug fixes** → Skip `spec` if already well-defined
+- **Complex refactors** → Enable quality loop
+- **Security-sensitive** → Add `security-review` phase
+- **Documentation only** → Skip `spec`, just `exec → qa`
+
+### 5. Issue Comment Draft
 
 Generate a Markdown snippet with:
 - AC checklist with verification criteria
@@ -159,7 +178,7 @@ Label clearly as:
 --- DRAFT GITHUB ISSUE COMMENT (PLAN) ---
 ```
 
-### 5. Update GitHub Issue
+### 6. Update GitHub Issue
 
 Post the draft comment to GitHub:
 ```bash
@@ -176,6 +195,7 @@ gh issue edit <issue-number> --add-label "planned"
 - [ ] **AC Checklist** - Numbered AC items (AC-1, AC-2, etc.) with descriptions
 - [ ] **Verification Criteria** - Each AC has Verification Method and Test Scenario
 - [ ] **Implementation Plan** - 3-7 concrete steps with codebase references
+- [ ] **Recommended Workflow** - Phases, Quality Loop setting, and Reasoning
 - [ ] **Open Questions** - Any ambiguities with recommended defaults
 - [ ] **Issue Comment Draft** - Formatted for GitHub posting
 
@@ -221,6 +241,14 @@ You MUST include these sections in order:
 
 ---
 
+## Recommended Workflow
+
+**Phases:** exec → qa
+**Quality Loop:** disabled
+**Reasoning:** [Why these phases based on issue analysis]
+
+---
+
 --- DRAFT GITHUB ISSUE COMMENT (PLAN) ---
 
 [Complete formatted comment for GitHub]