Skip to main content

SpecWeave Installation

Comprehensive installation guide for all scenarios.

Prerequisites​

Before installing SpecWeave, ensure you have:

Required:

  • Node.js 20.12.0+ (we recommend Node.js 22 LTS) - Check with node --version
  • npm 9+ - Check with npm --version
Node.js Version Critical

SpecWeave requires Node.js 20.12.0 or higher. If you see SyntaxError: Unexpected token 'with', your Node.js is too old.

# Check your version
node --version

# If below v20.12.0, upgrade:
nvm install 22 && nvm use 22 && nvm alias default 22

See detailed upgrade instructions for all platforms.

Recommended:

  • Claude Code (best experience)
  • Git for version control

Installation Methods​

Install once, use everywhere:

# Install globally
npm install -g specweave

# Verify installation
specweave --version

# Create new project
specweave init my-project
cd my-project

Pros:

  • ✅ Command always available (specweave command)
  • ✅ Faster subsequent runs (no download)
  • ✅ Works offline after first install
  • ✅ Consistent version across projects

Cons:

  • ❌ Requires admin/root on some systems
  • ❌ Manual updates needed: npm update -g specweave

Best for: Regular SpecWeave users, developers working on multiple projects

Method 2: npx (No Install)​

Run without installing:

# New project (always uses latest version)
npx specweave init my-project
cd my-project

# Existing project
cd my-existing-project
npx specweave init .

Pros:

  • ✅ No global installation needed
  • ✅ Always uses latest version
  • ✅ No permission issues
  • ✅ Perfect for CI/CD

Cons:

  • ❌ Slower (downloads each time)
  • ❌ Requires internet connection

Best for: First-time users, CI/CD pipelines, testing latest version

Method 3: From Source (Contributors)​

For contributors or testing unreleased features:

# Clone repository
git clone https://github.com/anton-abyzov/specweave.git
cd specweave

# Install dependencies
npm install

# Build TypeScript
npm run build

# Link globally
npm link

# Verify
specweave --version

# Create project
specweave init my-project

Best for: Contributors, debugging, custom modifications

What Gets Installed​

Directory Structure​

After running specweave init, you get:

your-project/
├── .claude/                  # Claude Code integration (if detected)
│   ├── settings.json         # Plugin marketplace reference (GitHub remote)
│   ├── agents/               # 11 specialized agents (installed from plugins)
│   │   ├── pm/               # Product Manager AI
│   │   ├── architect/        # System Architect
│   │   ├── tech-lead/        # Tech Lead
│   │   ├── qa-lead/          # QA Lead
│   │   ├── security/         # Security Engineer
│   │   ├── performance/      # Performance Engineer
│   │   ├── docs-writer/      # Technical Documentation
│   │   ├── tdd-orchestrator/ # TDD Master
│   │   ├── test-aware-planner/ # Test Planning
│   │   ├── translator/       # Multilingual Support
│   │   └── code-reviewer.md  # Code Review (standalone file)
│   ├── skills/               # 17 development skills (installed from plugins)
│   │   ├── increment-planner/
│   │   ├── spec-generator/
│   │   ├── context-loader/
│   │   ├── tdd-workflow/
│   │   ├── brownfield-analyzer/
│   │   ├── brownfield-onboarder/
│   │   ├── increment-quality-judge/
│   │   ├── increment-quality-judge-v2/
│   │   ├── context-optimizer/
│   │   ├── plugin-detector/
│   │   ├── role-orchestrator/
│   │   ├── specweave-detector/
│   │   ├── specweave-framework/
│   │   ├── task-builder/
│   │   ├── translator/
│   │   └── docs-updater/
│   ├── commands/             # 22 slash commands (installed from plugins)
│   │   ├── increment.md
│   │   ├── do.md
│   │   ├── progress.md
│   │   ├── done.md
│   │   ├── validate.md
│   │   ├── qa.md
│   │   ├── status.md
│   │   ├── pause.md
│   │   ├── resume.md
│   │   ├── abandon.md
│   │   ├── sync-docs.md
│   │   ├── sync-tasks.md
│   │   ├── check-tests.md
│   │   ├── costs.md
│   │   ├── translate.md
│   │   ├── update-scope.md
│   │   ├── next.md
│   │   └── ... (5 more)
│   └── hooks/                # 8 automation hooks (installed from plugins)
│       ├── post-task-completion.sh
│       ├── pre-implementation.sh
│       ├── post-implementation.sh
│       ├── pre-increment-planning.sh
│       ├── post-increment-planning.sh
│       └── ... (3 more)
│
├── .specweave/               # SpecWeave framework
│   ├── increments/           # Auto-numbered features
│   │   ├── README.md
│   │   ├── roadmap.md
│   │   └── 0001-feature/     # Created by workflow
│   ├── docs/                 # Living documentation
│   │   ├── internal/
│   │   │   ├── strategy/     # PRDs, market research
│   │   │   ├── architecture/ # HLDs, ADRs, C4 diagrams
│   │   │   ├── delivery/     # Roadmap, CI/CD
│   │   │   ├── operations/   # Runbooks, SLOs
│   │   │   └── governance/   # Security, compliance
│   │   └── public/           # Published docs
│   ├── tests/                # Centralized test repository
│   ├── config.yaml           # Configuration
│   └── logs/                 # Execution logs
│
├── CLAUDE.md                 # Complete development guide
├── AGENTS.md                 # Universal adapter (for non-Claude tools)
└── .gitignore                # Standard ignores

