Spec-driven development for Claude Code. Build → Fix → Modify → Ship, with quality gates, multi-agent orchestration, version-controlled specs, autonomous chunk execution (v7.1.0–v7.10.0), and the AUTO-MAGIC loop (v7.13.0–v7.17.0): a taste model that learns your rulings, assume-first clarification, adversarial verification with teeth, and /ss:go — a full feature ladder with a median of ≤4 human touchpoints.
# 1. Add the marketplace
/plugin marketplace add MartyBonacci/specswarm
# 2. Install SpecSwarm
/plugin install ss@specswarm-marketplaceRestart Claude Code to activate the plugin. (Upgrading from v5.x? See Migrating from v5.x at the bottom.)
| Command | What it does |
|---|---|
/ss:go |
The default entry point (v7.17.0) — the full ladder end-to-end, pausing only at 4 human touchpoints |
/ss:init |
Set up or refresh project knowledge: tech stack, constitution, quality gates |
/ss:build |
Spec → plan → tasks → implement → quality score (pre-v7.17 ladder; still supported) |
/ss:fix |
Test-driven bug fix with auto-retry and silent-failure audit |
/ss:modify |
Behavior change with impact analysis and backward-compat plan |
/ss:ship |
Multi-agent review + quality gate + merge to parent branch |
The core commands above remain the canonical loop (with /ss:go as the v7.17.0 default entry point). The v7.1+ commands compose with them to enable single-session execution and unattended chunks. Each is optional; the core loop works without any of them.
| Command | Since | What it does |
|---|---|---|
/ss:preflight |
v7.1.0 | Deterministic 7-check plan.md validator (versions, memory, §refs, grep boundaries, headings, assumption provenance, ground-truth bias) |
/ss:notify |
v7.2.0 | Fire a notification (cascading fallback: notifier plugin → notify-send → osascript → bell) |
/ss:intervention |
v7.3.0 | Capture "wait, something feels off" moments as durable training-data memory files |
/ss:verify |
v7.4.0 | Adversarial spec-vs-code verification via fresh-context spec-mentor subagent |
/ss:retrospective |
v7.5.0 | Auto-distill chunk lessons into 1–3 durable memory files via chunk-retrospective subagent |
/ss:decisions |
v7.6.0 | Pre-batch all strategic decisions into ONE upfront AskUserQuestion touchpoint |
/ss:dry-run |
v7.8.0 | Predict the full chunk lifecycle without running it (anticipated decisions, risk register) |
/ss:watchdog |
v7.9.0 | Background daemon — out-of-session monitor; auto-queues verifications on new commits |
/ss:overnight |
v7.10.0 | Run a chunk autonomously while you sleep (cron/systemd/launchd-compatible) |
/ss:bakeoff |
v7.16.0 | Calibration loop: N candidates → contact sheet → verdict → pinned winner + distilled ruling |
Together these implement the autonomous chunk loop: pre-batch decisions at 9pm, schedule /ss:overnight via cron between 10pm-6am, wake to a phone notification (success or "needs review"). The dual mentor↔builder session pattern is now optional, not required. See CHANGELOG.md for the full architectural story.
v7.17.0 — /ss:go, the single entry point. The mind-reading loops (taste model, assume-first, adversarial verification, calibration) compose into one command: median ≤4 human touchpoints per shipped chunk — kickoff, one assumptions-review + decision-sheet sitting, sighted gates, ship blessing. Driven by a dedicated Stop hook (go-loop-hook.sh, state in .specswarm/go-loop.state); every phase command remains a standalone escape hatch and /ss:build is unchanged.
v7.16.0 — bakeoff + decided-by-data. /ss:bakeoff makes the calibration loop first-class: N deliberately-diverse candidates → side-by-side contact sheet → one batched verdict → winner pinned with a regression test → ruling distilled into the taste model (hand-run ~15×, this loop converted more fuzzy judgment into deterministic constants than anything else). Specs may defer a fork to a named metric with [DECIDED-BY-DATA: <metric>, <review-when>] — tracked by /ss:metrics and the watchdog. A new ground-truth-bias preflight check WARNs when a plan tunes against acceptance data without addressing provenance (22/26 "user-accepted" items in production were the scorer's own suggestions).
v7.15.0 — ruling distiller + overnight resilience. Deterministic taste rulings now carry embedded specswarm-rule blocks and generate edit-time hooks the moment they're distilled — an intervention captured in chunk N fires automatically in chunk N+1, no /ss:init re-run. Spec-mentor's verify bundle now includes the judgment taste rules (previously never wired). Headless runs get sync-gate + budget clauses at both dispatch sites, work-tree-aware failure classification (timeout-stranded / api-error / yield-await), and a one-shot auto-resume whose prompt orders a critical self-review of the half-done diff — the protocol that recovered 3/3 real overnight failures.
v7.14.0 — deterministic slice gates + sighted-gate classification. Every task now runs the project's production build + lint synchronously (SPECSWARM_SLICE_GATES=block|warn|off, default block) — only the build catches framework-boundary breaks, and per-slice beats ship-time archaeology. lib/test-framework-detector.sh and lib/quality-gates.sh (referenced by /ss:implement since Phase 1 but never authored) now exist for real, detecting frameworks/build/lint/test-roots from repo reality. Verify-time diff screeners flag geometry code without asymmetric fixtures, round-trip-only transform tests, schema-derived fixtures, and multi-test-root glob traps. Visual slices are auto-held NEEDS-SIGHTED and block /ss:ship until a human signs off (/ss:verify --sighted or the ship-time batch review) — every production false-green was a visual slice.
v7.13.0 — the taste model + assume-first clarify. Every AskUserQuestion answer, verify-DRIFT lesson, and retrospective ruling now accretes into distilled feedback_*.md entries (rule + WHY + HOW-TO-APPLY + check-type) via a shared writer (lib/taste.sh) — rules survive sessions; transcripts don't. Clarify inverts from "ask up to 5 questions" to assume-first: gaps resolvable from the taste model, spec corpus, or codebase precedent are AUTO-FILLED into a provenance-cited ## Assumptions ledger (reviewing assumptions is ~5× faster than answering questions); only genuine forks are asked, batched. A new assumptions-provenance preflight check keeps the ledger honest.
- Write a clear spec of the feature, sprint, or project that you want.
- Run
/ss:initin your project. - Run
/ss:go "<your feature description referencing your spec document>"— the full ladder runs itself; you touch it at the assumptions review, the batched decision sheet, sighted sign-offs on visual slices, and the ship blessing. (Prefer step-by-step control?/ss:buildstill works exactly as before.) - Use
/ss:fix "<bug>"for anything broken, or/ss:modify "<change>"for things that work but aren't right. Repeat as needed. - Run
/ss:shipwhen everything's good.
That's the loop.
Re-run /ss:init any time the project's tech stack, conventions, or constitution changes — it refreshes SpecSwarm's knowledge of the project.
Most of SpecSwarm's value comes from a clear spec document and a prompt that points to it. Keep the spec in your repo (e.g., docs/specs/...); the prompt itself stays short and points SpecSwarm at the spec, optionally with scope or exclusions to keep this build focused.
/ss:build "Implement the email + password authentication feature
described in docs/specs/auth-v1.md.
Out of scope for this build:
- OAuth and social sign-in
- Password reset flow
- Multi-factor authentication"
The clearer the spec document, the less back-and-forth during clarification.
v6.1.0 makes this even better. If your project has existing PRDs, design docs, decision logs, or a legacy/prototype reference codebase, declare them in .specswarm/references.md (auto-populated by /ss:init) and SpecSwarm will read them automatically during /ss:specify and /ss:clarify — quoting from corpus content with citations instead of fabricating, and skipping clarification questions whose answers are already locked in.
v6.2.0 closes the loop on Claude Code memory. If your project has memory directories declared in references.md, /ss:init now scans your feedback_*.md files for imperative rules ("X must NEVER appear in Y") and proposes constitution principles in the mechanical hook format. You wrote the rule once in memory; SpecSwarm proposes the enforcement; you accept or reject each proposal. Accepted principles get PostToolUse hooks generated automatically.
v6.3.0 gives constitutional principles teeth. Each rule block now accepts an optional severity: warn | block field (default warn). When a severity: block rule fires — say, a trade-secret import slipping into the frontend bundle — the PostToolUse hook returns decision: block and Claude is told to revert/fix rather than just being warned. v6.3.0 also fixes a pre-existing path-glob bug that had been silently preventing warn hooks from firing in production. See CHANGELOG.md for details.
A lot happens automatically inside each command. You don't invoke these phases directly — they run as the command needs them. The list below is descriptive, not a control surface; trust the system to sequence them correctly.
- Tech stack detection — parses package.json, requirements.txt, go.mod, etc.
- Constitution creation — captures project principles and non-negotiable rules
- Tech stack documentation — locks approved technologies into
.specswarm/tech-stack.mdto prevent drift across builds - Quality standards — sets coverage, score, and performance gates
- Convention analysis — extracts coding patterns from existing code
- MCP discovery & registration — adds Context7, Playwright, Postgres, etc., based on detected stack
- Project subagent seeding — generates project-specific implementer agents matched to your stack
- Constitutional hooks — turns mechanically-checkable principles into PostToolUse hooks; (v6.3.0) each principle can declare
severity: warnorseverity: block— warn surfaces a system message, block returnsdecision: blockso Claude reverts/fixes - References discovery (v6.1.0) — auto-discovers spec corpus markdown docs, sibling reference codebases (stem-similarity filter), and Claude Code memory directories; interactive picker writes
.specswarm/references.md - Memory-driven principle import (v6.2.0, severity-aware in v6.3.0) — scans declared memory directories for
feedback_*.mdrules, drafts constitution principles in hook-enforceable format, asks user to accept/reject each; gravity signals in the source memory (trade secret,compliance,must NEVER, etc.) proposeseverity: blockautomatically
- Feature branch creation — branches from your current branch
- Specification generation — turns your prompt into a structured, version-controlled spec; (v6.1.0) when
.specswarm/references.mdis populated, reads spec corpus + memory dirs and extracts canonical content with citations instead of fabricating - Clarification — asks targeted questions on ambiguous areas (skipped in
--quickmode); (v6.1.0) skips questions auto-resolved from corpus and surfacesCORPUS-CONFLICTmarkers when feature description disagrees with corpus - Implementation plan — architecture, file layout, data flow, technology choices
- Task breakdown — dependency-ordered tasks with parallel-safe markers
- Project subagent refresh — adds agents for any new recurring task types in this build
- Orchestration analysis — detects parallelizable task streams and dispatches multiple agents when safe
- Implementation — executes tasks sequentially or in parallel as appropriate
- Per-task verification — a verifier subagent confirms each task's acceptance criteria before it's marked complete
- Quality analysis — proportional 0-100 scoring across unit tests, coverage, integration tests, and browser tests
- Regression test creation — captures the bug as a failing test
- Root-cause analysis — investigates the cause, with multi-bug coordination if requested
- Fix implementation — applies the targeted change
- Test verification — runs the full test suite
- Silent-failure audit — scans the diff for swallowed errors, empty catches, and masking fallbacks
- Auto-retry — retries with additional context if tests still fail (up to retry limit)
- Context discovery — locates the feature's existing spec, plan, and dependents
- Impact analysis — finds every file and feature affected by the change
- Change categorization — breaking, backward-compatible, or phased deprecation
- Migration planning — designs an optional compatibility layer
- Spec update — rewrites the spec to reflect the new intended behavior so it stays canonical
- Phased task generation — validation → compat layer → implementation → testing → migration
- Implementation — executes the modification
- Regression validation — confirms existing tests still pass
- Security audit (optional with
--security-audit) — dependency CVEs, hardcoded secrets, OWASP pattern scan - Quality analysis — proportional 0-100 scoring across all test types
- Multi-agent review — parallel dispatch of code reviewer, silent-failure hunter, type-design analyzer, and comment analyzer
- Quality threshold gate — configurable, default 80/100
- Merge to parent branch — clean fast-forward when possible
- Feature branch cleanup — deletes the merged branch
/ss:init now reads your project's existing spec corpus — Strategy docs, decision logs, RULES.md, BUDGETS.md, plus Claude Code memory files — and proposes content for the four foundation files instead of asking you to re-state every decision interactively.
Under the hood it dispatches subagents in parallel:
- Step 3.0 — a discovery subagent classifies the project's documentation surface (
spec-doc,documentation,config,memory,reference-codebase,source-code,noise) and writes a structured map to.specswarm/.discovery.tmp. - Step 4.0 — three extractor subagents (tech-stack, quality-standards, constitution) run concurrently against the discovered sources. Each returns pipe-delimited proposals with confidence ratings (
high/medium/low) and citations. - Step 4.1 — the parent aggregates proposals, deduplicates, detects cross-source conflicts, and grep-verifies citations.
- Step 4.2 — you see batch-accept prompts for high-confidence extractions and per-item prompts for conflicts. The total prompt count is capped (~20 per
/ss:init). - Steps 4 / 5 / 6 — accepted proposals fill canonical templates; extras land in
<!-- ss:user-additions -->blocks that survive future re-runs.
For projects without a spec corpus (just a README and package.json), the discovery step finds nothing relevant and extraction is skipped — /ss:init behaves the same as v6.4.0.
New flags:
--full-scan— lift default depth bounds on Step 3.0. Use when spec docs live outsidedocs/,specs/, ordocumentation/.--include-user-memory— includeuser_*.mdfiles in extraction (default-skipped as personal context).
Existing flags (--reset, --minimal, --skip-detection) keep their v6.4.0 semantics. --minimal skips discovery and extraction entirely.
- COMMANDS.md — every command, every flag, every internal detail
- docs/CHEATSHEET.md — fast reference card
- docs/WORKFLOW.md — extended walkthroughs
- docs/FEATURES.md — what makes SpecSwarm different
- docs/SETUP.md — detailed setup guide
- CHANGELOG.md — version history
If you have the old specswarm plugin installed, install the canonical ss plugin first, then uninstall the old one:
/plugin install ss@specswarm-marketplace
/plugin uninstall specswarmAll commands have moved from /specswarm:* to /ss:*. Skill IDs renamed from specswarm-* to ss-*. The .specswarm/ per-project state directory and the SpecSwarm name are unchanged — only the command prefix moved.
The deprecated specswarm plugin still appears in the marketplace as a stub through v7.x. It's kept in lockstep version-wise (currently v7.17.0) so users who installed the old name see a clear migration message. Slated for full removal in v8.0.0.