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

High-Level Commands (v3.2)

Simplified workflow - build features in 2 commands

/specswarm:build

Complete feature development from spec to implementation. Handles planning, task breakdown, execution, and quality analysis autonomously.

Usage:
/specswarm:build "feature description" [--validate] [--quality-gate N]
Flags:
  • --validate - Run Playwright browser testing during implementation
  • --quality-gate N - Set minimum quality score (default: 80)

/specswarm:fix

Test-driven bug fixing with automatic retry logic. Creates regression tests first, then implements and validates fix.

Usage:
/specswarm:fix "bug description" [--regression-test] [--hotfix] [--max-retries N]
Flags:
  • --regression-test - Create failing test before fixing (TDD approach)
  • --hotfix - Expedited workflow for production emergencies
  • --max-retries N - Maximum fix attempts (default: 2)

/specswarm:upgrade

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

Usage:
/specswarm:upgrade "migration description" [--dry-run]
Flags:
  • --dry-run - Analyze risks without making changes

/specswarm:ship

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

Usage:
/specswarm:ship [--force-quality N]
Flags:
  • --force-quality N - Override quality threshold for this merge

Granular Workflow (Manual Control)

Step-by-step control for complex features

/specswarm:specify

Create detailed feature specification. Generates spec.md with user scenarios, functional requirements, and success criteria.

Usage:
/specswarm:specify "feature description"

/specswarm:clarify

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

Usage:
/specswarm:clarify

/specswarm:plan

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

Usage:
/specswarm:plan

/specswarm:tasks

Generate dependency-ordered task breakdown. Creates tasks.md with acceptance criteria and parallelization flags.

Usage:
/specswarm:tasks

/specswarm:implement

Execute implementation plan. Processes tasks sequentially with checkpoint updates and error handling.

Usage:
/specswarm:implement

/specswarm:complete

Finish feature and merge to parent branch. Shows merge plan before executing, validates branch safety.

Usage:
/specswarm:complete

Quality & Analysis

Validate quality and assess impact

/specswarm:analyze-quality

Comprehensive 0-100 quality scoring. Analyzes test coverage, bundle size, code quality, and more.

Usage:
/specswarm:analyze-quality

/specswarm:impact

Standalone impact analysis for features or changes. Assesses affected files, risks, and required tests.

Usage:
/specswarm:impact "change description"

/specswarm:suggest

AI-powered workflow recommendations based on context analysis. Suggests simplified vs. granular approach.

Usage:
/specswarm:suggest "task description"

Bug & Issue Management

Fix bugs with regression testing

/specswarm:bugfix

Regression-test-first bug fixing. Creates failing test, implements fix, validates across scenarios.

Usage:
/specswarm:bugfix "bug description with reproduction steps"

/specswarm:hotfix

Emergency production fix workflow. Expedited process with critical priority and immediate validation.

Usage:
/specswarm:hotfix "production issue description"

Code Maintenance

Modify, refactor, and deprecate features

/specswarm:modify

Feature modification workflow with impact analysis. Assesses backward compatibility before changes.

Usage:
/specswarm:modify "modification description"

/specswarm:refactor

Metrics-driven code quality improvement. Maintains behavior while improving structure and performance.

Usage:
/specswarm:refactor "refactoring goals"

/specswarm:deprecate

Phased feature sunset workflow. Provides migration guidance and removes deprecated code safely.

Usage:
/specswarm:deprecate "feature to remove"

Project Setup

Initialize and configure projects

/specswarm:init

Initialize project with constitution, tech stack, and quality standards. Auto-detects from package.json.

Usage:
/specswarm:init [--minimal]
Flags:
  • --minimal - Use minimal defaults without interactive questions

/specswarm:constitution

Create or update project constitution. Establishes coding principles and governance rules.

Usage:
/specswarm:constitution

/specswarm:checklist

Generate custom requirement checklists based on feature specifications.

Usage:
/specswarm:checklist

Configuration Files

Optional files to customize SpecSwarm behavior for your project

.specswarm/tech-stack.md

Define approved technologies to prevent 95% of 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 95% of 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