Metadata-Version: 2.4
Name: SuperGemini
Version: 3.1.0
Summary: SuperGemini Framework Management Hub
Project-URL: Homepage, https://github.com/SuperGemini-Org/SuperGemini_Framework
Project-URL: Repository, https://github.com/SuperGemini-Org/SuperGemini_Framework
Project-URL: Bug Tracker, https://github.com/SuperGemini-Org/SuperGemini_Framework/issues
Project-URL: GitHub, https://github.com/SuperGemini-Org/SuperGemini_Framework
Project-URL: Mithun Gowda B, https://github.com/mithun50
Project-URL: NomenAK, https://github.com/NomenAK
Author-email: Mithun Gowda B <contact@supergemini.dev>, NomenAK <contact@supergemini.dev>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Requires-Dist: setuptools>=45.0.0
Description-Content-Type: text/markdown

# SuperGemini v3 🚀
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Version](https://img.shields.io/badge/version-3.1.0-blue.svg)](https://github.com/SuperGemini-Org/SuperGemini_Framework)
[![GitHub issues](https://img.shields.io/github/issues/SuperGemini-Org/SuperGemini_Framework)](https://github.com/SuperGemini-Org/SuperGemini_Framework/issues)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/SuperGemini-Org/SuperGemini_Framework/blob/master/CONTRIBUTING.md)
[![Contributors](https://img.shields.io/github/contributors/SuperGemini-Org/SuperGemini_Framework)](https://github.com/SuperGemini-Org/SuperGemini_Framework/graphs/contributors)

A framework that extends Gemini Code with specialized commands, personas, and MCP server integration.

**📢 Status**: Initial release, fresh out of beta! Bugs may occur as we continue improving things.

## What is SuperGemini? 🤔

SuperGemini tries to make Gemini Code more helpful for development work by adding:
- 🛠️ **16 specialized commands** for common dev tasks
- 🎭 **Smart personas** that usually pick the right expert for different domains 
- 🔧 **MCP server integration** for docs, UI components, and browser automation
- 📋 **Task management** that tries to keep track of progress
- ⚡ **Token optimization** to help with longer conversations

This is what we've been building to make development workflows smoother. Still rough around the edges, but getting better! 😊

## Current Status 📊

✅ **What's Working Well:**
- Installation suite (rewritten from the ground up)
- Core framework with 9 documentation files 
- 16 slash commands for various development tasks
- MCP server integration (Context7, Sequential, Magic, Playwright)
- Unified CLI installer for easy setup

⚠️ **Known Issues:**
- This is an initial release - bugs are expected
- Some features may not work perfectly yet
- Documentation is still being improved
- Hooks system was removed (coming back in v4)

## Key Features ✨

### Commands 🛠️
Essential commands for the most common tasks:

**Development**: `/sg:implement`, `/sg:build`, `/sg:design`  
**Analysis**: `/sg:analyze`, `/sg:troubleshoot`, `/sg:explain`  
**Quality**: `/sg:improve`, `/sg:test`, `/sg:cleanup`  
**Others**: `/sg:document`, `/sg:git`, `/sg:estimate`, `/sg:task`, `/sg:index`, `/sg:load`, `/sg:spawn`

### Smart Personas 🎭
AI specialists that try to jump in when they seem relevant:
- 🏗️ **architect** - Systems design and architecture stuff
- 🎨 **frontend** - UI/UX and accessibility  
- ⚙️ **backend** - APIs and infrastructure
- 🔍 **analyzer** - Debugging and figuring things out
- 🛡️ **security** - Security concerns and vulnerabilities
- ✍️ **scribe** - Documentation and writing
- *...and 5 more specialists*


### MCP Integration 🔧
External tools that connect when useful:
- **Context7** - Grabs official library docs and patterns 
- **Sequential** - Helps with complex multi-step thinking  
- **Magic** - Generates modern UI components 
- **Playwright** - Browser automation and testing stuff


## ⚠️ Upgrading from v2? Important!

If you're coming from SuperGemini v2, you'll need to clean up first:

1. **Uninstall v2** using its uninstaller if available
2. **Manual cleanup** - delete these if they exist:
   - `SuperGemini/`
   - `~/.gemini/shared/`
   - `~/.gemini/commands/` 
   - `~/.gemini/GEMINI.md`
4. **Then proceed** with v3 installation below

This is because v3 has a different structure and the old files can cause conflicts.

### 🔄 **Key Change for v2 Users**
**The `/build` command changed!** In v2, `/build` was used for feature implementation. In v3:
- `/sg:build` = compilation/packaging only 
- `/sg:implement` = feature implementation (NEW!)

**Migration**: Replace `v2 /build myFeature` with `v3 /sg:implement myFeature`

## Installation 📦

SuperGemini installation is a **two-step process**:
1. First install the Python package
2. Then run the installer to set up Gemini Code integration

### Step 1: Install the Package

**Option A: From Source (Currently Only Option)**
```bash
git clone https://github.com/SuperGemini-Org/SuperGemini_Framework.git
cd SuperGemini_Framework
uv sync
```

**Option B: From Source**
```bash
git clone https://github.com/SuperGemini-Org/SuperGemini_Framework.git
cd SuperGemini_Framework
uv sync
```
### 🔧 UV / UVX Setup Guide

SuperGemini v3 also supports installation via [`uv`](https://github.com/astral-sh/uv) (a faster, modern Python package manager) or `uvx` for cross-platform usage.

### 🌀 Install with `uv`

Make sure `uv` is installed:

```bash
curl -Ls https://astral.sh/uv/install.sh | sh
```

> Or follow instructions from: [https://github.com/astral-sh/uv](https://github.com/astral-sh/uv)

Once `uv` is available, you can install SuperGemini like this:

```bash
uv venv
source .venv/bin/activate
uv pip install SuperGemini
```

### ⚡ Install with `uvx` (Cross-platform CLI)

If you’re using `uvx`, just run:

```bash
uvx pip install SuperGemini
```

### ✅ Finish Installation

After installing, continue with the usual installer step:

```bash
python3 -m SuperGemini install
```

Or using bash-style CLI:

```bash
SuperGemini install
```

### 🧠 Note:

* `uv` provides better caching and performance.
* Compatible with Python 3.8+ and works smoothly with SuperGemini.

---
**Missing Python?** Install Python 3.7+ first:
```bash
# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install python3 python3-pip

# macOS  
brew install python3

# Windows
# Download from https://python.org/downloads/
```

### Step 2: Run the Installer

After installing the package, run the SuperGemini installer to configure Gemini Code (You can use any of the method):
### ⚠️ Important Note 
**After installing the SuperGemini.**
**You can use `SuperGemini commands`
, `python3 -m SuperGemini commands` or also `python3 SuperGemini commands`**
```bash
# Quick setup (recommended for most users)
python3 SuperGemini install

# Interactive selection (choose components)
python3 SuperGemini install --interactive

# Minimal install (just core framework)
python3 SuperGemini install --minimal

# Developer setup (everything included)
python3 SuperGemini install --profile developer

# See all available options
python3 SuperGemini install --help
```
### Or Python Modular Usage
```bash
# Quick setup (recommended for most users)
python3 -m SuperGemini install

# Interactive selection (choose components)
python3 -m SuperGemini install --interactive

# Minimal install (just core framework)
python3 -m SuperGemini install --minimal

# Developer setup (everything included)
python3 -m SuperGemini install --profile developer

# See all available options
python3 -m SuperGemini install --help
```
### Simple bash Command Usage 
```bash
# Quick setup (recommended for most users)
SuperGemini install

# Interactive selection (choose components)
SuperGemini install --interactive

# Minimal install (just core framework)
SuperGemini install --minimal

# Developer setup (everything included)
SuperGemini install --profile developer

# See all available options
SuperGemini install --help
```

**That's it! 🎉** The installer handles everything: framework files, MCP servers, and Gemini Code configuration.

## How It Works 🔄

SuperGemini tries to enhance Gemini Code through:

1. **Framework Files** - Documentation installed to `~/.gemini/` that guides how Gemini responds
2. **Slash Commands** - 16 specialized commands for different dev tasks  
3. **MCP Servers** - External services that add extra capabilities (when they work!)
4. **Smart Routing** - Attempts to pick the right tools and experts based on what you're doing

Most of the time it plays nicely with Gemini Code's existing stuff. 🤝

## What's Coming in v4 🔮

We're hoping to work on these things for the next version:
- **Hooks System** - Event-driven stuff (removed from v3, trying to redesign it properly)
- **MCP Suite** - More external tool integrations  
- **Better Performance** - Trying to make things faster and less buggy
- **More Personas** - Maybe a few more domain specialists
- **Cross-CLI Support** - Might work with other AI coding assistants

*(No promises on timeline though - we're still figuring v3 out! 😅)*

## Configuration ⚙️

After installation, you can customize SuperGemini by editing:
- `~/.gemini/settings.json` - Main configuration
- `~/.gemini/*.md` - Framework behavior files

Most users probably won't need to change anything - it usually works okay out of the box. 🎛️

## Documentation 📖

Want to learn more? Check out our guides:

- 📚 [**User Guide**](https://github.com/SuperGemini-Org/SuperGemini_Framework/blob/master/Docs/supergemini-user-guide.md) - Complete overview and getting started
- 🛠️ [**Commands Guide**](https://github.com/SuperGemini-Org/SuperGemini_Framework/blob/master/Docs/commands-guide.md) - All 16 slash commands explained  
- 🏳️ [**Flags Guide**](https://github.com/SuperGemini-Org/SuperGemini_Framework/blob/master/Docs/flags-guide.md) - Command flags and options
- 🎭 [**Personas Guide**](https://github.com/SuperGemini-Org/SuperGemini_Framework/blob/master/Docs/personas-guide.md) - Understanding the persona system
- 📦 [**Installation Guide**](https://github.com/SuperGemini-Org/SuperGemini_Framework/blob/master/Docs/installation-guide.md) - Detailed installation instructions

These guides have more details than this README and are kept up to date.

## Contributing 🤝

We welcome contributions! Areas where we could use help:
- 🐛 **Bug Reports** - Let us know what's broken
- 📝 **Documentation** - Help us explain things better  
- 🧪 **Testing** - More test coverage for different setups
- 💡 **Ideas** - Suggestions for new features or improvements

The codebase is pretty straightforward Python + documentation files.

## Project Structure 📁

```
SuperGemini/
├── setup.py               # pypi setup file
├── SuperGemini/           # Framework files  
│   ├── Core/              # Behavior documentation (COMMANDS.md, FLAGS.md, etc.)
│   ├── Commands/          # 16 slash command definitions
│   └── Settings/          # Configuration files
├── setup/                 # Installation system
└── profiles/              # Installation profiles (quick, minimal, developer)
```

## Architecture Notes 🏗️

The v3 architecture focuses on:
- **Simplicity** - Removed complexity that wasn't adding value
- **Reliability** - Better installation and fewer breaking changes  
- **Modularity** - Pick only the components you want
- **Performance** - Faster operations with smarter caching

We learned a lot from v2 and tried to address the main pain points.

## FAQ 🙋

**Q: Why was the hooks system removed?**  
A: It was getting complex and buggy. We're redesigning it properly for v4.

**Q: Does this work with other AI assistants?**  
A: Currently Gemini Code only, but v4 will have broader compatibility.

**Q: Is this stable enough for daily use?**  
A: The basic stuff works pretty well, but definitely expect some rough edges since it's a fresh release. Probably fine for experimenting! 🧪

## Author

Created by hyunjaelim - Inspired by the SuperClaude Framework architecture

## Acknowledgments

This project is inspired by and based on the **SuperClaude Framework** architecture developed by the SuperClaude Framework Contributors.

- **Original Project**: [SuperClaude Framework](https://github.com/SuperClaude-Org/SuperClaude_Framework)
- **Original License**: MIT License
- **Our Implementation**: SuperGemini is an independent implementation that adapts the SuperClaude architecture for Gemini CLI compatibility

We express our gratitude to the original SuperClaude team for their innovative framework design and for releasing it under the MIT License, which enables projects like SuperGemini to exist.

**Note**: SuperGemini is not affiliated with or endorsed by the original SuperClaude project. It is a separate, independent implementation created specifically for Gemini CLI users.

## License

MIT - [See LICENSE file for details](https://opensource.org/licenses/MIT)

Inspired by SuperClaude Framework architecture

## Star History

<a href="https://www.star-history.com/#SuperGemini-Org/SuperGemini_Framework&Date">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=SuperGemini-Org/SuperGemini_Framework&type=Date&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=SuperGemini-Org/SuperGemini_Framework&type=Date" />
   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=SuperGemini-Org/SuperGemini_Framework&type=Date" />
 </picture>
</a>
---

*Built by developers who got tired of generic responses. Hope you find it useful! 🙂*

---
