SuperQwen Framework

https://github.com/superclaude-org/superqwen_framework
Admin
SuperQwen is an AI-enhanced development framework designed to supercharge your command-line workflow...
Tokens:20,998
Snippets:137
Trust Score:7.5
License:MIT
Update:11 months ago
Show doc for...
Tokens:
Raw
### Install SuperQwen Package

Source: https://context7.com/superclaude-org/superqwen_framework/llms.txt

Installs the SuperQwen framework package using pip and initiates an interactive setup process to configure components. The installer guides the user through selecting core components, MCP configuration, or all available options.

```bash
# Install the package
pip install SuperQwen

# Run interactive installer
superqwen install

# The installer presents a menu:
# ============================================================
#                     SuperQwen Installer
#                      Interactive Setup
# ============================================================
#
# Installation Options
# ====================
# 1. Core Components (Commands, Modes, Agents)
# 2. MCP Config (for advanced users)
# 3. All of the above
#
# Enter your choice (1-3):
# > 3
```

--------------------------------

### User Installation Commands (Bash)

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Instructions for users to install the SuperGemini package from PyPI. It covers production installation, installation of the development version from GitHub, and installation of a specific version.

```bash
# Production installation
pip install SuperGemini

# Development version
pip install git+https://github.com/SuperGemini-Org/SuperGemini_Framework.git

# Specific version
pip install SuperGemini==4.0.0
```

--------------------------------

### Python Virtual Environment Setup (Bash)

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Commands to set up a Python virtual environment for development. This includes checking the Python version, creating a virtual environment, activating it, and installing development dependencies.

```bash
# Python 3.8+ required
python3 --version

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
# For Windows: venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"
```

--------------------------------

### Launch SuperQwen Interactive Installer

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/README.md

After installing the SuperQwen framework, this command launches an interactive installer. The installer guides the user through selecting and setting up core components like commands, modes, and agents, ensuring a tailored environment.

```bash
superqwen install
```

--------------------------------

### Run Package Installation Test Script

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Executes a script to test the installation of the package in a clean environment. This script verifies fresh virtual environment installation, entry point functionality, core component functionality, and dependency resolution.

```bash
# Test package installation in clean environment
python scripts/test_installation.py

# Tests:
# - Fresh virtual environment installation
# - Entry point functionality
# - Core component functionality
# - Dependency resolution
```

--------------------------------

### Handle Interactive Installation with Menu Selection (Python)

Source: https://context7.com/superclaude-org/superqwen_framework/llms.txt

Guides users through component selection using a menu-driven interface for installing SuperQwen components. It handles core components, MCP config, or both, and provides progress feedback during installation. Dependencies include SuperQwen's UI and installer modules.

```python
# From interactive.py:8-51
from SuperQwen.setup import ui
from SuperQwen.setup.installer import INSTALL_MAP

def handle_interactive_install():
    """Interactive installation with menu selection"""
    ui.display_header("SuperQwen Installer", "Interactive Setup")

    menu_options = [
        "Core Components (Commands, Modes, Agents)",
        "MCP Config (for advanced users)",
        "All of the above"
    ]

    install_menu = ui.Menu("Installation Options", menu_options)
    choice = install_menu.display()

    if choice == -1:
        ui.display_warning("Installation cancelled.")
        return

    tasks_to_run = []
    if choice == 0:
        tasks_to_run.extend(['commands', 'modes', 'agents'])
    elif choice == 1:
        tasks_to_run.append('mcp')
    elif choice == 2:
        tasks_to_run.extend(['commands', 'modes', 'agents', 'mcp'])

    if ui.confirm("Ready to install the selected components?"):
        ui.display_info("Starting installation...")
        total_tasks = len(tasks_to_run)

        for i, component in enumerate(tasks_to_run, 1):
            ui.display_step(i, total_tasks, f"Installing {component}...")
            progress_bar = ui.ProgressBar(1, prefix=f"{component.capitalize()}: ")
            INSTALL_MAP[component](progress_bar=progress_bar)
            progress_bar.finish()

        ui.display_success("\n✅ Interactive installation complete!")

# Usage from command line:
# $ superqwen install
# User selects option 3 (All)
# Confirms with 'y'
# All components install with progress bars

```

--------------------------------

### Example: Session 1 - Start Authentication Task

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/SuperQwen/Modes/MODE_Task_Management.md

A practical example of starting a new task, specifically the 'Authentication Task'. It shows initial memory state, setting the plan, defining phases, creating tasks, and updating task completion.

```pseudocode
list_memories() → Empty
write_memory("plan_auth", "Implement JWT authentication system")
write_memory("phase_1", "Analysis - security requirements review")
write_memory("task_1.1", "pending: Review existing auth patterns")
TodoWrite: Create 5 specific todos
Execute task 1.1 → write_memory("task_1.1", "completed: Found 3 patterns")
```

--------------------------------

### TestPyPI Upload and Installation

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Bash commands for uploading the package to TestPyPI, installing it from TestPyPI, and performing functional tests.

```bash
# 1. Upload to TestPyPI
twine upload --repository testpypi dist/*

# 2. Test installation from TestPyPI
pip install --index-url https://test.pypi.org/simple/ SuperGemini

# 3. Functional testing
SuperGemini install --list-components
SuperGemini --help

# 4. Clean up test environment
pip uninstall SuperGemini
```

--------------------------------

### Install SuperQwen Framework using Pip

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/README.md