For Claude Code (Native)​

Gets full native integration:

  • ✅ 11 agents in .claude/agents/
  • ✅ 17 skills in .claude/skills/
  • ✅ 22 slash commands in .claude/commands/
  • ✅ 8 automation hooks in .claude/hooks/

For Other AI Tools (Cursor, Copilot, Gemini, ChatGPT)​

Gets universal adapter:

  • ✅ AGENTS.md - Works with ANY AI tool
  • ✅ .cursorrules - For Cursor (if detected)
  • ✅ .github/copilot/ - For Copilot (if detected)
  • ✅ Same .specweave/ structure
  • ✅ Same CLAUDE.md guide

Note: Only Claude Code gets native agents/skills. Other tools use the universal AGENTS.md adapter with manual workflow.

Scenario-Specific Installation​

New Project (Greenfield)​

# Method 1: Create new directory
npx specweave init my-project
cd my-project

# Method 2: Create directory first
mkdir my-project && cd my-project
npx specweave init .

What happens:

  1. Creates project directory (if needed)
  2. Detects your AI tool (Claude, Cursor, Copilot, etc.)
  3. Installs appropriate components
  4. Creates .specweave/ structure
  5. Generates CLAUDE.md and AGENTS.md
  6. Sets up .gitignore
  7. Initializes git repository (if git is available)

Existing Project (Brownfield)​

cd my-existing-project
npx specweave init .

What happens:

  1. Detects existing files
  2. Prompts for confirmation if directory is not empty
  3. ✅ Preserves your existing code and git history
  4. Adds SpecWeave structure without touching your code
  5. Uses directory name as project name (or prompts if invalid)

Safe Operations:

  • ✅ Never modifies existing source code
  • ✅ Never overwrites existing files (asks first)
  • ✅ Keeps your git history intact
  • ✅ All SpecWeave work isolated in .specweave/

Multiple Projects​

Install SpecWeave to multiple projects:

# Install to several projects
npx specweave init project-a
npx specweave init project-b
npx specweave init project-c

# Or using a loop
for project in project-a project-b project-c; do
  npx specweave init $project
done

Each project gets its own independent SpecWeave installation.

Verification​

After installation, verify everything is set up correctly:

cd your-project

# Verify SpecWeave structure
ls -la .specweave/          # Should have increments/, docs/, config.yaml
cat .specweave/config.yaml  # Should show configuration
cat CLAUDE.md               # Should exist
cat .gitignore              # Should exist

# For Claude Code users
ls -la .claude/agents/      # Should have 11 agents
ls -la .claude/skills/      # Should have 17 skills
ls -la .claude/commands/    # Should have 22 commands
ls -la .claude/hooks/       # Should have 8 hooks

