sequant 1.13.0 → 1.13.2

package/.claude-plugin/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "sequant",
+  "description": "Sequant plugin marketplace - structured workflow system for Claude Code",
+  "owner": {
+    "name": "admarble",
+    "email": "github@admarble.com"
+  },
+  "plugins": [
+    {
+      "name": "sequant",
+      "description": "Structured workflow system for Claude Code - GitHub issue resolution with spec, exec, test, and QA phases. Includes 16 skills for planning, implementation, testing, code review, and quality assurance.",
+      "version": "1.13.0",
+      "author": {
+        "name": "admarble",
+        "email": "github@admarble.com"
+      },
+      "source": "./",
+      "category": "workflow"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "sequant",
+  "description": "Structured workflow system for Claude Code - GitHub issue resolution with spec, exec, test, and QA phases",
+  "version": "1.13.2",
+  "author": {
+    "name": "admarble",
+    "email": "github@admarble.com"
+  }
+}

package/dist/bin/cli.js

@@ -43,6 +43,7 @@ import { logsCommand } from "../src/commands/logs.js";
 import { statsCommand } from "../src/commands/stats.js";
 import { dashboardCommand } from "../src/commands/dashboard.js";
 import { stateInitCommand, stateRebuildCommand, stateCleanCommand, } from "../src/commands/state.js";
+import { syncCommand } from "../src/commands/sync.js";
 const program = new Command();
 // Handle --no-color before parsing
 if (process.argv.includes("--no-color")) {
@@ -85,6 +86,12 @@ program
     .option("-d, --dry-run", "Show what would be updated without making changes")
     .option("-f, --force", "Overwrite local modifications")
     .action(updateCommand);
+program
+    .command("sync")
+    .description("Sync skills and templates from the Sequant package (non-interactive)")
+    .option("-f, --force", "Sync even if versions match")
+    .option("-q, --quiet", "Suppress output")
+    .action(syncCommand);
 program
     .command("doctor")
     .description("Check your Sequant installation for issues")

package/dist/src/commands/doctor.js

@@ -8,6 +8,7 @@ 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";
 import { checkVersionThorough, getVersionWarning, } from "../lib/version-check.js";
+import { areSkillsOutdated } from "./sync.js";
 /**
  * Labels that indicate an issue should be skipped from closed-issue verification
  * (case-insensitive matching)
@@ -157,6 +158,22 @@ export async function doctorCommand(options = {}) {
             message: `Missing skills: ${missingSkills.join(", ")}`,
         });
     }
+    // Check 3.5: Skills version (are skills in sync with package?)
+    const skillsStatus = await areSkillsOutdated();
+    if (skillsStatus.outdated) {
+        checks.push({
+            name: "Skills Version",
+            status: "warn",
+            message: `Outdated (${skillsStatus.currentVersion || "unknown"} → ${skillsStatus.packageVersion}) - run: npx sequant sync`,
+        });
+    }
+    else {
+        checks.push({
+            name: "Skills Version",
+            status: "pass",
+            message: `Up to date (${skillsStatus.packageVersion})`,
+        });
+    }
     // Check 4: Hooks directory
     const hooksExist = await fileExists(".claude/hooks");
     if (hooksExist) {

package/dist/src/commands/run.js

@@ -21,6 +21,7 @@ import { checkVersionCached, getVersionWarning } from "../lib/version-check.js";
 import { MetricsWriter } from "../lib/workflow/metrics-writer.js";
 import { determineOutcome, } from "../lib/workflow/metrics-schema.js";
 import { ui, colors } from "../lib/cli-ui.js";
+import { PhaseSpinner } from "../lib/phase-spinner.js";
 /**
  * Slugify a title for branch naming
  */
@@ -581,7 +582,7 @@ const ISOLATED_PHASES = ["exec", "test", "qa"];
 /**
  * Execute a single phase for an issue using Claude Agent SDK
  */
-async function executePhase(issueNumber, phase, config, sessionId, worktreePath, shutdownManager) {
+async function executePhase(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner) {
     const startTime = Date.now();
     if (config.dryRun) {
         // Dry run - just simulate
@@ -686,7 +687,10 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
                     capturedOutput += textContent;
                     // Show streaming output in verbose mode
                     if (config.verbose) {
+                        // Pause spinner during verbose streaming to avoid terminal corruption
+                        spinner?.pause();
                         process.stdout.write(chalk.gray(textContent));
+                        spinner?.resume();
                     }
                 }
             }
@@ -1516,7 +1520,14 @@ async function runIssueWithLogging(issueNumber, config, logWriter, stateManager,
         else {
             // Run spec first to get recommended workflow
             console.log(chalk.gray(`    Running spec to determine workflow...`));
-            console.log(chalk.gray(`    ⏳ spec...`));
+            // Create spinner for spec phase (1 of estimated 3: spec, exec, qa)
+            const specSpinner = new PhaseSpinner({
+                phase: "spec",
+                phaseIndex: 1,
+                totalPhases: 3, // Estimate; will be refined after spec
+                shutdownManager,
+            });
+            specSpinner.start();
             // Track spec phase start in state
             if (stateManager) {
                 try {
@@ -1529,7 +1540,7 @@ async function runIssueWithLogging(issueNumber, config, logWriter, stateManager,
             const specStartTime = new Date();
             // Note: spec runs in main repo (not worktree) for planning
             const specResult = await executePhase(issueNumber, "spec", config, sessionId, worktreePath, // Will be ignored for spec (non-isolated phase)
-            shutdownManager);
+            shutdownManager, specSpinner);
             const specEndTime = new Date();
             if (specResult.sessionId) {
                 sessionId = specResult.sessionId;
@@ -1567,7 +1578,7 @@ async function runIssueWithLogging(issueNumber, config, logWriter, stateManager,
                 }
             }
             if (!specResult.success) {
-                console.log(chalk.red(`    ✗ spec: ${specResult.error}`));
+                specSpinner.fail(specResult.error);
                 const durationSeconds = (Date.now() - startTime) / 1000;
                 return {
                     issueNumber,
@@ -1577,10 +1588,7 @@ async function runIssueWithLogging(issueNumber, config, logWriter, stateManager,
                     loopTriggered: false,
                 };
             }
-            const duration = specResult.durationSeconds
-                ? ` (${formatDuration(specResult.durationSeconds)})`
-                : "";
-            console.log(chalk.green(`    ✓ spec${duration}`));
+            specSpinner.succeed();
             // Parse recommended workflow from spec output
             const parsedWorkflow = specResult.output
                 ? parseRecommendedWorkflow(specResult.output)
@@ -1634,8 +1642,22 @@ async function runIssueWithLogging(issueNumber, config, logWriter, stateManager,
             loopTriggered = true;
         }
         let phasesFailed = false;
-        for (const phase of phases) {
-            console.log(chalk.gray(`    ⏳ ${phase}...`));
+        // Calculate total phases for progress indicator
+        // If spec already ran in auto-detect mode, it's counted separately
+        const totalPhases = specAlreadyRan ? phases.length + 1 : phases.length;
+        const phaseIndexOffset = specAlreadyRan ? 1 : 0;
+        for (let phaseIdx = 0; phaseIdx < phases.length; phaseIdx++) {
+            const phase = phases[phaseIdx];
+            const phaseNumber = phaseIdx + 1 + phaseIndexOffset;
+            // Create spinner for this phase
+            const phaseSpinner = new PhaseSpinner({
+                phase,
+                phaseIndex: phaseNumber,
+                totalPhases,
+                shutdownManager,
+                iteration: useQualityLoop ? iteration : undefined,
+            });
+            phaseSpinner.start();
             // Track phase start in state
             if (stateManager) {
                 try {
@@ -1646,7 +1668,7 @@ async function runIssueWithLogging(issueNumber, config, logWriter, stateManager,
                 }
             }
             const phaseStartTime = new Date();
-            const result = await executePhase(issueNumber, phase, config, sessionId, worktreePath, shutdownManager);
+            const result = await executePhase(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, phaseSpinner);
             const phaseEndTime = new Date();
             // Capture session ID for subsequent phases
             if (result.sessionId) {
@@ -1690,29 +1712,34 @@ async function runIssueWithLogging(issueNumber, config, logWriter, stateManager,
                 }
             }
             if (result.success) {
-                const duration = result.durationSeconds
-                    ? ` (${formatDuration(result.durationSeconds)})`
-                    : "";
-                console.log(chalk.green(`    ✓ ${phase}${duration}`));
+                phaseSpinner.succeed();
             }
             else {
-                console.log(chalk.red(`    ✗ ${phase}: ${result.error}`));
+                phaseSpinner.fail(result.error);
                 phasesFailed = true;
                 // If quality loop enabled, run loop phase to fix issues
                 if (useQualityLoop && iteration < maxIterations) {
-                    console.log(chalk.yellow(`    Running /loop to fix issues...`));
-                    const loopResult = await executePhase(issueNumber, "loop", config, sessionId, worktreePath, shutdownManager);
+                    // Create spinner for loop phase
+                    const loopSpinner = new PhaseSpinner({
+                        phase: "loop",
+                        phaseIndex: phaseNumber,
+                        totalPhases,
+                        shutdownManager,
+                        iteration,
+                    });
+                    loopSpinner.start();
+                    const loopResult = await executePhase(issueNumber, "loop", config, sessionId, worktreePath, shutdownManager, loopSpinner);
                     phaseResults.push(loopResult);
                     if (loopResult.sessionId) {
                         sessionId = loopResult.sessionId;
                     }
                     if (loopResult.success) {
-                        console.log(chalk.green(`    ✓ loop - retrying phases`));
+                        loopSpinner.succeed();
                         // Continue to next iteration
                         break;
                     }
                     else {
-                        console.log(chalk.red(`    ✗ loop: ${loopResult.error}`));
+                        loopSpinner.fail(loopResult.error);
                     }
                 }
                 // Stop on first failure (if not in quality loop or loop failed)

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

@@ -0,0 +1,28 @@
+/**
+ * sequant sync - Fast, non-interactive template sync
+ *
+ * Syncs skills and other templates from the package to the local project.
+ * Designed for plugin users who need to update after upgrading sequant.
+ */
+interface SyncOptions {
+    force?: boolean;
+    quiet?: boolean;
+}
+/**
+ * Get the version of skills currently installed
+ */
+export declare function getSkillsVersion(): Promise<string | null>;
+/**
+ * Check if skills are outdated compared to package version
+ */
+export declare function areSkillsOutdated(): Promise<{
+    outdated: boolean;
+    currentVersion: string | null;
+    packageVersion: string;
+}>;
+export declare function syncCommand(options?: SyncOptions): Promise<void>;
+/**
+ * Check and warn if skills are outdated (for use by other commands)
+ */
+export declare function checkAndWarnSkillsOutdated(): Promise<boolean>;
+export {};

package/dist/src/commands/sync.js

@@ -0,0 +1,102 @@
+/**
+ * sequant sync - Fast, non-interactive template sync
+ *
+ * Syncs skills and other templates from the package to the local project.
+ * Designed for plugin users who need to update after upgrading sequant.
+ */
+import chalk from "chalk";
+import { getManifest, updateManifest, getPackageVersion, } from "../lib/manifest.js";
+import { copyTemplates } from "../lib/templates.js";
+import { getConfig } from "../lib/config.js";
+import { writeFile, readFile, fileExists } from "../lib/fs.js";
+const SKILLS_VERSION_PATH = ".claude/skills/.sequant-version";
+/**
+ * Get the version of skills currently installed
+ */
+export async function getSkillsVersion() {
+    if (!(await fileExists(SKILLS_VERSION_PATH))) {
+        return null;
+    }
+    try {
+        const content = await readFile(SKILLS_VERSION_PATH);
+        return content.trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if skills are outdated compared to package version
+ */
+export async function areSkillsOutdated() {
+    const currentVersion = await getSkillsVersion();
+    const packageVersion = getPackageVersion();
+    return {
+        outdated: currentVersion !== packageVersion,
+        currentVersion,
+        packageVersion,
+    };
+}
+/**
+ * Update the skills version marker
+ */
+async function updateSkillsVersion() {
+    await writeFile(SKILLS_VERSION_PATH, getPackageVersion());
+}
+export async function syncCommand(options = {}) {
+    const { force = false, quiet = false } = options;
+    if (!quiet) {
+        console.log(chalk.blue("\n🔄 Syncing templates...\n"));
+    }
+    // Check if initialized
+    const manifest = await getManifest();
+    if (!manifest) {
+        console.log(chalk.red("❌ Sequant is not initialized. Run `sequant init` first."));
+        process.exitCode = 1;
+        return;
+    }
+    const packageVersion = getPackageVersion();
+    const skillsVersion = await getSkillsVersion();
+    if (!quiet) {
+        console.log(chalk.gray(`Skills version: ${skillsVersion || "(unknown)"}`));
+        console.log(chalk.gray(`Package version: ${packageVersion}`));
+        console.log(chalk.gray(`Stack: ${manifest.stack}\n`));
+    }
+    // Check if sync is needed
+    if (!force && skillsVersion === packageVersion) {
+        if (!quiet) {
+            console.log(chalk.green("✅ Skills are already up to date!"));
+        }
+        return;
+    }
+    // Get config tokens for template processing
+    const config = await getConfig();
+    const tokens = config?.tokens || {};
+    // Copy templates with force to overwrite existing files
+    const copyOptions = {
+        force: true, // Always overwrite when syncing
+    };
+    if (!quiet) {
+        console.log(chalk.blue("📥 Copying templates..."));
+    }
+    await copyTemplates(manifest.stack, tokens, copyOptions);
+    // Update version markers
+    await updateSkillsVersion();
+    await updateManifest();
+    if (!quiet) {
+        console.log(chalk.green(`\n✅ Synced to v${packageVersion}`));
+        console.log(chalk.gray("\nSkills, hooks, and memory files have been updated."));
+    }
+}
+/**
+ * Check and warn if skills are outdated (for use by other commands)
+ */
+export async function checkAndWarnSkillsOutdated() {
+    const { outdated, currentVersion, packageVersion } = await areSkillsOutdated();
+    if (outdated) {
+        console.log(chalk.yellow(`\n⚠️  Skills are outdated (${currentVersion || "unknown"} → ${packageVersion})`));
+        console.log(chalk.yellow("   Run: npx sequant sync\n"));
+        return true;
+    }
+    return false;
+}

package/dist/src/lib/phase-spinner.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Phase Spinner - Animated spinner with elapsed time for phase execution
+ *
+ * Wraps the cli-ui spinner with:
+ * - Elapsed time tracking (updates every 5 seconds)
+ * - Phase progress indicator (e.g., "spec (1/3)")
+ * - Integration with ShutdownManager for graceful cleanup
+ *
+ * @example
+ * ```typescript
+ * const spinner = new PhaseSpinner({
+ *   phase: 'exec',
+ *   phaseIndex: 2,
+ *   totalPhases: 3,
+ *   shutdownManager,
+ * });
+ *
+ * spinner.start();
+ * // ... phase execution
+ * spinner.succeed(); // Shows "✓ exec (2/3) (45s)"
+ * ```
+ */
+import type { ShutdownManager } from "./shutdown.js";
+/**
+ * Options for creating a PhaseSpinner
+ */
+export interface PhaseSpinnerOptions {
+    /** Phase name (e.g., "spec", "exec", "qa") */
+    phase: string;
+    /** Current phase index (1-based) */
+    phaseIndex: number;
+    /** Total number of phases */
+    totalPhases: number;
+    /** Optional ShutdownManager for graceful cleanup */
+    shutdownManager?: ShutdownManager;
+    /** Optional prefix for indentation (default: "    ") */
+    prefix?: string;
+    /** Optional quality loop iteration (shows "iteration N" if > 1) */
+    iteration?: number;
+}
+/**
+ * Format elapsed time in human-readable format
+ *
+ * @param seconds - Elapsed time in seconds
+ * @returns Formatted string (e.g., "45s", "2m 15s", "1h 5m")
+ */
+export declare function formatElapsedTime(seconds: number): string;
+/**
+ * PhaseSpinner - Animated spinner with elapsed time and phase progress
+ *
+ * Features:
+ * - Animated spinner (or text fallback) via cli-ui
+ * - Elapsed time tracking with automatic updates
+ * - Phase progress indicator (e.g., "exec (2/3)")
+ * - ShutdownManager integration for graceful Ctrl+C cleanup
+ * - Pause/resume for verbose streaming output
+ */
+export declare class PhaseSpinner {
+    private spinner;
+    private startTime;
+    private intervalId;
+    private disposed;
+    private paused;
+    private readonly phase;
+    private readonly phaseIndex;
+    private readonly totalPhases;
+    private readonly shutdownManager?;
+    private readonly prefix;
+    private readonly iteration?;
+    private readonly cleanupName;
+    constructor(options: PhaseSpinnerOptions);
+    /**
+     * Format the spinner text with phase, progress, and elapsed time
+     */
+    private formatText;
+    /**
+     * Update the spinner text with current elapsed time
+     */
+    private updateElapsedTime;
+    /**
+     * Start the spinner
+     *
+     * Begins the animation and elapsed time tracking.
+     */
+    start(): PhaseSpinner;
+    /**
+     * Mark the phase as succeeded
+     *
+     * Stops the spinner and shows a checkmark with total duration.
+     */
+    succeed(customText?: string): PhaseSpinner;
+    /**
+     * Mark the phase as failed
+     *
+     * Stops the spinner and shows an error indicator with message.
+     */
+    fail(error?: string): PhaseSpinner;
+    /**
+     * Stop the spinner without success/fail indication
+     *
+     * Use this for cleanup or when the phase is interrupted.
+     */
+    stop(): PhaseSpinner;
+    /**
+     * Pause the spinner (for verbose streaming output)
+     *
+     * Temporarily stops the animation without disposing.
+     * Call resume() to continue.
+     */
+    pause(): PhaseSpinner;
+    /**
+     * Resume the spinner after pause
+     *
+     * Restarts the animation with updated elapsed time.
+     */
+    resume(): PhaseSpinner;
+    /**
+     * Check if the spinner is currently active
+     */
+    get isSpinning(): boolean;
+    /**
+     * Get the total elapsed time in seconds
+     */
+    get elapsedSeconds(): number;
+    /**
+     * Dispose of the spinner and clean up resources
+     *
+     * Called automatically by succeed(), fail(), or stop().
+     * Safe to call multiple times.
+     */
+    dispose(): void;
+    /**
+     * Clear the elapsed time update interval
+     */
+    private clearInterval;
+    /**
+     * Unregister from ShutdownManager
+     */
+    private unregisterCleanup;
+}
+/**
+ * Create a PhaseSpinner with the given options
+ *
+ * Convenience function matching the pattern of cli-ui.spinner().
+ */
+export declare function phaseSpinner(options: PhaseSpinnerOptions): PhaseSpinner;

package/dist/src/lib/phase-spinner.js

@@ -0,0 +1,255 @@
+/**
+ * Phase Spinner - Animated spinner with elapsed time for phase execution
+ *
+ * Wraps the cli-ui spinner with:
+ * - Elapsed time tracking (updates every 5 seconds)
+ * - Phase progress indicator (e.g., "spec (1/3)")
+ * - Integration with ShutdownManager for graceful cleanup
+ *
+ * @example
+ * ```typescript
+ * const spinner = new PhaseSpinner({
+ *   phase: 'exec',
+ *   phaseIndex: 2,
+ *   totalPhases: 3,
+ *   shutdownManager,
+ * });
+ *
+ * spinner.start();
+ * // ... phase execution
+ * spinner.succeed(); // Shows "✓ exec (2/3) (45s)"
+ * ```
+ */
+import { spinner as createSpinner } from "./cli-ui.js";
+/**
+ * Elapsed time update interval in milliseconds
+ */
+const ELAPSED_UPDATE_INTERVAL_MS = 5000;
+/**
+ * Format elapsed time in human-readable format
+ *
+ * @param seconds - Elapsed time in seconds
+ * @returns Formatted string (e.g., "45s", "2m 15s", "1h 5m")
+ */
+export function formatElapsedTime(seconds) {
+    if (seconds < 60) {
+        return `${Math.floor(seconds)}s`;
+    }
+    if (seconds < 3600) {
+        const minutes = Math.floor(seconds / 60);
+        const remainingSeconds = Math.floor(seconds % 60);
+        return remainingSeconds > 0
+            ? `${minutes}m ${remainingSeconds}s`
+            : `${minutes}m`;
+    }
+    const hours = Math.floor(seconds / 3600);
+    const remainingMinutes = Math.floor((seconds % 3600) / 60);
+    return remainingMinutes > 0 ? `${hours}h ${remainingMinutes}m` : `${hours}h`;
+}
+/**
+ * PhaseSpinner - Animated spinner with elapsed time and phase progress
+ *
+ * Features:
+ * - Animated spinner (or text fallback) via cli-ui
+ * - Elapsed time tracking with automatic updates
+ * - Phase progress indicator (e.g., "exec (2/3)")
+ * - ShutdownManager integration for graceful Ctrl+C cleanup
+ * - Pause/resume for verbose streaming output
+ */
+export class PhaseSpinner {
+    spinner;
+    startTime = 0;
+    intervalId = null;
+    disposed = false;
+    paused = false;
+    phase;
+    phaseIndex;
+    totalPhases;
+    shutdownManager;
+    prefix;
+    iteration;
+    cleanupName;
+    constructor(options) {
+        this.phase = options.phase;
+        this.phaseIndex = options.phaseIndex;
+        this.totalPhases = options.totalPhases;
+        this.shutdownManager = options.shutdownManager;
+        this.prefix = options.prefix ?? "    ";
+        this.iteration = options.iteration;
+        this.cleanupName = `phase-spinner-${options.phase}`;
+        // Create the underlying spinner with initial text
+        this.spinner = createSpinner(this.formatText(0));
+    }
+    /**
+     * Format the spinner text with phase, progress, and elapsed time
+     */
+    formatText(elapsedSeconds) {
+        const progress = `(${this.phaseIndex}/${this.totalPhases})`;
+        const elapsed = elapsedSeconds > 0 ? ` ${formatElapsedTime(elapsedSeconds)}` : "";
+        const iterationSuffix = this.iteration && this.iteration > 1
+            ? ` [iteration ${this.iteration}]`
+            : "";
+        return `${this.prefix}${this.phase} ${progress}...${elapsed}${iterationSuffix}`;
+    }
+    /**
+     * Update the spinner text with current elapsed time
+     */
+    updateElapsedTime() {
+        if (this.disposed || this.paused)
+            return;
+        const elapsedSeconds = (Date.now() - this.startTime) / 1000;
+        this.spinner.text = this.formatText(elapsedSeconds);
+    }
+    /**
+     * Start the spinner
+     *
+     * Begins the animation and elapsed time tracking.
+     */
+    start() {
+        if (this.disposed)
+            return this;
+        this.startTime = Date.now();
+        this.spinner.start(this.formatText(0));
+        // Start elapsed time update interval
+        this.intervalId = setInterval(() => {
+            this.updateElapsedTime();
+        }, ELAPSED_UPDATE_INTERVAL_MS);
+        // Register with ShutdownManager for graceful cleanup
+        if (this.shutdownManager) {
+            this.shutdownManager.registerCleanup(this.cleanupName, async () => {
+                this.stop();
+            });
+        }
+        return this;
+    }
+    /**
+     * Mark the phase as succeeded
+     *
+     * Stops the spinner and shows a checkmark with total duration.
+     */
+    succeed(customText) {
+        if (this.disposed)
+            return this;
+        this.clearInterval();
+        this.unregisterCleanup();
+        const elapsedSeconds = (Date.now() - this.startTime) / 1000;
+        const duration = formatElapsedTime(elapsedSeconds);
+        const progress = `(${this.phaseIndex}/${this.totalPhases})`;
+        const text = customText ?? `${this.prefix}${this.phase} ${progress} (${duration})`;
+        this.spinner.succeed(text);
+        this.disposed = true;
+        return this;
+    }
+    /**
+     * Mark the phase as failed
+     *
+     * Stops the spinner and shows an error indicator with message.
+     */
+    fail(error) {
+        if (this.disposed)
+            return this;
+        this.clearInterval();
+        this.unregisterCleanup();
+        const elapsedSeconds = (Date.now() - this.startTime) / 1000;
+        const duration = formatElapsedTime(elapsedSeconds);
+        const progress = `(${this.phaseIndex}/${this.totalPhases})`;
+        const errorSuffix = error ? `: ${error}` : "";
+        const text = `${this.prefix}${this.phase} ${progress} (${duration})${errorSuffix}`;
+        this.spinner.fail(text);
+        this.disposed = true;
+        return this;
+    }
+    /**
+     * Stop the spinner without success/fail indication
+     *
+     * Use this for cleanup or when the phase is interrupted.
+     */
+    stop() {
+        if (this.disposed)
+            return this;
+        this.clearInterval();
+        this.unregisterCleanup();
+        this.spinner.stop();
+        this.disposed = true;
+        return this;
+    }
+    /**
+     * Pause the spinner (for verbose streaming output)
+     *
+     * Temporarily stops the animation without disposing.
+     * Call resume() to continue.
+     */
+    pause() {
+        if (this.disposed || this.paused)
+            return this;
+        this.paused = true;
+        this.spinner.stop();
+        return this;
+    }
+    /**
+     * Resume the spinner after pause
+     *
+     * Restarts the animation with updated elapsed time.
+     */
+    resume() {
+        if (this.disposed || !this.paused)
+            return this;
+        this.paused = false;
+        const elapsedSeconds = (Date.now() - this.startTime) / 1000;
+        this.spinner.start(this.formatText(elapsedSeconds));
+        return this;
+    }
+    /**
+     * Check if the spinner is currently active
+     */
+    get isSpinning() {
+        return this.spinner.isSpinning && !this.disposed && !this.paused;
+    }
+    /**
+     * Get the total elapsed time in seconds
+     */
+    get elapsedSeconds() {
+        if (this.startTime === 0)
+            return 0;
+        return (Date.now() - this.startTime) / 1000;
+    }
+    /**
+     * Dispose of the spinner and clean up resources
+     *
+     * Called automatically by succeed(), fail(), or stop().
+     * Safe to call multiple times.
+     */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.clearInterval();
+        this.unregisterCleanup();
+        this.spinner.stop();
+        this.disposed = true;
+    }
+    /**
+     * Clear the elapsed time update interval
+     */
+    clearInterval() {
+        if (this.intervalId !== null) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+    }
+    /**
+     * Unregister from ShutdownManager
+     */
+    unregisterCleanup() {
+        if (this.shutdownManager) {
+            this.shutdownManager.unregisterCleanup(this.cleanupName);
+        }
+    }
+}
+/**
+ * Create a PhaseSpinner with the given options
+ *
+ * Convenience function matching the pattern of cli-ui.spinner().
+ */
+export function phaseSpinner(options) {
+    return new PhaseSpinner(options);
+}

package/dist/src/lib/templates.js

@@ -5,6 +5,8 @@ import { readdir, chmod } from "fs/promises";
 import { join, dirname, relative, isAbsolute } from "path";
 import { fileURLToPath } from "url";
 import { readFile, writeFile, ensureDir, fileExists, isSymlink, createSymlink, removeFileOrSymlink, } from "./fs.js";
+import { getPackageVersion } from "./manifest.js";
+const SKILLS_VERSION_PATH = ".claude/skills/.sequant-version";
 import { getStackConfig, getStackNotes, getMultiStackNotes } from "./stacks.js";
 import { isNativeWindows } from "./system.js";
 import { getProjectName } from "./project-name.js";
@@ -227,5 +229,7 @@ export async function copyTemplates(stack, tokens, options = {}) {
         const content = await readFile(settingsPath);
         await writeFile(".claude/settings.json", processTemplate(content, variables));
     }
+    // Write skills version marker for sync detection
+    await writeFile(SKILLS_VERSION_PATH, getPackageVersion());
     return { scriptsSymlinked, symlinkResults };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "1.13.0",
+  "version": "1.13.2",
   "description": "Quantize your development workflow - Sequential AI phases with quality gates",
   "type": "module",
   "bin": {
@@ -17,7 +17,8 @@
   "files": [
     "dist",
     "templates",
-    "stacks"
+    "stacks",
+    ".claude-plugin"
   ],
   "scripts": {
     "build": "tsc",

package/templates/skills/solve/SKILL.md

@@ -50,71 +50,299 @@ gh issue view <issue-number> --json labels --jq '.labels[].name'
 - Recommend `--quality-loop` flag for auto-retry on failures
 - Quality loop auto-enables for these labels in `sequant run`
 
-## Output Format
+**New Features** (labels: `enhancement`, `feature`):
+- Include `testgen` phase when ACs need automated tests
+- Workflow: `spec → testgen → exec → qa`
 
-Provide a clear, actionable response with:
+### Quality Loop Detection
 
-1. **Issue Summary Table** showing:
-   - Issue number
-   - Title
-   - Labels
-   - Recommended workflow
+Quality loop (`--quality-loop` or `-q`) provides automatic fix iterations when phases fail. **Recommend quality loop broadly** for any non-trivial work.
 
-2. **Recommended Commands** in order
+**Always recommend `--quality-loop` when:**
+- Labels include: `complex`, `refactor`, `breaking`, `major` (auto-enabled)
+- Labels include: `enhancement`, `feature` (new functionality)
+- Issue involves multiple files or components
+- Issue title contains: "add", "implement", "create", "refactor", "update"
+- Issue is NOT a simple bug fix with `bug` or `fix` label only
 
-3. **CLI Command** - ALWAYS include `npx sequant run <issue>` for terminal/CI usage
+**Skip quality loop recommendation only when:**
+- Simple bug fix (only `bug` or `fix` label, no other labels)
+- Documentation-only changes (`docs` label only)
+- Issue explicitly marked as trivial
 
-4. **Explanation** of why this workflow was chosen
+**Quality loop benefits:**
+- Auto-retries failed phases up to 3 times
+- Catches intermittent test failures
+- Handles build issues from dependency changes
+- Reduces manual intervention for recoverable errors
 
-### Example Output
+### Feature Branch Detection
 
-```markdown
-## Solve Workflow for Issues: 152, 153
+When analyzing issues, check if `--base` flag should be recommended.
 
-### Issue Analysis
+**Check for feature branch indicators:**
 
-| Issue | Title | Labels | Workflow |
-|-------|-------|--------|----------|
-| #152 | Add user dashboard | ui, enhancement | Full (with /test) |
-| #153 | Refactor auth module | backend, refactor | Standard + quality loop |
+```bash
+# Check for feature branch references in issue body
+gh issue view <issue-number> --json body --jq '.body' | grep -iE "(feature/|branch from|based on|part of.*feature)"
 
-### Recommended Workflow
+# Check issue labels for feature context
+gh issue view <issue-number> --json labels --jq '.labels[].name' | grep -iE "(dashboard|feature-|epic-)"
 
-**For #152 (UI feature):**
-```bash
-/spec 152      # Plan the implementation
-/exec 152      # Implement the feature
-/test 152      # Browser-based UI testing
-/qa 152        # Quality review
+# Check if project has defaultBase configured
+cat .sequant/settings.json 2>/dev/null | jq -r '.run.defaultBase // empty'
 ```
 
-**For #153 (Backend refactor):**
+**Recommend `--base <branch>` when:**
+- Issue body references a feature branch (e.g., "Part of dashboard feature")
+- Issue is labeled with a feature epic label (e.g., `dashboard`, `epic-auth`)
+- Multiple related issues reference the same parent feature
+- Project has `run.defaultBase` configured in settings
+
+**Do NOT recommend `--base` when:**
+- Issue should branch from main (default, most common)
+- No feature branch context detected
+- Issue is a standalone bug fix or independent feature
+
+### Chain Mode Detection
+
+When analyzing multiple issues, determine if `--chain` flag should be recommended.
+
+**Check for chain indicators:**
+
 ```bash
-/spec 153      # Plan the refactor
-/exec 153      # Implement changes
-/qa 153        # Quality review
+# Check for dependency keywords in issue body
+gh issue view <issue-number> --json body --jq '.body' | grep -iE "(depends on|blocked by|requires|after #|builds on)"
+
+# Check for sequence labels
+gh issue view <issue-number> --json labels --jq '.labels[].name' | grep -iE "(part-[0-9]|step-[0-9]|phase-[0-9])"
+
+# Check for related issue references
+gh issue view <issue-number> --json body --jq '.body' | grep -oE "#[0-9]+"
 ```
 
-> **Note:** Issue #153 has `refactor` label. Quality loop will **auto-enable** when using `sequant run`, providing automatic fix iterations if phases fail.
+**Recommend `--chain` when:**
+- Multiple issues have explicit dependencies (e.g., "depends on #123")
+- Issues are labeled as parts of a sequence (e.g., `part-1`, `part-2`)
+- Issue titles indicate sequence (e.g., "Part 1:", "Step 2:")
+- Issues reference each other in their bodies
+- Issues modify the same files in a specific order
 
-### CLI Command
+**Do NOT recommend `--chain` when:**
+- Single issue (chain requires 2+ issues)
+- Issues are independent (no shared files or dependencies)
+- Issues touch completely different areas of codebase
+- Parallel batch mode is more appropriate (unrelated issues)
 
-Run from terminal:
-```bash
-npx sequant run 152 153
+### QA Gate Detection
+
+When recommending `--chain`, also consider if `--qa-gate` should be added.
+
+**Recommend `--qa-gate` when:**
+- Chain has 3+ issues (longer chains have higher stale code risk)
+- Issues have tight dependencies (later issues heavily rely on earlier ones)
+- Issues modify the same files across the chain
+- Production-critical or high-risk changes
+
+**Do NOT recommend `--qa-gate` when:**
+- Chain has only 2 issues (lower risk)
+- Issues are mostly independent despite chain structure
+- Speed is prioritized over safety
+- Simple, low-risk changes
+
+**Chain structure visualization:**
 ```
+origin/main → #10 → #11 → #12
+              │      │      │
+              └──────┴──────┴── Each branch builds on previous
+```
+
+## Output Format
+
+**Design Principles:**
+- Lead with the recommendation (command first, top-down)
+- Show all flag decisions explicitly with reasoning
+- Be concise — signal over prose
+- Visual hierarchy using ASCII boxes and lines
+- Max ~25 lines (excluding conflict warnings)
+
+**Required Sections (in order):**
+
+1. **Header Box** — Command recommendation prominently displayed
+2. **Issues List** — Compact: `#N  Title ··· labels → workflow`
+3. **Flags Table** — ALL flags with ✓/✗ and one-line reasoning
+4. **Why Section** — 3-5 bullet points explaining key decisions
+5. **Also Consider** — Conditional curated alternatives (0-3 items)
+6. **Conflict Warning** — Only if in-flight work overlaps (conditional)
+
+---
+
+## Conflict Detection
+
+Before generating output, check for in-flight work that may conflict:
 
-For issue #153 (or any complex work), quality loop is recommended:
 ```bash
-npx sequant run 153 --quality-loop   # Explicit (auto-enabled for refactor label)
+# List open worktrees
+git worktree list --porcelain 2>/dev/null | grep "^worktree" | cut -d' ' -f2
+
+# For each worktree, get changed files
+git -C <worktree-path> diff --name-only main...HEAD 2>/dev/null
 ```
 
-> **Tip:** Install globally with `npm install -g sequant` to omit the `npx` prefix.
+**If overlap detected** with files this issue likely touches, include warning:
+```
+⚠ Conflict risk: #45 (open) modifies lib/auth/* — coordinate or wait
+```
+
+---
+
+## "Also Consider" Logic
+
+Only show alternatives representing genuine trade-offs. Max 2-3 items.
 
-### Notes
-- Issue #152 requires UI testing due to `ui` label
-- Issue #153 will auto-enable quality loop due to `refactor` label
-- Quality loop: auto-retries failed phases up to 3 times
+| Condition | Show Alternative |
+|-----------|------------------|
+| Complex issues OR user unfamiliar with sequant | `--dry-run` (preview before executing) |
+| UI-adjacent AND test phase not included | `--phases +test` (add browser testing) |
+| Mild dependency risk between issues | `--sequential` (run one at a time) |
+| Dependencies ambiguous | Show both parallel and `--chain` options |
+
+**Rules:**
+- Omit section entirely if nothing worth showing
+- Never list every flag — only curated, contextual options
+- Each alternative needs one-line explanation
+
+---
+
+## Output Template
+
+You MUST use this exact structure:
+
+```
+╭──────────────────────────────────────────────────────────────╮
+│  sequant solve                                               │
+│                                                              │
+│  npx sequant run <ISSUES> <FLAGS>                            │
+╰──────────────────────────────────────────────────────────────╯
+
+#<N>  <Title truncated to ~35 chars> ·········· <labels> → <workflow>
+#<N>  <Title truncated to ~35 chars> ·········· <labels> → <workflow>
+
+┌─ Flags ──────────────────────────────────────────────────────┐
+│  -q  quality-loop   ✓/✗  <one-line reasoning>                │
+│  --chain            ✓/✗  <one-line reasoning>                │
+│  --qa-gate          ✓/✗  <one-line reasoning>                │
+│  --base             ✓/✗  <one-line reasoning>                │
+│  --testgen          ✓/✗  <one-line reasoning>                │
+└──────────────────────────────────────────────────────────────┘
+
+Why this workflow:
+  • <reason 1>
+  • <reason 2>
+  • <reason 3>
+
+<!-- CONDITIONAL: Only if alternatives worth showing -->
+Also consider:
+  <flag>     <one-line explanation>
+  <flag>     <one-line explanation>
+
+<!-- CONDITIONAL: Only if conflict detected -->
+⚠ Conflict risk: #<N> (open) modifies <path> — coordinate or wait
+```
+
+---
+
+### Example Output (Independent Issues)
+
+```
+╭──────────────────────────────────────────────────────────────╮
+│  sequant solve                                               │
+│                                                              │
+│  npx sequant run 152 153 -q                                  │
+╰──────────────────────────────────────────────────────────────╯
+
+#152  Add user dashboard ······················ ui → spec → testgen → exec → test → qa
+#153  Refactor auth module ···················· backend → spec → exec → qa
+
+┌─ Flags ──────────────────────────────────────────────────────┐
+│  -q  quality-loop   ✓  refactor label auto-enables retry     │
+│  --chain            ✗  independent (different codepaths)     │
+│  --qa-gate          ✗  no chain mode                         │
+│  --base             ✗  branching from main                   │
+│  --testgen          ✓  #152 has testable ACs (Unit Tests)    │
+└──────────────────────────────────────────────────────────────┘
+
+Why this workflow:
+  • #152 has ui label → includes /test for browser verification
+  • #152 has testable ACs → includes /testgen for test stubs
+  • #153 has refactor label → quality loop auto-enabled
+  • No shared files → safe to parallelize
+
+Also consider:
+  --dry-run     Preview execution before running
+```
+
+---
+
+### Example Output (Dependent Issues — Chain)
+
+```
+╭──────────────────────────────────────────────────────────────╮
+│  sequant solve                                               │
+│                                                              │
+│  npx sequant run 10 11 12 --sequential --chain --qa-gate -q  │
+╰──────────────────────────────────────────────────────────────╯
+
+#10  Add auth middleware ······················ backend → spec → testgen → exec → qa
+#11  Add login page ··························· ui → spec → testgen → exec → test → qa
+#12  Add logout functionality ················· ui → spec → exec → test → qa
+
+┌─ Flags ──────────────────────────────────────────────────────┐
+│  -q  quality-loop   ✓  multi-step implementation             │
+│  --chain            ✓  #11 depends on #10, #12 depends on #11│
+│  --qa-gate          ✓  3 issues with tight dependencies      │
+│  --base             ✗  branching from main                   │
+│  --testgen          ✓  #10, #11 have Unit Test ACs           │
+└──────────────────────────────────────────────────────────────┘
+
+Chain structure:
+  main → #10 → #11 → #12
+
+Why this workflow:
+  • Explicit dependencies detected in issue bodies
+  • Chain ensures each branch builds on previous
+  • QA gate prevents stale code in downstream issues
+  • UI issues (#11, #12) include /test phase
+  • #10, #11 have testable ACs → include /testgen
+```
+
+---
+
+### Example Output (With Conflict Warning)
+
+```
+╭──────────────────────────────────────────────────────────────╮
+│  sequant solve                                               │
+│                                                              │
+│  npx sequant run 85 -q                                       │
+╰──────────────────────────────────────────────────────────────╯
+
+#85  Update auth cookie handling ·············· bug → exec → qa
+
+┌─ Flags ──────────────────────────────────────────────────────┐
+│  -q  quality-loop   ✓  auth changes benefit from retry       │
+│  --chain            ✗  single issue                          │
+│  --qa-gate          ✗  no chain mode                         │
+│  --base             ✗  branching from main                   │
+│  --testgen          ✗  bug fix (targeted tests in exec)      │
+└──────────────────────────────────────────────────────────────┘
+
+Why this workflow:
+  • Bug fix with clear AC → skip /spec
+  • Bug fix → skip /testgen (targeted tests added during exec)
+  • Single issue → no chain needed
+
+⚠ Conflict risk: #82 (open) modifies lib/auth/cookies.ts — coordinate or wait
 ```
 
 ## Workflow Selection Logic
@@ -128,17 +356,30 @@ npx sequant run 153 --quality-loop   # Explicit (auto-enabled for refactor label
    - UI/frontend changes → Add `test` phase
    - Complex refactors → Enable quality loop
    - Security-sensitive → Add `security-review` phase
+   - New features with testable ACs → Add `testgen` phase
 
 ### Standard Workflow (Most Issues)
 ```
 /spec → /exec → /qa
 ```
 
+### Feature with Testable ACs
+```
+/spec → /testgen → /exec → /qa
+```
+Include `testgen` when ACs have Unit Test or Integration Test verification methods.
+
 ### UI Feature Workflow
 ```
 /spec → /exec → /test → /qa
 ```
 
+### UI Feature with Tests
+```
+/spec → /testgen → /exec → /test → /qa
+```
+Combine `testgen` and `test` for UI features with testable ACs.
+
 ### Bug Fix Workflow (Simple)
 ```
 /exec → /qa
@@ -156,11 +397,25 @@ Runs complete workflow with automatic fix iterations.
 | Issue Type | Labels | Workflow |
 |------------|--------|----------|
 | UI Feature | ui, frontend, admin | spec → exec → test → qa |
+| UI Feature with Tests | ui + enhancement | spec → testgen → exec → test → qa |
 | Backend Feature | backend, api | spec → exec → qa |
+| New Feature (testable) | enhancement, feature | spec → testgen → exec → qa |
 | Bug Fix | bug, fix | exec → qa (or full if complex) |
 | Complex Feature | complex, refactor | `--quality-loop` or fullsolve |
 | Documentation | docs | exec → qa |
 
+### Testgen Phase Detection
+
+**Include `testgen` in workflow when:**
+- Issue has `enhancement` or `feature` label AND
+- Issue is NOT a simple bug fix or docs-only change AND
+- Project has test infrastructure (Jest, Vitest, etc.)
+
+**Skip `testgen` when:**
+- Issue is `bug` or `fix` only (targeted tests added during exec)
+- Issue is `docs` only (no code tests needed)
+- All ACs use Manual Test or Browser Test verification
+
 **Quality Loop vs Fullsolve:**
 - `--quality-loop`: Enables auto-retry within `sequant run` (good for CI/automation)
 - `/fullsolve`: Interactive single-issue resolution with inline loops (good for manual work)
@@ -179,6 +434,18 @@ npx sequant run 152 153 154
 # Sequential execution (respects dependencies)
 npx sequant run 152 153 --sequential
 
+# Chain mode (each issue branches from previous completed issue)
+npx sequant run 10 11 12 --sequential --chain
+
+# Chain mode with QA gate (pause if QA fails, prevent stale code)
+npx sequant run 10 11 12 --sequential --chain --qa-gate
+
+# Custom base branch (branch from feature branch instead of main)
+npx sequant run 117 --base feature/dashboard
+
+# Chain mode with custom base branch
+npx sequant run 117 118 119 --sequential --chain --base feature/dashboard
+
 # Custom phases
 npx sequant run 152 --phases spec,exec,qa
 
@@ -192,6 +459,50 @@ npx sequant run 152 --quality-loop --max-iterations 5
 npx sequant run 152 --dry-run
 ```
 
+### Custom Base Branch
+
+The `--base` flag specifies which branch to create worktrees from:
+
+```
+Without --base:           With --base feature/dashboard:
+origin/main               feature/dashboard
+    ├── #117                  ├── #117
+    ├── #118                  ├── #118
+    └── #119                  └── #119
+```
+
+**Use `--base` when:**
+- Working on issues for a feature integration branch
+- Issue references a parent branch (e.g., "Part of dashboard feature")
+- Project uses `.sequant/settings.json` with `run.defaultBase` configured
+- Issues should build on an existing feature branch
+
+**Do NOT use `--base` when:**
+- Issues should branch from main (default behavior)
+- Working on independent bug fixes or features
+
+### Chain Mode Explained
+
+The `--chain` flag (requires `--sequential`) creates dependent branches:
+
+```
+Without --chain:          With --chain:
+origin/main               origin/main
+    ├── #10                   └── #10 (merged)
+    ├── #11                       └── #11 (merged)
+    └── #12                           └── #12
+```
+
+**Use `--chain` when:**
+- Issues have explicit dependencies
+- Later issues build on earlier implementations
+- Order matters for correctness
+
+**Do NOT use `--chain` when:**
+- Issues are independent
+- Parallel execution is appropriate
+- Issues can be merged in any order
+
 > **Tip:** Install globally with `npm install -g sequant` to omit the `npx` prefix.
 
 ## Edge Cases
@@ -224,56 +535,37 @@ If issues depend on each other:
 
 ---
 
-## Output Verification
-
-**Before responding, verify your output includes ALL of these:**
-
-- [ ] **Issue Summary Table** - Table with Issue, Title, Labels, Workflow columns
-- [ ] **Recommended Workflow** - Slash commands in order for each issue
-- [ ] **CLI Command** - `npx sequant run <issue-numbers>` command (REQUIRED)
-- [ ] **Explanation** - Brief notes explaining workflow choices
-
-**DO NOT respond until all items are verified.**
-
-## Output Template
+## State Tracking
 
-You MUST use this exact structure:
+**IMPORTANT:** `/solve` initializes issue state when analyzing issues.
 
-```markdown
-## Solve Workflow for Issues: <ISSUE_NUMBERS>
+### State Updates
 
-### Issue Analysis
+When analyzing issues, initialize state tracking so the dashboard can show planned work:
 
-| Issue | Title | Labels | Workflow |
-|-------|-------|--------|----------|
-<!-- FILL: one row per issue. For complex/refactor/breaking/major labels, add "+ quality loop" to Workflow -->
-
-### Recommended Workflow
+**Initialize each issue being analyzed:**
+```bash
+# Get issue title
+TITLE=$(gh issue view <issue-number> --json title -q '.title')
 
-**For #<N> (<type>):**
-\`\`\`bash
-<!-- FILL: slash commands in order -->
-\`\`\`
+# Initialize state (if not already tracked)
+npx tsx scripts/state/update.ts init <issue-number> "$TITLE"
+```
 
-<!-- IF any issue has complex/refactor/breaking/major label, include this callout: -->
-> **Note:** Issue #<N> has `<label>` label. Quality loop will **auto-enable** when using `sequant run`, providing automatic fix iterations if phases fail.
+**Note:** `/solve` only initializes issues - actual phase tracking happens during workflow execution (`/fullsolve`, `sequant run`, or individual skills).
 
-### CLI Command
+---
 
-Run from terminal:
-\`\`\`bash
-npx sequant run <ISSUE_NUMBERS>
-\`\`\`
+## Output Verification
 
-<!-- IF any issue has complex/refactor/breaking/major label, include: -->
-For complex issues, quality loop is recommended:
-\`\`\`bash
-npx sequant run <ISSUE_NUMBER> --quality-loop   # Explicit (auto-enabled for <label> label)
-\`\`\`
+**Before responding, verify your output includes ALL of these:**
 
-> **Tip:** Install globally with `npm install -g sequant` to omit the `npx` prefix.
+- [ ] **Header Box** — ASCII box with `sequant solve` and full command
+- [ ] **Issues List** — Each issue with dot leaders: `#N  Title ··· labels → workflow`
+- [ ] **Flags Table** — ALL five flags (-q, --chain, --qa-gate, --base, --testgen) with ✓/✗ and reasoning
+- [ ] **Why Section** — 3-5 bullet points explaining decisions
+- [ ] **Also Consider** — (conditional) Curated alternatives if applicable
+- [ ] **Conflict Warning** — (conditional) If in-flight work overlaps
+- [ ] **Line Count** — Total ≤25 lines (excluding conflict warnings)
 
-### Notes
-<!-- FILL: explanation of workflow choices -->
-<!-- Include note about quality loop auto-enabling if applicable -->
-```
+**DO NOT respond until all items are verified.**