This command installs the SuperQwen framework from the Python Package Index (PyPI) using pip. Ensure you have Python and pip installed on your system. This is the initial step before running the interactive setup.

```bash
pip install SuperQwen
```

--------------------------------

### Cross-Platform Testing with Docker

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

A bash script demonstrating how to test the package within a Docker container for Linux environments, simulating installation and version checking.

```bash
# Docker-based testing for Linux environments
docker run -v $(pwd):/app python:3.9 /bin/bash -c "
  cd /app && 
  pip install dist/SuperGemini-*.whl && 
  SuperGemini --version
"
```

--------------------------------

### Troubleshooting Installation Failures: Command Not Found

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Offers solutions for 'Command 'SuperGemini' not found' errors, suggesting checks of the system's PATH and package entry points.

```bash
# Issue: "Command 'SuperGemini' not found"
# Solution: Check PATH and entry points
pip show -f SuperGemini | grep console_scripts
which SuperGemini
```

--------------------------------

### SuperQwen Installer Preview (Bash)

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/README.md

This is a simulated output of the SuperQwen interactive installer. It demonstrates the process of selecting installation options (Core Components, MCP Config, or All) and shows the progress of installing commands, modes, agents, and MCP.

```bash
superqwen install

============================================================
                    SuperQwen Installer
                     Interactive Setup
NomenAK <anton.knoery@gmail.com> | Mithun Gowda B <mithungowda.b7411@gmail.com>
============================================================


Installation Options
====================
1. Core Components (Commands, Modes, Agents)
2. MCP Config (for advanced users)
3. All of the above

Enter your choice (1-3):
> 3
Ready to install the selected components? [Y/n]
> y
[INFO] Starting installation...
[1/4] Installing commands...
Commands: [██████████████████████████████████████████████████] 100.0% Complete
[2/4] Installing modes...
Modes:    [██████████████████████████████████████████████████] 100.0% Complete
[3/4] Installing agents...
Agents:   [██████████████████████████████████████████████████] 100.0% Complete
[4/4] Installing mcp...
Mcp:      [██████████████████████████████████████████████████] 100.0% Complete

✅ Interactive installation complete!
```

--------------------------------

### Troubleshooting Build Failures: Setuptools

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Addresses the 'No module named 'setuptools'' build error by providing a command to upgrade setuptools and wheel.

```bash
# Issue: "No module named 'setuptools'"
# Solution: Update setuptools
pip install --upgrade setuptools wheel
```

--------------------------------

### Local Package Verification and Build (Bash)

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Commands for verifying the package structure, building the package locally, checking its contents, and performing a local installation test. These steps ensure the package is correctly prepared before publishing.

```bash
# Verify package structure
python scripts/validate_pypi_ready.py

# Build package locally
python -m build

# Verify package contents
twine check dist/*

# Local installation test
pip install dist/SuperGemini-*.whl
```

--------------------------------

### Verify PyPI Publication and Installation

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

This bash snippet provides commands to verify a successful PyPI publication and test the installation of a package. It uses `curl` and `jq` to check the latest version on PyPI and `pip` to install and verify the package version.

```bash
# 1. Verify PyPI publication
curl -s https://pypi.org/pypi/SuperGemini/json | jq '.info.version'

# 2. Test installation from PyPI
pip install SuperGemini==4.0.1
SuperGemini --version

# 3. Verify entry points functional
SuperGemini install --list-components
```

--------------------------------

### Troubleshooting Installation Failures: No Distribution Found

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Addresses 'No matching distribution found' errors by advising users to check Python version compatibility, as SuperGemini requires Python 3.8+.

```bash
# Issue: "No matching distribution found"
# Solution: Check Python version compatibility
python --version  # Must be 3.8+
```

--------------------------------

### Required Python Tools Installation (Bash)

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

List of Python packages required for publishing and development. Includes core publishing tools (build, twine, wheel), development and testing tools (pytest, black), and security scanning tools (safety, bandit).

```bash
# Core publishing tools
pip install build twine wheel

# Development and testing tools
pip install pytest pytest-cov black flake8 mypy

# Security scanning
pip install safety bandit
```

--------------------------------

### Install All Components Non-Interactively

Source: https://context7.com/superclaude-org/superqwen_framework/llms.txt

Installs all SuperQwen framework components simultaneously without requiring user interaction. Provides progress indicators for each component installation phase.

```bash
# Install all components at once
superqwen install all

# Expected output:
# [INFO] Starting installation...
# [1/4] Installing commands...
# Commands: [██████████████████] 100.0% Complete
# [2/4] Installing modes...
# Modes:    [██████████████████] 100.0% Complete
# [3/4] Installing agents...
# Agents:   [██████████████████] 100.0% Complete
# [4/4] Installing mcp...
# Mcp:      [██████████████████] 100.0% Complete
# ✅ All components installed successfully!
```

--------------------------------

### Contributor Testing Workflow (Bash)

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Commands for contributors to test the SuperGemini package locally and validate its readiness for PyPI. Includes installing in development mode, running tests, validating the package, and preparing for TestPyPI uploads.

```bash
# 1. Local development testing
pip install -e ".[dev]"
python -m pytest tests/

# 2. Package validation
python scripts/validate_pypi_ready.py

# 3. TestPyPI testing (maintainers only)
python -m build
twine upload --repository testpypi dist/*
```

--------------------------------

### Package Structure: Source Distribution

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Details the contents of the SuperGemini source distribution archive (.tar.gz), including the main package directory, setup scripts, and metadata files.

