aidevops 2.52.1

package/.agent/tools/code-review/best-practices.md

@@ -0,0 +1,203 @@
+---
+description: Best practices for AI-assisted coding
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: false
+  glob: true
+  grep: true
+  webfetch: false
+  task: true
+---
+
+# AI-Assisted Coding Best Practices
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Mandatory Patterns**: Local variables for params (`local param="$1"`), explicit returns, constants for 3+ strings
+- **SC2155**: Separate `local var` and `var=$(command)`
+- **S7679**: Never use `$1` directly - assign to local variables
+- **S1192**: Create `readonly CONSTANT="value"` for repeated strings
+- **S1481**: Remove unused variables or enhance functionality
+- **Pre-Dev**: Run `linters-local.sh`, note current issues, plan improvements
+- **Post-Dev**: Re-run quality check, test functionality, commit with metrics
+- **Quality Scripts**: `linters-local.sh`, `fix-content-type.sh`, `fix-auth-headers.sh`, `fix-error-messages.sh`
+- **Targets**: SonarCloud <50 issues, 0 critical violations, 100% feature preservation
+<!-- AI-CONTEXT-END -->
+
+## Framework-Specific Guidelines for AI Agents
+
+> **IMPORTANT**: This document is supplementary to the [AGENTS.md](../AGENTS.md).
+> For any conflicts, the main AGENTS.md takes precedence as the single source of truth.
+
+### Overview
+
+This document provides detailed implementation examples and advanced patterns for AI agents working on the AI DevOps Framework.
+
+### Code Quality Requirements
+
+#### Shell Script Standards (MANDATORY)
+
+**These patterns are REQUIRED for SonarCloud/CodeFactor/Codacy compliance:**
+
+```bash
+# ✅ CORRECT Function Structure
+function_name() {
+    local param1="$1"
+    local param2="$2"
+    
+    # Function logic here
+    
+    return 0  # MANDATORY: Every function must have explicit return
+}
+
+# ✅ CORRECT Variable Declaration (SC2155 compliance)
+local variable_name
+variable_name=$(command_here)
+
+# ✅ CORRECT String Literal Management (S1192 compliance)
+readonly COMMON_STRING="repeated text"
+echo "$COMMON_STRING"  # Use constant for 3+ occurrences
+
+# ✅ CORRECT Positional Parameter Handling (S7679 compliance)
+printf 'Price: %s50/month\n' '$'  # Not: echo "Price: $50/month"
+```
+
+#### Quality Issue Prevention
+
+**Before making ANY changes, check for these patterns:**
+
+1. **Positional Parameters**: Never use `$50`, `$200` in strings - use printf format
+2. **String Literals**: If text appears 3+ times, create a readonly constant
+3. **Unused Variables**: Every variable must be used or removed
+4. **Return Statements**: Every function must end with `return 0` or appropriate code
+5. **Variable Declaration**: Separate `local var` and `var=$(command)`
+
+### Development Workflow
+
+#### Pre-Development Checklist
+
+1. **Run quality check**: `bash .agent/scripts/linters-local.sh`
+2. **Check current issues**: Note SonarCloud/Codacy/CodeFactor status
+3. **Plan improvements**: How will changes enhance quality?
+4. **Test functionality**: Ensure no feature loss
+
+#### Post-Development Validation
+
+1. **Quality verification**: Re-run linters-local.sh
+2. **Functionality testing**: Verify all features work
+3. **Documentation updates**: Update AGENTS.md if needed
+4. **Commit with metrics**: Include before/after quality metrics
+
+### Common Patterns & Solutions
+
+#### String Literal Consolidation
+
+**Target patterns with 3+ occurrences:**
+
+- HTTP headers: `Content-Type: application/json`, `Authorization: Bearer`
+- Error messages: `Unknown command:`, `Usage:`, help text
+- API endpoints: Repeated URLs or paths
+- Configuration values: Common settings or defaults
+
+```bash
+# Create constants section after colors
+readonly NC='\033[0m' # No Color
+
+# Common constants
+readonly CONTENT_TYPE_JSON="Content-Type: application/json"
+readonly AUTH_BEARER_PREFIX="Authorization: Bearer"
+readonly ERROR_UNKNOWN_COMMAND="Unknown command:"
+```
+
+#### Error Message Standardization
+
+**Consistent error handling patterns:**
+
+```bash
+# Error message constants
+readonly ERROR_UNKNOWN_COMMAND="Unknown command:"
+readonly ERROR_CONFIG_NOT_FOUND="Configuration file not found"
+readonly ERROR_INVALID_OPTION="Invalid option"
+readonly USAGE_PREFIX="Usage:"
+readonly HELP_MESSAGE_SUFFIX="Show this help message"
+
+# Usage in functions
+print_error "$ERROR_UNKNOWN_COMMAND $command"
+echo "$USAGE_PREFIX $0 [options]"
+```
+
+#### Function Enhancement Over Deletion
+
+**When fixing unused variables, prefer enhancement:**
+
+```bash
+# ❌ DON'T: Remove functionality
+# local port  # Removed to fix unused variable
+
+# ✅ DO: Enhance functionality
+local port
+read -r port
+if [[ -n "$port" && "$port" != "22" ]]; then
+    ssh -p "$port" "$host"  # Enhanced SSH with port support
+else
+    ssh "$host"
+fi
+```
+
+### Quality Tools Usage
+
+#### Available Quality Scripts
+
+- **linters-local.sh**: Run before and after changes
+- **fix-content-type.sh**: Fix Content-Type header duplications
+- **fix-auth-headers.sh**: Fix Authorization header patterns
+- **fix-error-messages.sh**: Standardize error messages
+- **markdown-formatter.sh**: Fix markdown formatting issues
+
+#### Quality CLI Integration
+
+```bash
+# CodeRabbit analysis
+bash .agent/scripts/coderabbit-cli.sh review
+
+# Comprehensive analysis
+bash .agent/scripts/quality-cli-manager.sh analyze all
+
+# Individual platform analysis
+bash .agent/scripts/codacy-cli.sh analyze
+bash .agent/scripts/sonarscanner-cli.sh analyze
+```
+
+### Success Metrics
+
+#### Quality Targets
+
+- **SonarCloud**: <50 total issues (currently 42)
+- **Critical Issues**: 0 S7679, 0 S1481 violations
+- **String Literals**: <10 S1192 violations
+- **ShellCheck**: <5 critical issues per file
+- **Functionality**: 100% feature preservation
+
+#### Commit Standards
+
+**Include quality metrics in commit messages:**
+
+```text
+🔧 FEATURE: Enhanced SSH functionality with port support
+
+✅ QUALITY IMPROVEMENTS:
+- Fixed S1481: Unused 'port' variable → Enhanced SSH port support
+- Maintained functionality: All existing SSH features preserved
+- Added capability: Custom port support for non-standard configurations
+
+📊 METRICS:
+- SonarCloud: 43 → 42 issues (1 issue resolved)
+- Functionality: 100% preserved + enhanced
+```
+
+This framework maintains industry-leading quality standards through systematic application of these practices.

