aidevops 2.52.1 → 2.53.2

package/.agent/tools/git/github-actions.md

@@ -1,207 +0,0 @@
----
-description: GitHub Actions CI/CD workflow setup and management
-mode: subagent
-tools:
-  read: true
-  write: true
-  edit: true
-  bash: true
-  glob: true
-  grep: true
-  webfetch: true
-  task: true
----
-
-# GitHub Actions Setup Guide
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- **Workflow File**: `.github/workflows/code-quality.yml`
-- **Triggers**: Push to main/develop, PRs to main
-- **Jobs**: Framework validation, SonarCloud analysis, Codacy analysis
-- **Required Secrets**: `SONAR_TOKEN` (configured), `CODACY_API_TOKEN` (needs setup)
-- **Auto-Provided**: `GITHUB_TOKEN` by GitHub
-- **SonarCloud Dashboard**: https://sonarcloud.io/project/overview?id=marcusquinn_aidevops
-- **Codacy Dashboard**: https://app.codacy.com/gh/marcusquinn/aidevops
-- **Actions URL**: https://github.com/marcusquinn/aidevops/actions
-- **Add Secrets**: Repository Settings → Secrets and variables → Actions
-<!-- AI-CONTEXT-END -->
-
-## Automated Code Quality Analysis
-
-### Current GitHub Actions Status
-
-#### ✅ Configured and Working:
-
-- **SonarCloud Analysis**: ✅ Runs on every push and PR
-- **Framework Validation**: ✅ Validates repository structure
-- **Security Scanning**: ✅ Checks for hardcoded API keys
-
-#### Requires Setup:
-
-- **Codacy Analysis**: Requires `CODACY_API_TOKEN` secret
-
-## Required GitHub Repository Secrets
-
-### **1. SONAR_TOKEN (Already Configured)**
-
-- **Status**: ✅ **CONFIGURED**
-- **Purpose**: SonarCloud analysis in GitHub Actions
-- **Value**: Your SonarCloud API token
-- **Source**: https://sonarcloud.io/account/security
-
-### **2. CODACY_API_TOKEN (Needs Setup)**
-
-- **Status**: ❌ **NEEDS CONFIGURATION**
-- **Purpose**: Codacy analysis in GitHub Actions
-- **Value**: Your Codacy API token
-- **Source**: https://app.codacy.com/account/api-tokens
-
-## Setup Instructions
-
-### **Add Missing GitHub Secret:**
-
-1. **Go to Repository Settings**:
-
-   ```text
-   https://github.com/marcusquinn/aidevops/settings/secrets/actions
-   ```
-
-2. **Click "New repository secret"**
-
-3. **Add Codacy Secret**:
-   - **Name**: `CODACY_API_TOKEN`
-   - **Value**: Your Codacy API token (get from secure local storage)
-
-## Workflow Triggers
-
-### **Automatic Execution:**
-
-- **Push to main**: ✅ Triggers full analysis
-- **Push to develop**: ✅ Triggers full analysis
-- **Pull Request to main**: ✅ Triggers full analysis
-
-### **Analysis Jobs:**
-
-1. **Framework Validation**: Repository structure and security checks
-2. **SonarCloud Analysis**: Code quality, security, and maintainability
-3. **Codacy Analysis**: Code quality and complexity analysis
-
-## Viewing Results
-
-### **SonarCloud Dashboard:**
-
-```text
-https://sonarcloud.io/project/overview?id=marcusquinn_aidevops
-```
-
-### **Codacy Dashboard:**
-
-```text
-https://app.codacy.com/gh/marcusquinn/aidevops
-```
-
-### **GitHub Actions:**
-
-```text
-https://github.com/marcusquinn/aidevops/actions
-```
-
-## Workflow Configuration
-
-### **File**: `.github/workflows/code-quality.yml`
-
-#### **Key Features:**
-
-- **Multi-job workflow** with framework validation and code analysis
-- **Security scanning** to prevent API key exposure
-- **Conditional Codacy analysis** (runs only if token is configured)
-- **Comprehensive reporting** with links to analysis dashboards
-- **Fail-fast security** checks to prevent credential exposure
-
-#### **Environment Variables Used:**
-
-- `GITHUB_TOKEN`: Automatic (provided by GitHub)
-- `SONAR_TOKEN`: From repository secrets
-- `CODACY_API_TOKEN`: From repository secrets (optional)
-
-## Security Features
-
-### **Automated Security Checks:**
-
-- **API Key Detection**: Scans for hardcoded credentials
-- **Repository Structure**: Validates framework integrity
-- **Secret Management**: Uses GitHub Secrets for sensitive data
-
-### **Security Best Practices:**
-
-- **No secrets in code**: All API keys use GitHub Secrets
-- **Conditional execution**: Graceful handling of missing secrets
-- **Fail-fast security**: Stops workflow if security issues detected
-
-## Workflow Patterns
-
-### Handling Concurrent Push Failures
-
-When GitHub Actions workflows push to repositories, concurrent runs can cause push failures due to race conditions. Use these patterns for workflows that commit and push:
-
-#### Full Retry Pattern (Recommended for External Repos)
-
-```yaml
-# Retry loop to handle concurrent pushes (up to 3 attempts)
-for i in 1 2 3; do
-  echo "Push attempt $i..."
-  git pull --rebase origin main || true
-  if git push; then
-    echo "Push succeeded on attempt $i"
-    exit 0
-  fi
-  echo "Push failed, waiting before retry..."
-  sleep $((i * 5))  # Exponential backoff: 5s, 10s, 15s
-done
-
-echo "All push attempts failed"
-exit 1
-```
-
-#### Simple Pattern (For Same-Repo Auto-Fixes)
-
-```yaml
-# Pull with rebase to handle concurrent pushes, then push
-git pull --rebase origin main || true
-git push
-```
-
-#### When to Use Each Pattern
-
-| Scenario | Pattern | Rationale |
-|----------|---------|-----------|
-| Pushing to external repo | Full retry | Higher chance of conflicts |
-| Auto-fix commits to same repo | Simple | Usually succeeds |
-| Wiki sync | Full retry | Wiki can have manual edits |
-| Release workflows | Simple | Should be serialized anyway |
-
-#### Key Points
-
-- Always `git pull --rebase` before pushing to incorporate remote changes
-- Use `|| true` after pull to continue even if pull fails (empty repo, etc.)
-- Exponential backoff (`sleep $((i * 5))`) reduces collision probability
-- Exit with error after all retries fail to surface the issue
-
-## Next Steps
-
-1. **Add CODACY_API_TOKEN** to GitHub repository secrets
-2. **Push a commit** to trigger the workflow
-3. **Verify analysis results** in SonarCloud and Codacy dashboards
-4. **Monitor workflow runs** in GitHub Actions
-
-## Benefits
-
-- **Automated Quality Gates**: Every commit analyzed for quality
-- **Security Monitoring**: Prevents credential exposure
-- **Multi-Platform Analysis**: SonarCloud + Codacy coverage
-- **Professional Standards**: Industry-grade CI/CD pipeline
-
-**Your repository now has comprehensive automated code quality analysis running on every commit!**