```tree
SuperGemini-4.0.0.tar.gz
├── superclaude/
│   ├── __init__.py                 # Version and package metadata
│   ├── cli.py                      # Main CLI entry point
│   ├── core/
│   │   ├── __init__.py
│   │   ├── agent_manager.py        # Agent coordination logic
│   │   ├── command_parser.py       # Command parsing and routing
│   │   └── session_manager.py      # Session persistence
│   ├── setup/
│   │   ├── __init__.py
│   │   ├── installer.py            # Component installation
│   │   ├── components/             # Component definitions
│   │   └── validators.py           # Installation validation
│   └── utils/
│       ├── __init__.py
│       ├── file_utils.py           # File system utilities
│       └── logging_utils.py        # Logging configuration
├── setup.py                        # Package setup configuration
├── pyproject.toml                  # Modern packaging configuration
├── README.md                       # PyPI package description
├── LICENSE                         # MIT license text
├── CHANGELOG.md                    # Version history
├── requirements.txt                # Runtime dependencies
└── PKG-INFO                        # Package metadata
```

--------------------------------

### Python Package Entry Points

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Defines command-line script entry points for the SuperGemini package. These allow the package to be executed directly from the command line after installation, providing access to its functionality.

```python
[console_scripts]
SuperGemini = superclaude.cli:main
superclaude = superclaude.cli:main  # Alternative entry point
```

--------------------------------

### Integration Testing with Gemini Code

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Bash commands to perform integration testing by installing components and verifying slash commands in conjunction with a Gemini Code environment.

```bash
# Test with real Gemini Code environment
gemini --version
SuperGemini install --components core
# Verify slash commands work: SuperGemini help
```

--------------------------------

### Install Specific SuperQwen Component

Source: https://context7.com/superclaude-org/superqwen_framework/llms.txt

Allows for the installation of individual SuperQwen framework components, such as commands, modes, agents, or MCP configuration. Specifies the target directory for installed files.

```bash
# Install commands only
superqwen install commands

# Install modes only
superqwen install modes

# Install agents only
superqwen install agents

# Install MCP configuration only
superqwen install mcp

# Each command installs files to ~/.qwen/ directory
# - Commands go to: ~/.qwen/commands/sq/*.toml
# - Modes go to: ~/.qwen/modes/*.md
# - Agents go to: ~/.qwen/agents/*.md
# - MCP config creates: ~/.qwen/settings.json
```

--------------------------------

### Troubleshooting Build Failures: Visual C++

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Provides solutions for the 'error: Microsoft Visual C++ 14.0 is required' build error, suggesting installation of Visual Studio Build Tools or using wheel distributions on Windows.

```bash
# Issue: "error: Microsoft Visual C++ 14.0 is required"
# Solution: Install Visual Studio Build Tools (Windows)
# Or use wheel distribution instead of source
```

--------------------------------

### Local Package Build and Validation

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

A bash script outlining the steps to clean the build environment, build the package, and validate its contents and local installation.

```bash
# 1. Clean environment setup
rm -rf build/ dist/ *.egg-info/
python -m venv test_env
source test_env/bin/activate

# 2. Build package
python -m build

# 3. Validate package contents
twine check dist/*
tar -tzf dist/SuperGemini-*.tar.gz | head -20

# 4. Local installation test
pip install dist/SuperGemini-*.whl
SuperGemini --version
SuperGemini install --dry-run
```

--------------------------------

### Troubleshooting Build Failures: Permissions

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Offers a solution for 'Permission denied' errors during the build process by adjusting file permissions for build and distribution directories.

```bash
# Issue: "Permission denied" during build
# Solution: Check file permissions and virtual environment
chmod -R u+w build/ dist/
```

--------------------------------

### Package Structure: Wheel Distribution

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Describes the contents of the SuperGemini wheel distribution archive (.whl), which is a pre-compiled package format for easier installation.

```tree
SuperGemini-4.0.0-py3-none-any.whl
├── superclaude/                    # Compiled package code
├── SuperGemini-4.0.0.dist-info/   # Package metadata
│   ├── METADATA                    # Package description and requirements
│   ├── WHEEL                       # Wheel format metadata
│   ├── entry_points.txt            # CLI entry points
│   └── LICENSE                     # License information
```

--------------------------------

### Run Package Build Script

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Executes a script to perform a clean build process for the Python package. This script generates wheel and source distributions, validates package contents, and tests local installation.

```bash
# Clean build process with validation
python scripts/build_package.py

# Features:
# - Clean previous builds
# - Generate wheel and source distributions
# - Validate package contents
# - Test installation locally
```

--------------------------------

### Manual Python Package Build and Upload

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Provides manual commands for building the Python package using the 'build' tool and uploading it to PyPI or TestPyPI using 'twine'. Includes a command for cleaning build artifacts.

```bash
# Build package manually
python -m build

# Upload to TestPyPI
twine upload --repository testpypi dist/*

# Upload to PyPI (production)
twine upload dist/*

# Clean build artifacts
rm -rf build/ dist/ *.egg-info/
```

--------------------------------

### Install Core Components

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/CONTRIBUTING.md

This command installs the core components of the SuperGemini framework. It is often a necessary first step before executing other commands or workflows.

```bash
SuperGemini install --components core
```

--------------------------------

### SuperQwen CLI Core Commands

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/README.md

This table outlines the primary commands available through the `superqwen` command-line interface. These commands manage the framework's installation, uninstallation, updates, and provide help information.