package/.agent/tools/code-review/codacy.md

@@ -0,0 +1,151 @@
+---
+description: Codacy auto-fix for code quality issues
+mode: subagent
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  glob: true
+  grep: true
+  webfetch: false
+  task: true
+---
+
+# Codacy Auto-Fix Integration Guide
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- Auto-fix command: `bash .agent/scripts/codacy-cli.sh analyze --fix`
+- Via manager: `bash .agent/scripts/quality-cli-manager.sh analyze codacy-fix`
+- Fix types: Code style, best practices, security, performance, maintainability
+- Safety: Non-breaking, reversible, conservative (skips ambiguous)
+- Metrics: 70-90% time savings, 99%+ accuracy, 60-80% violation coverage
+- Cannot fix: Complex logic, architecture, context-dependent, breaking changes
+- Best practices: Always review, test after, incremental batches, clean git state
+- Workflow: quality-check -> analyze --fix -> quality-check -> commit with metrics
+<!-- AI-CONTEXT-END -->
+
+## Automated Code Quality Fixes
+
+### Overview
+
+Codacy CLI v2 provides automated fix capabilities that mirror the "Fix Issues" functionality available in the Codacy web dashboard. This feature can automatically resolve many common code quality violations without manual intervention.
+
+### **🔧 AUTO-FIX CAPABILITIES**
+
+#### **Supported Fix Types:**
+
+- **Code Style Issues**: Formatting, indentation, spacing
+- **Best Practice Violations**: Variable naming, function structure
+- **Security Issues**: Basic security pattern fixes
+- **Performance Issues**: Simple optimization patterns
+- **Maintainability**: Code complexity reduction where safe
+
+#### **Safety Guarantees:**
+
+- **Non-Breaking**: Only applies fixes guaranteed not to break functionality
+- **Reversible**: All changes can be reverted via Git
+- **Conservative**: Skips ambiguous cases requiring human judgment
+- **Tested**: Fixes are based on proven patterns from millions of repositories
+
+### **🛠️ USAGE METHODS**
+
+#### **Method 1: Direct CLI Usage**
+
+```bash
+# Basic auto-fix analysis
+bash .agent/scripts/codacy-cli.sh analyze --fix
+
+# Auto-fix with specific tool
+bash .agent/scripts/codacy-cli.sh analyze eslint --fix
+
+# Check what would be fixed (dry-run equivalent)
+bash .agent/scripts/codacy-cli.sh analyze
+```
+
+#### **Method 2: Quality CLI Manager**
+
+```bash
+# Auto-fix via unified manager
+bash .agent/scripts/quality-cli-manager.sh analyze codacy-fix
+
+# Status check before auto-fix
+bash .agent/scripts/quality-cli-manager.sh status codacy
+```
+
+#### **Method 3: Integration with Quality Workflow**
+
+```bash
+# Pre-commit auto-fix workflow
+bash .agent/scripts/linters-local.sh
+bash .agent/scripts/codacy-cli.sh analyze --fix
+bash .agent/scripts/linters-local.sh  # Verify improvements
+```
+
+### **📊 EXPECTED RESULTS**
+
+#### **Typical Fix Categories:**
+
+- **String Literals**: Consolidation into constants
+- **Variable Declarations**: Proper scoping and initialization
+- **Function Returns**: Adding missing return statements
+- **Code Formatting**: Consistent style application
+- **Import/Export**: Optimization and organization
+
+#### **Performance Impact:**
+
+- **Time Savings**: 70-90% reduction in manual fix time
+- **Accuracy**: 99%+ accuracy for supported fix types
+- **Coverage**: Handles 60-80% of common quality violations
+- **Consistency**: Uniform application across entire codebase
+
+### **🔄 WORKFLOW INTEGRATION**
+
+#### **Recommended Development Workflow:**
+
+1. **Pre-Development**: Run quality check to identify issues
+2. **Auto-Fix**: Apply automated fixes where available
+3. **Manual Review**: Address remaining issues requiring judgment
+4. **Validation**: Re-run quality checks to verify improvements
+5. **Commit**: Include before/after metrics in commit message
+
+#### **CI/CD Integration:**
+
+```yaml
+# GitHub Actions example
+- name: Auto-fix code quality issues
+  run: |
+    bash .agent/scripts/codacy-cli.sh analyze --fix
+    git add .
+    git diff --staged --quiet || git commit -m "🔧 AUTO-FIX: Applied Codacy automated fixes"
+```
+
+### **⚠️ LIMITATIONS & CONSIDERATIONS**
+
+#### **What Auto-Fix Cannot Do:**
+
+- **Complex Logic**: Business logic or algorithmic changes
+- **Architecture**: Structural or design pattern modifications
+- **Context-Dependent**: Fixes requiring domain knowledge
+- **Breaking Changes**: Modifications that could affect functionality
+
+#### **Best Practices:**
+
+- **Always Review**: Check auto-applied changes before committing
+- **Test After**: Run tests to ensure functionality is preserved
+- **Incremental**: Apply auto-fixes in small batches for easier review
+- **Backup**: Ensure clean Git state before running auto-fix
+
+### **🎯 SUCCESS METRICS**
+
+#### **Quality Improvement Tracking:**
+
+- **Before/After Counts**: Track violation reduction
+- **Fix Success Rate**: Monitor auto-fix effectiveness
+- **Time Savings**: Measure development efficiency gains
+- **Quality Trends**: Long-term code quality improvements
+
+This auto-fix integration represents a significant advancement in automated code quality management, providing the same powerful fix capabilities available in the Codacy web interface directly through our CLI workflows.

