DOCSEARCHbyAlgolia
Submit Docs

SuperGemini Framework

repository·main·Indexed 42 days ago

https://github.com/superclaude-org/supergemini_framework

A meta-programming configuration framework that transforms the Gemini CLI into a structured software development platform. It features 13 specialized AI personas, 18 slash commands for workflow automation, and integration with 6 Model Context Protocol (MCP) servers including context7, sequential, magic, playwright, morphllm, and serena. The framework uses instruction injection and behavioral programming via .md configuration files to enhance Gemini Code without modifying underlying source code.

Tokens
203.5K
Snippets
512
Records
681
Agent score
50%

What's inside SuperGemini

  1. Developer Documentation Roadmap

    main

    The SuperGemini technical documentation is divided into three primary interconnected guides, each serving a specific role in the development lifecycle:

    1. Contributing Code Guide (contributing-code.md)

      • Focus: Development workflows, coding standards, and component creation.
      • Best for: New contributors and framework maintainers.

    2. Technical Architecture Guide (technical-architecture.md)

      • Focus: Deep system design, agent coordination, MCP integration, and performance systems.
      • Best for: System architects and advanced developers.

    3. Testing & Debugging Guide (testing-debugging.md)

      • Focus: Test frameworks, performance testing, security validation, and troubleshooting techniques.
      • Best for: QA engineers and testing specialists.

  2. What is SuperGemini?

    main

    SuperGemini is a meta-programming configuration framework designed to enhance the Gemini CLI with structured development capabilities.

    Key features include:

    • 18 Slash Commands: TOML-based commands for workflow automation (e.g., /sg:analyze, /sg:implement).
    • Persona Mode: 13 specialized AI agents (such as system-architect or security-engineer) that the Gemini CLI embodies to perform specific roles.
    • SuperAgent MCP Support: Optional subagent orchestration via superagent:gemini for multi-agent workflows.
    • Behavioral Instructions: Core principles that ensure consistent development practices.
    • Workflow Automation: Systematic approaches to software analysis, implementation, and optimization.

    Mental Model: Unlike tools that spawn separate sub-agents, SuperGemini uses Persona Mode, where the Gemini CLI itself embodies the requested agent role.

  3. What is a SuperGemini session?

    main

    A session is a persistent development context that allows SuperGemini to remember your project, decisions, and progress across interruptions. Unlike standard Gemini conversations which start fresh each time, SuperGemini sessions build cumulative understanding.

    Core Concepts

    • Session: A persistent development context containing project understanding, work history, and current state.
    • Context: The accumulated knowledge about your project, including structure, patterns, and decisions.
    • Memory: Long-term storage of insights, patterns, and project knowledge that survives restarts.

    Comparison: Standard Gemini vs. SuperGemini Sessions

    FeatureStandard GeminiSuperGemini Sessions
    PersistenceStarts fresh each conversationRemembers previous work
    Project MemoryNo project memoryBuilds cumulative understanding
    ContextRequires re-explanationKnows your codebase and patterns
    ScopeSingle conversation scopeCross-session continuity

  4. Overview of available MCP Servers

    main

    Model Context Protocol (MCP) servers provide enhanced capabilities to the SuperGemini framework.

    Core MCP Servers

    • Context7: Official documentation lookup and framework patterns.
    • Sequential: Multi-step reasoning and complex analysis.
    • Magic: Modern UI component generation from 21st.dev patterns.
    • Playwright: Browser automation and E2E testing.
    • Morphllm: Pattern-based code editing with token optimization.
    • Serena: Semantic code understanding and project memory.

    System Requirements

    To run these servers, your environment must meet the following:

    • Node.js: version 16.0.0 or higher.
    • Package Manager: npm or yarn.
    • Memory: 2GB+ recommended.
    • Network: Stable connection (required for certain servers).

  5. What is the Morphllm MCP Server and when to use it

    main

    The Morphllm MCP Server is a pattern-based code editing engine designed for bulk transformations with high token optimization (achieving 30-50% efficiency gains).

    Use Morphllm when:

    • You need to perform multi-file edit operations requiring consistent patterns.
    • You are performing framework updates, style guide enforcement, or code cleanup.
    • You need bulk text replacements across multiple files.
    • You are providing natural language edit instructions with a specific scope.
    • You need token optimization for 'Fast Apply' scenarios.

    Do NOT use Morphllm for:

    • Semantic operations: It does not handle symbol renames, dependency tracking, or LSP integration. Use Serena for these tasks instead.
    • High complexity: It is best suited for simple to moderate complexity tasks involving fewer than 10 files with straightforward transformations.

  6. What is Task Management Mode?

    main

    Task Management Mode is a specialized operational mode designed for hierarchical task organization with persistent memory. It is intended for complex, multi-step operations that require coordination across multiple files, directories, or phases.

    When to use Task Management Mode

    • Complex Operations: Operations involving more than 3 steps that require coordination.
    • Broad Scope: Operations affecting more than 2 directories or more than 3 files.
    • Phased Dependencies: Projects with complex dependencies requiring distinct phases.
    • Quality Requests: Requests to 'polish', 'refine', or 'enhance' existing work.
    • Manual Activation: You can trigger this mode using the --task-manage or --orchestrate flags.

  7. Coordinate sessions within a team

    main

    SuperGemini supports collaborative workflows through shared contexts and individual developer sessions. Use the --shared flag to create a common understanding for a team, or the --developer flag to maintain personal development context within a shared project. Use --integration for cross-developer system-level work.

    # Shared Project Context
