Start orchestrating ...fast

From installation to your first shipped feature.

Works with new projects or established codebases—start with as little as a README file.

Before You Start

Make sure you have these basics in place. SpecSwarm is flexible—you can start minimal and evolve as you build.

Git Repository

Initialized with at least one commit. SpecSwarm creates feature branches automatically and merges them when quality gates pass.

Project Context

SpecSwarm reads your README.md to extract project context. Languages, frameworks, and libraries are derived from available files and follow-up questions. For new projects, answer a few setup questions—then build features immediately!

Claude Code

Installed and initialized with /init

1

Install SpecSwarm

Add SpecSwarm to your Claude Code environment. Takes about 30 seconds.

Install SpecSwarm bash 
claude> /plugin https://github.com/MartyBonacci/specswarm
claude> /plugin install specswarm
2

Initialize Your Project

Create foundation files for coding principles, tech stack, and quality standards. SpecSwarm analyzes your project to detect existing technologies and prompts you for missing context.

Initialize Your Project bash 
claude> /specswarm:init

# Creates your project foundation:
# - .specswarm/constitution.md (coding principles)
# - .specswarm/tech-stack.md (approved technologies)
# - .specswarm/quality-standards.md (quality gates)
#
# SpecSwarm analyzes your project and asks for any missing context.
# Tech stack evolves as you build—no crystal ball needed.
3

Build Your First Feature

Describe your feature in natural language. SpecSwarm handles everything else with tech stack enforcement.

Build Your First Feature bash 
claude> /specswarm:build "Add user authentication with email/password"

# Answer clarification questions
# Autonomous execution: spec → plan → tasks → implementation → quality
4

Fix

Fix issues found during manual user testing. SpecSwarm implements fixes with automatic retry logic and verifies all automated tests still pass.

Fix bash 
/specswarm:fix "Login fails with special characters in password"

# Automatic retry logic and test verification
5

Ship with Quality Gates

Merge to parent branch with quality validation. Blocks if quality falls below your standards.

Ship with Quality Gates bash 
claude> /specswarm:ship

# Quality-gated merge to parent branch

What's Next?

You've shipped your first feature. Here's where to go from here.

📚 Explore All Features

Learn about tech stack enforcement, quality validation, autonomous orchestration, and all 28 commands.

View Features

🔧 Read the Documentation

Comprehensive command reference, configuration options, and advanced workflows for complex features.

Read Docs

⚙️ Configure Your Project

Fine-tune quality thresholds, performance budgets, and tech stack rules for your specific needs.

Configuration Guide

Common Questions

When should I use simplified vs. granular workflow?

Use simplified (/specswarm:build → /specswarm:ship) for 90% of features. Switch to granular (/specswarm:specify → /specswarm:clarify → /specswarm:plan → ...) when you need step-by-step review for complex architectural changes.

How does tech stack enforcement work?

Define approved technologies in .specswarm/tech-stack.md. During planning, SpecSwarm validates every library and pattern against your stack. If it detects prohibited technologies or drift, it suggests approved alternatives. Your tech stack isn't static—as you build features with new technologies, SpecSwarm checks for conflicts and updates your approved tech stack automatically.

Do I need to define my entire tech stack upfront?

No! Start with basic context in your README (even 2-3 sentences works). When you build features, you can specify technologies as needed (e.g., 'build a 3D viewer using Three.js'). SpecSwarm automatically checks for conflicts and adds new technologies to your tech stack. Your tech stack evolves naturally as your project grows—no need to predict everything on day one.

What does the --validate flag do?

Adds Playwright browser automation to test your feature in a real browser. Runs alongside implementation to catch UI bugs early. Optional but recommended for features with user interfaces.

Can I use SpecSwarm with existing projects?

Yes! SpecSwarm works with any existing git repository. Run /specswarm:init to set up project configuration, then start building features. It integrates with your existing workflow seamlessly.

What if quality score is below threshold?

Use /specswarm:fix to address specific issues with automatic retry logic. This command will implement the fix, verify all tests pass, and re-run quality checks. Then re-run /specswarm:ship when ready. Common fixes: add missing tests, reduce bundle size, fix TypeScript errors.

How do I get help?

Check the documentation, browse GitHub Discussions, or open an issue. The community is active and responsive.

Questions? Feedback?

Join the community on GitHub to share your experience, ask questions, or contribute to SpecSwarm development.

View on GitHub Join Discussions