```bash
superqwen install
supterqwen install all
supterqwen install [component]
supterqwen uninstall
supterqwen uninstall all
supterqwen uninstall [component]
supterqwen update
supterqwen --help
```

--------------------------------

### Entry Points Configuration for CLI

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Defines the console script entry points for the SuperGemini package, mapping command names to specific functions within the package.

```ini
[console_scripts]
SuperGemini = superclaude.cli:main
superclaude = superclaude.cli:main
```

--------------------------------

### GitHub Actions PyPI API Token Configuration (Bash)

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Instructions for setting up the PyPI API token for GitHub Actions. It details how to generate the token with SuperGemini package scope and add it to GitHub repository secrets.

```bash
# Generate PyPI API token with SuperGemini package scope
# Add to GitHub repository secrets as PYPI_API_TOKEN
# Token format: pypi-AgEIcHl... (scoped to SuperGemini package)
```

--------------------------------

### Updating Project Versions Across Files

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Commands for updating version numbers in critical project files before a release. This ensures consistency across the codebase, including the main package file, setup configuration, and changelog.

```bash
# Update version in multiple files:
# - superclaude/__init__.py
# - setup.py
# - pyproject.toml
# - CHANGELOG.md

# Validate version consistency
python scripts/validate_pypi_ready.py

```

--------------------------------

### Troubleshooting Upload Failures: File Exists

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Provides guidance for 'File already exists' upload errors, recommending cleaning the distribution directory and rebuilding the package.

```bash
# Issue: "File already exists"
# Solution: Clean dist/ directory and rebuild
rm -rf dist/ && python -m build
```

--------------------------------

### Brainstorming Mode Examples

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/SuperQwen/Modes/MODE_Brainstorming.md

Illustrates how standard project requests are transformed into interactive brainstorming dialogues within the Superqwen Framework. These examples show the shift from a simple statement to a series of probing questions and a clear outcome statement.

```text
Standard: "I want to build a web app"
Brainstorming: "🤔 Discovery Questions:
               - What problem does this solve for users?
               - Who are your target users and their main workflows?
               - What's your expected user volume and performance needs?
               - Any existing systems to integrate with?
               📝 Brief: [Generate structured requirements document]"

Standard: "Maybe we could improve the authentication system"
Brainstorming: "🔍 Let's explore this together:
               - What specific auth challenges are users facing?
               - Current vs desired user experience?
               - Security requirements and compliance needs?
               - Timeline and resource constraints?
               ✅ Outcome: Clear improvement roadmap"
```

--------------------------------

### Troubleshooting Upload Failures: Forbidden

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Explains how to resolve '403 Forbidden' errors during package upload by verifying API tokens and package permissions on PyPI.

```bash
# Issue: "403 Forbidden" during upload
# Solution: Verify API token and package permissions
twine upload --username __token__ --password pypi-... dist/*
```

--------------------------------

### Creating and Pushing Git Tags for Releases

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Demonstrates the process of creating an annotated Git tag for a new release and pushing it to the remote repository. This action typically triggers automated CI/CD pipelines for publishing.

```bash
# Create and push git tag
git tag -a v4.0.1 -m "Release v4.0.1: Bug fixes and stability improvements"
git push origin v4.0.1

```

--------------------------------

### Pre-Release Version Validation Checklist

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

A checklist of commands and steps to validate a pre-release version before final publishing. It includes consistency checks across files, changelog verification, dependency validation using pip-compile and safety check.

```bash
# 1. Version consistency check
python scripts/validate_pypi_ready.py

# 2. Verify version in all files matches
grep -r "4\.0\.0" superclaude/ setup.py pyproject.toml

# 3. Changelog validation
# Ensure CHANGELOG.md includes version with release date and changes

# 4. Dependency validation
pip-compile requirements.in
safety check

```

--------------------------------

### Configure Git for GPG Signing

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Sets up Git to automatically sign commits and tags using GPG, recommended for release integrity. This ensures that all contributions and releases can be cryptographically verified.

```bash
git config commit.gpgsign true
git config tag.gpgsign true
```

--------------------------------

### Git Configuration for Release Tagging (Bash)

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Commands to configure Git user name and email, which are necessary for creating release tags and commits. This ensures proper attribution for version control operations.

```bash
# Configure for release tagging
git config user.name "Your Name"
git config user.email "your.email@example.com"
```

--------------------------------

### Troubleshooting GitHub Actions: Token Not Found

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Explains how to resolve 'PYPI_API_TOKEN not found' errors in GitHub Actions by configuring repository secrets.

```bash
# Issue: "PYPI_API_TOKEN not found"
# Solution: Configure repository secrets
# GitHub Settings → Secrets → Add PYPI_API_TOKEN
```

--------------------------------

### Manual Production Publishing Workflow

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

This bash script details the manual process for publishing a package to PyPI, intended for emergency use. It includes validating the package readiness, building the package, uploading it to PyPI using Twine, and manually creating a GitHub release.

```bash
# 1. Validate and build
python scripts/validate_pypi_ready.py
python -m build

# 2. Upload to PyPI
twine upload dist/*

# 3. Create GitHub release manually
gh release create v4.0.1 --title "v4.0.1" --notes-file CHANGELOG.md
```

--------------------------------

### Check SuperGemini Version

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/CONTRIBUTING.md

This command retrieves the installed version of the SuperGemini framework. It is a prerequisite for reporting issues and ensuring compatibility.

```bash
SuperGemini --version
```

--------------------------------