/sg:load --shared team-project/

# Individual Developer Sessions
/sg:load --developer alice team-project/user-auth/
/sg:load --developer bob team-project/payment-system/

# Integration Sessions
/sg:load --integration team-project/

  8. Maintain Backward Compatibility in SuperGemini

    main

    To ensure smooth upgrades for existing users, SuperGemini follows strict backward compatibility guidelines across APIs, components, and configurations.

    Compatibility Requirements

    • API Compatibility: Public APIs must maintain signature compatibility. Breaking changes are restricted to major version releases. Deprecated features must include a 2-version warning period.
    • Component Compatibility: Existing component installations must remain functional. New components must not break existing functionality. Agent coordination protocols and MCP server integrations must maintain interface stability through version negotiation.
    • Configuration Compatibility: Configuration file formats must support migration paths from older versions to newer ones.

    Testing Compatibility

    Use the following commands to validate compatibility:

    # Test compatibility with previous versions
python -m pytest tests/compatibility/ -v

# Test configuration migration
python scripts/test_migration.py --from-version 3.2 --to-version 4.0

# Validate deprecated features still work
python -m pytest tests/compatibility/test_deprecated.py -v

  9. What are MCP Servers and how do they work?

    main

    MCP (Model Context Protocol) servers are specialized tools that extend the Gemini CLI's capabilities. Instead of manual configuration, SuperGemini uses Automatic Activation logic to select the appropriate server based on the keywords or patterns in your request.

    Integrated MCP Servers

    • context7: Provides official library documentation and framework patterns.
    • sequential: Enables multi-step reasoning and hypothesis testing.
    • magic: Generates modern UI components (based on 21st.dev patterns).
    • playwright: Handles real browser automation and E2E testing.
    • morphllm: Performs efficient, pattern-based code transformations.
    • serena: Provides semantic code understanding and project memory.
    • superagent: Orchestrates specialized subagents for complex workflows.

  10. How SuperGemini selects MCP servers

    main

    SuperGemini uses an intelligent context-based selection process to activate servers automatically. When you issue a command, the framework parses keywords and matches them against a priority logic table.

    Server Activation Mapping

    Trigger Keywords / PatternsActivated Server
    import, require, API namescontext7
    --introspect, debuggingsequential
    agents, panel, multi-domainsuperagent
    component, UI, /ui, formmagic
    test, e2e, browser, playwrightplaywright
    Multi-file edits, refactormorphllm
    load, save, large projectsserena

    Selection Logic Behavior

    • Multiple Triggers: If a command triggers multiple servers, the higher priority server takes the lead while others provide assistance.
    • Missing Keys: If a required API key is missing, the server is skipped and the system falls back to native tools.
    • Manual Control: User-provided flags (e.g., --magic or --no-serena) always take precedence over automatic selection.

  11. Use the Sequential MCP Server for complex reasoning

    main

    The Sequential MCP Server is a multi-step reasoning engine designed for complex analysis and systematic problem-solving. It is intended for scenarios where a single-step response is insufficient due to the depth or interconnectedness of the problem.

    When to use Sequential MCP

    Use the Sequential engine instead of native reasoning when:

    • Complexity is high: Problems involve 3 or more interconnected components.
    • Systematic analysis is required: For root cause analysis, architecture reviews, or security assessments.
    • Structure is critical: When the problem benefits from decomposition and evidence gathering.
    • Issues are cross-domain: Problems spanning multiple layers like frontend, backend, database, and infrastructure.

    When NOT to use Sequential MCP

    Do not use Sequential for simple tasks such as:

    • Basic explanations.
    • Single-file changes.
    • Straightforward fixes (e.g., fixing a typo).

    Triggering Sequential Analysis

    You can trigger structured analysis using the --seq flag.

    # Example trigger via CLI flag
supergemini --seq [your_query]

  12. Manage resources using the Zone system

    main

    The framework adapts its behavior based on current resource usage levels:

    • 🟢 Green Zone (0-75%): Full capabilities available. Use all tools and features with normal verbosity.
    • 🟡 Yellow Zone (75-85%): Efficiency mode activated. Reduce verbosity and defer non-critical operations.
    • 🔴 Red Zone (85%+): Essential operations only. Use minimal output and employ a 'fail fast' strategy on complex requests.