# For other AI tool users
cat AGENTS.md               # Should exist

# Test a command (Claude Code only)
# Open Claude Code and type: /sw:progress

Verification Checklist​

  • .specweave/ directory exists
  • .specweave/config.yaml is present
  • CLAUDE.md exists
  • .gitignore includes SpecWeave ignores
  • Git repository initialized (if git available)
  • For Claude Code: .claude/agents/ has 11 agent folders
  • For Claude Code: .claude/skills/ has 17 skill folders
  • For Claude Code: .claude/commands/ has 22 command files
  • For other tools: AGENTS.md exists

Test the Interactive Flow​

Try the quick build workflow:

# Open Claude Code in your project and type:
"build a very simple web calculator app"

# SpecWeave will guide you through:
# 1. Approach selection (Quick build vs plan first)
# 2. Feature selection (multi-select checkboxes)
# 3. Tech stack choice (Vanilla, React, etc.)
# 4. Review and submit

# Your app will be built in ~2 minutes!

Or use slash commands for full control:

# In Claude Code:
/sw:increment "my first feature"

# This creates:
# ✅ .specweave/increments/0001-my-first-feature/
#    ├── spec.md (requirements)
#    ├── plan.md (architecture)
#    └── tasks.md (implementation steps with embedded tests)

Configuration​

After installation, optionally customize .specweave/config.yaml:

project:
  name: "your-project"
  type: "greenfield"  # or "brownfield"

hooks:
  enabled: true
  post_task_completion:
    enabled: true
    notification_sound: true  # macOS notification

testing:
  e2e_playwright_mandatory_for_ui: true
  min_coverage: 80

integrations:
  jira:
    enabled: false
    url: ""
    project_key: ""
  github:
    enabled: false
    repository: ""
  azure_devops:
    enabled: false
    organization: ""
    project: ""

Configuration options:

  • project.type - "greenfield" or "brownfield"
  • hooks.enabled - Enable automation hooks
  • testing.e2e_playwright_mandatory_for_ui - Enforce E2E tests
  • testing.min_coverage - Minimum test coverage (default: 80%)
  • integrations.* - Enable JIRA, GitHub, Azure DevOps sync

Upgrading​

The easiest way to upgrade SpecWeave:

# Full update: CLI + instructions + config + plugins
specweave update

# Skip plugins refresh
specweave update --no-plugins

# Full update with ALL 24 plugins (not just router)
specweave update --all

# Dry run - see what would change
specweave update --check

# Skip CLI self-update (only update project files)
specweave update --no-self

What specweave update does:

  1. Self-updates CLI via npm install -g specweave@latest
  2. Migrates config.json - adds missing sections like auto for older projects
  3. Updates instruction files - CLAUDE.md, AGENTS.md with latest templates
  4. Refreshes marketplace plugins - router + context-detected plugins
  5. Validates project health - checks for stale files, missing config
Config Migration

Projects created before v1.0.131 may be missing the auto config section. Running specweave update automatically adds default values without affecting existing settings.

Alternative: Manual npm Update​

# Check current version
specweave --version

# Upgrade to latest
npm update -g specweave

# Or reinstall
npm install -g specweave@latest

# Verify new version
specweave --version

npx (Always Latest)​

npx automatically uses the latest version, no upgrade needed.

Reinstall Project​

If you need to reinstall SpecWeave in a project:

cd your-project

# Safe reinstall (keeps all increments and docs)
specweave init .
# When prompted, select: "Continue working"
# This updates files without deleting your data

# Or with npm
npx specweave init .

⚠️ WARNING about --force flag:

# ⛔ DANGER: --force DELETES ALL DATA!
# This will permanently delete:
# - All increments (.specweave/increments/)
# - All documentation (.specweave/docs/)
# - All configuration
# ONLY use --force if you want to start completely fresh!

# If you must use --force, backup first:
cp -r .specweave .specweave.backup-$(date +%Y%m%d)
specweave init . --force

