sequant 1.10.1 → 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,7 +107,11 @@ 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
+- **Anti-Pattern Detection** — Catches N+1 queries, empty catch blocks, stale dependencies
 
 When checks fail, `/loop` automatically fixes and re-runs (up to 3x).
 
@@ -112,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
 
@@ -123,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 |
 
@@ -136,9 +189,12 @@ npx sequant update            # Update skill templates
 npx sequant doctor            # Check installation
 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) for advanced usage.
+See [Run Command Options](docs/run-command.md), [State Command](docs/state-command.md), and [Analytics](docs/analytics.md) for details.
 
 ---
 
@@ -173,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/bin/cli.js

@@ -39,6 +39,8 @@ import { statusCommand } from "../src/commands/status.js";
 import { runCommand } from "../src/commands/run.js";
 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";
 const program = new Command();
 // Handle --no-color before parsing
 if (process.argv.includes("--no-color")) {
@@ -64,6 +66,7 @@ program
     .option("-f, --force", "Overwrite existing configuration")
     .option("-i, --interactive", "Force interactive mode even in non-TTY environment")
     .option("--skip-setup", "Skip the dependency setup wizard")
+    .option("--no-symlinks", "Use copies instead of symlinks for scripts/dev/ files")
     .action(initCommand);
 program
     .command("update")
@@ -74,11 +77,26 @@ program
 program
     .command("doctor")
     .description("Check your Sequant installation for issues")
+    .option("--skip-issue-check", "Skip closed-issue verification check")
     .action(doctorCommand);
 program
     .command("status")
-    .description("Show Sequant version and configuration status")
-    .action(statusCommand);
+    .description("Show Sequant version, configuration, and workflow state")
+    .argument("[issue]", "Issue number to show details for", parseInt)
+    .option("--issues", "Show all tracked issues")
+    .option("--json", "Output as JSON")
+    .option("--rebuild", "Rebuild state from run logs")
+    .option("--cleanup", "Clean up stale/orphaned entries")
+    .option("--dry-run", "Preview cleanup without changes")
+    .option("--max-age <days>", "Remove entries older than N days", parseInt)
+    .option("--all", "Remove all orphaned entries (merged and abandoned)")
+    .action((issue, options) => {
+    // Support positional arg: `sequant status 42` → --issue 42
+    if (issue) {
+        options.issue = issue;
+    }
+    return statusCommand(options);
+});
 program
     .command("run")
     .description("Execute workflow for GitHub issues using Claude Agent SDK")
@@ -99,7 +117,9 @@ program
     .option("--testgen", "Run testgen phase after spec")
     .option("--quiet", "Suppress version warnings and non-essential output")
     .option("--chain", "Chain issues: each branches from previous (requires --sequential)")
+    .option("--qa-gate", "Wait for QA pass before starting next issue in chain (requires --chain)")
     .option("--base <branch>", "Base branch for worktree creation (default: main or settings.run.defaultBase)")
+    .option("--no-mcp", "Disable MCP server injection in headless mode")
     .action(runCommand);
 program
     .command("logs")
@@ -119,6 +139,39 @@ program
     .option("--csv", "Output as CSV")
     .option("--json", "Output as JSON")
     .action(statsCommand);
+program
+    .command("dashboard")
+    .description("Start visual workflow dashboard in browser")
+    .option("-p, --port <port>", "Port to run server on", parseInt)
+    .option("--no-open", "Don't automatically open browser")
+    .option("-v, --verbose", "Enable verbose logging")
+    .action(dashboardCommand);
+// State management command with subcommands
+const stateCmd = program
+    .command("state")
+    .description("Manage workflow state for worktrees");
+stateCmd
+    .command("init")
+    .description("Populate state for untracked worktrees")
+    .option("--json", "Output as JSON")
+    .option("-v, --verbose", "Enable verbose output")
+    .action(stateInitCommand);
+stateCmd
+    .command("rebuild")
+    .description("Recreate state from logs and worktrees")
+    .option("--json", "Output as JSON")
+    .option("-v, --verbose", "Enable verbose output")
+    .option("-f, --force", "Force rebuild without confirmation")
+    .action(stateRebuildCommand);
+stateCmd
+    .command("clean")
+    .description("Remove entries for deleted worktrees")
+    .option("--json", "Output as JSON")
+    .option("-v, --verbose", "Enable verbose output")
+    .option("-d, --dry-run", "Preview cleanup without changes")
+    .option("--max-age <days>", "Remove entries older than N days", parseInt)
+    .option("--all", "Remove all orphaned entries (merged and abandoned)")
+    .action(stateCleanCommand);
 // Parse and execute
 program.parse();
 // Show help if no command provided

package/dist/dashboard/server.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Sequant Dashboard Server
+ *
+ * A lightweight web dashboard for visualizing workflow state using:
+ * - Hono: Fast, lightweight web framework
+ * - htmx: HTML-first interactivity
+ * - Pico CSS: Classless styling
+ * - SSE: Server-sent events for live updates
+ *
+ * @example
+ * ```typescript
+ * import { startDashboard } from './server';
+ * await startDashboard({ port: 3456, open: true });
+ * ```
+ */
+import { Hono } from "hono";
+import { StateManager } from "../src/lib/workflow/state-manager.js";
+export interface DashboardOptions {
+    /** Port to run the server on (default: 3456) */
+    port?: number;
+    /** Whether to open browser automatically (default: true) */
+    open?: boolean;
+    /** Custom state file path */
+    statePath?: string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+/**
+ * Create the Hono app
+ */
+export declare function createApp(stateManager: StateManager): Hono;
+/**
+ * Start the dashboard server
+ */
+export declare function startDashboard(options?: DashboardOptions): Promise<{
+    close: () => void;
+}>;