Core Principles & Rules
Relevant source files
The following files were used as context for generating this wiki page:
The Core Principles & Rules of the SuperGemini Framework define the operational philosophy and actionable constraints that govern the meta-programming framework. SuperGemini operates as an enhancement layer for Gemini CLI, utilizing behavioral instruction injection to modify AI behavior via configuration files (.md, .toml) rather than traditional code modifications. These principles ensure that all interactions within the framework remain evidence-based, efficient, and systematically organized.
At its heart, the framework prioritizes a "Task-First" approach: Understand → Plan → Execute → Validate. This cycle ensures that AI agents (such as the system-architect or security-engineer) operate within a strict hierarchy of safety and quality, maintaining high context retention across complex development sessions.
Sources: CLAUDE.md:6-10, SuperGemini/Core/PRINCIPLES.md:5-10, SuperGemini/Core/RULES.md:14-17
Operational Philosophy
The framework's philosophy is built on the core directive: Evidence > assumptions | Code > documentation | Efficiency > verbosity. This drives a non-linear, adaptive problem-solving mindset where the system must semantically understand user intent rather than just literal instruction.
Internal Processing & Transparency
SuperGemini emphasizes "Silent Analysis"—processing documents and code internally to avoid verbose output, while maintaining a "Heartbeat" of status updates every 30-60 seconds during long operations. This ensures the user is informed of progress without being overwhelmed by raw data.
The following diagram illustrates the internal processing flow:
This flow represents the internal processing philosophy where silent analysis is prioritized over verbose logging.
Sources: SuperGemini/Core/PRINCIPLES.md:4-22, SuperGemini/Core/PRINCIPLES.md:60-70
Software Engineering Principles
The framework adheres to standard industry principles to ensure maintainability:
- SOLID: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion.
- DRY/KISS/YAGNI: Abstract common functionality, prefer simplicity, and avoid speculative feature implementation.
- Quality Quadrants: Focus on Functional (correctness), Structural (maintainability), Performance (efficiency), and Security (protection).
Sources: SuperGemini/Core/PRINCIPLES.md:25-50
Actionable Rule System
SuperGemini implements a strict priority system for its rules to ensure safety and quality are never compromised.
Rule Priority Levels
| Priority | Category | Description |
|---|---|---|
| 🔴 CRITICAL | Safety & Security | Never compromise. Includes data safety and production breaks. |
| 🟡 IMPORTANT | Quality | Strong preference for maintainability and professionalism. |
| 🟢 RECOMMENDED | Best Practices | Optimization and style guidelines to be applied when practical. |
Sources: SuperGemini/Core/RULES.md:5-10
Workflow and Planning
The framework mandates a systematic workflow for all development tasks. Developers and agents must explicitly identify operations that can run concurrently to maximize performance.
This sequence ensures that planning explicitly includes a parallelization analysis before any tool calls are executed.
Sources: SuperGemini/Core/RULES.md:14-30, SuperGemini/Core/RULES.md:33-40
Implementation Standards
SuperGemini sets a high bar for "Implementation Completeness." It forbids the use of placeholder content or partial features.
Completeness Constraints
- No Partial Features: Implementations must reach a working state once started.
- No TODOs/Mocks: Core functionality must not contain TODO comments, fake data, or stub implementations.
- Professional Honesty: Prohibits "marketing language" (e.g., "blazingly fast"). All technical claims must be verifiable.
- Workspace Hygiene: Temporary scripts, logs, and artifacts must be deleted immediately after use.
Sources: SuperGemini/Core/RULES.md:45-55, SuperGemini/Core/RULES.md:85-95, SuperGemini/Core/RULES.md:110-120
Git & Tool Optimization
The framework enforces a non-destructive Git workflow and the use of the most powerful tools available via MCP (Model Context Protocol).
| Requirement | Rule |
|---|---|
| Git Status | Always check git status and git branch before starting work. |
| Branches | Use feature branches for all work; never work on main. |
| MCP Usage | Leverage specialized servers (e.g., morphllm for bulk edits, sequential-thinking for analysis). |
| Batching | Use MultiEdit over individual Edit calls for 3+ file changes. |
Sources: SuperGemini/Core/RULES.md:125-135, SuperGemini/Core/RULES.md:140-150, CLAUDE.md:165-175
Architectural Integration
Core Principles are injected into the environment during installation. The setup/ directory handles the logic of distributing these instructions to the user's local configuration.
Architectural relationship where .md principle files are treated as "payload" by the Python setup engine to modify Gemini CLI behavior.
Sources: CLAUDE.md:55-65, CLAUDE.md:100-110
Summary
The Core Principles & Rules of SuperGemini provide a rigorous framework for AI-assisted development. By prioritizing evidence over assumptions and enforcing strict workflow gates—from parallel planning to mandatory validation—the framework ensures that meta-programming remains safe, professional, and highly efficient. These rules are not merely guidelines but are actively injected into the system's behavioral engine to ensure consistent adherence across all agents and modes.
Sources: SuperGemini/Core/PRINCIPLES.md:1-5, SuperGemini/Core/RULES.md:200-210