package/.agent/tools/git/github-cli.md

@@ -1,223 +0,0 @@
----
-description: GitHub CLI (gh) for repos, PRs, issues, and actions
-mode: subagent
-tools:
-  read: true
-  write: false
-  edit: false
-  bash: true
-  glob: true
-  grep: true
-  webfetch: true
-  task: true
----
-
-# GitHub CLI Guide
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- **CLI Tool**: `gh` (GitHub CLI) - the official GitHub CLI
-- **Install**: `brew install gh` (macOS) | `apt install gh` (Ubuntu)
-- **Auth**: `gh auth login` (stores token in keyring)
-- **Status**: `gh auth status`
-- **Docs**: https://cli.github.com/manual
-
-**Common Commands**:
-
-```bash
-gh repo list                    # List your repos
-gh repo create NAME             # Create repo
-gh issue list                   # List issues
-gh issue create                 # Create issue
-gh pr list                      # List PRs
-gh pr create                    # Create PR
-gh pr merge                     # Merge PR
-gh release create TAG           # Create release
-gh release list                 # List releases
-```
-
-**Multi-Account**: `gh auth login` supports multiple accounts via keyring
-<!-- AI-CONTEXT-END -->
-
-## Overview
-
-The `gh` CLI is the official GitHub command-line tool. It handles authentication securely via your system keyring and provides comprehensive access to GitHub features. **Use `gh` directly rather than wrapper scripts.**
-
-## Installation
-
-```bash
-# macOS
-brew install gh
-
-# Ubuntu/Debian
-sudo apt install gh
-
-# Other platforms
-# See: https://cli.github.com/manual/installation
-```
-
-## Authentication
-
-```bash
-# Login (interactive - stores token in keyring)
-gh auth login
-
-# Check auth status
-gh auth status
-
-# Get current token (for scripts that need GITHUB_TOKEN)
-gh auth token
-```
-
-Authentication is stored securely in your system keyring. No need for `GITHUB_TOKEN` environment variable for normal `gh` operations.
-
-## Repository Management
-
-```bash
-# List your repositories
-gh repo list
-
-# Create new repository
-gh repo create my-repo --public --description "My project"
-
-# Clone a repository
-gh repo clone owner/repo
-
-# View repository info
-gh repo view owner/repo
-
-# Fork a repository
-gh repo fork owner/repo
-```
-
-## Issue Management
-
-```bash
-# List issues
-gh issue list
-gh issue list --state open --label bug
-
-# Create issue
-gh issue create --title "Bug report" --body "Description"
-
-# View issue
-gh issue view 123
-
-# Close issue
-gh issue close 123
-```
-
-## Pull Request Management
-
-```bash
-# List PRs
-gh pr list
-gh pr list --state open
-
-# Create PR
-gh pr create --title "Feature X" --body "Description"
-gh pr create --fill  # Auto-fill from commits
-
-# View PR
-gh pr view 123
-
-# Merge PR
-gh pr merge 123 --squash
-gh pr merge 123 --merge
-gh pr merge 123 --rebase
-```
-
-## Release Management
-
-```bash
-# Create release with auto-generated notes
-gh release create v1.2.3 --generate-notes
-
-# Create release with custom notes
-gh release create v1.2.3 --notes "Release notes here"
-
-# Create draft release
-gh release create v1.2.3 --draft --generate-notes
-
-# List releases
-gh release list
-
-# View latest release
-gh release view
-
-# Download release assets
-gh release download v1.2.3
-```
-
-## Workflow/Actions
-
-```bash
-# List workflow runs
-gh run list
-
-# View run details
-gh run view 123456
-
-# Watch a running workflow
-gh run watch
-
-# Re-run failed jobs
-gh run rerun 123456 --failed
-```
-
-## API Access
-
-```bash
-# Make API calls directly
-gh api repos/owner/repo
-gh api repos/owner/repo/issues
-
-# Create via API
-gh api repos/owner/repo/issues -f title="Bug" -f body="Details"
-```
-
-## Multi-Account Support
-
-The `gh` CLI supports multiple accounts:
-
-```bash
-# Login to additional account
-gh auth login
-
-# Switch between accounts
-gh auth switch
-
-# List authenticated accounts
-gh auth status
-```
-
-## Environment Variables
-
-For scripts that need a token:
-
-```bash
-# Get token from gh auth
-export GITHUB_TOKEN=$(gh auth token)
-
-# Or use GH_TOKEN (preferred by gh)
-export GH_TOKEN=$(gh auth token)
-```
-
-## Troubleshooting
-
-| Issue | Solution |
-|-------|----------|
-| "not logged in" | Run `gh auth login` |
-| "token expired" | Run `gh auth refresh` |
-| Wrong account | Run `gh auth switch` |
-| Need token for script | Use `$(gh auth token)` |
-
-## Best Practices
-
-1. **Use `gh` directly** - No wrapper scripts needed
-2. **Use keyring auth** - More secure than env vars
-3. **Use `--generate-notes`** - Auto-generate release notes from commits/PRs
-4. **Use `gh api`** - For advanced GitHub API access
-5. **Use `gh pr create --fill`** - Auto-fill PR details from commits

