sequant 1.5.4 → 1.5.6

package/README.md

@@ -1,410 +1,185 @@
 # Sequant
 
-**Structured AI workflow for GitHub issues.**
+**Workflow automation for [Claude Code](https://claude.ai/code).**
 
-Turn GitHub issues into working code through sequential AI-assisted phases with quality gates.
+Solve GitHub issues with structured phases and quality gates — from issue to merge-ready PR.
 
 [![npm version](https://img.shields.io/npm/v/sequant.svg)](https://www.npmjs.com/package/sequant)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-## Why Sequant?
-
-When using AI coding assistants, work can become scattered and quality inconsistent. Sequant solves this by:
-
-- **Consistent quality** — Every issue goes through the same review gates
-- **Traceable decisions** — Plans and progress documented in GitHub issues
-- **Isolated work** — Git worktrees prevent half-finished features from polluting main
-- **AI-assisted** — Claude Code handles implementation while you review and approve
-
-## How It Works
-
-```
-┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
-│  /spec  │───▶│  /exec  │───▶│  /test  │───▶│   /qa   │───▶ Merge
-└─────────┘    └─────────┘    └─────────┘    └─────────┘
-     │              │              │              │
-     ▼              ▼              ▼              ▼
-   Plan          Build          Verify        Review
-  (drafts AC)   (worktree)    (optional)    (vs criteria)
-```
-
-1. **`/spec`** — Reads issue, drafts implementation plan, posts to GitHub for your approval
-2. **`/exec`** — Creates isolated git worktree, implements changes, runs tests
-3. **`/test`** — Optional browser/CLI verification
-4. **`/qa`** — Reviews code against acceptance criteria, suggests fixes
-
 ## Quick Start
 
-### Prerequisites
-
-| Requirement | Check Command | Notes |
-|------------|---------------|-------|
-| [Claude Code](https://claude.ai/code) | `claude --version` | Required |
-| [GitHub CLI](https://cli.github.com/) | `gh auth status` | Required, must be authenticated |
-| Node.js 18+ | `node --version` | Required |
-| Git | `git --version` | Required |
-| [jq](https://jqlang.github.io/jq/) | `jq --version` | Optional, improves hook performance |
-
-> **Note:** Sequant currently requires GitHub for issue tracking. GitLab and Bitbucket support is planned for a future release. See [Platform Requirements](docs/platform-requirements.md) for workarounds if you use a different platform.
-
-### Setup
-
 ```bash
-# Install and initialize in your project
+# In your project directory
 npx sequant init
-
-# Verify installation and prerequisites
-npx sequant doctor
+npx sequant doctor   # Verify setup
 ```
 
-The `doctor` command checks all prerequisites including GitHub CLI authentication.
-
-### First Workflow
+Then in Claude Code:
 
-Open Claude Code in your project, then:
-
-```bash
-/spec 123    # Plan implementation for GitHub issue #123
-/exec 123    # Implement the feature in a worktree
-/qa 123      # Quality review before merge
 ```
-
-> Replace `123` with an actual GitHub issue number from your repository.
-
-## Installation
-
-```bash
-npm install -g sequant
-# or use npx
-npx sequant init
+/fullsolve 123    # Solve issue #123 end-to-end
 ```
 
-## Features
-
-- **🔢 Quantized** - Each issue is an atomic unit of work
-- **🔄 Sequential** - Phases execute in order with gates
-- **🚦 Gated** - Quality checks before progression
-- **🌳 Isolated** - Git worktrees prevent cross-contamination
-- **📦 Stack Adapters** - Pre-configured for Next.js, Rust, Python, Go
-- **🔄 Update-Safe** - Customize without losing updates
+Or step-by-step:
 
-## Optional MCP Integrations
-
-Sequant works fully without any MCP servers, but these optional integrations enhance specific workflows. See the [MCP Integrations Guide](docs/mcp-integrations.md) for detailed setup and troubleshooting.
-
-| MCP Server | Skills | Purpose | Install |
-|------------|--------|---------|---------|
-| [Chrome DevTools](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-chrome-devtools) | `/test`, `/testgen`, `/loop` | Browser automation for UI testing | See [setup guide](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-chrome-devtools#setup) |
-| [Context7](https://github.com/upstash/context7) | `/exec`, `/fullsolve` | External library documentation lookup | `npx -y @anthropic/mcp-cli add upstash/context7` |
-| [Sequential Thinking](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-sequential-thinking) | `/fullsolve` | Complex multi-step reasoning | See [setup guide](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-sequential-thinking#setup) |
-
-**What happens without MCPs:**
-- `/test` and `/testgen` fall back to manual testing instructions
-- `/exec` uses codebase search instead of library docs lookup
-- `/fullsolve` uses standard reasoning (no extended thinking)
+```
+/spec 123    # Plan implementation
+/exec 123    # Build in isolated worktree
+/qa 123      # Review before merge
+```
 
-Run `sequant doctor` to check which optional MCPs are configured.
+### Prerequisites
 
-## Commands
+- [Claude Code](https://claude.ai/code) — AI coding assistant
+- [GitHub CLI](https://cli.github.com/) — run `gh auth login`
+- Node.js 18+ and Git
 
-### CLI Commands
+---
 
-```bash
-npx sequant init              # Initialize in your project
-npx sequant update            # Update templates from package
-npx sequant doctor            # Check installation health
-npx sequant status            # Show version and config
-npx sequant run <issues...>   # Execute workflow for issues
-```
+## How It Works
 
-#### Run Command Options
+Sequant adds slash commands to Claude Code that enforce a structured workflow:
 
-```bash
-npx sequant run 123                    # Single issue
-npx sequant run 1 2 3                  # Multiple issues in parallel
-npx sequant run 1 2 3 --sequential     # Run in order
-npx sequant run 123 --phases spec,qa   # Custom phases
-npx sequant run 123 --quality-loop     # Auto-retry on failures
-npx sequant run 123 --dry-run          # Preview without execution
 ```
-
-#### Quality Loop
-
-Quality loop provides automatic fix iterations when phases fail:
-
-```bash
-npx sequant run 123 --quality-loop              # Enable for any issue
-npx sequant run 123 --quality-loop --max-iterations 5  # Custom limit
+┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
+│  /spec  │───▶│  /exec  │───▶│  /test  │───▶│   /qa   │───▶ Merge
+└─────────┘    └─────────┘    └─────────┘    └─────────┘
+     │              │              │              │
+     ▼              ▼              ▼              ▼
+   Plan          Build        Verify (UI)     Review
 ```
 
-**How it works:**
-1. Runs phases normally (spec → exec → qa)
-2. If a phase fails, runs `/loop` to fix issues
-3. Re-runs failed phases after fixes
-4. Iterates up to 3 times (default)
-
-**Smart defaults:** Quality loop auto-enables for issues with `complex`, `refactor`, `breaking`, or `major` labels—no flag needed.
+> `/test` is optional — used for UI features when Chrome DevTools MCP is available.
 
-#### Phase Detection
+### Quality Gates
 
-When you run `sequant run`, phases are determined automatically using a three-level detection system:
+Every `/qa` runs automated checks:
 
-1. **Explicit phases** — If you specify `--phases`, those are used
-2. **Spec-driven** — Otherwise, `/spec` runs first and outputs a recommended workflow
-3. **Label-based fallback** — If spec parsing fails, issue labels determine phases
+- **AC Adherence** — Code verified against acceptance criteria
+- **Type Safety** — Detects `any`, `as any`, missing types
+- **Security Scans** — OWASP-style vulnerability detection
+- **Scope Analysis** — Flags changes outside issue scope
 
-**Label-based detection:**
+When checks fail, `/loop` automatically fixes and re-runs (up to 3x).
 
-| Labels | Phases | Notes |
-|--------|--------|-------|
-| `bug`, `fix`, `hotfix`, `patch` | `exec → qa` | Skip spec for simple fixes |
-| `docs`, `documentation`, `readme` | `exec → qa` | Skip spec for docs changes |
-| `ui`, `frontend`, `admin`, `web`, `browser` | `spec → exec → test → qa` | Add browser testing |
-| `complex`, `refactor`, `breaking`, `major` | (default phases) | Enable quality loop |
+---
 
-**Spec-driven detection:**
+## Two Ways to Use
 
-The `/spec` command outputs a recommended workflow that the CLI parses:
+### Interactive (Claude Code)
 
-```markdown
-## Recommended Workflow
+Type commands directly in Claude Code chat:
 
-**Phases:** exec → test → qa
-**Quality Loop:** disabled
-**Reasoning:** UI changes detected, adding browser testing phase
+```
+/fullsolve 123              # Complete pipeline
+/spec 123 → /exec → /qa     # Step by step
 ```
 
-**CLI examples:**
-
-```bash
-# Phases auto-detected (default)
-npx sequant run 123
-
-# Explicit phases (skip auto-detection)
-npx sequant run 123 --phases exec,qa
+### Headless (CLI)
 
-# Disable logging for one run
-npx sequant run 123 --no-log
+Run without Claude Code UI:
 
-# Enable quality loop for complex changes
+```bash
+npx sequant run 123              # Single issue
+npx sequant run 1 2 3            # Batch (parallel)
 npx sequant run 123 --quality-loop
 ```
 
-### Workflow Commands (in Claude Code)
-
-| Command | Phase | Purpose |
-|---------|-------|---------|
-| `/assess` | 0 | Issue triage and status assessment |
-| `/spec` | 1 | Plan implementation vs acceptance criteria |
-| `/exec` | 2 | Implement in feature worktree |
-| `/test` | 2.5 | Browser-based UI testing (optional) |
-| `/verify` | 2.5 | CLI/script verification (optional) |
-| `/qa` | 3 | Code review and quality gate |
-| `/docs` | 4 | Generate feature documentation |
-| `/loop` | * | Fix iteration when tests fail |
-| `/fullsolve` | 1-4 | Complete pipeline in one command |
+---
 
-## Platform Support
-
-| Platform | Status | Notes |
-|----------|--------|-------|
-| macOS | ✅ Tested | Full support with Claude Code, Cursor, VS Code |
-| Linux | ✅ Supported | Bash required for shell scripts |
-| Windows WSL | ✅ Supported | Use WSL2 with bash |
-| Windows Native | ⚠️ Limited | CLI works, but shell scripts require WSL |
-
-### Windows Users
-
-**WSL is recommended** for the full Sequant experience on Windows. Here's why:
-
-| Feature | Native Windows | Windows + WSL |
-|---------|----------------|---------------|
-| CLI commands (`init`, `doctor`, `status`) | ✅ Works | ✅ Works |
-| Workflow hooks (pre-tool, post-tool) | ❌ Requires bash | ✅ Works |
-| Shell scripts (`new-feature.sh`, etc.) | ❌ Requires bash | ✅ Works |
-| Git worktree workflows | ✅ Works | ✅ Works |
-
-**Quick WSL Setup:**
-
-1. Install WSL (run in PowerShell as Administrator): `wsl --install`
-2. Restart your computer when prompted
-3. Open Ubuntu from Start menu and complete setup
-4. Install Node.js: See [NodeSource distributions](https://github.com/nodesource/distributions)
-5. Install GitHub CLI: `apt install gh` then `gh auth login`
-6. Use Sequant: `npx sequant init`
-
-For detailed instructions, see [Microsoft's WSL documentation](https://learn.microsoft.com/en-us/windows/wsl/install).
+## Commands
 
-### Requirements
+### Core Workflow
 
-- **Node.js** 18.0.0 or higher
-- **Git** for worktree support
-- **GitHub CLI** (`gh`) for issue integration — must be authenticated via `gh auth login`
-- **Bash** for shell scripts (included in macOS/Linux, use WSL on Windows)
-- **jq** (optional) for faster JSON parsing in hooks — falls back to grep if not installed
+| Command | Purpose |
+|---------|---------|
+| `/spec` | Plan implementation, draft acceptance criteria |
+| `/exec` | Implement in isolated git worktree |
+| `/test` | Browser-based UI testing (optional) |
+| `/qa` | Code review and quality gate |
 
-### IDE Compatibility
+### Automation
 
-| IDE | Status |
-|-----|--------|
-| Claude Code | ✅ Full support |
-| Cursor | ✅ Supported |
-| VS Code + Copilot | ✅ Supported |
+| Command | Purpose |
+|---------|---------|
+| `/fullsolve` | Complete pipeline in one command |
+| `/solve` | Recommend optimal workflow for issue |
+| `/loop` | Fix iteration when checks fail |
 
-## Stack Support
+### Integration
 
-Sequant auto-detects your project stack and configures appropriate commands:
+| Command | Purpose |
+|---------|---------|
+| `/merger` | Multi-issue integration and merge |
+| `/testgen` | Generate test stubs from spec |
+| `/verify` | CLI/script execution verification |
 
-| Stack | Detection | Test | Build | Lint |
-|-------|-----------|------|-------|------|
-| Next.js | `next.config.*` | `npm test` | `npm run build` | `npm run lint` |
-| Rust | `Cargo.toml` | `cargo test` | `cargo build --release` | `cargo clippy` |
-| Python | `pyproject.toml` | `pytest` | `python -m build` | `ruff check .` |
-| Go | `go.mod` | `go test ./...` | `go build ./...` | `golangci-lint run` |
+### Utilities
 
-## Customization
+| Command | Purpose |
+|---------|---------|
+| `/assess` | Issue triage and status assessment |
+| `/docs` | Generate feature documentation |
+| `/release` | Automated release workflow |
+| `/clean` | Repository cleanup |
+| `/security-review` | Deep security analysis |
+| `/reflect` | Workflow improvement analysis |
 
-### Local Overrides
+---
 
-Create files in `.claude/.local/` to override templates without losing updates:
+## CLI Commands
 
+```bash
+npx sequant init              # Initialize in project
+npx sequant update            # Update skill templates
+npx sequant doctor            # Check installation
+npx sequant status            # Show version and config
+npx sequant run <issues...>   # Execute workflow
 ```
-.claude/
-├── skills/           # Package-provided (updated by sequant update)
-├── skills.local/     # Your overrides (never modified)
-├── hooks/            # Package-provided
-├── hooks.local/      # Your overrides
-└── memory/           # Your project context (never modified)
-```
-
-### Constitution
-
-Edit `.claude/memory/constitution.md` to define project-specific principles:
 
-```markdown
-# My Project Constitution
-
-## Core Principles
-1. Always use TypeScript strict mode
-2. Test coverage must exceed 80%
-3. All PRs require security review
-
-## Naming Conventions
-- Components: PascalCase
-- Utilities: camelCase
-- Constants: SCREAMING_SNAKE_CASE
-```
+See [Run Command Options](docs/run-command.md) for advanced usage.
 
-### Settings
+---
 
-Configure `sequant run` defaults in `.sequant/settings.json`:
+## Configuration
 
 ```json
+// .sequant/settings.json
 {
-  "version": "1.0",
   "run": {
-    "logJson": true,
-    "logPath": ".sequant/logs",
-    "autoDetectPhases": true,
-    "timeout": 300,
-    "sequential": false,
     "qualityLoop": false,
-    "maxIterations": 3,
-    "smartTests": true
-  },
-  "agents": {
-    "parallel": false,
-    "model": "haiku"
+    "maxIterations": 3
   }
 }
 ```
 
-#### Run Settings
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `logJson` | `true` | Enable JSON logging for run sessions |
-| `logPath` | `.sequant/logs` | Directory for log files |
-| `autoDetectPhases` | `true` | Auto-detect phases from labels/spec output |
-| `timeout` | `300` | Timeout per phase in seconds |
-| `sequential` | `false` | Run issues sequentially (vs parallel) |
-| `qualityLoop` | `false` | Enable quality loop by default |
-| `maxIterations` | `3` | Max quality loop iterations |
-| `smartTests` | `true` | Auto-detect test commands |
-
-#### Agent Settings
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `parallel` | `false` | Run sub-agents in parallel (faster but higher token usage) |
-| `model` | `"haiku"` | Default model for sub-agents (`haiku`, `sonnet`, or `opus`) |
-
-##### Cost vs Speed Trade-offs
-
-Skills like `/qa`, `/merger`, and `/fullsolve` spawn sub-agents for quality checks. The `agents` settings control how these agents execute:
+See [Customization Guide](docs/customization.md) for all options.
 
-| Mode | Token Usage | Speed | Best For |
-|------|-------------|-------|----------|
-| Sequential (`parallel: false`) | 1x (baseline) | Slower | Limited API plans, cost-conscious users |
-| Parallel (`parallel: true`) | ~2-3x | ~50% faster | Unlimited plans, batch operations |
+---
 
-**Override per invocation:**
-
-```bash
-/qa 123 --parallel     # Force parallel (faster)
-/qa 123 --sequential   # Force sequential (cheaper)
-```
-
-CLI flags override settings file values.
+## Platform Support
 
-## Directory Structure
+| Platform | Status |
+|----------|--------|
+| macOS | ✅ Full support |
+| Linux | ✅ Full support |
+| Windows WSL | ✅ Full support |
+| Windows Native | ⚠️ CLI only |
 
-After `sequant init`:
-
-```
-.claude/
-├── skills/              # Workflow commands
-│   ├── spec/SKILL.md
-│   ├── exec/SKILL.md
-│   ├── qa/SKILL.md
-│   └── ...
-├── hooks/               # Pre/post tool hooks
-│   ├── pre-tool.sh
-│   └── post-tool.sh
-├── memory/              # Project context
-│   └── constitution.md
-└── settings.json        # Hooks configuration
-
-.sequant-manifest.json   # Version tracking
-```
+---
 
 ## Documentation
 
-- [Run Command](docs/run-command.md) — Batch execution options
-- [Customization Guide](docs/customization.md) — Override templates safely
-- [MCP Integrations](docs/mcp-integrations.md) — Optional MCP server setup
-- [Platform Requirements](docs/platform-requirements.md) — GitHub dependency and workarounds
-- [Troubleshooting](docs/troubleshooting.md) — Common issues and solutions
-- [Testing Guide](docs/testing.md) — Cross-platform testing matrix
-- [Git Patterns](docs/git-patterns.md) — Worktree and merge workflows
-- [Release Checklist](docs/release-checklist.md) — Pre-release verification
-- Stack Guides: [Next.js](docs/stacks/nextjs.md) | [Rust](docs/stacks/rust.md) | [Python](docs/stacks/python.md) | [Go](docs/stacks/go.md)
-
-## Philosophy
-
-Sequant is built on these principles:
-
-1. **Explicit over implicit** — Every phase has clear inputs and outputs
-2. **Quality gates** — No phase completes without validation
-3. **Isolation** — Work happens in dedicated worktrees
-4. **Traceability** — All decisions recorded in GitHub issues
-5. **Composability** — Use phases individually or combine them
+- [Getting Started](docs/getting-started/installation.md)
+- [Workflow Concepts](docs/concepts/workflow-phases.md)
+- [Run Command](docs/run-command.md)
+- [Customization](docs/customization.md)
+- [Troubleshooting](docs/troubleshooting.md)
 
-## Acknowledgments
+Stack guides: [Next.js](docs/stacks/nextjs.md) · [Rust](docs/stacks/rust.md) · [Python](docs/stacks/python.md) · [Go](docs/stacks/go.md)
 
-Built on ideas from:
-- [Agent Skills](https://agentskills.io) — Open standard for cross-platform skills
-- [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) — Update-safe directories
+---
 
 ## License
 

package/dist/src/commands/run.js

@@ -135,6 +135,16 @@ async function ensureWorktree(issueNumber, title, verbose, packageManager) {
     if (verbose) {
         console.log(chalk.gray(`    🌿 Creating worktree for #${issueNumber}...`));
     }
+    // Fetch latest main to ensure worktree starts from fresh baseline
+    if (verbose) {
+        console.log(chalk.gray(`    🔄 Fetching latest main...`));
+    }
+    const fetchResult = spawnSync("git", ["fetch", "origin", "main"], {
+        stdio: "pipe",
+    });
+    if (fetchResult.status !== 0 && verbose) {
+        console.log(chalk.yellow(`    ⚠️  Could not fetch origin/main, using local state`));
+    }
     // Ensure worktrees directory exists
     if (!existsSync(worktreesDir)) {
         spawnSync("mkdir", ["-p", worktreesDir], { stdio: "pipe" });
@@ -148,8 +158,8 @@ async function ensureWorktree(issueNumber, title, verbose, packageManager) {
         });
     }
     else {
-        // Create new branch from main
-        createResult = spawnSync("git", ["worktree", "add", worktreePath, "-b", branch], { stdio: "pipe" });
+        // Create new branch from origin/main (fresh baseline)
+        createResult = spawnSync("git", ["worktree", "add", worktreePath, "-b", branch, "origin/main"], { stdio: "pipe" });
     }
     if (createResult.status !== 0) {
         const error = createResult.stderr.toString();

package/dist/src/lib/version-check.js

@@ -31,11 +31,24 @@ export function getCachePath() {
  */
 export function getCurrentVersion() {
     try {
-        // Navigate from dist/lib to package.json
-        const packagePath = path.resolve(__dirname, "..", "..", "package.json");
-        const content = fs.readFileSync(packagePath, "utf8");
-        const pkg = JSON.parse(content);
-        return pkg.version || "0.0.0";
+        // Walk up from current directory until we find sequant's package.json
+        // Works from both source (src/lib/) and compiled (dist/src/lib/) locations
+        let dir = __dirname;
+        while (dir !== path.dirname(dir)) {
+            const candidate = path.resolve(dir, "package.json");
+            try {
+                const content = fs.readFileSync(candidate, "utf8");
+                const pkg = JSON.parse(content);
+                if (pkg.name === "sequant") {
+                    return pkg.version || "0.0.0";
+                }
+            }
+            catch {
+                // Not found, continue searching
+            }
+            dir = path.dirname(dir);
+        }
+        return "0.0.0";
     }
     catch {
         return "0.0.0";

package/package.json

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