Directory Structure

SuperGemini employs a dual-directory architecture designed to separate the installation logic from the configuration payloads. This "meta-programming framework" operates by injecting behavioral instructions into the Gemini CLI rather than modifying its core binary. The structure is bifurcated into the setup/ directory, which houses the Python-based installation engine, and the SuperGemini/ directory, which contains the Markdown and TOML configuration files that define AI behavior.

Sources: CLAUDE.md:7-14, CLAUDE.md:88-105

Core Architectural Layout

The project maintains a strict separation between the "installer" (Python code) and the "payload" (configuration files). This ensures that the framework can be updated or managed via standard terminal commands while the AI agents and slash commands reside in specialized behavioral instruction files.

High-Level Components

Sources: CLAUDE.md:92-105, Docs/Developer-Guide/README.md:15-32

The Dual Directory Pattern

The following diagram illustrates the relationship between the source directories and the target installation environment on the user's system.

The SuperGemini/ Directory (Payload)

The SuperGemini/ directory contains the behavioral definitions. These files are not executed as Python code; instead, they are converted and installed to the ~/.gemini/ directory where the Gemini CLI reads them to modify its own internal prompts and tool-calling logic.

Commands/

Contains the definitions for the 18 slash commands (e.g., /sg:analyze, /sg:implement). These are typically authored as Markdown files with front matter and converted to TOML during the installation process.
Sources: CLAUDE.md:107-128, SuperGemini/Commands/index.toml:1-10

Agents/

Contains instructions for 13 specialized AI specialists. These specialists (e.g., security-engineer, backend-architect) use "Persona Mode," where the AI embodies the role described in the Markdown instruction file.
Sources: CLAUDE.md:130-155

Core/

Houses the foundational behavioral files, including PRINCIPLES.md, RULES.md, and FLAGS.md. These files provide the high-level orchestration logic for the framework.
Sources: CLAUDE.md:182-188

Modes/ & MCP/

• Modes/: Defines behavioral modes like "brainstorming" or "introspection."
• MCP/: Configuration files for the 6 Model Context Protocol servers (e.g., context7, sequential, serena).
  Sources: CLAUDE.md:167-172, CLAUDE.md:218-228

The setup/ Directory (Installation Engine)

The setup/ directory contains the Python implementation of the SuperGemini management system. It follows an object-oriented component architecture where each installable entity (commands, agents, modes) is treated as a discrete class.

Component Logic Flow

Every component in setup/components/ inherits from a base abstract class to ensure consistent installation, validation, and uninstallation behavior.

Key Setup Subdirectories

• core/: Contains the main installer logic (installer.py) and base component definitions.
• components/: Discrete Python modules for core, commands, modes, and mcp.
• services/: Shared logic for file operations, settings, and MCP management.
• utils/: Cross-platform utilities for path resolution, logging, and security.
  Sources: CLAUDE.md:164-173, claudedocs/PHASE_1_COMPLETION_REPORT.md:55-65

Documentation and Research Structure

The framework includes a multi-layered documentation system and specialized internal tracking directories for automated tools like Claude Code.

Docs/ Structure

Documentation is organized by target audience and lifecycle stage:

• Getting-Started/: Quick start guides and installation instructions.
• User-Guide/: Detailed command, agent, and mode references.
• Developer-Guide/: Technical architecture, contributing guidelines, and testing procedures.
• Reference/: Troubleshooting guides and best practices.
  Sources: CONTRIBUTING.md:105-110, Docs/Developer-Guide/README.md:15-32

claudedocs/ (Workflow Tracking)

This directory is used for internal project tracking, particularly for standardizing command syntax and documentation consistency (CSI_WF). It contains completion reports and standardization rules.
Sources: claudedocs/CSI_WF.md:1-15, claudedocs/PHASE_1_COMPLETION_REPORT.md:1-20

Summary of File Relationships

The following entity-relationship diagram shows how different file types interact across the directory structure.

SuperGemini's directory structure is a deliberate implementation of a "Manager-Payload" design. By separating the execution logic in setup/ from the behavioral instructions in SuperGemini/, the framework achieves cross-platform portability and allows users to modify AI behavior simply by editing Markdown files, which are then re-synced by the Python installation engine.