Introduction & Philosophy
Relevant source files
The following files were used as context for generating this wiki page:
SuperGemini is a meta-programming framework designed to transform the Gemini CLI from a general-purpose AI assistant into a structured, systematic software development platform. It operates through behavioral instruction injection, modifying AI behavior via configuration files rather than modifying the underlying Gemini Code. This approach enables automated expert coordination, quality gates, and session persistence within the native Gemini environment.
Sources: CLAUDE.md:6-10, CONTRIBUTING.md:1-5, Docs/Getting-Started/quick-start.md:67-75
The project's mission is to enable systematic software development workflows that leverage intelligent orchestration of domain-specific agents and Model Context Protocol (MCP) integrations. It prioritizes practical utility, educational value, and professional development standards, providing a supportive environment for developers to build complex systems with AI assistance.
Sources: CONTRIBUTING.md:7-10, Docs/Developer-Guide/README.md:129-132
Core Philosophy: Meta-Framework Architecture
The fundamental philosophy of SuperGemini is its "Meta-Framework" approach. Unlike traditional applications that execute logic directly, SuperGemini serves as a configuration distribution system. It injects structured instructions—stored in .md and .toml files—into the Gemini CLI to steer its behavior toward specific software engineering personas and workflows.
Instruction Injection Mechanism
SuperGemini manages a set of behavioral instructions that are installed to the user's ~/.gemini/ directory. When a user executes a slash command (e.g., /sg:analyze), the framework provides a pre-defined prompt to the Gemini CLI that includes constraints, available tools, and domain-specific rules.
Sources: CLAUDE.md:12-16, CLAUDE.md:104-122
Dual-Directory System
The project maintains a strict separation between the installation engine and the behavioral payload:
- installer (
setup/): Python code responsible for file management, validation, and configuration. - payload (
SuperGemini/): The actual behavioral instructions (Markdown/TOML) that define the framework's "intelligence."
Sources: CLAUDE.md:86-102
System Architecture Overview
SuperGemini is organized into a multi-layered orchestration pattern. This architecture allows the framework to process simple user requests through a complex pipeline of analysis, routing, and tool coordination.
The Orchestration Pipeline
When a command is issued, the system follows a 5-step technical workflow:
- Command Parser: Analyzes user intent and task complexity.
- Agent Router: Selects domain specialists (e.g., Security Engineer, Backend Architect).
- MCP Coordinator: Activates external tool servers via the Model Context Protocol.
- Session Manager: Tracks progress and maintains project context.
- Quality Gates: Validates output against framework standards.
Sources: Docs/Getting-Started/quick-start.md:37-45
The following diagram illustrates the high-level flow from user input to orchestrated execution:
Component Taxonomy
The framework's functionality is divided into four primary pillars, summarized in the table below:
| Component Type | Description | Examples |
|---|---|---|
| Slash Commands | 18 specialized commands for workflow automation. | /sg:analyze, /sg:implement, /sg:workflow |
| AI Agents | 13 domain experts that embody specific personas. | Security Engineer, Backend Architect, DevOps Architect |
| Behavioral Modes | 6 modes that adapt the framework to specific contexts. | Brainstorming, Introspection, Orchestration |
| MCP Servers | 6 integrations for external tool capabilities. | Context7, Sequential, Magic, Playwright, MorphLLM, Serena |
| Sources: Docs/Getting-Started/quick-start.md:27-33, CLAUDE.md:125-144 |
Agent Specialization (Persona Mode)
SuperGemini agents do not operate as separate processes. Instead, the framework uses "Persona Mode," where the Gemini CLI embodies a specific role based on the task context. Agents are triggered by keywords, file types, or explicit mentions (e.g., @agent-security-engineer).
Sources: CLAUDE.md:125-132, CLAUDE.md:146-152
Tooling and Protocol Integration
A key architectural feature is the integration of the Model Context Protocol (MCP). This allows the framework to connect to external servers for specialized tasks like browsing, database querying, or semantic code understanding.
Key MCP Server Functions
- Context7: Provides official library documentation and framework patterns.
- Sequential: Enables multi-step reasoning and deep analysis.
- Serena: Manages semantic code understanding and large codebase memory.
- Magic: Specializes in UI component generation and design systems.
Sources: Docs/Reference/README.md:127-140
Development and Contribution Principles
The project follows a "Security-First" and "Professional Standards" philosophy. All code contributions must pass quality gates, including comprehensive testing (>90% coverage) and security validation.
Sources: CONTRIBUTING.md:125-140, Docs/Developer-Guide/README.md:73-75
Command Casing Standards
To ensure consistency across documentation and the CLI, the framework enforces specific naming conventions:
- Product Name: Always "SuperGemini" (Capitalized).
- CLI Executable:
SuperGemini(Terminal commands). - Slash Commands:
/sg:prefix (Gemini CLI interior).
Sources: CLAUDE.md:18-24, CLAUDE.md:231-241
Conclusion
SuperGemini's philosophy centers on transforming a standard LLM interface into a professional workstation through structured, instruction-based orchestration. By combining persona-based agents with robust protocol integrations (MCP) and a meta-framework architecture, it provides a systematic approach to AI-assisted software engineering that prioritizes context preservation and quality assurance.
Sources: CONTRIBUTING.md:1-10, Docs/Getting-Started/quick-start.md:67-85