package/.agent/tools/git/gitlab-cli.md

@@ -1,190 +0,0 @@
----
-description: GitLab CLI (glab) for repos, MRs, issues, and pipelines
-mode: subagent
-tools:
-  read: true
-  write: false
-  edit: false
-  bash: true
-  glob: true
-  grep: true
-  webfetch: true
-  task: true
----
-
-# GitLab CLI Helper Documentation
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- **CLI Tool**: `glab` (GitLab CLI)
-- **Install**: `brew install glab` (macOS) | `apt install glab` (Ubuntu)
-- **Auth**: `glab auth login` (GitLab.com) | `glab auth login --hostname gitlab.company.com` (self-hosted)
-- **Config**: `configs/gitlab-cli-config.json`
-- **Script**: `.agent/scripts/gitlab-cli-helper.sh`
-- **Requires**: `jq` for JSON parsing
-
-**Commands**: `list-projects|create-project|delete-project|list-issues|create-issue|close-issue|list-mrs|create-mr|merge-mr|list-branches|create-branch`
-
-**Usage**: `./providers/gitlab-cli-helper.sh [command] [account] [args]`
-
-**Multi-Instance**: Supports GitLab.com + self-hosted via instance_url in config
-<!-- AI-CONTEXT-END -->
-
-## Overview
-
-The GitLab CLI Helper provides a comprehensive interface for managing GitLab projects, issues, merge requests, and branches directly from the command line. It leverages the `glab` CLI tool to offer a seamless experience for developers working with GitLab.com and self-hosted instances.
-
-## Prerequisites
-
-1. **GitLab CLI (`glab`)**: Must be installed.
-    - **macOS**: `brew install glab`
-    - **Ubuntu/Debian**: `sudo apt install glab`
-    - **Other**: See [GitLab CLI Installation](https://glab.readthedocs.io/en/latest/installation/)
-2. **`jq`**: JSON processor (required for configuration parsing).
-3. **Authentication**: You must authenticate `glab` with your GitLab instance(s).
-
-## Configuration
-
-The helper uses a JSON configuration file located at `configs/gitlab-cli-config.json`.
-
-### Setup
-
-1. Copy the template:
-
-    ```bash
-    cp configs/gitlab-cli-config.json.txt configs/gitlab-cli-config.json
-    ```
-
-2. Edit `configs/gitlab-cli-config.json` with your account details.
-
-### Multi-Account/Instance Support
-
-The configuration supports multiple accounts and instances (e.g., `primary` for GitLab.com, `work` for self-hosted).
-
-**1. Authenticate `glab`:**
-
-```bash
-# For GitLab.com
-glab auth login
-
-# For Self-Hosted
-glab auth login --hostname gitlab.company.com
-```
-
-**2. Update `configs/gitlab-cli-config.json`:**
-
-```json
-{
-  "accounts": {
-    "primary": {
-      "instance_url": "https://gitlab.com",
-      "owner": "your-username",
-      "default_visibility": "public"
-    },
-    "work": {
-      "instance_url": "https://gitlab.company.com",
-      "owner": "work-username",
-      "default_visibility": "private"
-    }
-  }
-}
-```
-
-## Usage
-
-Run the helper script:
-
-```bash
-./providers/gitlab-cli-helper.sh [command] [account] [arguments]
-```
-
-### Project Management
-
-- **List Projects**:
-
-    ```bash
-    ./providers/gitlab-cli-helper.sh list-projects primary
-    ```
-
-- **Create Project**:
-
-    ```bash
-    # Usage: create-project <account> <name> [desc] [visibility] [init]
-    ./providers/gitlab-cli-helper.sh create-project primary my-new-project "Description" private true
-    ```
-
-- **Get Project Details**:
-
-    ```bash
-    ./providers/gitlab-cli-helper.sh get-project primary my-new-project
-    ```
-
-- **Delete Project**:
-
-    ```bash
-    ./providers/gitlab-cli-helper.sh delete-project primary my-new-project
-    ```
-
-### Issue Management
-
-- **List Issues**:
-
-    ```bash
-    ./providers/gitlab-cli-helper.sh list-issues primary my-project opened
-    ```
-
-- **Create Issue**:
-
-    ```bash
-    ./providers/gitlab-cli-helper.sh create-issue primary my-project "Bug Title" "Issue description"
-    ```
-
-- **Close Issue**:
-
-    ```bash
-    ./providers/gitlab-cli-helper.sh close-issue primary my-project 1
-    ```
-
-### Merge Request Management
-
-- **List Merge Requests**:
-
-    ```bash
-    ./providers/gitlab-cli-helper.sh list-mrs primary my-project opened
-    ```
-
-- **Create Merge Request**:
-
-    ```bash
-    # Usage: create-mr <account> <project> <title> <source> [target] [desc]
-    ./providers/gitlab-cli-helper.sh create-mr primary my-project "Feature X" feature-branch main "Description"
-    ```
-
-- **Merge Merge Request**:
-
-    ```bash
-    # Usage: merge-mr <account> <project> <mr_number> [method]
-    ./providers/gitlab-cli-helper.sh merge-mr primary my-project 1 squash
-    ```
-
-### Branch Management
-
-- **List Branches**:
-
-    ```bash
-    ./providers/gitlab-cli-helper.sh list-branches primary my-project
-    ```
-
-- **Create Branch**:
-
-    ```bash
-    # Usage: create-branch <account> <project> <new_branch> [source_branch]
-    ./providers/gitlab-cli-helper.sh create-branch primary my-project feature-branch main
-    ```
-
-## Troubleshooting
-
-- **"GitLab CLI is not authenticated"**: Run `glab auth status` to check your login status for the configured hostname.
-- **"Instance URL not configured"**: Check `configs/gitlab-cli-config.json` and ensure the `instance_url` is correct for the account you are using.