Local overrides (read this first). Before following any instruction below, check whether .claude/.local/skills/setup/overrides.md exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor /setup without forking it — overrides.md lives under .claude/.local/, which sequant update and sync never overwrite.

Sequant Setup

Initialize Sequant workflow system in your current project.

Purpose

When invoked as /sequant:setup or /setup, this skill configures everything a plugin user needs — the equivalent of sequant init for npm users.

Usage

/sequant:setup

What It Does

1. Check Prerequisites

Verify all required tools are installed and authenticated.

echo "=== Sequant Prerequisites Check ==="

# 1. Git
if git --version >/dev/null 2>&1; then
  echo "✅ git: $(git --version | head -1)"
else
  echo "❌ git: not found — install from https://git-scm.com"
  PREREQ_FAIL=true
fi

# 2. GitHub CLI
if gh --version >/dev/null 2>&1; then
  echo "✅ gh: $(gh --version | head -1)"
  if gh auth status >/dev/null 2>&1; then
    echo "✅ gh auth: authenticated"
  else
    echo "❌ gh auth: not authenticated — run 'gh auth login'"
    PREREQ_FAIL=true
  fi
else
  echo "❌ gh: not found — install from https://cli.github.com"
  PREREQ_FAIL=true
fi

# 3. Node.js 22.13+ (for MCP server via npx)
if node --version >/dev/null 2>&1; then
  NODE_VER=$(node --version | sed 's/v//' | cut -d. -f1)
  if [ "$NODE_VER" -ge 22 ] 2>/dev/null; then
    echo "✅ node: $(node --version) (>= 22)"
  else
    echo "⚠️  node: $(node --version) — MCP server requires Node.js 22.13+. Upgrade recommended."
  fi
else
  echo "⚠️  node: not found — MCP server (npx sequant serve) requires Node.js 22.13+"
fi

if [ "$PREREQ_FAIL" = "true" ]; then
  echo ""
  echo "Fix the issues above, then re-run /sequant:setup"
fi

If any critical prerequisite fails (git or gh), stop and report. Node.js is a warning (needed for MCP server but not skills).

2. Create Worktrees Directory

mkdir -p ../worktrees/feature
echo "✅ Created ../worktrees/feature/"

3. Detect Project Name

The skill automatically detects your project name from available sources in priority order:

1. package.json - Node.js projects (name field)
2. Cargo.toml - Rust projects ([package] name)
3. pyproject.toml - Python projects ([project] name or [tool.poetry] name)
4. go.mod - Go projects (module path, last segment)
5. Git remote - Extract repo name from origin URL
6. Directory name - Fallback to current directory name

# Detection script (run each step until a name is found)

# 1. Try package.json
if [ -f "package.json" ]; then
  PROJECT_NAME=$(cat package.json | jq -r '.name // empty' 2>/dev/null)
fi