Uninstallation​

Remove from Project​

cd your-project

# Remove SpecWeave files
rm -rf .claude .specweave CLAUDE.md AGENTS.md

# Your application code remains untouched!

Note: Your source code is never modified by SpecWeave, so uninstallation is safe and clean.

Uninstall Global Package​

npm uninstall -g specweave

Troubleshooting​

npx not found​

# Update npm
npm install -g npm@latest

# Verify npx
npx --version

Permission denied (global install)​

Option 1: Use npx instead (recommended)

npx specweave init my-app

Option 2: Fix npm permissions

# See: https://docs.npmjs.com/resolving-eacces-permissions-errors

# Quick fix (macOS/Linux):
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Skills not activating (Claude Code)​

# Verify installation
ls -la .claude/skills/
# Should see 17 skills with SKILL.md files

# Check a specific skill
cat .claude/skills/increment-planner/SKILL.md

# If missing, safe reinstall (keeps all your data)
npx specweave init .
# When prompted, select: "Continue working"

# ⚠️ DO NOT use --force (deletes all increments/docs)

Commands not found (Claude Code)​

# Verify commands
ls -la .claude/commands/
# Should see: increment.md, do.md, etc. (22 total)

# Check a specific command
cat .claude/commands/increment.md

# If missing, safe reinstall (keeps all your data)
npx specweave init .
# When prompted, select: "Continue working"

# ⚠️ DO NOT use --force (deletes all increments/docs)

Hooks not running​

# Make hooks executable
chmod +x .claude/hooks/*.sh

# Verify permissions
ls -la .claude/hooks/
# Should show -rwxr-xr-x permissions

# Test hook manually
./.claude/hooks/post-task-completion.sh

Node.js version too old / "SyntaxError: Unexpected token 'with'"​

SpecWeave requires Node.js 20.12.0 or higher (we recommend Node.js 22 LTS).

# Check version
node --version

# If below v20.12.0, upgrade using nvm (recommended):
nvm install 22
nvm use 22
nvm alias default 22

# Verify
node --version  # Should show v22.x.x

Other upgrade methods: See detailed upgrade instructions for all platforms (macOS, Linux, Windows) and version managers (nvm, fnm, Volta, asdf, Homebrew).

npm version too old​

# Check version
npm --version

# Upgrade npm
npm install -g npm@latest

# Verify
npm --version

Installation hangs or times out​

# Clear npm cache
npm cache clean --force

# Try again with verbose logging
npm install -g specweave --verbose

# Or use npx instead
npx specweave init my-project

.gitignore not created​

# Manually create .gitignore
cat > .gitignore << 'EOF'
# Node
node_modules/
npm-debug.log
yarn-error.log
.pnpm-debug.log

# SpecWeave logs
.specweave/logs/

# Environment
.env
.env.local
.env.*.local

# IDE
.vscode/
.idea/
*.swp
*.swo
EOF

Platform-Specific Notes​

macOS​

  • ✅ Full support, all features work
  • ✅ Hooks include notification sounds (Glass.aiff)
  • ✅ Recommended platform for development

Linux​

  • ✅ Full support, all features work
  • ⚠️ Notification sounds may not work (requires audio system)
  • ✅ Perfect for CI/CD and servers

Windows​

  • ✅ Full support with v0.3.3+
  • ✅ UNC paths supported (e.g., \\Mac\Home\...)
  • ✅ Network drives supported
  • ⚠️ Hooks may require WSL or Git Bash
  • ⚠️ Notification sounds not supported

WSL (Windows Subsystem for Linux)​

  • ✅ Full support, recommended for Windows users
  • ✅ All Linux features available
  • ✅ Better compatibility than native Windows

Next Steps​

After successful installation:

  1. ✅ Read the Quick Start Guide
  2. ✅ Review CLAUDE.md in your project
  3. ✅ Explore Core Concepts
  4. ✅ Start your first increment

Support​

Need help? We've got you covered:

SpecWeave - Spec-Driven Development Framework

🚀 Install now: npm install -g specweave (requires Node.js 20.12.0+)