### Maintainer Production Publishing Workflow (Bash)

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Steps for maintainers to prepare and initiate a production release of the SuperGemini package. This involves validating readiness, creating a Git tag, and pushing it to trigger the automated GitHub Actions workflow for building, testing, and publishing to PyPI.

```bash
# 1. Prepare release
python scripts/validate_pypi_ready.py
git tag v4.0.1
git push origin v4.0.1

# 2. GitHub Actions handles the rest automatically
# - Builds package
# - Tests on multiple platforms
# - Publishes to PyPI
# - Creates GitHub release
```

--------------------------------

### Git Tagging Workflow for Releases

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Detailed steps for creating and pushing a Git tag for a software release. It emphasizes ensuring a clean working directory, creating an annotated tag with a descriptive message including release notes, and pushing the tag to trigger automated deployments.

```bash
# 1. Ensure clean working directory
git status
git pull origin main

# 2. Create annotated tag with release notes
git tag -a v4.0.1 -m "Release v4.0.1

Bug Fixes:
- Fixed MCP server connection timeout
- Resolved agent coordination race condition

Improvements:
- Enhanced error messaging for command validation
- Updated documentation for best practices"

# 3. Push tag to trigger release
git push origin v4.0.1

```

--------------------------------

### Install Commands Component (Python)

Source: https://context7.com/superclaude-org/superqwen_framework/llms.txt

Copies command TOML files to the Qwen CLI commands directory. It identifies TOML files within the 'commands' package and copies them to the user's configuration directory. Requires `shutil` and `importlib.resources`.

```python
# From installer.py:11-28
import shutil
import importlib.resources
from pathlib import Path
from SuperQwen.setup.file_utils import QWEN_DIR, get_package_files
from SuperQwen.setup.ui import ProgressBar

def install_commands(progress_bar=None):
    """Install slash commands to ~/.qwen/commands/sq/"""
    commands_dst = QWEN_DIR / "commands" / "sq"
    commands_dst.mkdir(parents=True, exist_ok=True)

    files = get_package_files("commands")
    files_to_copy = [f for f in files if f.name.endswith('.toml')]

    if progress_bar:
        progress_bar.total = len(files_to_copy)

    for i, file in enumerate(files_to_copy):
        with importlib.resources.as_file(file) as src_path:
            shutil.copy2(src_path, commands_dst)
        if progress_bar:
            progress_bar.update(i + 1)

# Result: Installs files like:
# ~/.qwen/commands/sq/analyze.toml
# ~/.qwen/commands/sq/implement.toml
# ~/.qwen/commands/sq/test.toml
# Each containing command prompts and descriptions

```

--------------------------------

### Local Publishing .pypirc Configuration (INI)

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Configuration for the .pypirc file used for local publishing to PyPI and TestPyPI. It includes settings for the distribution index servers, username, and password (API token).

```ini
[distutils]
index-servers = pypi testpypi

[pypi]
username = __token__
password = pypi-AgEIcHl...

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-AgEIcHl...
```

--------------------------------

### Automated Production Publishing with GitHub Actions

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

This bash script outlines the steps for an automated production release using GitHub Actions. It involves creating an annotated Git tag, pushing it to the origin, which then triggers the GitHub Actions workflow. The workflow automatically runs tests, validates the package, publishes to PyPI, and creates a GitHub release.

```bash
# Create release tag
git tag -a v4.0.1 -m "Release v4.0.1: Bug fixes and improvements"
git push origin v4.0.1

# GitHub Actions automatically:
# 1. Runs full test suite
# 2. Validates package integrity  
# 3. Publishes to PyPI
# 4. Creates GitHub release
```

--------------------------------

### Verifying Git Tag Creation and Signature

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Commands to verify that a Git tag has been successfully created and pushed, and to check its signature if GPG signing is enabled. This is a crucial step in validating the integrity of the release process.

```bash
# Verify tag creation
git tag -l "v4.0.*"
git show v4.0.1

# Verify tag signature (if GPG signing enabled)
git tag -v v4.0.1

```

--------------------------------

### Check Python Version

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/CONTRIBUTING.md

This command shows the installed Python version. Accurate Python version information is crucial for diagnosing environment-specific issues and ensuring correct dependencies.

```bash
python3 --version
```

--------------------------------

### Install MCP Configuration (Python)

Source: https://context7.com/superclaude-org/superqwen_framework/llms.txt

Detects and configures Model Context Protocol (MCP) servers by verifying their executability and checking for available npm packages. It creates or updates the `settings.json` file with verified MCP server configurations. Dependencies include `json`, `subprocess`, and `shutil`.

```python
# From installer.py:86-132
import json
import subprocess

def install_mcp(progress_bar=None):
    """Install MCP server configuration with verification"""
    settings_file = QWEN_DIR / "settings.json"

    default_mcp_servers = {
        "serena": {
            "command": "serena-mcp-server",
            "args": ["--context", "ide-assistant", "--project", "/path/to/your/project"]
        },
        "context7": {
            "command": "npx",
            "args": ["-y", "@upstash/context7-mcp@latest"]
        },
        "sequential": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
        }
    }

    if progress_bar:
        progress_bar.total = len(default_mcp_servers)

    verified_mcp_servers = {}

    for name, config in default_mcp_servers.items():
        command_to_check = config["command"]
        if shutil.which(command_to_check):
            is_verified = True
            if command_to_check == "npx":
                npx_package = next((arg for arg in config["args"] if arg.startswith('@')), None)
                if npx_package:
                    # Verify npm package exists
                    package_name = npx_package.split('@')[1]
                    result = subprocess.run(
                        ["npm", "view", package_name, "version"],
                        capture_output=True, text=True, check=False
                    )
                    is_verified = result.returncode == 0

            if is_verified:
                verified_mcp_servers[name] = config

        if progress_bar:
            progress_bar.update(len(verified_mcp_servers))

    if verified_mcp_servers:
        final_settings = {"mcpServers": verified_mcp_servers}
        with open(settings_file, "w") as f:
            json.dump(final_settings, f, indent=2)

# Creates ~/.qwen/settings.json with:
# {
#   "mcpServers": {
#     "context7": {
#       "command": "npx",
#       "args": ["-y", "@upstash/context7-mcp@latest"]
#     }
#   }
# }

```

