sequant 1.11.0 → 1.12.0

package/README.md

@@ -9,12 +9,31 @@ Solve GitHub issues with structured phases and quality gates — from issue to m
 
 ## Quick Start
 
+### Option A: Install as Claude Code Plugin (Recommended)
+
+```bash
+# Add the Sequant marketplace
+/plugin marketplace add admarble/sequant
+
+# Install the plugin
+/plugin install sequant
+```
+
+Then run setup:
+```
+/sequant:setup    # Initialize worktrees directory
+```
+
+### Option B: Install via npm
+
 ```bash
 # In your project directory
 npx sequant init
 npx sequant doctor   # Verify setup
 ```
 
+### Start Using
+
 Then in Claude Code:
 
 ```
@@ -31,9 +50,20 @@ Or step-by-step:
 
 ### Prerequisites
 
+**Required:**
 - [Claude Code](https://claude.ai/code) — AI coding assistant
 - [GitHub CLI](https://cli.github.com/) — run `gh auth login`
-- Node.js 18+ and Git
+- Git (for worktree-based isolation)
+
+**For npm installation:**
+- Node.js 18+
+
+**Optional MCP servers (enhanced features):**
+- `chrome-devtools` — enables `/test` for browser-based UI testing
+- `sequential-thinking` — enhanced reasoning for complex decisions
+- `context7` — library documentation lookup
+
+> **Note:** Sequant is optimized for Node.js/TypeScript projects. The worktree workflow works with any git repository.
 
 ---
 
@@ -52,6 +82,24 @@ Sequant adds slash commands to Claude Code that enforce a structured workflow:
 
 > `/test` is optional — used for UI features when Chrome DevTools MCP is available.
 
+### Worktree Isolation
+
+Sequant uses Git worktrees to isolate each issue's work:
+
+```
+your-project/           # Main repo (stays on main branch)
+../worktrees/
+  feature/
+    123-add-login/     # Issue #123 worktree (feature branch)
+    456-fix-bug/       # Issue #456 worktree (feature branch)
+```
+
+**Why worktrees?**
+- Work on multiple issues simultaneously
+- Never pollute your main branch
+- Each issue has its own dependencies and build
+- Safe to discard failed experiments
+
 ### Quality Gates
 
 Every `/qa` runs automated checks:
@@ -59,6 +107,7 @@ Every `/qa` runs automated checks:
 - **AC Adherence** — Code verified against acceptance criteria
 - **Type Safety** — Detects `any`, `as any`, missing types
 - **Security Scans** — OWASP-style vulnerability detection
+- **Semgrep Static Analysis** — Stack-aware rulesets, custom rules via `.sequant/semgrep-rules.yaml`
 - **Scope Analysis** — Flags changes outside issue scope
 - **Execution Evidence** — Scripts/CLI must pass smoke tests
 - **Test Quality** — Validates test coverage and mock hygiene
@@ -115,9 +164,9 @@ npx sequant run 123 --base feature/dashboard  # Custom base branch
 
 | Command | Purpose |
 |---------|---------|
-| `/merger` | Multi-issue integration and merge |
 | `/testgen` | Generate test stubs from spec |
 | `/verify` | CLI/script execution verification |
+| `/setup` | Initialize Sequant in a project |
 
 ### Utilities
 
@@ -126,6 +175,7 @@ npx sequant run 123 --base feature/dashboard  # Custom base branch
 | `/assess` | Issue triage and status assessment |
 | `/docs` | Generate feature documentation |
 | `/clean` | Repository cleanup |
+| `/improve` | Codebase analysis and improvement discovery |
 | `/security-review` | Deep security analysis |
 | `/reflect` | Workflow improvement analysis |
 
@@ -141,6 +191,7 @@ npx sequant status            # Show version and config
 npx sequant run <issues...>   # Execute workflow
 npx sequant state <cmd>       # Manage workflow state (init/rebuild/clean)
 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.
@@ -178,16 +229,49 @@ See [Customization Guide](docs/customization.md) for all options.
 ## Documentation
 
 - [Getting Started](docs/getting-started/installation.md)
+- [What We've Built](docs/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)
 - [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)
 
 ---
 
+## Feedback & Contributing
+
+### Reporting Issues
+
+- **Plugin issues:** [Plugin Feedback template](https://github.com/admarble/sequant/issues/new?template=plugin-feedback.yml)
+- **Bug reports:** [Bug template](https://github.com/admarble/sequant/issues/new?template=bug.yml)
+- **Feature requests:** [Feature template](https://github.com/admarble/sequant/issues/new?template=feature.yml)
+- **Questions:** [GitHub Discussions](https://github.com/admarble/sequant/discussions)
+
+### Using `/improve` for Feedback
+
+Run `/improve` in Claude Code to analyze your codebase and create structured issues:
+
+```
+/improve              # Analyze entire codebase
+/improve security     # Focus on security concerns
+/improve tests        # Find test coverage gaps
+```
+
+The skill will present findings and offer to create GitHub issues automatically.
+
+### Contributing
+
+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.
+
+---
+
 ## License
 
 MIT

package/dist/src/lib/ac-linter.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Acceptance Criteria Linter
+ *
+ * Static analysis of acceptance criteria to flag vague, untestable,
+ * or incomplete requirements before implementation begins.
+ *
+ * @example
+ * ```typescript
+ * import { lintAcceptanceCriteria } from './ac-linter';
+ * import { parseAcceptanceCriteria } from './ac-parser';
+ *
+ * const criteria = parseAcceptanceCriteria(issueBody);
+ * const lintResults = lintAcceptanceCriteria(criteria);
+ *
+ * console.log(formatACLintResults(lintResults));
+ * ```
+ */
+import type { AcceptanceCriterion } from "./workflow/state-schema.js";
+/**
+ * Types of issues that can be flagged in AC
+ */
+export type ACLintIssueType = "vague" | "unmeasurable" | "incomplete" | "open_ended";
+/**
+ * A lint issue found in an acceptance criterion
+ */
+export interface ACLintIssue {
+    /** Type of issue detected */
+    type: ACLintIssueType;
+    /** The matched pattern that triggered this issue */
+    matchedPattern: string;
+    /** Human-readable description of the problem */
+    problem: string;
+    /** Suggested improvement */
+    suggestion: string;
+}
+/**
+ * Lint result for a single acceptance criterion
+ */
+export interface ACLintResult {
+    /** The AC being linted */
+    ac: AcceptanceCriterion;
+    /** Issues found (empty if AC is clear) */
+    issues: ACLintIssue[];
+    /** Whether this AC passed linting (no issues) */
+    passed: boolean;
+}
+/**
+ * Overall lint results for all acceptance criteria
+ */
+export interface ACLintResults {
+    /** Results for each AC */
+    results: ACLintResult[];
+    /** Summary counts */
+    summary: {
+        total: number;
+        passed: number;
+        flagged: number;
+    };
+    /** Whether any issues were found */
+    hasIssues: boolean;
+}
+/**
+ * Pattern definition for detecting issues
+ */
+interface LintPattern {
+    /** Regular expression to match (case-insensitive) */
+    regex: RegExp;
+    /** Type of issue this pattern indicates */
+    type: ACLintIssueType;
+    /** Problem description */
+    problem: string;
+    /** Suggested fix */
+    suggestion: string;
+}
+/**
+ * Lint a single acceptance criterion against all patterns
+ *
+ * @param ac - The acceptance criterion to lint
+ * @param patterns - Optional custom patterns (defaults to DEFAULT_LINT_PATTERNS)
+ * @returns Lint result with any issues found
+ */
+export declare function lintAcceptanceCriterion(ac: AcceptanceCriterion, patterns?: LintPattern[]): ACLintResult;
+/**
+ * Lint all acceptance criteria
+ *
+ * @param criteria - Array of acceptance criteria to lint
+ * @param patterns - Optional custom patterns
+ * @returns Complete lint results with summary
+ */
+export declare function lintAcceptanceCriteria(criteria: AcceptanceCriterion[], patterns?: LintPattern[]): ACLintResults;
+/**
+ * Format lint results as markdown for the spec output
+ *
+ * @param results - Lint results to format
+ * @returns Markdown-formatted output string
+ */
+export declare function formatACLintResults(results: ACLintResults): string;
+/**
+ * Get the default lint patterns
+ *
+ * @returns Copy of the default lint patterns
+ */
+export declare function getDefaultLintPatterns(): LintPattern[];
+/**
+ * Create custom lint patterns from a simplified configuration
+ *
+ * @param config - Array of pattern configurations
+ * @returns Array of LintPattern objects
+ */
+export declare function createLintPatterns(config: Array<{
+    pattern: string;
+    type: ACLintIssueType;
+    problem: string;
+    suggestion: string;
+}>): LintPattern[];
+export {};

package/dist/src/lib/ac-linter.js

@@ -0,0 +1,304 @@
+/**
+ * Acceptance Criteria Linter
+ *
+ * Static analysis of acceptance criteria to flag vague, untestable,
+ * or incomplete requirements before implementation begins.
+ *
+ * @example
+ * ```typescript
+ * import { lintAcceptanceCriteria } from './ac-linter';
+ * import { parseAcceptanceCriteria } from './ac-parser';
+ *
+ * const criteria = parseAcceptanceCriteria(issueBody);
+ * const lintResults = lintAcceptanceCriteria(criteria);
+ *
+ * console.log(formatACLintResults(lintResults));
+ * ```
+ */
+/**
+ * Default lint patterns organized by issue type
+ *
+ * Patterns are checked in order, with longer/more specific patterns first
+ */
+const DEFAULT_LINT_PATTERNS = [
+    // Vague patterns
+    {
+        regex: /\bshould work\b/i,
+        type: "vague",
+        problem: 'Vague: "should work" is not specific',
+        suggestion: "Specify the expected behavior and success criteria",
+    },
+    {
+        regex: /\bwork(?:s|ing)? (?:properly|correctly|well|nicely)\b/i,
+        type: "vague",
+        problem: "Vague: adverb does not define expected behavior",
+        suggestion: "Define specific, measurable outcomes",
+    },
+    {
+        regex: /\bproperly\b/i,
+        type: "vague",
+        problem: 'Vague: "properly" is subjective',
+        suggestion: "Specify what correct behavior looks like",
+    },
+    {
+        regex: /\bcorrectly\b/i,
+        type: "vague",
+        problem: 'Vague: "correctly" is subjective',
+        suggestion: "Define the expected output or behavior",
+    },
+    {
+        regex: /\bnicely\b/i,
+        type: "vague",
+        problem: 'Vague: "nicely" is subjective',
+        suggestion: "Specify concrete UX requirements",
+    },
+    {
+        regex: /\bgood\b(?!\s+(?:practice|pattern|reason))/i,
+        type: "vague",
+        problem: 'Vague: "good" is subjective without context',
+        suggestion: "Define measurable quality criteria",
+    },
+    {
+        regex: /\bas expected\b/i,
+        type: "vague",
+        problem: 'Vague: "as expected" requires explicit expectations',
+        suggestion: "Define what the expected behavior is",
+    },
+    {
+        regex: /\bshould be fine\b/i,
+        type: "vague",
+        problem: 'Vague: "should be fine" is not a testable criterion',
+        suggestion: "Specify the acceptance threshold",
+    },
+    // Unmeasurable patterns (performance-related)
+    {
+        regex: /\bfast(?:er)?\b(?!\s+forward)/i,
+        type: "unmeasurable",
+        problem: 'Unmeasurable: "fast" has no threshold',
+        suggestion: "Add latency threshold (e.g., <2 seconds, <100ms)",
+    },
+    {
+        regex: /\bslow(?:er)?\b/i,
+        type: "unmeasurable",
+        problem: 'Unmeasurable: "slow" has no threshold',
+        suggestion: "Define specific timing or threshold",
+    },
+    {
+        regex: /\bperformant\b/i,
+        type: "unmeasurable",
+        problem: 'Unmeasurable: "performant" has no threshold',
+        suggestion: "Add specific performance metrics (latency, throughput)",
+    },
+    {
+        regex: /\befficient(?:ly)?\b/i,
+        type: "unmeasurable",
+        problem: 'Unmeasurable: "efficient" has no threshold',
+        suggestion: "Define resource usage limits or benchmarks",
+    },
+    {
+        regex: /\bresponsive\b/i,
+        type: "unmeasurable",
+        problem: 'Unmeasurable: "responsive" has no threshold',
+        suggestion: "Add response time target (e.g., <100ms interaction, <3s load)",
+    },
+    {
+        regex: /\bquick(?:ly)?\b/i,
+        type: "unmeasurable",
+        problem: 'Unmeasurable: "quickly" has no threshold',
+        suggestion: "Specify time limit (e.g., completes in <5 seconds)",
+    },
+    {
+        regex: /\bscalable\b/i,
+        type: "unmeasurable",
+        problem: 'Unmeasurable: "scalable" needs concrete bounds',
+        suggestion: "Define load targets (e.g., handles 1000 concurrent users)",
+    },
+    // Incomplete patterns (error handling, edge cases)
+    {
+        regex: /\bhandle(?:s)? errors?\b/i,
+        type: "incomplete",
+        problem: "Incomplete: error types not specified",
+        suggestion: "List specific error types and expected responses (e.g., 400 for invalid input, 503 for service unavailable)",
+    },
+    {
+        regex: /\berror handling\b/i,
+        type: "incomplete",
+        problem: "Incomplete: error scenarios not specified",
+        suggestion: "Enumerate error conditions and recovery behaviors",
+    },
+    {
+        regex: /\bedge cases?\b/i,
+        type: "incomplete",
+        problem: "Incomplete: edge cases not enumerated",
+        suggestion: "List the specific edge cases to handle",
+    },
+    {
+        regex: /\bcorner cases?\b/i,
+        type: "incomplete",
+        problem: "Incomplete: corner cases not enumerated",
+        suggestion: "List the specific corner cases to handle",
+    },
+    {
+        regex: /\ball (?:cases|scenarios|situations)\b/i,
+        type: "incomplete",
+        problem: 'Incomplete: "all" cases cannot be verified',
+        suggestion: "Enumerate the specific cases to test",
+    },
+    {
+        regex: /\bappropriate(?:ly)?\b/i,
+        type: "incomplete",
+        problem: 'Incomplete: "appropriate" behavior not defined',
+        suggestion: "Specify what the appropriate response is",
+    },
+    // Open-ended patterns
+    {
+        regex: /\betc\.?\b/i,
+        type: "open_ended",
+        problem: 'Open-ended: "etc." leaves scope undefined',
+        suggestion: "Enumerate all items explicitly",
+    },
+    {
+        regex: /\band more\b/i,
+        type: "open_ended",
+        problem: 'Open-ended: "and more" leaves scope undefined',
+        suggestion: "List all items explicitly",
+    },
+    {
+        regex: /\bsuch as\b/i,
+        type: "open_ended",
+        problem: 'Open-ended: "such as" implies incomplete list',
+        suggestion: "Provide exhaustive list or define boundaries",
+    },
+    {
+        regex: /\bincluding but not limited to\b/i,
+        type: "open_ended",
+        problem: "Open-ended: scope is unbounded",
+        suggestion: "Define explicit boundaries or enumerate all items",
+    },
+    {
+        regex: /\bfor example\b/i,
+        type: "open_ended",
+        problem: 'Open-ended: "for example" implies other cases exist',
+        suggestion: "List all cases or define scope boundaries",
+    },
+    {
+        regex: /\bvarious\b/i,
+        type: "open_ended",
+        problem: 'Open-ended: "various" items not specified',
+        suggestion: "Enumerate the specific items",
+    },
+    {
+        regex: /\bother(?:s)?\b(?!\s+(?:than|hand|words|side))/i,
+        type: "open_ended",
+        problem: 'Open-ended: "other" items not specified',
+        suggestion: "List all items explicitly or define boundaries",
+    },
+];
+/**
+ * Lint a single acceptance criterion against all patterns
+ *
+ * @param ac - The acceptance criterion to lint
+ * @param patterns - Optional custom patterns (defaults to DEFAULT_LINT_PATTERNS)
+ * @returns Lint result with any issues found
+ */
+export function lintAcceptanceCriterion(ac, patterns = DEFAULT_LINT_PATTERNS) {
+    const issues = [];
+    const description = ac.description;
+    for (const pattern of patterns) {
+        const match = description.match(pattern.regex);
+        if (match) {
+            issues.push({
+                type: pattern.type,
+                matchedPattern: match[0],
+                problem: pattern.problem,
+                suggestion: pattern.suggestion,
+            });
+        }
+    }
+    return {
+        ac,
+        issues,
+        passed: issues.length === 0,
+    };
+}
+/**
+ * Lint all acceptance criteria
+ *
+ * @param criteria - Array of acceptance criteria to lint
+ * @param patterns - Optional custom patterns
+ * @returns Complete lint results with summary
+ */
+export function lintAcceptanceCriteria(criteria, patterns) {
+    const results = criteria.map((ac) => lintAcceptanceCriterion(ac, patterns));
+    const passed = results.filter((r) => r.passed).length;
+    const flagged = results.filter((r) => !r.passed).length;
+    return {
+        results,
+        summary: {
+            total: criteria.length,
+            passed,
+            flagged,
+        },
+        hasIssues: flagged > 0,
+    };
+}
+/**
+ * Format lint results as markdown for the spec output
+ *
+ * @param results - Lint results to format
+ * @returns Markdown-formatted output string
+ */
+export function formatACLintResults(results) {
+    if (results.summary.total === 0) {
+        return "## AC Quality Check\n\nNo acceptance criteria found to lint.";
+    }
+    const lines = ["## AC Quality Check", ""];
+    // Add summary line
+    if (!results.hasIssues) {
+        lines.push(`✅ All ${results.summary.total} acceptance criteria are clear and testable.`);
+        lines.push("");
+        return lines.join("\n");
+    }
+    // Add issues
+    for (const result of results.results) {
+        if (!result.passed) {
+            lines.push(`⚠️ **${result.ac.id}:** "${result.ac.description}"`);
+            for (const issue of result.issues) {
+                lines.push(`   → ${issue.problem}`);
+                lines.push(`   → Suggest: ${issue.suggestion}`);
+            }
+            lines.push("");
+        }
+    }
+    // Add passed ACs summary
+    const passedIds = results.results.filter((r) => r.passed).map((r) => r.ac.id);
+    if (passedIds.length > 0) {
+        lines.push(`✅ ${passedIds.join(", ")}: Clear and testable`);
+        lines.push("");
+    }
+    // Add summary
+    lines.push(`**Summary:** ${results.summary.flagged}/${results.summary.total} AC items flagged for review`);
+    return lines.join("\n");
+}
+/**
+ * Get the default lint patterns
+ *
+ * @returns Copy of the default lint patterns
+ */
+export function getDefaultLintPatterns() {
+    return [...DEFAULT_LINT_PATTERNS];
+}
+/**
+ * Create custom lint patterns from a simplified configuration
+ *
+ * @param config - Array of pattern configurations
+ * @returns Array of LintPattern objects
+ */
+export function createLintPatterns(config) {
+    return config.map((c) => ({
+        regex: new RegExp(c.pattern, "i"),
+        type: c.type,
+        problem: c.problem,
+        suggestion: c.suggestion,
+    }));
+}

package/dist/src/lib/plugin-version-sync.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Plugin version sync utilities
+ *
+ * Ensures plugin.json version stays in sync with package.json version.
+ * Used by CI validation and /release skill.
+ */
+export interface VersionSyncResult {
+    inSync: boolean;
+    packageVersion: string | null;
+    pluginVersion: string | null;
+    error?: string;
+}
+/**
+ * Check if package.json and plugin.json versions are in sync
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Sync status with version details
+ */
+export declare function checkVersionSync(projectRoot?: string): VersionSyncResult;
+/**
+ * Get a helpful error message for version mismatch
+ *
+ * @param result - Version sync result
+ * @returns Human-readable error message with fix command
+ */
+export declare function getVersionMismatchMessage(result: VersionSyncResult): string;

package/dist/src/lib/plugin-version-sync.js

@@ -0,0 +1,91 @@
+/**
+ * Plugin version sync utilities
+ *
+ * Ensures plugin.json version stays in sync with package.json version.
+ * Used by CI validation and /release skill.
+ */
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+/**
+ * Check if package.json and plugin.json versions are in sync
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Sync status with version details
+ */
+export function checkVersionSync(projectRoot = process.cwd()) {
+    const packageJsonPath = join(projectRoot, "package.json");
+    const pluginJsonPath = join(projectRoot, ".claude-plugin", "plugin.json");
+    // Check package.json exists
+    if (!existsSync(packageJsonPath)) {
+        return {
+            inSync: false,
+            packageVersion: null,
+            pluginVersion: null,
+            error: "package.json not found",
+        };
+    }
+    // Check plugin.json exists
+    if (!existsSync(pluginJsonPath)) {
+        return {
+            inSync: false,
+            packageVersion: null,
+            pluginVersion: null,
+            error: "plugin.json not found",
+        };
+    }
+    try {
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+        const pluginJson = JSON.parse(readFileSync(pluginJsonPath, "utf8"));
+        const packageVersion = packageJson.version || null;
+        const pluginVersion = pluginJson.version || null;
+        if (!packageVersion) {
+            return {
+                inSync: false,
+                packageVersion: null,
+                pluginVersion,
+                error: "package.json missing version field",
+            };
+        }
+        if (!pluginVersion) {
+            return {
+                inSync: false,
+                packageVersion,
+                pluginVersion: null,
+                error: "plugin.json missing version field",
+            };
+        }
+        return {
+            inSync: packageVersion === pluginVersion,
+            packageVersion,
+            pluginVersion,
+        };
+    }
+    catch (e) {
+        return {
+            inSync: false,
+            packageVersion: null,
+            pluginVersion: null,
+            error: `Failed to parse JSON: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+}
+/**
+ * Get a helpful error message for version mismatch
+ *
+ * @param result - Version sync result
+ * @returns Human-readable error message with fix command
+ */
+export function getVersionMismatchMessage(result) {
+    if (result.inSync) {
+        return `✓ Versions are in sync: ${result.packageVersion}`;
+    }
+    if (result.error) {
+        return `✗ Version sync check failed: ${result.error}`;
+    }
+    return `✗ Version mismatch!
+  package.json: ${result.packageVersion}
+  plugin.json:  ${result.pluginVersion}
+
+Run the following to sync:
+  node -e "const p=require('./.claude-plugin/plugin.json');p.version='${result.packageVersion}';require('fs').writeFileSync('./.claude-plugin/plugin.json',JSON.stringify(p,null,2)+'\\n')"`;
+}