Maintenance & Operations Commands
Relevant source files
The following files were used as context for generating this wiki page:
Maintenance and Operations (M&O) commands within the SuperGemini Framework represent a critical suite of tools designed to ensure codebase health, diagnostic integrity, and systematic version control. These commands are executed via the /sg: prefix within the Gemini CLI environment, distinguishing them from the terminal-based installation and configuration commands. They leverage specialized AI agents and Model Context Protocol (MCP) servers to automate technical debt reduction, issue diagnosis, and quality assurance workflows.
The primary scope of M&O commands includes systematic troubleshooting, technical debt cleanup, comprehensive testing, and intelligent version control management. By automating these operational tasks, the framework ensures that development sessions remain performant and that the codebase adheres to predefined quality standards.
Sources: Docs/User-Guide/commands.md:1-25, CLAUDE.md:150-175
Core Maintenance Workflow
The framework employs a systematic approach to maintenance where diagnostic commands identify issues, and operation-focused commands implement fixes and validate results.
This diagram illustrates the logical progression from problem identification to version control persistence.
Sources: Docs/User-Guide/commands.md:150-180, Docs/Reference/basic-examples.md:80-100
Diagnostic & Troubleshooting Operations
The /sg:troubleshoot command is the primary entry point for systematic issue diagnosis. It utilizes the Root-Cause-Analyst and DevOps specialized agents, often coordinating with the Sequential MCP server to perform multi-step reasoning.
Troubleshooting Logic
The troubleshooting process involves identifying the issue type (build, runtime, or performance) and executing a diagnostic sequence to isolate the failure point.
| Parameter | Type | Description |
|---|---|---|
--type | Flag | Specifies error category: build, runtime, or performance. |
--fix | Flag | Instructs the framework to suggest or apply targeted repairs. |
--verbose | Flag | Enables detailed diagnostic output including log analysis. |
Sources: Docs/User-Guide/commands.md:95-115, Docs/Reference/basic-examples.md:40-50
This sequence shows how the framework decomposes a user-reported problem into a technical root cause using specialized agents.
Sources: Docs/User-Guide/commands.md:100-110, Docs/Reference/basic-examples.md:195-210
Codebase Hygiene & Cleanup
Hygiene operations are performed using /sg:cleanup and /sg:improve. These commands target technical debt, such as dead code, import optimization, and formatting inconsistencies.
Cleanup Operations
The cleanup module focuses on structural maintenance. It typically activates the Analyzer specialist and the Morphllm MCP server for pattern-based code transformations.
- Imports: Removes unused imports and organizes dependencies.
- Dead Code: Identifies and removes unreachable logic or unused variables.
- Formatting: Standardizes code style across the project.
Sources: Docs/User-Guide/commands.md:205-220, Docs/Reference/quick-start-practices.md:190-205
Quality Assurance & Testing
Testing is a core operational requirement, managed by the /sg:test command. This command is overseen by the QA specialist agent and integrates with the Playwright MCP for End-to-End (E2E) validation.
Testing Parameters & Outputs
The framework supports multiple testing tiers, which can be specified via flags:
- Unit Tests: Focused on individual functions or components.
- Integration Tests: Validating interactions between modules.
- E2E Tests: Full browser-based automation for user flows.
| Flag | Purpose | Source File |
|---|---|---|
--coverage | Generates code coverage analysis reports. | Docs/User-Guide/commands.md:118 |
--fix | Repairs failing tests automatically. | Docs/User-Guide/commands.md:120 |
--watch | Continuous execution of unit tests during development. | Docs/User-Guide/commands.md:122 |
Sources: Docs/User-Guide/commands.md:115-135, Docs/Reference/basic-examples.md:52-60
Version Control Operations
The /sg:git command provides an intelligent interface for version control. Unlike standard git, it utilizes the DevOps specialist to generate "smart" commit messages that adhere to conventional commit standards based on the analyzed changes.
Git Feature Set
- Smart Messages: Auto-generates descriptions of the work performed during the session.
- Conflict Resolution: Assists in managing merge conflicts by analyzing logic differences.
- Workflow Optimization: Suggests branch strategies and commit patterns.
Sources: Docs/User-Guide/commands.md:280-290, CLAUDE.md:165-170
This flow illustrates the automated commit message generation process.
Sources: Docs/User-Guide/commands.md:285-288
Operational Error Codes
The maintenance system uses specific error codes to signify operational failures.
| Code | Meaning | Resolution |
|---|---|---|
| E003 | MCP server connection failed | Check Node.js/NPM cache or restart servers. |
| E005 | Timeout exceeded | Reduce scope with --scope file or increase timeout. |
| E006 | Memory limit exceeded | Use --memory-limit or module-level scope. |
| E008 | Dependency missing | Verify installation via SuperGemini --version. |
Sources: Docs/User-Guide/commands.md:380-400
Summary
Maintenance & Operations commands in the SuperGemini Framework provide a specialized toolkit for sustaining high-quality development environments. By combining diagnostic tools like /sg:troubleshoot with hygiene tools like /sg:cleanup and persistence tools like /sg:git, the framework automates the most labor-intensive aspects of codebase management. These operations ensure that technical debt is managed proactively and that every code change is validated through systematic testing protocols.