--------------------------------

### Memory Operations: Session Start

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/SuperQwen/Modes/MODE_Task_Management.md

Demonstrates how to initiate a task management session by listing existing memories, reading a specific context, and processing collected information. These operations are crucial for resuming work or understanding the current state.

```pseudocode
1. list_memories() → Show existing task state
2. read_memory("current_plan") → Resume context
3. think_about_collected_information() → Understand where we left off
```

--------------------------------

### Manual Release Triggering and Version Planning

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

This section shows commands for triggering manual workflows and planning version updates. It includes checking Git logs to review changes and determining the appropriate version increment (MAJOR, MINOR, PATCH) based on Semantic Versioning principles.

```bash
# Review changes since last release
git log v3.5.0..HEAD --oneline

# Determine version increment based on changes
# Breaking changes → MAJOR
# New features → MINOR  
# Bug fixes only → PATCH

```

--------------------------------

### JavaScript Function Implementation Example

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/SuperQwen/Core/RULES.md

Demonstrates a correctly implemented JavaScript function for calculation, contrasting it with incorrect implementations like throwing an error or leaving a TODO comment. This highlights the 'Completion Mindset' principle.

```javascript
function calculate() { return price * tax; }
```

```javascript
function calculate() { throw new Error("Not implemented"); }
```

```javascript
// TODO: implement tax calculation
```

--------------------------------

### Introspection Mode Examples

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/SuperQwen/Modes/MODE_Introspection.md

Illustrates the difference between standard responses and introspective responses, showcasing the enhanced transparency and self-analysis capabilities of the Introspection Mode. This includes reasoning, alternative approaches, pattern detection, and learning insights.

```text
Standard: "I'll analyze this code structure"
Introspective: "🧠 Reasoning: Why did I choose structural analysis over functional? 
               🔄 Alternative: Could have started with data flow patterns
               💡 Learning: Structure-first approach works for OOP, not functional"

Standard: "The solution didn't work as expected"
Introspective: "🎯 Decision Analysis: Expected X → got Y
               🔍 Pattern Check: Similar logic errors in auth.js:15, config.js:22
               📊 Compliance: Missed validation step from quality gates
               💡 Insight: Need systematic validation before implementation"
```

--------------------------------

### Run PyPI Pre-Publication Validation Script

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

Executes a script to perform comprehensive checks before publishing the package to PyPI. This script validates package structure, metadata, version consistency, dependency compatibility, entry points, security scan results, and cross-platform compatibility.

```bash
# Comprehensive pre-publication validation
python scripts/validate_pypi_ready.py

# Validates:
# - Package structure and metadata
# - Version consistency across files
# - Dependency compatibility
# - Entry point functionality
# - Security scanning results
# - Cross-platform compatibility
```

--------------------------------

### GitHub Actions Workflow for Testing

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

YAML configuration for a GitHub Actions workflow that runs on pull requests and pushes to the main branch. It automates testing across multiple Python versions (3.8-3.12) and operating systems (Linux, macOS, Windows).

```yaml
# Triggered on: Pull requests, pushes to main
# Tests: Python 3.8-3.12, Linux/macOS/Windows

```

--------------------------------

### Example: Session 3 - Completion Check

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/SuperQwen/Modes/MODE_Task_Management.md

Illustrates the process of checking for task completion and finalizing a session. It involves assessing readiness, completing remaining tasks, updating outcomes, and cleaning up temporary memory entries.

```pseudocode
think_about_whether_you_are_done() → "Testing phase remains incomplete"
Complete remaining testing tasks
write_memory("outcome_auth", "Successfully implemented with 95% test coverage")
delete_memory("checkpoint_*") → Clean temporary states
write_memory("session_summary", "Auth system complete and validated")
```

--------------------------------

### GitHub Secrets Configuration for PyPI and Code Coverage

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

This snippet lists the required GitHub repository secrets for automating PyPI package publishing and code coverage reporting. It includes tokens for PyPI, Codecov, and optional GPG keys for release signing.

```bash
# Required secrets for automated publishing:
PYPI_API_TOKEN          # PyPI publishing token (scoped to SuperGemini)
CODECOV_TOKEN          # Code coverage reporting
GPG_PRIVATE_KEY        # Optional: GPG signing for releases
GPG_PASSPHRASE         # Optional: GPG key passphrase
```

--------------------------------

### Example: Session 2 - Resume After Interruption

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/SuperQwen/Modes/MODE_Task_Management.md

Demonstrates how to resume a task management session after an interruption. It shows listing memories, retrieving the plan, and using 'think' functions to determine the next steps and update phases.

