Unified AI-powered development framework combining Claude Code, SuperClaude agents, and Gemini delegation.
SuperClaude Spec Workflow is a comprehensive framework that enhances Claude Code with:
- 19 AI Agents: Context-aware personas activated based on task type
- 7 Behavioral Modes: Brainstorming, research, token-efficiency, and more
- 9 MCP Servers: Extended capabilities (sequential-thinking, serena, context7, tavily, etc.)
- Gemini Delegation: 2M token capacity for token-heavy operations
- Spec-Driven Workflows: Phase-gated feature development with user approval
Before using SCW, you need:
Anthropic's official CLI tool for AI-powered development.
# Install via npm
npm install -g @anthropic-ai/claude-codeRequired for token-heavy operations delegation (2M token context).
# Install via npm
npm install -g @google/gemini-cli
# Authenticate
gemini auth# Install CLI globally
npm install -g @neverg3t/scw-cli
# Setup MCP servers
scw mcp setup
# Initialize your project
cd your-project
scw init# Clone and build
git clone https://github.com/NeverGET/superclaude-spec-workflow.git
cd superclaude-spec-workflow
npm install
npm run build --workspaces
# Setup MCP servers
./cli/scw/dist/index.js mcp setup
# Initialize your project
cd your-project
/path/to/superclaude-spec-workflow/cli/scw/dist/index.js initOpen Claude Code in your project and try:
/scw:help # See all commands
/scw:brainstorm [topic] # Discover requirements
/scw:spec-create [feature] # Create feature specification
After running scw init, your project will have:
project/
├── .claude/
│ ├── commands/scw/ → SCW commands (symlink)
│ ├── steering/ # Project context
│ │ ├── product.md # Vision, goals, users
│ │ ├── tech.md # Stack, conventions
│ │ └── structure.md # Directory layout
│ ├── specs/ # Feature specifications
│ ├── bugs/ # Bug workflows
│ └── templates/ → Document templates (symlink)
├── agents/ → 19 AI agents (symlink)
├── modes/ → 7 behavioral modes (symlink)
├── CLAUDE.md # Claude's role definition
└── GEMINI.md # Gemini's role definition
| Command | Description |
|---|---|
/scw:help |
Show all available commands |
/scw:spec-create [feature] |
Create feature specification (4-phase workflow) |
/scw:spec-execute [task-id] |
Execute a spec task |
/scw:brainstorm [topic] |
Socratic requirements discovery |
/scw:design [feature] |
Architecture design workflow |
/scw:implement [task] |
Implementation with pattern matching |
/scw:test [scope] |
Run tests with coverage reporting |
/scw:research [topic] |
Deep research with Gemini delegation |
/scw:bug-create [issue] |
Bug workflow (report → analyze → fix → verify) |
| Command | Description |
|---|---|
scw init |
Initialize SCW in current project |
scw init --quick |
Quick initialization with defaults |
scw doctor |
Check installation health |
scw mcp setup |
Configure MCP servers |
scw mcp check |
Verify servers are running |
scw mcp list |
List configured servers |
scw mcp tokens |
Manage API tokens |
┌─────────────────────────────────────────────────────────────────────────────┐
│ SUPERCLAUDE SPEC WORKFLOW (/scw:*) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ USER LAYER (Primary Commands) │
│ ├── /scw:spec-create → Requirements → Design → Tasks → Implementation │
│ ├── /scw:spec-execute → Task execution with validation │
│ ├── /scw:bug-create → Report → Analysis → Fix → Verification │
│ └── Steering documents (product.md, tech.md, structure.md) │
│ │
│ ORCHESTRATION LAYER (Claude Code - 200K tokens) │
│ ├── PM Agent: ConfidenceChecker (pre) + SelfCheckProtocol (post) │
│ ├── 19 Merged Agents (auto-activated by context) │
│ ├── 7 Behavioral Modes │
│ ├── 9 MCP Servers (Context7, Tavily, Serena, Sequential, Gemini...) │
│ └── Wave→Checkpoint→Wave parallel execution (3.5x speedup) │
│ │
│ DELEGATION LAYER (Gemini MCP Wrapper - 2M tokens) │
│ ├── 8 MCP Tools: research, file_scan, generate, dialogue, test, etc. │
│ ├── Claude validates ALL Gemini outputs before accepting │
│ ├── Session tracking for multi-step operations │
│ └── Triggers: >10 files, >5 file generation, deep research, bulk tests │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
SCW integrates 9 MCP servers:
| Server | Purpose | Repository | Token |
|---|---|---|---|
| sequential-thinking | Complex problem decomposition | modelcontextprotocol/servers | No |
| serena | Session persistence | oraios/serena | No |
| context7 | Library documentation | upstash/context7 | Yes (CONTEXT7_API_KEY) |
| tavily | Web research | tavily-ai/tavily-mcp | Yes (TAVILY_API_KEY) |
| playwright | Browser automation | microsoft/playwright-mcp | No |
| chrome-devtools | Performance analysis | ChromeDevTools/chrome-devtools-mcp | No |
| gemini-wrapper | Gemini delegation | Included in SCW | No (Gemini CLI auth) |
| filesystem-morph | Fast file editing | morphllm.com/mcp | Yes (MORPH_API_KEY) |
| morph | Semantic code merging | docs.morphllm.com | Yes (MORPH_API_KEY) |
19 agents organized by tier:
| Tier | Agents | Activation |
|---|---|---|
| Core | pm-agent, self-review | Always active |
| Spec Workflow | requirements-analyst, system-architect, quality-engineer | Phase-based |
| Domain | backend-architect, frontend-architect, security-engineer, devops-architect, performance-engineer, python-expert | Task-based |
| Analysis | root-cause-analyst, refactoring-expert | Context-triggered |
| Research | deep-research-agent, socratic-mentor, learning-guide | Mode-triggered |
| Communication | technical-writer, business-panel-experts, repo-index | Explicit request |
Steering documents define project context:
- product.md: Vision, goals, non-goals, target users, success metrics
- tech.md: Stack, conventions, coding standards
- structure.md: Directory layout, key files
These documents guide all agents and ensure consistent, project-aware responses.
The spec workflow is a 4-phase process with user approval gates:
- Requirements Phase → User approves
requirements.md - Design Phase → User approves
design.md - Tasks Phase → User approves
tasks.md - Implementation → Execute with validation
Each phase includes:
- ConfidenceChecker (≥90% to proceed)
- SelfCheckProtocol (validation after completion)
- Reflexion Pattern (error handling and learning)
Claude delegates to Gemini for token-heavy operations:
- File Scanning: >10 files
- Code Generation: >5 files
- Deep Research: Extensive web crawling
- Bulk Testing: Large test suites
- Context Overflow: >80% of 200K tokens
Gemini can also be used independently:
gemini -p "@src/ Analyze the architecture of this codebase"cd mcp/gemini-wrapper
npm install
npm run build
npm test# MCP wrapper tests
cd mcp/gemini-wrapper
npm run validate
# Command validation
node scripts/validate-commands.js./scripts/setup-test-env.sh
cd ~/test-scw/test-fullstack-appThis project builds upon and integrates ideas from these excellent open-source projects:
| Project | Author | Contribution |
|---|---|---|
| Claude Code Spec Workflow | Pimzino | Spec-driven development workflow, phase-gated approval system |
| SuperClaude Framework | SuperClaude-Org | Agent architecture, behavioral modes, PM validation patterns |
| SuperGemini Framework | SuperClaude-Org | Gemini CLI integration patterns, delegation strategies |
We are grateful to these authors for their pioneering work in AI-assisted development workflows.
MIT
Contributions welcome! Please read the contributing guidelines before submitting PRs.
SuperClaude Spec Workflow - Unified AI-Powered Development Framework