Documentation

Complete command reference with usage examples and best practices

Quick Start

Get started in 5 minutes with this copy-paste workflow

Installation to First Feature bash 
/plugin https://github.com/MartyBonacci/specswarm
/plugin install specswarm
/specswarm:init
/specswarm:build "your first feature" --validate
/specswarm:ship
Full Tutorial

Core Workflows (v4.0)

The commands you use daily - build, fix, modify, and ship

/specswarm:init

Interactive project initialization. Creates .specswarm/ directory with constitution, tech-stack, and quality-standards. Auto-detects from package.json.

Usage:
/specswarm:init [--skip-detection] [--minimal]
Flags:
  • --skip-detection - Skip auto-detection of project settings
  • --minimal - Use minimal defaults without interactive questions

/specswarm:build

Build complete feature from spec to implementation. Handles specify, clarify, plan, tasks, implement, validate, and quality analysis autonomously.

Usage:
/specswarm:build "feature description" [flags]
Flags:
  • --validate - Run Playwright browser testing after implementation
  • --quality-gate N - Set minimum quality score (default: 80)
  • --orchestrate - Force multi-agent parallel execution
  • --no-orchestrate - Force sequential execution
  • --analyze - Cross-artifact consistency analysis after task generation
  • --checklist - Requirements validation checklist
  • --background - Run in background, return session ID
  • --notify - Play sound when complete

/specswarm:fix

Fix bugs with test-driven approach and auto-retry. Creates regression tests first, then implements and validates fix.

Usage:
/specswarm:fix "bug description" [flags]
Flags:
  • --regression-test - Create failing test before fixing (TDD approach)
  • --hotfix - Expedited workflow for production emergencies
  • --max-retries N - Maximum fix attempts (default: 2)
  • --coordinate - Multi-bug orchestrated debugging with specialists
  • --background - Run in background, return session ID
  • --notify - Play sound when complete

/specswarm:modify

Change existing feature behavior with impact analysis. Assesses backward compatibility before making changes.

Usage:
/specswarm:modify "modification description" [flags]
Flags:
  • --refactor - Behavior-preserving quality improvement
  • --deprecate - Phased feature sunset with migration guidance
  • --analyze-only - Impact analysis without implementation

/specswarm:ship

Quality-gated merge to parent branch. Analyzes quality, enforces thresholds, and provides remediation steps if below threshold.

Usage:
/specswarm:ship [flags]
Flags:
  • --force-quality N - Override quality threshold for this merge
  • --skip-tests - Skip test validation (not recommended)
  • --security-audit - Comprehensive security scan before merge

Distinct Workflows

Specialized workflows that can't be expressed as flags on core commands

/specswarm:release

Complete release workflow. Quality gates, optional security audit, version bump, changelog generation, git tag, and publish.

Usage:
/specswarm:release [--patch|--minor|--major] [--skip-audit] [--background] [--notify]
Flags:
  • --patch - Patch version bump
  • --minor - Minor version bump
  • --major - Major version bump
  • --skip-audit - Skip security audit step

/specswarm:upgrade

Framework and dependency migrations with breaking change analysis. Automated refactoring with codemods and guided manual tasks.

Usage:
/specswarm:upgrade "migration target" [--deps] [--package] [--dry-run]
Flags:
  • --deps - Upgrade dependencies
  • --package - Upgrade a specific package
  • --dry-run - Analyze risks without making changes

/specswarm:rollback

Safe rollback with artifact cleanup. Identifies previous version, reverts changes, runs smoke tests.

Usage:
/specswarm:rollback [--dry-run] [--keep-artifacts] [--force]
Flags:
  • --dry-run - Preview rollback without executing
  • --keep-artifacts - Keep build artifacts after rollback
  • --force - Skip safety checks

/specswarm:status

Check background session progress. Shows current phase, completion percentage, and any errors.

Usage:
/specswarm:status [session_id] [--verbose] [--json]

/specswarm:metrics

Feature-level orchestration analytics. View task completion, timing, and quality trends.

Usage:
/specswarm:metrics [--feature N] [--export] [--sprint NAME] [--recent N]

Internal Commands

Run automatically inside build/fix/modify workflows. Call directly to re-run individual steps.

/specswarm:specify

Create detailed feature specification from natural language. Generates spec.md with user scenarios and requirements.

Usage:
/specswarm:specify "feature description"

/specswarm:clarify

Ask up to 5 targeted clarification questions. Encodes answers back into the specification.

Usage:
/specswarm:clarify

/specswarm:plan

Design implementation with tech stack validation. Creates plan.md with phases and compliance report.

Usage:
/specswarm:plan

/specswarm:tasks

Generate dependency-ordered task breakdown with acceptance criteria.

Usage:
/specswarm:tasks

/specswarm:implement

Execute implementation plan by processing all tasks sequentially.

Usage:
/specswarm:implement

/specswarm:validate

Run AI-powered interaction flow validation (web/API/desktop).

Usage:
/specswarm:validate

/specswarm:analyze-quality

Comprehensive 0-100 quality scoring across test coverage, code quality, and more.

Usage:
/specswarm:analyze-quality

/specswarm:complete

Alias for ship. Finish feature and merge to parent branch.

Usage:
/specswarm:complete

/specswarm:constitution

Create or update project constitution with governance principles.

Usage:
/specswarm:constitution

Configuration Files

Optional files to customize SpecSwarm behavior for your project

.specswarm/tech-stack.md

Define approved technologies to prevent technology drift. List core technologies, approved libraries, and prohibited patterns.

Example: Enforce React 19 functional components, block Redux in favor of React Router loaders

.specswarm/quality-standards.md

Set quality thresholds and performance budgets. Defines minimum test coverage, quality scores, and bundle size limits.

Example: Require 85% test coverage, 500KB max bundle size, block merges below 80 quality score

.specswarm/constitution.md

Establish project governance and coding principles. Defines architectural patterns, code style rules, and decision-making processes.

Example: Functional programming preferred, composition over inheritance, explicit over implicit

Best Practices

Proven patterns for effective SpecSwarm usage

1. Define Tech Stack First

Run /specswarm:init before building features. Tech stack enforcement prevents technology drift across all features.

2. Use Simplified Workflow

Start with /specswarm:build for 90% of features. Switch to granular only for complex architectural changes.

3. Always Test Manually

Even with --validate flag, manually test features before shipping. AI catches bugs, but human validation is critical.

4. Check Quality Before Merge

Run /specswarm:analyze-quality to catch issues early. Fix before /specswarm:ship blocks the merge.

5. Use Correct Parent Branch

Always checkout parent branch before starting features. SpecSwarm merges back to the branch you started from.

6. Review Planning Artifacts

Check spec.md, plan.md, and tasks.md before implementation. Catch issues during planning, not during code review.

Additional Resources

GitHub Repository

Source code, issue tracker, and community discussions

Complete Workflow Guide

Step-by-step guide with real-world examples and troubleshooting

Quick Reference Cheat Sheet

Visual command reference and configuration templates

Changelog

Version history, new features, and Feature 015 validation details

Claude Code Documentation

Official Claude Code docs for getting started and advanced usage

Report Issues

Bug reports, feature requests, and support questions

Ready to Get Started?

Install SpecSwarm and build your first feature with tech stack enforcement and quality gates.

Quick Start