```pseudocode
list_memories() → Shows plan_auth, phase_1, task_1.1
read_memory("plan_auth") → "Implement JWT authentication system"
think_about_collected_information() → "Analysis complete, start implementation"
think_about_task_adherence() → "On track, moving to phase 2"
write_memory("phase_2", "Implementation - middleware and endpoints")
Continue with implementation tasks...
```

--------------------------------

### Release Publishing Workflow (.github/workflows/publish.yml)

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

This YAML configuration defines the GitHub Actions workflow for publishing releases. It triggers on Git tag creation, performs multi-platform testing, security validation, package building, PyPI publication, and GitHub release creation. It requires secrets like PYPI_API_TOKEN and CODECOV_TOKEN.

```yaml
# Triggered on: Git tag creation (v*.*.*)
# Steps:
# 1. Multi-platform testing
# 2. Security validation
# 3. Package building
# 4. PyPI publication
# 5. GitHub release creation

```

--------------------------------

### Secure Credential Storage Guidelines

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

This bash snippet outlines locations where credentials should NOT be stored and recommends secure alternatives. It emphasizes avoiding source code, configuration files, and shell history, favoring GitHub secrets, environment variables, and credential managers.

```bash
# Never store credentials in:
# - Source code or configuration files
# - Shell history or scripts
# - Documentation or comments
# - Temporary files or logs

# Use secure storage:
# - GitHub repository secrets
# - Environment variables (local development)
# - Secure credential managers (keyring, etc.)
```

--------------------------------

### Install AI Agents to Agents Directory (Python)

Source: https://context7.com/superclaude-org/superqwen_framework/llms.txt

Copies AI persona markdown files to the ~/.qwen/agents/ directory. It utilizes importlib.resources to access package files and shutil for copying. Handles optional progress bar updates during the process. Assumes agent files are in markdown format.

```python
import shutil
import importlib.resources
from pathlib import Path

QWEN_DIR = Path.home() / ".qwen"

def get_package_files(sub_dir):
    # This is a placeholder for the actual function that retrieves files from the package.
    # In a real scenario, this would use importlib.resources.files('your_package_name')
    # and then filter for files within the specified sub_dir.
    # For this example, we'll simulate some files.
    if sub_dir == "agents":
        class MockFile:
            def __init__(self, name):
                self.name = name
            
            def __str__(self):
                return self.name

        class MockPackage:
            def __init__(self):
                self.files = [
                    MockFile("python-expert.md"),
                    MockFile("backend-architect.md"),
                    MockFile("security-engineer.md"),
                    MockFile("performance-engineer.md"),
                    MockFile("some_other_file.txt")
                ]
            
            def __enter__(self):
                return self
            
            def __exit__(self, exc_type, exc_val, exc_tb):
                pass

        return MockPackage()
    return []

class ProgressBar:
    # Placeholder for ProgressBar class definition
    def __init__(self, total=0):
        self.total = total
        self.current = 0

    def update(self, i):
        self.current = i
        # In a real implementation, this would print progress.
        pass

def install_agents(progress_bar=None):
    """Install AI agent personas to ~/.qwen/agents/"""
    agents_dst = QWEN_DIR / "agents"
    agents_dst.mkdir(exist_ok=True)

    files = get_package_files("agents")
    files_to_copy = [f for f in files if f.name.endswith('.md')]

    if progress_bar:
        progress_bar.total = len(files_to_copy)

    for i, file in enumerate(files_to_copy):
        # In a real scenario, 'src_path' would be a valid path to the file.
        # Here we simulate the copy operation.
        print(f"Copying {file.name} to {agents_dst}")
        # with importlib.resources.as_file(file) as src_path:
        #     shutil.copy2(src_path, agents_dst)
        if progress_bar:
            progress_bar.update(i + 1)

# Example Usage:
# progress = ProgressBar(total=100)
# install_agents(progress_bar=progress)

```

--------------------------------

### Tagging and Retagging Git Commits

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/PUBLISHING.md

This snippet demonstrates how to delete an existing Git tag and immediately recreate it. This is useful for correcting a tag or ensuring it points to the latest commit after an update. It first removes the local tag 'v4.0.0' and then creates a new tag 'v4.0.0'.

```bash
git tag -d v4.0.0 && git tag v4.0.0
```

--------------------------------

### Get Package Files Utility in Python

Source: https://context7.com/superclaude-org/superqwen_framework/llms.txt

A Python function to retrieve files from specific subfolders within the SuperQwen package. It handles module and file not found errors, returning an empty list if the package or subfolder is inaccessible. This is useful for accessing configuration or agent definition files.

```python
# From file_utils.py:1-16
import importlib.resources
from pathlib import Path

QWEN_DIR = Path.home() / ".qwen"

def get_package_files(subfolder):
    """Helper to get files from a package subfolder"""
    try:
        package_name = 'SuperQwen'
        data_dir = importlib.resources.files(package_name) / subfolder.capitalize()
        return [file for file in data_dir.iterdir() if file.is_file()]
    except (ModuleNotFoundError, FileNotFoundError):
        return []

# Usage:
from SuperQwen.setup.file_utils import get_package_files

# Get all command files
command_files = get_package_files("commands")
# Returns: [Path('analyze.toml'), Path('implement.toml'), ...] 

# Get all agent files
agent_files = get_package_files("agents")
# Returns: [Path('python-expert.md'), Path('backend-architect.md'), ...] 

# Get all mode files
mode_files = get_package_files("modes")
# Returns: [Path('MODE_Task_Management.md'), ...] 
```

