| name | superclaude-prompt-generator |
| description | Expert SuperClaude prompt engineering assistant that analyzes user needs and crafts optimal prompts using the full SuperClaude framework - commands, flags, personas, MCP servers, wave orchestration, parallel execution patterns, continuous execution directives, and the new PM Agent orchestration system with PDCA cycles and Serena memory integration. |
| version | 2.3.0 |
| author | SuperClaude Framework |
| category | productivity |
SuperClaude Prompt Generator
Expert prompt engineering for the SuperClaude framework
This skill helps you craft optimal SuperClaude prompts by:
- Analyzing your current need and context
- Selecting the right commands, flags, personas, and MCP servers
- Leveraging orchestration and parallel execution patterns
- Applying parallel-by-default optimization strategies
- Explaining the reasoning behind each prompt design choice
- Ensuring best practices and framework compliance
🔴 CRITICAL: All SuperClaude Prompts MUST Start with a Command
Every generated prompt MUST begin with a /sc: command. This is non-negotiable for SuperClaude framework compliance.
Why Commands Are Mandatory
- Commands activate the SuperClaude orchestration engine
- Commands enable auto-persona activation and MCP coordination
- Commands trigger wave orchestration for complex operations
- Commands ensure proper task management and quality gates
- Natural language alone bypasses the SuperClaude framework
Command Selection Priority
- First: Choose the most appropriate
/sc: command from available commands
- Always: Start the prompt with the command + required arguments
- Then: Add flags, personas, and other modifiers
- Never: Generate prompts without a leading
/sc: command
Available Commands: 30+ total (organized by category)
Development & Implementation (4 commands):
/sc:build - Project builder with framework detection/sc:implement - Feature and code implementation with intelligent persona activation/sc:design - Design orchestration across architecture, API, and UI domains/sc:workflow - Generate implementation workflows from PRDs and feature requirements
Analysis & Investigation (4 commands):
/sc:analyze - Multi-dimensional code and system analysis (wave-enabled)/sc:troubleshoot - Problem investigation and debugging/sc:explain - Educational explanations of code and concepts/sc:business-panel - Multi-expert business strategy analysis
Quality & Enhancement (2 commands):
/sc:improve - Evidence-based code enhancement (wave-enabled)/sc:cleanup - Systematic technical debt reduction and code cleanup
Planning & Estimation (3 commands):
/sc:task - Long-term project management and task orchestration/sc:estimate - Evidence-based development estimation/sc:brainstorm - Interactive requirements discovery and exploration
Testing (1 command):
/sc:test - Comprehensive testing workflows with Playwright integration
Documentation (1 command):
/sc:document - Generate focused documentation for components and APIs
Version Control (1 command):
/sc:git - Git workflow assistant with intelligent commit messages
Session Lifecycle (3 commands):
/sc:load - Load project context and session state using Serena MCP/sc:save - Save session context with timestamped versioning/sc:reflect - Task validation and quality reflection using Serena MCP
Meta & Discovery (3 commands):
/sc:index - Browse command catalog and framework documentation/sc:help - List all available /sc commands with descriptions/sc:select-tool - Intelligent MCP tool selection (Serena vs Morphllm routing)
Orchestration & Project Management (4 commands - NEW):
/sc:pm - PM Agent: Always-active orchestration layer with PDCA cycles and Serena memory integration/sc:agent - SC Agent session controller that orchestrates investigation, implementation, and review/sc:recommend - Ultra-intelligent command recommendation engine with multi-language support/sc:index-repo - Repository indexing for 94% token reduction (58K → 3K tokens)
Expert Review (1 command):
/sc:spec-panel - Multi-expert specification review and critique
Team Coordination (1 command):
/sc:team - Activate specialized team members (37+ roles: pm, lead, backend, frontend, devops, qa, security, performance, data, ml, mobile, dba, ux, platform, docs, accessibility, release, compliance, ba, solutions, observability, api, cost, designer, researcher, analyst, product-analyst, integration, architect, fullstack, growth, sre, technical-writer, enterprise-architect, program-manager, customer-success-engineer, solutions-engineer, growth-engineer, product-designer)
- Special Note:
/sc:team is a framework-level meta-command that loads agent contexts from ~/.claude/agents/[role].md rather than being a standalone command file
Wave Orchestration (1 command):
/sc:spawn - Meta-system task orchestration with intelligent breakdown
Research (1 command):
/sc:research - Deep web research with adaptive strategies
Note: Check /Users/arlenagreer/.claude/commands/sc/ directory for the complete and current list of available commands. The /sc:team command is implemented through the agent system in /Users/arlenagreer/.claude/agents/ rather than as a standalone command file.
If Required Command Doesn't Exist
If the ideal command doesn't exist:
- First: Check
/Users/arlenagreer/.claude/commands/sc/ to verify it truly doesn't exist
- Option A: Note that the command should be created (preferred for recurring needs)
- Option B: Use the closest existing command (e.g.,
/sc:analyze for analysis tasks)
- Always: Explain which command was chosen and why
How to Use This Skill
Simply describe what you need to accomplish, and this skill will:
- Analyze Your Need: Understand complexity, domain, operation type, and scope
- Select SuperClaude Command: Choose the appropriate
/sc: command (MANDATORY FIRST STEP)
- Design the Prompt: Add optimal flags, personas, and MCP servers
- Identify Parallelization: Apply parallel-first optimization (CRITICAL for efficiency)
- Explain the Thinking: Document why each choice was made and how it ensures the best result
- Output the Prompt: Provide the complete, ready-to-use SuperClaude prompt starting with the command
🔴 CRITICAL: Continuous Execution Principle
Unless explicitly instructed otherwise, all generated prompts MUST emphasize continuous, uninterrupted execution.
Default Behavior
- Complete the entire task from start to finish without stopping
- Do not pause to summarize progress after each major step
- Do not ask permission to proceed to the next phase
- Execute all planned steps in the workflow without interruption
When to Include Pauses
Only suggest stopping points when:
- User explicitly requests checkpoints ("pause after analysis", "wait for approval")
- Safety-critical operations requiring manual validation
- User input is genuinely needed to proceed (missing requirements, unclear specifications)
- Resource constraints require staged execution
Prompt Language Patterns
Good (Continuous):
- "Complete the entire implementation from start to finish"
- "Execute all steps in this workflow without stopping"
- "Proceed through all phases: analysis → design → implementation → testing"
- "Work through the complete task until done"
Bad (Unnecessary Pauses):
- "After completing phase 1, summarize and ask if you should continue"
- "Complete the analysis, then wait for confirmation before proceeding"
- "Stop after each component to check if the approach is correct"
- "Pause between steps to get user approval"
Integration with Generated Prompts
Every generated prompt should include explicit continuous execution language unless the user specifically requests otherwise.
Prompt Engineering Workflow
Step 1: Understand the Request
Analyze the user's request to identify:
- Primary Domain: Frontend, backend, security, performance, architecture, etc.
- Operation Type: Analysis, creation, implementation, modification, debugging, iterative
- Complexity Level: Simple (1-2 files, basic task), Moderate (3-10 files, analysis), Complex (system-wide, >10 steps)
- Scope: File, module, project, or system level
- Special Requirements: Security, performance, quality focus, testing needs
- Parallelization Opportunities: Independent operations, multi-file work, analysis scope
Step 2: Select SuperClaude Command (MANDATORY FIRST)
🔴 CRITICAL: Every prompt MUST start with a /sc: command.
Based on the analysis, select the most appropriate command:
Commands (from /sc: commands):
- Development:
/sc:build, /sc:implement, /sc:design
- Analysis:
/sc:analyze, /sc:troubleshoot, /sc:explain, /sc:business-panel
- Quality:
/sc:improve, /sc:cleanup
- Planning:
/sc:workflow, /sc:estimate, /sc:task, /sc:brainstorm
- Orchestration:
/sc:pm (PM Agent), /sc:agent, /sc:recommend, /sc:index-repo
- Testing:
/sc:test
- Documentation:
/sc:document
- Research:
/sc:research
- Meta:
/sc:git, /sc:load, /sc:index, /sc:spawn
To find all available commands:
Check /Users/arlenagreer/.claude/commands/sc/ directory for the complete current list.
If the ideal command doesn't exist:
- First verify by checking the commands directory
- Note that it should be created (preferred for recurring needs)
- Use the closest existing command as a fallback
- Explain the gap and workaround in the analysis section
Step 2.3: Key Command Details
/sc:help - Command Discovery
Purpose: Primary discovery mechanism for finding available SuperClaude commands
Usage:
/sc:help [query]
Key Features:
- Lists all available
/sc: commands with descriptions
- Searchable by keyword or category
- Shows command syntax and common usage patterns
- Provides quick reference for flag combinations
- Auto-updates when new commands are added
When to Use:
- User unsure which command exists for their need
- Exploring available SuperClaude capabilities
- Quick reference lookup for command syntax
- Verifying command availability before crafting prompts
Integration:
- Works with Context7 for command documentation
- Provides examples from COMMANDS.md reference
- Links to detailed command specifications
/sc:save - Session Persistence
Purpose: Save session context and project state using Serena MCP for cross-session continuity
Usage:
/sc:save [--type session|learnings|context|all] [--summarize] [--checkpoint]
Key Features:
- Idempotency Contract: Append-only model with ISO 8601 timestamps
- Versioning: Each save creates new timestamped entry (session_YYYY-MM-DD_HHMMSS)
- Data Safety: No overwrites - all saves preserved in memory history
- Automatic Triggers: 30-minute intervals, task completion, risky operations
- Rollback Capability: Previous versions accessible via Serena memory operations
Idempotency Behavior:
- First Call: Creates timestamped memory entry
- Repeated Calls: Creates NEW timestamped version (append-only)
- Conflict Resolution: Last-write-wins within same minute
- Data Integrity: Validation ensures memory write success before confirmation
When to Use:
- End of coding session to preserve context
- Before risky operations (create restore point)
- After completing major milestones
- When switching between projects
- Automatic checkpoints (every 30 minutes)
Integration:
- Serena MCP: Memory management and persistence
- Compensation Logic: Atomic writes with rollback on failure
- Session Lifecycle: Works with
/sc:load for complete session management
/sc:reflect - Quality Validation
Purpose: Task reflection and validation using Serena MCP analysis capabilities
Usage:
/sc:reflect [--aspect task-adherence|collected-information|completion]
Key Features:
- Task Adherence: Validates approach against original goals
- Information Completeness: Analyzes session completeness and gaps
- Completion Criteria: Evaluates whether task is truly done
- Evidence-Based: All assessments supported by session data
Reflection Tools (Serena MCP):
think_about_task_adherence: Validates approach against goalsthink_about_collected_information: Analyzes session completenessthink_about_whether_you_are_done: Evaluates completion criteria
When to Use:
- Before marking complex tasks as complete
- Mid-task validation of approach correctness
- After analysis phase to verify thoroughness
- When uncertain if requirements are fully met
- Quality gate checkpoints in workflows
Integration:
- Serena MCP: Semantic code understanding for context analysis
- Sequential: Structured reasoning for validation logic
- Quality Gates: Steps 2.5 & 7.5 in 10-step validation cycle
Performance: <200ms for core reflection operations
Step 2.3.1: Session Lifecycle Workflow
Purpose: Understanding how /sc:load, /sc:save, and /sc:reflect work together as a unified session management system.
Complete Session Management Cycle
Phase 1: Session Initialization
- Command:
/sc:load [project-name]
- Purpose: Restore project context, previous learnings, and active tasks from prior sessions
- Serena MCP: Loads session memory with project-specific context and discoveries
- Triggers:
- New terminal session starting work on existing project
- Project switch (moving from one codebase to another)
- Context refresh needed (reconnecting to previous work state)
- Returning after break (hours, days, or weeks later)
- What Gets Loaded:
- Project structure understanding and architectural decisions
- Previous discoveries and learnings about the codebase
- Active task context and workflow state
- Code patterns, conventions, and project-specific knowledge
- Team decisions and documentation references
Phase 2: Active Development
- Auto-Checkpoints: Every 30 minutes via
/sc:save --checkpoint
- Automatic background saves preserve ongoing work
- No user intervention required
- Captures incremental progress and discoveries
- Manual Saves: Triggered strategically
- Before risky operations (major refactors, schema changes, deployments)
- After completing major milestones (feature complete, PR ready, tests passing)
- Before context switches (switching branches, different project focus)
- When significant decisions are made (architectural choices, pattern adoptions)
- Memory Accumulation: Continuous learning during work
- Session discoveries (new code patterns identified, edge cases found)
- Code patterns recognized (architectural patterns, anti-patterns, best practices)
- Decisions documented (why certain approaches chosen, alternatives considered)
- Problem-solving strategies (debugging techniques that worked, performance insights)
Phase 3: Quality Validation
- Command:
/sc:reflect --aspect task-adherence
- Purpose: Validate work against original goals before marking tasks complete
- Serena Analysis: Semantic validation using project context
- Task Adherence: Did the approach align with stated objectives?
- Information Completeness: Was sufficient information gathered and considered?
- True Completion: Is the task genuinely done, or are there remaining gaps?
- Validation Timing:
- Before marking complex tasks as "completed"
- Mid-task validation when approach seems off-track
- After analysis phase to verify thoroughness
- When uncertain if all requirements met
- At quality gate checkpoints in multi-phase workflows
- Reflection Aspects:
--aspect task-adherence: Validate approach correctness--aspect collected-information: Analyze session data completeness--aspect completion: Evaluate true completion criteria
Phase 4: Session Closure
- Command:
/sc:save --type all --summarize
- Purpose: Comprehensive session capture with learnings for future sessions
- Versioning: Timestamped entry
session_YYYY-MM-DD_HHMMSS
- ISO 8601 format ensures consistent chronological sorting
- Each save creates new version (append-only, no overwrites)
- Previous versions preserved in memory history
- Rollback capability via Serena memory operations
- Idempotency: Append-only model ensures data safety
- First call: Creates timestamped memory entry
- Repeated calls: Creates NEW timestamped version (never overwrites)
- Conflict resolution: Last-write-wins within same minute
- Data integrity: Validation ensures write success before confirmation
- What Gets Saved:
- Session summary and key accomplishments
- New learnings and discoveries about the codebase
- Decisions made and their rationale
- Problems encountered and solutions found
- Code patterns identified and adopted
- Next session recommendations (what to focus on, what to avoid)
Workflow Diagram
┌──────────────────────────────────────────────────────────────────────────┐
│ Session Lifecycle Flow │
└──────────────────────────────────────────────────────────────────────────┘
┌─────────────┐
│ START │
│ New Session │
└──────┬──────┘
│
▼
┌─────────────────────────────────────────────┐
│ Phase 1: LOAD │
│ /sc:load [project] │
│ • Restore context from Serena memory │
│ • Load previous learnings │
│ • Resume active tasks │
└──────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Phase 2: WORK │
│ Active Development │
│ • Code, analyze, implement │
│ • Accumulate discoveries │
│ • Auto-checkpoint every 30min │
│ • Manual saves at milestones │
└──────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Phase 3: REFLECT │
│ /sc:reflect --aspect task-adherence │
│ • Validate approach correctness │
│ • Verify information completeness │
│ • Confirm true task completion │
└──────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Phase 4: SAVE │
│ /sc:save --type all --summarize │
│ • Capture session summary │
│ • Document learnings & decisions │
│ • Create timestamped version │
│ • Preserve for future sessions │
└──────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ NEXT SESSION │
│ Loop back to Phase 1 (LOAD) │
│ Context preserved, ready to continue │
└─────────────────────────────────────────────┘
Continuous Cycle: Load → Work → Reflect → Save → (Next Session Load)
▲_______________________________________________|
Practical Usage Examples
Example 1: Starting Work on Existing Project
/sc:load bryan-mobile-app
/sc:save --checkpoint --summarize
/sc:save --type context --checkpoint
/sc:reflect --aspect task-adherence
/sc:save --type all --summarize
Example 2: Multi-Day Feature Development
/sc:load my-project
/sc:save --type all --summarize
/sc:load my-project
/sc:reflect --aspect collected-information
/sc:save --type all --summarize
/sc:load my-project
/sc:reflect --aspect completion
/sc:save --type all --summarize
Example 3: Context Switch Between Projects
/sc:load project-a
/sc:save --type session --checkpoint
/sc:load project-b
/sc:save --type all --summarize
/sc:load project-a
Troubleshooting Common Issues
Issue 1: Load Fails with "Project Not Found"
- Symptom:
/sc:load project-name returns error saying project doesn't exist
- Root Cause: Project has never been saved, or name mismatch
- Solutions:
- Verify project name spelling (case-sensitive)
- Check available projects: Use Serena MCP
list_memories tool
- First-time project: Just start working, save will create new project memory
- Name standardization: Use consistent naming (e.g.,
project-name not Project Name)
Issue 2: Save Conflicts or Duplicate Entries
- Symptom: Multiple saves creating too many versions
- Root Cause: Frequent manual saves creating version bloat (idempotent behavior working as designed)
- Solutions:
- Rely on auto-checkpoints (every 30min) for routine saves
- Manual saves only for significant milestones
- This is actually expected behavior (append-only for safety)
- Periodic cleanup: Use Serena memory management to consolidate old versions
Issue 3: Reflect Shows Incomplete Task When You Think It's Done
- Symptom:
/sc:reflect --aspect completion indicates task not truly complete
- Root Cause: Missing test coverage, incomplete documentation, or edge cases not handled
- Solutions:
- Review reflection feedback carefully - often catches real gaps
- Run additional analysis passes to verify completeness
- Check task scope - did original requirements include tests, docs, validation?
- Use
/sc:reflect --aspect collected-information to identify missing data
Issue 4: Serena MCP Connection Errors
- Symptom: "Serena MCP unavailable" or timeout errors during load/save/reflect
- Root Cause: MCP server not running or network/permission issues
- Solutions:
- Check Serena MCP status: Verify server is running and accessible
- Restart MCP server: Sometimes resolves transient connection issues
- Check permissions: Ensure Claude Code has access to Serena
- Fallback: Document work manually, retry save when MCP restored
- Prevention: Use
--validate flag to check MCP status before critical operations
Issue 5: Memory Fragmentation After Long Project
- Symptom: Load times increasing, memory size growing too large
- Root Cause: Accumulated sessions over weeks/months without cleanup
- Solutions:
- Periodic consolidation: Use
/sc:save --consolidate to merge similar entries
- Archive old sessions: Move completed feature sessions to archive
- Clean delete: Remove obsolete sessions that are no longer relevant
- Memory hygiene: Monthly cleanup of stale project memories
Issue 6: Context Loss Between Sessions
- Symptom: After
/sc:load, context doesn't feel complete or accurate
- Root Cause: Insufficient save detail or missing --summarize flag
- Solutions:
- Use
--type all --summarize for comprehensive saves
- Add explicit summaries during save (describe key decisions made)
- Save more frequently at decision points
- Use
/sc:reflect before save to capture session insights
- Document "why" not just "what" in your work
Best Practices for Session Lifecycle
✅ DO:
- Always
/sc:load at start of work session to restore context
- Rely on 30-minute auto-checkpoints for routine progress saves
- Use
/sc:reflect before marking complex tasks complete
- Save with
--type all --summarize at end of significant work sessions
- Create restore points with
/sc:save --checkpoint before risky operations
- Use consistent project naming across sessions
- Document decisions and learnings in session work
❌ DON'T:
- Skip loading at session start (loses valuable context)
- Over-save manually (defeats purpose of auto-checkpoints)
- Mark tasks complete without reflection validation
- Use different project names for same codebase
- Delete memories unless absolutely certain they're obsolete
- Rely solely on auto-saves for critical milestones (use manual save)
Integration with Other Commands
Session Lifecycle + Workflow Commands:
/sc:implement → Use reflect to validate implementation completeness/sc:analyze → Save analysis insights for future reference/sc:improve → Reflect on improvements before/after for quality validation/sc:build → Save build configurations and decisions/sc:task → Load project context for long-term task continuity
Session Lifecycle + Quality Gates:
- Steps 2.5 & 7.5 in 10-step validation cycle use
/sc:reflect
- Pre-execution validation with loaded context awareness
- Post-completion verification before session save
Session Lifecycle + Team Coordination:
- Team handoffs benefit from comprehensive session saves
/sc:team agents can load shared project context- Collaborative work maintains session continuity across team members
/sc:spec-panel - Expert Specification Review
Purpose: Multi-expert specification review using renowned specification and software engineering experts
Usage:
/sc:spec-panel [document] [--mode discussion|critique|socratic] [--experts <list>] [--focus <areas>]
Key Features:
- Expert Panel: 11 renowned experts (Wiegers, Fowler, Hohpe, Newman, Nygard, Crispin, Gregory, Cockburn, Adzic, Hightower, Vogels)
- Three Analysis Modes:
- Discussion: Collaborative improvement through expert dialogue
- Critique: Systematic review with priorities and severity ratings
- Socratic: Learning-focused questioning for deeper understanding
- Multi-Domain: Requirements, architecture, testing, quality, cloud infrastructure
- Quality Scoring: 0-10 scale with improvement recommendations
Analysis Modes:
- Discussion Mode: Experts build on each other's insights collaboratively
- Critique Mode: Systematic review with CRITICAL/HIGH/MEDIUM/LOW severity ratings
- Socratic Mode: Expert-guided questioning for strategic learning
When to Use:
- Before implementing complex features (validation)
- After drafting PRDs or technical specifications
- When seeking expert-level architectural feedback
- For quality validation of critical system designs
- Learning best practices from multiple expert perspectives
Integration:
- Sequential: Multi-expert coordination and synthesis
- Context7: Specification patterns and best practices
- Quality Gates: Expert validation in Phase 2 of workflows
Output: Comprehensive critique with quality scores, prioritized issues, and improvement recommendations
/sc:team - Team Coordination
Purpose: Activate specialized software engineering team members for coordinated development
Usage:
/sc:team [member] [action]
/sc:team:pm [action]
/sc:team:backend [action]
Team Members (37+ specialized roles):
- Product & Planning: pm (Product Manager), ba (Business Analyst), product-analyst
- Technical Leadership: lead (Tech Lead), architect, solutions, enterprise-architect
- Engineering: backend, frontend, fullstack, mobile, data, ml, integration
- Infrastructure: devops, platform, sre, observability, release, cost
- Quality & Testing: qa, performance, security, accessibility
- Design & Research: ux, designer, researcher, product-designer
- Documentation: docs, technical-writer
- Database: dba
- Specialized: api, compliance, program-manager, customer-success-engineer, solutions-engineer, growth, growth-engineer
Key Features:
- Framework-Level Implementation: Loads agent contexts from
~/.claude/agents/[role].md
- Auto-Handoff: Automatic coordination triggers between team members
- Workflow Integration: TDD, specification-driven, handoff protocols
- Quality Gates: Team-specific validation checkpoints
Handoff Triggers (automatic):
- Requirements complete → Tech Lead activation
- Architecture approved → Engineering team activation
- Implementation complete → QA activation
- Testing complete → DevOps activation
- Security/Performance reviews → Throughout workflow
When to Use:
- Multi-phase development requiring multiple specialists
- When specific domain expertise needed (security, performance, compliance)
- Cross-functional coordination (PM → Lead → Engineers → QA → DevOps)
- Simulating real team workflows and handoffs
Integration:
- Agent System: Loads from
~/.claude/agents/ directory (47 agent files)
- Coordination:
team-config.md defines handoff protocols
- Personas: Maps to 11 SuperClaude personas for domain expertise
Special Note: /sc:team is a framework-level meta-command rather than a standalone command file. It integrates with the agent persona loading system.
/sc:select-tool - Intelligent MCP Tool Selection
Purpose: Intelligent routing between Serena and Morphllm MCP servers based on operation complexity and requirements
Usage:
/sc:select-tool [operation] [--analyze] [--explain]
Key Features:
- Complexity Scoring: Multi-dimensional analysis of file count, operation type, and requirements
- Intelligent Routing: Automatic selection between Serena (semantic) and Morphllm (pattern-based) operations
- Performance Optimization: Sub-100ms decision time with >95% selection accuracy
- Decision Transparency: Explain mode shows scoring logic and selection rationale
Decision Matrix (see Step 2.4 for detailed server capabilities):
Direct Mappings:
- Symbol operations (rename, extract, move) → Serena
- Pattern edits (bulk replacements, style enforcement) → Morphllm
- Memory operations (save, load, persistence) → Serena
- Session lifecycle → Serena
- Framework updates → Morphllm
Complexity Thresholds:
-
Score >0.6 (High complexity) → Serena MCP
- Multi-file symbol operations
- Dependency tracking required
- LSP integration needed
- Semantic understanding critical
-
Score <0.4 (Low complexity) → Morphllm MCP
- Simple text replacements
- Pattern-based bulk edits
- Speed-critical operations
- Token optimization priority
-
Score 0.4-0.6 (Medium complexity) → Feature-based selection
- Evaluate specific operation requirements
- Consider performance vs accuracy trade-offs
- Default to Serena for safety
Scoring Factors:
- File count: >10 files increases complexity
- Operation type: Semantic operations score higher
- Language/framework: Multi-language increases complexity
- Requirements: LSP, dependencies, context increase complexity
When to Use:
- Uncertain which MCP server is optimal for your operation
- Need to understand tool selection logic and reasoning
- Want to optimize between speed (Morphllm) and accuracy (Serena)
- Learning the decision patterns for future manual selection
Integration:
- Automatic: Used internally by
/sc:refactor, /sc:edit, /sc:implement, /sc:improve
- Manual: Explicit routing decisions when user specifies tool preference
- Cross-Reference: See Step 2.4 for detailed Serena vs Morphllm guidance
Example Routing Decisions:
"rename getUserData function everywhere"
→ Analysis: High complexity (symbol operation, multi-file)
→ Selection: Serena MCP (LSP capabilities, dependency tracking)
→ Confidence: 95%
"update all console.log to logger.info"
→ Analysis: Low complexity (pattern-based, text replacement)
→ Selection: Morphllm MCP (pattern matching, speed optimized)
→ Confidence: 98%
"save project context and discoveries"
→ Direct mapping: Memory operations → Serena MCP
→ Rationale: Session persistence and project memory
→ Confidence: 100%
Fallback Strategy:
- Tier 1: Selected MCP server (Serena or Morphllm)
- Tier 2: Alternative MCP server if primary unavailable
- Tier 3: Native Claude Code tools as last resort
Performance Metrics:
- Decision time: <100ms
- Selection accuracy: >95% based on operation outcomes
- Confidence scoring: 0-100% based on clarity of operation type
Special Note: This is a meta-command for intelligent tool routing. Most users won't call it directly - it's automatically invoked by other commands. However, using --analyze or --explain flags can help understand tool selection decisions and improve your own manual MCP server choices.
/sc:pm - PM Agent (Project Management Orchestration) - NEW
Purpose: Always-active foundation layer for intelligent orchestration with PDCA cycles and Serena memory integration
Usage:
/sc:pm [task-description]
/sc:pm --cycle plan|do|check|act
/sc:pm --self-improve
Key Features:
- Always-Active Foundation: PM Agent is the orchestration layer that coordinates all other commands
- PDCA Cycle Integration: Plan-Do-Check-Act methodology for systematic task execution
- Serena Memory Integration: Cross-session learning with standardized memory key schema
- Self-Improvement Workflows: Continuous documentation of patterns, mistakes, and learnings
- Sub-Agent Orchestration: Auto-delegation to domain specialists without manual routing
PDCA Cycle Methodology:
PLAN Phase:
├── Write plan to memory: plan/[feature]/hypothesis
├── Document: architecture, rationale, risks
└── Validate: requirements completeness
DO Phase:
├── Execute with checkpoints: execution/[feature]/do
├── Log errors and solutions: execution/[feature]/errors
└── Progressive implementation with validation
CHECK Phase:
├── Evaluate results: evaluation/[feature]/check
├── Measure against success criteria: evaluation/[feature]/metrics
└── Document lessons: evaluation/[feature]/lessons
ACT Phase:
├── Standardize successful patterns
├── Update learning memories: learning/patterns/[name]
└── Feed improvements into next cycle
Memory Key Schema (Serena MCP):
Session Context:
session/context - Current session state and discoveries
session/last - Previous session summary
session/checkpoint - Auto-save checkpoint data
Planning Artifacts:
plan/[feature]/hypothesis - Initial approach hypothesis
plan/[feature]/architecture - Architectural decisions
plan/[feature]/rationale - Decision justifications
Execution Tracking:
execution/[feature]/do - Implementation progress
execution/[feature]/errors - Encountered errors
execution/[feature]/solutions - Applied solutions
Evaluation Results:
evaluation/[feature]/check - Validation results
evaluation/[feature]/metrics - Success
Self-Correction Workflow:
- Root Cause Analysis: When errors occur, PM Agent analyzes underlying causes
- Solution Documentation: Successful fixes are logged to
learning/solutions/[error]
- Pattern Recognition: Recurring patterns are promoted to
learning/patterns/[name]
- Mistake Avoidance: Failures are documented in
learning/mistakes/[timestamp]
- Next Session Benefits: Learnings are loaded and applied in future sessions
Sub-Agent Orchestration:
- PM Agent automatically delegates to domain specialists based on task context
- No manual routing required - intelligent task analysis determines appropriate agents
- Handoff protocols ensure context preservation between agents
- Quality gates validate outputs before proceeding
When to Use:
- Starting new features that require systematic planning
- Complex tasks benefiting from PDCA methodology
- When you want cross-session learning and context preservation
- Long-running projects requiring orchestration across multiple sessions
- Tasks that benefit from self-improvement and pattern capture
Integration:
- Serena MCP: Primary integration for memory and persistence
- Sequential: Complex reasoning during PLAN and CHECK phases
- All Commands: PM Agent can orchestrate any other
/sc: command
- Session Lifecycle: Works with
/sc:load, /sc:save, /sc:reflect
Example Workflows:
/sc:pm "Implement user authentication with JWT tokens"
/sc:pm --cycle plan "authentication feature planning"
/sc:pm --cycle do "implement JWT authentication"
/sc:pm --cycle check "validate authentication implementation"
/sc:pm --cycle act "standardize authentication patterns"
/sc:pm --self-improve "capture learnings from this session"
Best Practices:
- ✅ Use PM Agent for complex, multi-step features
- ✅ Let PDCA cycle guide systematic execution
- ✅ Document decisions in memory for future reference
- ✅ Review learning memories to avoid repeated mistakes
- ❌ Don't use for simple, one-off tasks (use specific commands instead)
- ❌ Don't skip CHECK phase - validation is critical
/sc:agent - SC Agent Session Controller - NEW
Purpose: Session controller that orchestrates investigation, implementation, and review workflows
Usage:
/sc:agent [task-description]
Key Features:
- Startup Checklist: Auto-runs
git status and reports core service availability
- Confidence-Based Execution: Pre-implementation confidence score ≥0.90 required
- Helper Integration: Auto-activates
@confidence-check, @deep-research, @repo-index, @self-review
- Token Discipline: Short status messages, efficient communication
Task Protocol:
- Clarify Scope: Confirm success criteria, blockers, constraints
- Plan Investigation: Use parallel tool calls, reach for helper agents
- Iterate Until Confident: Track confidence, don't implement below 0.90
- Implementation Wave: Grouped edits, single checkpoint summary
- Self-Review: Invoke
@self-review to double-check outcomes
When to Use:
- Starting work sessions that need systematic orchestration
- Complex tasks requiring confidence validation before implementation
- When you want automatic helper agent coordination
/sc:recommend - Command Recommendation Engine - NEW
Purpose: Intelligent command recommendation based on user input analysis
Usage:
/sc:recommend [user-query]
Key Features:
- Multi-Language Support: Recognizes intent across languages
- Confidence Scoring: Ranks recommendations by relevance
- Context-Aware: Considers current project state and history
- Learning Integration: Improves recommendations based on usage patterns
When to Use:
- Uncertain which
/sc: command is best for your need
- Learning the SuperClaude command ecosystem
- Quick command discovery without reading full documentation
/sc:index-repo - Repository Indexing - NEW
Purpose: Generate comprehensive project index for 94% token reduction
Usage:
/sc:index-repo
/sc:index-repo mode=update
/sc:index-repo mode=quick
Key Features:
- Massive Token Savings: 58K tokens → 3K tokens (94% reduction)
- Parallel Analysis: 5 concurrent Glob searches for structure analysis
- Metadata Extraction: Entry points, key modules, API surface, dependencies
- Two Output Files:
PROJECT_INDEX.md (3KB human-readable) + PROJECT_INDEX.json (10KB machine-readable)
ROI Calculation:
- Index creation: 2,000 tokens (one-time)
- Index reading: 3,000 tokens (every session)
- Full codebase read: 58,000 tokens (every session)
- Break-even: 1 session
- 10 sessions savings: 550,000 tokens
When to Use:
- Starting work on a new codebase
- After major structural changes
- When token efficiency is critical
- For quick project orientation
Step 2.4: MCP Server Details
SuperClaude integrates with powerful MCP (Model Context Protocol) servers that extend Claude's capabilities. Understanding when to use each server is critical for optimal prompt crafting.
Serena MCP Server
Purpose: Semantic code understanding with project memory and session persistence
Capabilities:
- Symbol operations (rename, extract, move functions/classes)
- Project-wide code navigation and exploration
- Multi-language projects with LSP integration
- Session lifecycle management (
/sc:load, /sc:save, project activation)
- Memory-driven development workflows
- Large codebase analysis (>50 files, complex architecture)
Choose Serena When:
- Over Morphllm: For symbol operations, not pattern-based edits
- For semantic understanding: Symbol references, dependency tracking, LSP integration
- For session persistence: Project context, memory management, cross-session learning
- For large projects: Multi-language codebases requiring architectural understanding
- Not for simple edits: Basic text replacements, style enforcement, bulk operations
Works Best With:
- Morphllm: Serena analyzes semantic context → Morphllm executes precise edits
- Sequential: Serena provides project context → Sequential performs architectural analysis
Command Integration:
/sc:load - Requires Serena for project context loading/sc:save - Requires Serena for memory persistence/sc:reflect - Uses Serena for semantic code understanding/sc:select-tool - Routes between Serena and Morphllm intelligently
Example Use Cases:
"rename getUserData function everywhere" → Serena (symbol operation with dependency tracking)
"find all references to this class" → Serena (semantic search and navigation)
"load my project context" → Serena (/sc:load with project activation)
"save my current work session" → Serena (/sc:save with memory persistence)
When NOT to Use Serena:
"update all console.log to logger" → Use Morphllm (pattern-based replacement)
"create a login form" → Use Magic (UI component generation)
"enforce ESLint rules" → Use Morphllm (style guide application)
Activation Flags: --serena (explicit), auto-activated by session lifecycle commands
Morphllm MCP Server
Purpose: Pattern-based code editing engine with token optimization for bulk transformations
Capabilities:
- Multi-file edit operations with consistent patterns
- Framework updates, style guide enforcement, code cleanup
- Bulk text replacements across multiple files
- Natural language edit instructions with specific scope
- Token optimization with 30-50% efficiency gains
Choose Morphllm When:
- Over Serena: For pattern-based edits, not symbol operations
- For bulk operations: Style enforcement, framework updates, text replacements
- When token efficiency matters: Fast Apply scenarios with compression needs
- For simple to moderate complexity: <10 files, straightforward transformations
- Not for semantic operations: Symbol renames, dependency tracking, LSP integration
Works Best With:
- Serena: Serena analyzes semantic context → Morphllm executes precise edits
- Sequential: Sequential plans edit strategy → Morphllm applies systematic changes
Command Integration:
/sc:cleanup - Ideal for bulk cleanup operations/sc:improve - Pattern-based code improvements/sc:select-tool - Routes between Serena and Morphllm intelligently
Example Use Cases:
"update all React class components to hooks" → Morphllm (pattern transformation)
"enforce ESLint rules across project" → Morphllm (style guide application)
"replace all console.log with logger calls" → Morphllm (bulk text replacement)
"update import paths after refactoring" → Morphllm (bulk pattern replacement)
When NOT to Use Morphllm:
"rename getUserData function everywhere" → Use Serena (symbol operation)
"analyze code architecture" → Use Sequential (complex analysis)
"explain this algorithm" → Native Claude (simple explanation)
Activation Flags: --morph or --morphllm (explicit), auto-activated by bulk edit patterns
Serena vs Morphllm Decision Matrix
| Operation Type | Use Serena | Use Morphllm |
|---|
| Symbol rename | ✅ Yes | ❌ No |
| Bulk text replacement | ❌ No | ✅ Yes |
| Find references | ✅ Yes | ❌ No |
| Style enforcement | ❌ No | ✅ Yes |
| Session persistence | ✅ Yes | ❌ No |
| Framework updates | ❌ No | ✅ Yes |
| Dependency tracking | ✅ Yes | ❌ No |
| Pattern-based edits | ❌ No | ✅ Yes |
| LSP integration | ✅ Yes | ❌ No |
| Token optimization | Moderate | High (30-50%) |
Key Decision Factors:
- Semantic vs Pattern: Symbol operations → Serena, text patterns → Morphllm
- Scope: Single refactoring → Serena, bulk operations → Morphllm
- Integration: Session lifecycle → Serena, code cleanup → Morphllm
- Efficiency: Complex analysis → Serena, simple bulk edits → Morphllm
Combined Workflow Example:
Task: "Refactor authentication module and update all usage sites"
1. Serena: Analyze authentication module structure and find all references
2. Sequential: Plan refactoring strategy based on dependencies
3. Morphllm: Apply consistent patterns across all usage sites
4. Serena: Verify symbol references after refactoring
Step 2.5: Add Complementary Facilities
After selecting the command, add complementary facilities:
Flags (behavioral modifiers):
- Mode Activation:
--brainstorm, --introspect, --task-manage, --orchestrate, --token-efficient
- MCP Servers:
--c7/--context7, --seq/--sequential, --magic, --play/--playwright, --morph/--morphllm, --serena
- Analysis Depth:
--think, --think-hard, --ultrathink
- Execution Control:
--delegate, --concurrency, --loop, --validate, --safe-mode
- Output Optimization:
--scope, --focus, --uc
Personas (domain experts):
- Technical:
--persona-architect, --persona-frontend, --persona-backend, --persona-security, --persona-performance
- Process:
--persona-analyzer, --persona-qa, --persona-refactorer, --persona-devops
- Knowledge:
--persona-mentor, --persona-scribe
MCP Server Integration (see Step 2.4 for detailed server selection guidance):
- Context7: Library docs, framework patterns, best practices
- Sequential: Complex analysis, multi-step reasoning, systematic debugging
- Magic: UI component generation, design systems
- Playwright: Browser testing, E2E scenarios, performance metrics
- Serena: Semantic code understanding, symbol operations, session persistence (see Step 2.4)
- Morphllm: Pattern-based bulk edits, style enforcement, token optimization (see Step 2.4)
Wave Orchestration (for complex operations):
- Wave-enabled commands:
/sc:analyze, /sc:build, /sc:implement, /sc:improve, /sc:design, /sc:task, /sc:workflow
- Wave strategies:
--wave-strategy progressive, systematic, adaptive, enterprise
- Auto-activation: complexity ≥0.7 + files >20 + operation_types >2
Step 2.5: Apply Parallel-First Philosophy
🔴 CRITICAL PRINCIPLE FROM RULES.MD: "PARALLEL EVERYTHING"
SuperClaude's Tool Optimization rule mandates:
- Default Behavior: Execute independent operations in parallel, NEVER sequentially
- Planning Integration: Identify parallelization during planning phase (Plan → TodoWrite → Analyze Parallel Ops → Execute)
- Single Message Pattern: Use one message with multiple tool calls for independent operations
- Efficiency First: Choose speed and power over familiarity - use the fastest method available
Parallelization Analysis Checklist
Ask these questions for EVERY prompt:
-
File Operations:
-
Analysis Scope:
-
Multi-Domain Operations:
-
Wave Operations:
-
Dependencies:
Multi-Tool Call Pattern
How Claude Code Executes Parallel Operations:
Claude Code can call multiple tools in a single message. This is the key to parallelization:
Good (Parallel):
Message 1: [Read file1, Read file2, Read file3, Grep pattern1, Grep pattern2]
→ All execute simultaneously, results arrive together
Bad (Sequential):
Message 1: [Read file1]
Message 2: [Read file2]
Message 3: [Read file3]
→ Each waits for previous to complete (3x slower)
When crafting prompts, explicitly suggest parallel execution where applicable:
- "Read all configuration files in parallel"
- "Search for patterns across codebase simultaneously"
- "Analyze frontend, backend, and infrastructure in parallel"
When NOT to Parallelize
Sequential execution is appropriate when:
- Security-Critical Operations: Authentication, encryption, compliance validation (reduce attack surface)
- Sequential Dependencies: Operation B requires results from Operation A
- Resource Constraints: System already at 85%+ resource usage
- Data Consistency: Operations that must maintain strict ordering for correctness
- Debugging: When you need to observe step-by-step execution for troubleshooting
Important: In prompts, explicitly note when sequential execution is chosen and why.
Step 2.5.1: Parallelization Dependency Management
Purpose: Understanding when operations can be truly parallel vs when sequential ordering is required
Effective parallelization requires understanding dependency relationships between operations. This section provides patterns for identifying true independence, recognizing dependencies, and making informed execution ordering decisions.
Dependency Resolution Patterns
Independent Operations (can be parallelized):
- File reads from different files: Each read operation accesses distinct files with no shared state
- Example: Reading
config.json, package.json, README.md simultaneously
- Benefit: 3x speedup for 3 files
- Pattern searches across independent directories: Separate directory trees with no interdependencies
- Example: Searching
src/, tests/, docs/ in parallel
- Benefit: Near-linear scalability with directory count
- Analysis of separate domains: Frontend, backend, security, performance operate on different concerns
- Example: UI analysis + API analysis + security scan running simultaneously
- Benefit: Domain expertise applied concurrently
- Testing independent components: Test suites with no shared fixtures or state
- Example: Component A tests + Component B tests in parallel
- Benefit: Test execution time reduced proportionally
- Documentation generation for separate modules: Independent documentation contexts
- Example: API docs + User guide + Developer guide generated concurrently
- Benefit: Documentation pipeline parallelization
Sequential Dependencies (must be ordered):
- Read → Analyze → Edit same file: Each step requires previous step's output
- Example: Read config → Parse values → Update config → Validate changes
- Reasoning: Analysis needs file content, edit needs analysis results, validation needs new content
- Create directory → Create files within directory: Child creation depends on parent existence
- Example:
mkdir components/auth → touch components/auth/login.tsx
- Reasoning: File system hierarchy requires parent before children
- Build dependencies → Run dependent code: Runtime execution needs compiled artifacts
- Example: Compile TypeScript → Bundle JavaScript → Run application
- Reasoning: Each stage produces inputs for next stage
- Schema migration → Data migration: Data transformation depends on schema structure
- Example: Add column to table → Populate column with calculated values
- Reasoning: Data migration logic requires new schema to exist
- Authentication → Authorized operations: Security operations must validate before proceeding
- Example: Login → Fetch protected resource
- Reasoning: Authorization check must complete before accessing protected resources
Partial Dependencies (can be partially parallelized):
- Group A files independent from Group B files: Parallelize groups, sequence within if needed
- Example: Frontend files (parallel) + Backend files (parallel), then integration
- Pattern:
[Frontend1 || Frontend2 || Frontend3] && [Backend1 || Backend2] → Integration
- Benefit: Parallelism within domains, coordination across domains
- Multiple analysis passes: Parallelize within pass, sequence passes if each builds on previous
- Example: Pass 1 (syntax + style + imports in parallel) → Pass 2 (semantic analysis using Pass 1 results)
- Pattern:
Wave 1: [Analysis A || Analysis B || Analysis C] → Wave 2: [Synthesis using Wave 1]
- Benefit: Maximum parallelism within each analysis wave
- Test suites with setup/teardown: Parallelize tests, sequence lifecycle hooks
- Example:
Setup (sequential) → [Test1 || Test2 || Test3] → Teardown (sequential)
- Pattern:
Before → [Parallel Tests] → After
- Benefit: Test execution parallelized while maintaining fixture integrity
Parallel Execution Boundaries
Wave Boundaries:
Domain Boundaries:
- Frontend operations parallel to backend operations: Separate technology stacks and concerns
- Example: React component development || Node.js API development
- Independence: Frontend uses mocked APIs, backend uses test data
- Security analysis parallel to performance analysis: Different evaluation criteria
- Example: Vulnerability scanning || Performance profiling
- Independence: Security focuses on threats, performance on bottlenecks
- Testing parallel to documentation generation: Different artifacts and processes
- Example: E2E test execution || API documentation generation
- Independence: Testing validates behavior, docs describe interfaces
File System Boundaries:
- Independent directories can be processed in parallel: No cross-directory dependencies
- Example: Analyzing
src/components/ || src/utils/ || src/services/
- Assumption: Directories represent logical module boundaries
- Files within same directory can be read in parallel: Read-only operations are concurrent-safe
- Example: Reading all
.tsx files in components/ simultaneously
- Safety: File system handles concurrent reads
- Edits to same file must be sequential: Write operations require serialization
- Example: Edit 1 → Edit 2 → Edit 3 (all modifying
config.ts)
- Reasoning: Prevents race conditions and merge conflicts
Sequential Override Criteria
When to Force Sequential (override parallel default):
-
Security Operations: Authentication, encryption, authorization flows
- Reasoning: Attack surface reduction requires sequential validation gates
- Example: Login → Validate credentials → Establish session → Authorize request
- Trade-off: Security integrity > execution speed
- Flag: Use
--sequential with explicit security justification
-
Data Integrity: Database transactions, file system mutations, state updates
- Reasoning: ACID properties and consistency require atomic sequential operations
- Example: Begin transaction → Read balance → Deduct amount → Update balance → Commit transaction
- Trade-off: Correctness > parallelism
- Flag: Document transactional requirements
-
Resource Constraints: System at >85% resource usage, memory limits approaching
- Reasoning: Parallel operations could cause resource exhaustion and failures
- Example: Already at 90% memory → Sequential processing to stay within limits
- Trade-off: Stability > speed optimization
- Flag: Use
--safe-mode with resource justification
-
Debugging: Step-by-step execution needed for troubleshooting
- Reasoning: Understanding failure requires observing execution order
- Example: Sequential execution to identify which step in chain causes error
- Trade-off: Debuggability > efficiency
- Flag: Temporary for investigation, remove after debugging
-
Explicit Dependencies: Operation B requires Operation A results as input
- Reasoning: Cannot execute B without A's output data
- Example: API call returns ID → Use ID to fetch related resource
- Trade-off: Logical dependency (no choice)
- Documentation: Show dependency chain clearly: A → B → C
How to Specify Sequential:
- Flag Usage: Add
--sequential flag to override parallel default
- Document Reason: Always explain: "Sequential required for [security|dependencies|resources]"
- Specify Dependency Chain: Make execution order explicit: "A → B → C (results flow sequentially)"
- Justify Trade-off: Explain what parallel benefit is being sacrificed and why
Execution Ordering Examples
Example 1: Multi-File Analysis (Parallel)
Task: Analyze 10 component files for performance issues
Dependency: None (files are independent React components with no shared state)
Execution: Parallel read of all 10 files → Parallel analysis of each component
Reasoning:
- File reads are concurrent-safe (read-only operations)
- Each component analysis is independent (no cross-component dependencies)
- Performance metrics are per-component (no aggregation needed during analysis)
Efficiency: 10x speedup vs sequential (linear scaling with file count)
Tool Pattern: Single message with 10 Read calls + parallel analysis Task agents
Example 2: File Edit Chain (Sequential)
Task: Read config → Parse values → Update config → Validate
Dependency: Each step requires previous step's output
Execution: Sequential chain (Read → Parse → Update → Validate)
Reasoning:
- Parse needs file content from Read
- Update needs parsed values from Parse
- Validate needs new file content from Update
- True data dependencies prevent parallelization
Efficiency: Cannot parallelize (true dependencies exist)
Tool Pattern: Sequential Read → Edit → Validation with explicit ordering
Justification: Data flow dependencies require sequential execution
Example 3: Mixed Dependencies (Partial Parallel)
Task: Analyze frontend (5 files) and backend (5 files), then compare results
Dependency: Frontend files independent, backend files independent, comparison depends on both
Execution:
Wave 1 (Parallel): [Frontend analysis (5 files) || Backend analysis (5 files)]
Wave 2 (Sequential): Compare frontend vs backend results
Reasoning:
- Within frontend: 5 files are independent → Parallel
- Within backend: 5 files are independent → Parallel
- Between domains: Frontend independent of backend → Parallel
- Comparison: Requires both analyses complete → Sequential after Wave 1
Efficiency: 5x speedup (10 files in 2 parallel groups vs 10 sequential)
Tool Pattern: Single message with 10 parallel Read calls → 2 parallel domain Task agents → Sequential synthesis
Benefit: Maximum parallelism within waves, coordination across waves
Example 4: Security-Critical Sequential (Override)
Task: Implement authentication flow with security validation
Dependency: Security validation gates require sequential execution
Execution: Sequential (deliberately avoiding parallelization)
Login → Validate credentials → Rate limit check → Establish session → Authorize
Reasoning:
- Security operations must complete in strict order to reduce attack surface
- Each gate validates before proceeding to next stage
- Parallel execution would allow bypassing validation steps
Efficiency: 0% parallel benefit (security > speed trade-off)
Tool Pattern: Sequential operations with explicit `--sequential` flag
Justification: "Sequential required for security: validation gates must execute in order"
Trade-off: Sacrificing parallelization for security integrity
Example 5: Resource-Constrained Sequential (Override)
Task: Process 100 large video files with encoding
Dependency: None (files are independent)
Natural Execution: Parallel (all 100 files simultaneously for maximum speed)
Actual Execution: Sequential batches of 5 files at a time
Reasoning:
- System has 32GB RAM, each encoding uses 8GB
- Parallel execution of 100 would require 800GB RAM (not available)
- Resource constraint forces sequential batching despite independence
Efficiency: 5x speedup vs pure sequential (batch of 5), but 20x slower than full parallel (if resources allowed)
Tool Pattern: `--concurrency 5` to limit parallel operations to resource availability
Justification: "Sequential batching required for resource constraints: 32GB RAM limit"
Trade-off: Sacrificing maximum parallelization for system stability
Decision Framework
Step 1: Identify Operations
- List all operations in the task
- Determine what each operation produces and consumes
Step 2: Map Dependencies
- Create dependency graph showing data flow between operations
- Identify operations with no incoming edges (can start immediately)
- Identify operations with incoming edges (must wait for dependencies)
Step 3: Group by Waves
- Wave 1: All operations with no dependencies (fully parallel)
- Wave 2: Operations depending only on Wave 1 (parallel within wave)
- Wave N: Operations depending on Wave N-1 (parallel within wave)
Step 4: Check Constraints
- Security constraints: Do any operations require sequential validation?
- Resource constraints: Can system handle full parallelism?
- Data integrity: Do any operations require transactional sequencing?
Step 5: Document Decision
- Specify parallel operations: "Operations A, B, C execute in parallel"
- Specify sequential boundaries: "Operation D waits for A, B, C completion"
- Justify sequential overrides: "Sequential required for [reason]"
- Estimate efficiency gain: "Expected X% speedup via parallelization"
Integration with SuperClaude Framework
Automatic Parallelization:
--delegate --parallel-dirs: Auto-parallelizes directory processing--multi-agent --parallel-focus: Spawns parallel domain-specific agents- MultiEdit tool: Parallelizes edits across multiple files automatically
- Wave orchestration: Structures operations into parallel waves with sequential boundaries
Manual Parallelization Specification:
- Prompt language: "Execute operations A, B, C in parallel"
- Tool pattern: Single message with multiple tool calls
- Explicit documentation: "Parallel execution: [operations] because [independence reason]"
Sequential Override Specification:
--sequential flag: Forces sequential execution with justification- Explicit dependency chains: Document as "A → B → C (sequential due to dependencies)"
- Reasoning annotation: Always explain why parallel was overridden
Step 2.6: Workflow Compensation and Error Recovery
Purpose: Understanding how to handle failures, rollback operations, and recover from errors while maintaining system consistency and data integrity.
Effective workflow execution requires planning for failure scenarios. This section provides patterns for error recovery, rollback procedures, and compensation logic to ensure graceful degradation and recovery from failures.
Rollback Procedures
Rollback Patterns for Common Operations:
File Operations:
- Create File Rollback: Delete the created file
- Example: Created
new-config.json → Rollback deletes new-config.json
- Implementation: Track created files, delete on rollback trigger
- Safety: Verify file was created by this operation (timestamp/hash check)
- Edit File Rollback: Restore from backup or checkpoint
- Example: Modified
config.json → Rollback restores original content
- Implementation: Create backup before edit, restore from backup on failure
- Integration: Use
/sc:save --checkpoint before risky edits
- Delete File Rollback: Restore from backup
- Example: Deleted
old-config.json → Rollback restores from backup
- Implementation: Move to
.trash/ instead of permanent delete, restore from trash
- Retention: Keep
.trash/ backups for session duration
Database Operations:
- Transaction Rollback: Use database transaction boundaries
- Example:
BEGIN TRANSACTION → Updates → COMMIT or ROLLBACK
- Implementation: Wrap related database operations in explicit transactions
- Safety: Ensure all-or-nothing execution for related changes
- Schema Migration Rollback: Execute down migration
- Example: Add column migration → Rollback removes column
- Implementation: Maintain paired up/down migrations for all schema changes
- Testing: Test rollback path as rigorously as forward migration
- Data Migration Rollback: Compensating updates or restore from backup
- Example: Data transformation applied → Rollback reverses transformation
- Implementation: Log all data changes, apply inverse transformations
- Validation: Verify data integrity after rollback
Infrastructure Operations:
- Deployment Rollback: Revert to previous deployment version
- Example: Deploy v2.0 fails → Rollback to v1.9
- Implementation: Keep previous version artifacts, automated rollback triggers
- Safety: Health checks determine rollback necessity
- Configuration Rollback: Restore previous configuration state
- Example: Update load balancer config → Rollback to previous config
- Implementation: Version all configurations, track deployment history
- Automation: Automated rollback on validation failure
Error Recovery Patterns
Retry with Exponential Backoff:
Circuit Breaker Pattern:
Fallback Strategies:
- Cached Response: Return stale cached data when primary source fails
- Example: API call fails → Return last successful response from cache
- Validity: Cache expiration policy (e.g., 5-minute TTL acceptable)
- Indication: Mark response as "cached fallback" for user awareness
- Default Value: Use sensible default when data unavailable
- Example: Configuration fetch fails → Use built-in default configuration
- Safety: Ensure defaults are safe and tested
- Documentation: Clearly document default behavior
- Degraded Functionality: Operate with reduced features
- Example: Recommendation engine fails → Show popular items instead
- UX: Gracefully degrade rather than complete failure
- Notification: Inform user of degraded mode
- Alternative Service: Route to backup service when primary fails
- Example: Primary payment processor down → Use secondary processor
- Coordination: Ensure alternative service is compatible
- Monitoring: Track which service handled request
Partial Completion Handling
Resume from Checkpoint:
- Checkpoint Pattern: Save progress at known-good states
- Example: Multi-file refactoring → Checkpoint after each file
- Implementation:
/sc:save --checkpoint at milestone boundaries
- Granularity: Balance checkpoint frequency vs overhead (every 5-10 operations)
- Resume Logic: Detect incomplete work and restart from checkpoint
- Example: Operation interrupted at file 5/10 → Resume from file 6
- State Detection: Check which operations completed successfully
- Idempotency: Ensure resumed operations can safely re-execute
- Progress Tracking:
Checkpoint Structure:
- Operation ID: unique identifier for operation
- Completed Steps: [step1, step2, step3]
- Remaining Steps: [step4, step5, step6]
- State Data: {file_index: 5, total_files: 10}
- Timestamp: ISO 8601 timestamp
- Integration with
/sc:save:
- Automatic checkpoints every 30 minutes (session lifecycle)
- Manual checkpoints before risky operations
- Serena MCP memory persistence for checkpoint state
Compensating Transactions:
- Pattern: Execute compensating action to undo partial work
- Example Scenarios:
- Order Processing: Order placed but payment failed → Cancel order (compensating transaction)
- User Registration: User created but email send failed → Delete user account (compensation)
- Multi-Step Migration: Step 2 fails → Execute inverse of Step 1 (compensation)
- Compensation Logic:
Forward Transaction Chain:
Step 1: Create User → Success
Step 2: Send Welcome Email → FAILURE
Compensation Chain (reverse order):
Compensate Step 1: Delete User → Success (compensation)
Final State: Clean rollback (user not created)
- Implementation Requirements:
- Track all successful operations in forward chain
- Design compensating operation for each forward operation
- Execute compensations in reverse order (LIFO)
- Ensure compensations are idempotent (can be retried safely)
- Complex Example (Multi-Service Transaction):
E-commerce Purchase Flow:
1. Reserve Inventory → Success (compensation: Release Inventory)
2. Charge Payment → Success (compensation: Refund Payment)
3. Create Shipment → FAILURE
Compensation Execution:
- Compensate Step 2: Refund Payment → Success
- Compensate Step 1: Release Inventory → Success
- Final State: No charge, no inventory reserved, no shipment
Compensation Logic for Atomic Operations
Atomic Operation Requirements:
- Definition: Operation that must complete entirely or not at all (all-or-nothing)
- Examples: Database transactions, file system moves, multi-step deployments
- Guarantees: ACID properties (Atomicity, Consistency, Isolation, Durability)
Atomicity Patterns:
Two-Phase Commit (2PC):
- Phase 1 (Prepare): All participants prepare to commit and signal readiness
- Phase 2 (Commit/Abort): Coordinator tells all participants to commit or abort
- Use Case: Distributed transactions across multiple databases or services
- Failure Handling:
- Any participant fails Phase 1 → All participants abort
- Coordinator fails after Phase 1 → Timeout triggers abort
- Participant fails Phase 2 → Retry commit until success or manual intervention
Saga Pattern (Long-Running Transactions):
- Pattern: Break long transaction into series of local transactions with compensations
- Execution: Each local transaction followed by compensation definition
- Coordination: Choreography (event-driven) or Orchestration (central coordinator)
- Example:
Saga: Book Flight + Reserve Hotel + Rent Car
Step 1: Book Flight
- Success → Continue to Step 2
- Failure → Saga fails (nothing to compensate)
- Compensation: Cancel Flight Booking
Step 2: Reserve Hotel
- Success → Continue to Step 3
- Failure → Compensate Step 1 (Cancel Flight)
- Compensation: Cancel Hotel Reservation
Step 3: Rent Car
- Success → Saga completes
- Failure → Compensate Step 2 (Cancel Hotel), then Step 1 (Cancel Flight)
- Compensation: Cancel Car Rental
- Advantages: Works with long-running processes, handles distributed systems
- Trade-offs: Eventual consistency (not immediate), compensation must be designed carefully
Idempotent Operations:
- Definition: Operation that produces same result when executed multiple times
- Importance: Enables safe retries without side effects
- Design Guidelines:
- Use unique operation IDs to detect duplicates
- Check if operation already completed before executing
- Design operations to be naturally idempotent (e.g., SET vs INCREMENT)
- Examples:
- Idempotent:
SET user.status = "active" (can execute multiple times safely)
- NOT Idempotent:
INCREMENT user.login_count (multiple executions cause issues)
- Made Idempotent:
INCREMENT_ONCE(operation_id, user.login_count) (check operation_id first)
Integration with /sc:save Checkpoint System
Checkpoint Strategy for Workflows:
Pre-Operation Checkpoints:
- Before Risky Operations: Create restore point before dangerous changes
- Command:
/sc:save --type context --checkpoint
- Captures: Current file states, configuration, project context
- Use Case: Before major refactors, schema changes, deployments
- Rollback: Restore from checkpoint if operation fails
Mid-Operation Checkpoints:
- During Long-Running Operations: Periodic progress saves
- Trigger: Every 30 minutes (automatic) or after major milestones
- Captures: Completed steps, remaining work, intermediate state
- Use Case: Multi-hour operations, batch processing, large refactors
- Resume: Continue from last checkpoint if interrupted
Post-Operation Checkpoints:
- After Successful Completion: Capture successful end state
- Command:
/sc:save --type all --summarize
- Captures: Final state, learnings, decisions, next steps
- Use Case: Feature completion, milestone reached, phase done
- Value: Known-good state for future rollback point
Checkpoint Naming Convention:
session_YYYY-MM-DD_HHMMSS_[type]
- session_2025-11-12_143000_pre-refactor
- session_2025-11-12_150000_mid-refactor-checkpoint
- session_2025-11-12_153000_post-refactor-success
Rollback from Checkpoint:
1. Identify checkpoint to restore: `/sc:load` lists available checkpoints
2. Load checkpoint state: Serena MCP memory operations
3. Analyze differences: Compare current state vs checkpoint state
4. Restore files: Revert changed files to checkpoint versions
5. Validate: Verify restored state is consistent
6. Document: Record why rollback was necessary
Checkpoint Integration Examples:
Example 1: Risky Refactoring with Checkpoints
Workflow:
1. Current state: Authentication module working
2. Create checkpoint: /sc:save --type context --checkpoint
→ Checkpoint: session_2025-11-12_140000_pre-auth-refactor
3. Execute refactor: Restructure authentication module
4. Tests fail: New structure breaks existing integrations
5. Rollback decision: Restore from checkpoint
6. Load checkpoint: /sc:load session_2025-11-12_140000_pre-auth-refactor
7. Analyze failure: Study what went wrong before re-attempting
8. Revised approach: New refactoring strategy based on learnings
9. Create new checkpoint: /sc:save --checkpoint (before second attempt)
Example 2: Long-Running Migration with Progress Checkpoints
Workflow:
1. Start migration: 100 database tables to migrate
2. Checkpoint after every 10 tables:
- Table 10: /sc:save --checkpoint → session_...._table-10
- Table 20: /sc:save --checkpoint → session_...._table-20
- Table 30: /sc:save --checkpoint → session_...._table-30
3. Interruption at table 35: System failure or user cancellation
4. Resume from checkpoint: Load session_...._table-30
5. Restart from table 31: Skip already-completed tables 1-30
6. Continue migration: Tables 31-100 with continued checkpoints
7. Final checkpoint: /sc:save --type all --summarize (complete)
Best Practices for Workflow Compensation
✅ DO:
- Always checkpoint before risky operations
- Design compensating transactions for all critical operations
- Make operations idempotent whenever possible
- Test rollback procedures as thoroughly as forward operations
- Document compensation logic for each operation
- Use exponential backoff for transient failures
- Implement circuit breakers for external dependencies
- Track operation state for resume capability
❌ DON'T:
- Assume operations will always succeed (plan for failure)
- Forget to test rollback paths (untested rollbacks will fail when needed)
- Make operations that cannot be compensated (design for reversibility)
- Retry indefinitely without backoff (respect rate limits, prevent cascading failures)
- Delete data permanently without backup (always have recovery option)
