Maintenance Scripts
Relevant source files
The following files were used as context for generating this wiki page:
Maintenance scripts in the SuperGemini Framework serve as the operational backbone for lifecycle management, encompassing installation cleanup, version synchronization, and system uninstallation. These scripts ensure that the development environment remains clean of technical debt and that the framework's metadata remains consistent across its multi-layered architecture, which includes the Python package source and the behavioral configuration files installed to the user's home directory.
The scope of these scripts includes automated workspace hygiene, version propagation for release management, and secure removal procedures that prevent artifact pollution in the ~/.gemini/ workspace.
Sources: CLAUDE.md:14-23, PUBLISHING.md:200-215, SuperGemini/Core/RULES.md:85-95
Workspace Hygiene and Cleanup
Workspace hygiene is a critical maintenance priority, governed by established behavioral rules that mandate the removal of temporary files, build artifacts, and debugging outputs. The scripts/cleanup.sh utility automates this process to prevent "artifact pollution" and workspace bloat.
Cleanup Operations
The cleanup process targets specific categories of temporary data:
- Build Artifacts: Directories such as
build/,dist/, and*.egg-info/generated during package distribution. - Cache and Temporary Files: Python bytecode (
__pycache__) and local development caches. - Environment management: Removal of temporary debug scripts or logs.
Sources: SuperGemini/Core/RULES.md:85-95, PUBLISHING.md:225-230, scripts/cleanup.sh
The diagram above illustrates the logical flow of identifying and removing transient build and metadata artifacts from the repository.
Sources: scripts/cleanup.sh, PUBLISHING.md:227-230
Version Synchronization
The scripts/update_version_refs.py script manages the "single source of truth" for the framework's versioning. SuperGemini uses a central VERSION file in the project root, which must be propagated to multiple files across the repository to maintain synchronization during the build and release cycles.
Propagation Targets
When a new version is declared in the VERSION file, the maintenance script updates:
- Package Metadata:
pyproject.tomlandsetup.py. - Source Code:
SuperGemini/version.py, which is generated or updated during the build. - Component Metadata: Internal component versioning and release notes in
PUBLISHING.md.
Sources: CLAUDE.md:386-402, PUBLISHING.md:330-345, scripts/update_version_refs.py
| Component | Target File | Impact |
|---|---|---|
| Version File | VERSION | Primary source of truth for semantic versioning. |
| Project Config | pyproject.toml | Ensures PyPI and pip recognize the correct version. |
| Release Docs | PUBLISHING.md | Updates release cadence and version history notes. |
| Component Core | SuperGemini/version.py | Allows the CLI to report its version via SuperGemini --version. |
Sources: CLAUDE.md:386-395, PUBLISHING.md:340-348, scripts/update_version_refs.py
Uninstallation Procedures
The uninstall_supergemini.py script handles the secure removal of the framework from a user's system. Unlike standard library uninstalls, this script must account for the dual-directory structure of SuperGemini: the Python source code and the behavioral configurations residing in ~/.gemini/.
Removal Logic
The uninstallation process includes:
- Component Removal: Deleting files from the user-owned
~/.gemini/directory, including commands (/sg:prefix files), agents, and MCP configurations. - Environment Cleanup: Identifying and removing environment variable references (e.g.,
SUPERGEMINI_COMPONENTS_PATH) from shell configurations. - Safety Checks: Using regex patterns (e.g.,
r'SUPERGEMINI_') to avoid accidental deletion of unrelated user files while ensuring all framework-specific environment variables are purged.
Sources: claudedocs/PHASE_1_COMPLETION_REPORT.md:85-95, CLAUDE.md:144-155, uninstall_supergemini.py
This sequence diagram shows the interaction between the uninstallation script and the local environment to ensure total artifact removal.
Sources: claudedocs/PHASE_1_COMPLETION_REPORT.md:85-95, CLAUDE.md:144-155, uninstall_supergemini.py
Summary of Key Scripts
| Script Path | Purpose | Execution Context |
|---|---|---|
scripts/cleanup.sh | Workspace hygiene; removes build/cache artifacts. | Local Development |
scripts/update_version_refs.py | Propagates version from VERSION file to codebase. | Release Preparation |
uninstall_supergemini.py | Full system removal including ~/.gemini/ files. | User Maintenance |
scripts/validate_pypi_ready.py | Pre-publication package and metadata validation. | CI/CD & Distribution |
Sources: scripts/cleanup.sh, scripts/update_version_refs.py, uninstall_supergemini.py, PUBLISHING.md:210-220
Maintenance scripts are essential for preserving the integrity of the SuperGemini Framework throughout its lifecycle. By automating cleanup, versioning, and uninstallation, these utilities allow developers to focus on core framework enhancements while maintaining high standards for technical hygiene and distribution accuracy.
Sources: CLAUDE.md:435-445, SuperGemini/Core/RULES.md:120-130