--------------------------------

### Display SuperQwen CLI Help Information

Source: https://context7.com/superclaude-org/superqwen_framework/llms.txt

Python code demonstrating how to display help information for the SuperQwen CLI using the Typer library. It includes core commands and available '/sq' slash commands with their descriptions.

```python
# From cli.py:18-236
import typer
from SuperQwen.setup import ui
from SuperQwen import __version__

app = typer.Typer(
    name="superqwen",
    help="SuperQwen Framework CLI - Manage your Qwen CLI enhancements",
    add_completion=False,
)

@app.command()
def help():
    """Show framework help and available commands"""
    ui.display_header("SuperQwen Framework", f"Version {__version__}")

    core_headers = ["Command", "Description"]
    core_rows = [
        ["install", "Install framework components"],
        ["install all", "Install all components"],
        ["uninstall", "Uninstall components"],
        ["update", "Update to latest version"],
    ]
    ui.display_table(core_headers, core_rows, title="Core Commands")

    sq_headers = ["Slash Command", "Description"]
    sq_rows = [
        ["/sq:analyze", "Comprehensive code analysis"],
        ["/sq:implement", "Feature implementation"],
        ["/sq:test", "Execute tests with coverage"],
    ]
    ui.display_table(sq_headers, sq_rows, title="Available /sq Commands")

# Usage:
# $ superqwen help
# $ superqwen --help
# $ superqwen -h
```

--------------------------------

### Implement Feature with SuperGemini

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/CONTRIBUTING.md

This command initiates the implementation workflow for a specified feature using the SuperGemini framework. It requires the feature description as an argument and is part of the development process.

```bash
/sg:implement "user login"
```

--------------------------------

### Update SuperQwen Framework

Source: https://context7.com/superclaude-org/superqwen_framework/llms.txt

Updates the SuperQwen framework package to the latest version available on PyPI. Includes output messages indicating the update process status.

```bash
# Update to latest version
superqwen update

# Output:
# 🚀 Checking for updates...
# ⠋ Running pip install --upgrade SuperQwen...
# ✅ SuperQwen updated successfully!
```

--------------------------------

### Uninstall SuperQwen Components

Source: https://context7.com/superclaude-org/superqwen_framework/llms.txt

Provides options for uninstalling SuperQwen framework components, either interactively through a dedicated uninstaller or by specifying individual components to remove. This process cleans up files from the ~/.qwen/ directory.

```bash
# Interactive uninstaller
superqwen uninstall

# Uninstall all components
superqwen uninstall all

# Uninstall specific component
superqwen uninstall commands
superqwen uninstall modes
superqwen uninstall agents
superqwen uninstall mcp

# Files are removed from ~/.qwen/ directory structure
```

--------------------------------

### Code Organization Naming Conventions

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/SuperQwen/Core/RULES.md

Demonstrates correct naming conventions for files and functions in Python and JavaScript, adhering to project standards for clarity and consistency.

```javascript
getUserData()

```

```python
user_data.py

```

```javascript
components/auth/

```

--------------------------------

### Cross-Platform Progress Bar with ETA (Python)

Source: https://context7.com/superclaude-org/superqwen_framework/llms.txt

A customizable progress bar class that displays visual progress, percentage, elapsed time, and estimated time of arrival (ETA). It dynamically adjusts to terminal width and formats time for readability. Requires 'time' and 'shutil' modules.

```python
import time
import shutil

class ProgressBar:
    """Cross-platform progress bar with ETA calculation"""

    def __init__(self, total, width=50, prefix='', suffix=''):
        self.total = total
        self.width = width
        self.prefix = prefix
        self.suffix = suffix
        self.current = 0
        self.start_time = time.time()
        self.terminal_width = shutil.get_terminal_size().columns

    def update(self, current, message=''):
        """Update progress display"""
        self.current = current
        percent = min(100, (current / self.total) * 100) if self.total > 0 else 100

        filled_width = int(self.width * current / self.total) if self.total > 0 else self.width
        filled = '█' * filled_width
        empty = '░' * (self.width - filled_width)

        elapsed = time.time() - self.start_time
        if current > 0:
            eta = (elapsed / current) * (self.total - current)
            eta_str = f" ETA: {self._format_time(eta)}"
        else:
            eta_str = ""

        progress_line = (
            f"\r{self.prefix}[{filled}{empty}] "
            f"{percent:5.1f}%{message}{eta_str}"
        )
        print(progress_line, end='', flush=True)

    def finish(self, message='Complete'):
        """Complete progress bar"""
        self.update(self.total, message)
        print()

    def _format_time(self, seconds):
        """Format time as human-readable"""
        if seconds < 60:
            return f"{seconds:.0f}s"
        elif seconds < 3600:
            return f"{seconds/60:.0f}m {seconds%60:.0f}s"
        return f"{seconds//3600:.0f}h {(seconds%3600)//60:.0f}m"

# Usage example:
# progress = ProgressBar(total=100, prefix="Installing: ")
# for i in range(100):
#     time.sleep(0.05)
#     progress.update(i + 1)
# progress.finish("Installation complete")

```

--------------------------------

### Command Line Versions

Source: https://github.com/superclaude-org/superqwen_framework/blob/master/SECURITY.md

These commands are used to retrieve version information for the SuperGemini Framework, Python, and the Gemini CLI. This information is essential for accurately reporting security vulnerabilities.

```shell
SuperGemini --version
python3 --version
gemini --version
```
Tokens:
Raw