# 2. Try Cargo.toml
if [ -z "$PROJECT_NAME" ] && [ -f "Cargo.toml" ]; then
  PROJECT_NAME=$(grep -A5 '^\[package\]' Cargo.toml | grep '^name' | head -1 | sed 's/.*=\s*["'\'']\([^"'\'']*\)["'\''].*/\1/' || true)
fi

# 3. Try pyproject.toml
if [ -z "$PROJECT_NAME" ] && [ -f "pyproject.toml" ]; then
  # Try [project] section first (PEP 621)
  PROJECT_NAME=$(grep -A5 '^\[project\]' pyproject.toml | grep '^name' | head -1 | sed 's/.*=\s*["'\'']\([^"'\'']*\)["'\''].*/\1/' || true)
  # Fallback to [tool.poetry] section
  if [ -z "$PROJECT_NAME" ]; then
    PROJECT_NAME=$(grep -A5 '^\[tool\.poetry\]' pyproject.toml | grep '^name' | head -1 | sed 's/.*=\s*["'\'']\([^"'\'']*\)["'\''].*/\1/' || true)
  fi
fi

# 4. Try go.mod
if [ -z "$PROJECT_NAME" ] && [ -f "go.mod" ]; then
  MODULE_PATH=$(grep '^module ' go.mod | head -1 | awk '{print $(2)}' || true)
  PROJECT_NAME=$(basename "$MODULE_PATH")
fi

# 5. Try git remote
if [ -z "$PROJECT_NAME" ]; then
  REMOTE_URL=$(git remote get-url origin 2>/dev/null)
  if [ -n "$REMOTE_URL" ]; then
    # Handle both SSH and HTTPS formats
    PROJECT_NAME=$(echo "$REMOTE_URL" | sed 's/.*[:/]\([^/]*\)\.git$/\1/' | sed 's/.*\/\([^/]*\)$/\1/')
  fi
fi

# 6. Fallback to directory name
if [ -z "$PROJECT_NAME" ]; then
  PROJECT_NAME=$(basename "$(pwd)")
fi

echo "Detected project name: $PROJECT_NAME"

4. Create .sequant/ Configuration

mkdir -p .sequant

Create .sequant/settings.json with sensible defaults:

{
  "version": "1.0",
  "run": {
    "logJson": true,
    "logPath": ".sequant/logs",
    "autoDetectPhases": true,
    "timeout": 1800,
    "sequential": false,
    "qualityLoop": false,
    "maxIterations": 3,
    "smartTests": true,
    "mcp": true,
    "retry": true,
    "staleBranchThreshold": 5
  },
  "agents": {
    "parallel": false,
    "model": "haiku"
  }
}

Note: agents.model is currently inert per
anthropics/claude-code#43869.
Subagents inherit the parent session's model regardless of this value. The
field is kept for forward compatibility so existing settings.json files
continue to parse without error.

Use the Write tool to create .sequant/settings.json with the above content.

5. Detect Package Manager

# Detect package manager. PM stays EMPTY when no lockfile identifies one:
# an undeclared manager lets `resolvePackageManager` decide live at run time
# (#932); recording a guessed "npm" would short-circuit that detection.
PM=""
PM_RUN="npm run"
# Precedence mirrors LOCKFILE_PRIORITY in src/lib/stacks.ts (bun > yarn >
# pnpm > npm) so a declared value never outranks what live detection would pick.
if [ -f "bun.lockb" ] || [ -f "bun.lock" ]; then
  PM="bun"
  PM_RUN="bun run"
  echo "✅ Detected package manager: bun"
elif [ -f "yarn.lock" ]; then
  PM="yarn"
  PM_RUN="yarn"
  echo "✅ Detected package manager: yarn"
elif [ -f "pnpm-lock.yaml" ]; then
  PM="pnpm"
  PM_RUN="pnpm run"
  echo "✅ Detected package manager: pnpm"
elif [ -f "package-lock.json" ]; then
  PM="npm"
  PM_RUN="npm run"
  echo "✅ Detected package manager: npm"
else
  echo "ℹ️  No lock file found — leaving packageManager undeclared (pmRun defaults to npm run)"
fi

Store PM_RUN in settings for use by /exec and /spec:

After detecting PM_RUN, use the Edit tool to add it to .sequant/settings.json under the run section:

{
  "run": {
    "pmRun": "<detected PM_RUN value>"
  }
}

6. Detect Dev Server URL

# Detect dev server URL from common patterns
DEV_URL=""

if [ -f "package.json" ]; then
  # Check for common dev scripts
  DEV_SCRIPT=$(cat package.json | jq -r '.scripts.dev // empty' 2>/dev/null)

  if echo "$DEV_SCRIPT" | grep -q "next"; then
    DEV_URL="http://localhost:3000"
    echo "✅ Detected Next.js dev server: $DEV_URL"
  elif echo "$DEV_SCRIPT" | grep -q "vite"; then
    DEV_URL="http://localhost:5173"
    echo "✅ Detected Vite dev server: $DEV_URL"
  elif echo "$DEV_SCRIPT" | grep -q "nuxt"; then
    DEV_URL="http://localhost:3000"
    echo "✅ Detected Nuxt dev server: $DEV_URL"
  elif echo "$DEV_SCRIPT" | grep -q "remix"; then
    DEV_URL="http://localhost:3000"
    echo "✅ Detected Remix dev server: $DEV_URL"
  elif [ -n "$DEV_SCRIPT" ]; then
    DEV_URL="http://localhost:3000"
    echo "ℹ️  Dev script found but server URL unclear — defaulting to $DEV_URL"
    echo "    Update .sequant/settings.json if your dev server uses a different port."
  fi
fi

if [ -z "$DEV_URL" ]; then
  echo "ℹ️  No dev server detected (not needed for CLI/backend projects)"
fi

Store DEV_URL in settings if detected. Use the Edit tool to add:

{
  "run": {
    "devUrl": "<detected DEV_URL value>"
  }
}

7. Create .sequant-manifest.json

Create a manifest with version and stack info for diagnostics:

# Detect stack
STACK="unknown"
if [ -f "next.config.js" ] || [ -f "next.config.ts" ] || [ -f "next.config.mjs" ]; then
  STACK="nextjs"
elif [ -f "vite.config.ts" ] || [ -f "vite.config.js" ]; then
  STACK="vite"
elif [ -f "nuxt.config.ts" ]; then
  STACK="nuxt"
elif [ -f "Cargo.toml" ]; then
  STACK="rust"
elif [ -f "go.mod" ]; then
  STACK="go"
elif [ -f "pyproject.toml" ]; then
  STACK="python"
elif [ -f "package.json" ]; then
  STACK="node"
fi

Use the Write tool to create .sequant-manifest.json — plain JSON, exactly the
shape below. Include the packageManager line only when PM is non-empty
(a lockfile identified it); when no lockfile was found, omit that line entirely
so resolvePackageManager decides at run time (#932):

{
  "version": "latest",
  "installedVia": "plugin",
  "stack": "<detected stack>",
  "pmRun": "<detected PM_RUN>",
  "packageManager": "<detected PM>",
  "createdAt": "<ISO-8601 timestamp>"
}

8. Copy Constitution Template

mkdir -p .claude/memory
CONST_SRC="${CLAUDE_PLUGIN_ROOT:-./templates}/memory/constitution.md"
cp "$CONST_SRC" .claude/memory/constitution.md

9. Replace Project Name Placeholder

# Replace {{PROJECT_NAME}} with detected project name
sed -i.bak "s/{{PROJECT_NAME}}/$PROJECT_NAME/g" .claude/memory/constitution.md
rm -f .claude/memory/constitution.md.bak

10. Copy Phase Skills

sequant run phase agents load skills from .claude/skills/ only (project
scope, #813) — a plugin install alone leaves that directory empty. Copy the
phase skills from the plugin, the same way step 8 copies the constitution
template:

SKILLS_SRC="${CLAUDE_PLUGIN_ROOT:-./templates}/skills"
# Check every source before deleting anything: outside a plugin install
# CLAUDE_PLUGIN_ROOT is unset and ./templates usually doesn't exist, and an
# rm before a failed cp would delete the project's committed skills.
for dir in spec exec qa _shared; do
  if [ ! -d "$SKILLS_SRC/$dir" ]; then
    echo "Skipping phase-skill copy: $SKILLS_SRC/$dir not found. Run \`sequant sync\` instead." >&2
    SKILLS_SRC=""
    break
  fi
done
if [ -n "$SKILLS_SRC" ]; then
  mkdir -p .claude/skills
  # _shared holds the references/ files the phase skills link to (../_shared/...).
  for dir in spec exec qa _shared; do
    rm -rf ".claude/skills/$dir"
    cp -R "$SKILLS_SRC/$dir" ".claude/skills/$dir"
  done
fi

If the copy was skipped, say so in the summary and don't report the phase
skills as installed.

Tell the user to commit .claude/skills/spec, .claude/skills/exec,
.claude/skills/qa, and .claude/skills/_shared. They are a runtime dependency, not a cache: sequant run pre-flights the directory and fails fast if it is missing or uncommitted.

11. Print Summary

After setup completes, print a summary:

## Sequant Setup Complete

### What was configured

| Item | Status |
|------|--------|
| Prerequisites | ✅ git, gh, node checked |
| Worktrees | ✅ ../worktrees/feature/ created |
| Project name | ✅ <PROJECT_NAME> |
| Config | ✅ .sequant/settings.json |
| Package manager | ✅ <PM_RUN> |
| Dev server | ✅ <DEV_URL> (or ℹ️ not detected) |
| Manifest | ✅ .sequant-manifest.json |
| Constitution | ✅ .claude/memory/constitution.md |
| Phase skills | ✅ .claude/skills/spec, exec, qa, _shared (commit these) |

### MCP Tools Available

The plugin includes an MCP server that provides these tools automatically:

| Tool | Purpose |
|------|---------|
| `sequant_status` | Check issue progress and workflow state |
| `sequant_run` | Execute workflow phases (spec, exec, qa) |
| `sequant_logs` | Review past run results and debug failures |

### What's Next

You're all set — run `/assess <issue>` to start working on a GitHub issue.

**Common commands:**
- `/assess 123` — Analyze issue, get recommended workflow
- `/fullsolve 123` — End-to-end: spec → exec → qa → PR
- `/spec 123` — Plan implementation only
- `/exec 123` — Implement only

Post-Setup

1. Commit .claude/skills/spec, .claude/skills/exec, .claude/skills/qa, and .claude/skills/_shared - sequant run phase agents cannot resolve skills that aren't committed, and the phase skills link to _shared/references/
2. Review .claude/memory/constitution.md - project name should be filled in
3. Add any project-specific guidelines to the constitution
4. Optionally edit .sequant/settings.json to customize:
   • devUrl — if auto-detection picked the wrong port
   • pmRun — if using a non-standard package manager command
   • agents.parallel — set to true for faster but more token-expensive runs
5. Run /assess <issue> to start working

Troubleshooting

Project name shows as directory name instead of package name:

• Ensure your package.json, Cargo.toml, pyproject.toml, or go.mod has a valid name field
• Check that the file is valid JSON/TOML

MCP tools not available:

• Ensure Node.js 22.13+ is installed (node --version)
• The MCP server starts automatically via npx -y sequant@<version> serve (pinned to your installed version, not @latest, so reconnects don't reinstall on every release — see #793)
• Check Claude Code settings if tools don't appear

Settings not being picked up:

• Verify .sequant/settings.json is valid JSON
• Check that .sequant/ is not gitignored in your project (it should be — these are local settings)