package/.agent/tools/code-review/code-simplifier.md

@@ -0,0 +1,174 @@
+---
+description: Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality
+mode: subagent
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  glob: true
+  grep: true
+  webfetch: false
+  task: true
+---
+
+# Code Simplifier
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: Simplify and refine code for clarity, consistency, and maintainability
+- **Trigger**: `/code-simplifier` or after significant code changes
+- **Scope**: Recently modified code unless instructed otherwise
+- **Priority**: Clarity over brevity - explicit code beats compact code
+- **Rule**: Never change functionality - only improve how code is written
+
+**Key Principles**:
+- Preserve exact functionality
+- Apply project standards from CLAUDE.md/AGENTS.md
+- Reduce complexity and nesting
+- Eliminate redundancy
+- Avoid nested ternaries - use switch/if-else
+- Remove obvious comments
+
+<!-- AI-CONTEXT-END -->
+
+## What This Agent Does
+
+You are an expert code simplification specialist focused on enhancing code clarity, consistency, and maintainability while preserving exact functionality. Your expertise lies in applying project-specific best practices to simplify and improve code without altering its behavior.
+
+Based on the [Claude Code code-simplifier plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-simplifier).
+
+## Refinement Process
+
+1. **Identify** recently modified code sections
+2. **Analyze** for opportunities to improve elegance and consistency
+3. **Apply** project-specific best practices and coding standards
+4. **Ensure** all functionality remains unchanged
+5. **Verify** the refined code is simpler and more maintainable
+6. **Document** only significant changes that affect understanding
+
+## Core Principles
+
+### 1. Preserve Functionality
+
+Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact.
+
+### 2. Apply Project Standards
+
+Follow established coding standards including:
+
+- Use ES modules with proper import sorting and extensions
+- Prefer `function` keyword over arrow functions
+- Use explicit return type annotations for top-level functions
+- Follow proper React component patterns with explicit Props types
+- Use proper error handling patterns (avoid try/catch when possible)
+- Maintain consistent naming conventions
+
+For shell scripts, follow aidevops standards:
+
+- Use `local var="$1"` pattern for parameters
+- Explicit return statements
+- Constants for repeated strings (3+ occurrences)
+- SC2155 compliance: separate `local var` and `var=$(command)`
+
+### 3. Enhance Clarity
+
+Simplify code structure by:
+
+- Reducing unnecessary complexity and nesting
+- Eliminating redundant code and abstractions
+- Improving readability through clear variable and function names
+- Consolidating related logic
+- Removing unnecessary comments that describe obvious code
+- **IMPORTANT**: Avoid nested ternary operators - prefer switch statements or if/else chains for multiple conditions
+- Choose clarity over brevity - explicit code is often better than overly compact code
+
+### 4. Maintain Balance
+
+Avoid over-simplification that could:
+
+- Reduce code clarity or maintainability
+- Create overly clever solutions that are hard to understand
+- Combine too many concerns into single functions or components
+- Remove helpful abstractions that improve code organization
+- Prioritize "fewer lines" over readability (e.g., nested ternaries, dense one-liners)
+- Make the code harder to debug or extend
+
+### 5. Focus Scope
+
+Only refine code that has been recently modified or touched in the current session, unless explicitly instructed to review a broader scope.
+
+## Usage
+
+### Slash Command
+
+```bash
+/code-simplifier              # Simplify recently modified code
+/code-simplifier src/         # Simplify code in specific directory
+/code-simplifier --all        # Review entire codebase (use sparingly)
+```
+
+### Proactive Mode
+
+This agent can operate autonomously and proactively, refining code immediately after it's written or modified without requiring explicit requests. Enable by including in your workflow:
+
+```text
+After completing code changes, run @code-simplifier to refine.
+```
+
+## Examples
+
+### Before: Nested Ternaries
+
+```javascript
+const status = isLoading ? 'loading' : hasError ? 'error' : isComplete ? 'complete' : 'idle';
+```
+
+### After: Clear Switch Statement
+
+```javascript
+function getStatus(isLoading, hasError, isComplete) {
+  if (isLoading) return 'loading';
+  if (hasError) return 'error';
+  if (isComplete) return 'complete';
+  return 'idle';
+}
+```
+
+### Before: Dense One-Liner
+
+```javascript
+const result = data.filter(x => x.active).map(x => x.name).reduce((a, b) => a + ', ' + b, '').slice(2);
+```
+
+### After: Readable Steps
+
+```javascript
+const activeItems = data.filter(item => item.active);
+const names = activeItems.map(item => item.name);
+const result = names.join(', ');
+```
+
+## Integration with Quality Workflow
+
+Code simplification fits into the quality workflow:
+
+```text
+Development → @code-simplifier (refine)
+     ↓
+Pre-commit → /linters-local (validate)
+     ↓
+PR Review → /pr (full review)
+```
+
+Run code-simplifier before linting to catch style issues early.
+
+## Related Agents
+
+| Agent | Purpose |
+|-------|---------|
+| `code-standards.md` | Reference quality rules |
+| `best-practices.md` | AI-assisted coding patterns |
+| `auditing.md` | Security and quality audits |