Initial commit

references/agent-specific-commands.md

@@ -0,0 +1,260 @@
+# CLI Agent Commands Reference
+
+## Claude Code CLI (Anthropic)
+
+### Basic Headless Usage
+```bash
+claude -p "Your prompt here"
+```
+
+### Key Flags
+- `-p` or `--prompt`: Execute one-shot prompt and exit
+- `--add-dir <path>`: Add additional directory to workspace context
+- `--model <model>`: Specify model (optional)
+
+### Examples
+```bash
+# Basic one-shot query
+claude -p "Explain this function"
+
+# Pipe input to Claude
+cat error.log | claude -p "Summarize these errors"
+
+# Multiple directory context
+claude -p "Review the API design" --add-dir ../api-specs
+```
+
+### Authentication
+Requires configured API key or OAuth token. Run `claude --help` for setup options.
+
+---
+
+## OpenAI Codex CLI
+
+### Basic Headless Usage
+```bash
+codex exec "Your prompt here"
+codex e "Your prompt here"  # Short alias
+```
+
+### Key Flags
+- `--full-auto`: Unattended operation with workspace-write sandbox
+- `--dangerously-bypass-approvals-and-sandbox` or `--yolo`: Complete hands-off mode (use carefully)
+- `--skip-git-repo-check`: Allow execution outside Git repositories
+- `--cd <path>`: Set working directory
+- `--model <model>` or `-m`: Specify model (e.g., `-m gpt-5-codex`)
+
+### Examples
+```bash
+# Automated refactoring
+codex exec --full-auto "Update all README links to HTTPS"
+
+# Outside Git repo
+codex exec --skip-git-repo-check --full-auto "Create hello world HTML"
+
+# Different working directory
+codex exec --cd /path/to/project "Fix failing tests"
+```
+
+### Input Methods
+```bash
+# Pipe prompt from file
+codex exec - < prompt.txt
+
+# Standard input
+echo "Review this code" | codex exec -
+```
+
+---
+
+## Google Gemini CLI
+
+### Basic Headless Usage
+```bash
+gemini --prompt "Your prompt here"
+gemini -p "Your prompt here"  # Short form
+```
+
+### Key Flags
+- `--prompt` or `-p`: Execute prompt and exit
+- `--output-format <format>`: Output format (json, stream-json)
+- `--model <model>`: Specify model variant
+
+### Examples
+```bash
+# Basic query
+gemini -p "Summarize API design in this repo"
+
+# Pipe input with prompt
+echo "List TODO comments" | gemini -p "-"
+
+# JSON output
+gemini -p "Analyze code structure" --output-format json
+
+# Process file with instruction
+cat DESIGN.md | gemini -p "Improve this design document"
+```
+
+### Authentication
+Requires Google account authentication or API key setup.
+
+---
+
+## OpenCode CLI
+
+### Basic Headless Usage
+```bash
+opencode -p "Your prompt here"
+opencode --prompt "Your prompt here"
+```
+
+### Key Flags
+- `-p` or `--prompt`: Execute single prompt and exit
+- `-f <format>` or `--format`: Output format (json)
+- `-q` or `--quiet`: Suppress loading spinner
+- `--cwd <path>`: Set working directory
+
+### Examples
+```bash
+# Basic query
+opencode -p "Explain Go context usage"
+
+# JSON output
+opencode -p "How many files in project?" -f json
+
+# Quiet mode for scripting
+opencode -p "Review code" -q
+
+# Different working directory
+opencode -p "Analyze this project" --cwd /path/to/project
+```
+
+### Environment Setup
+Requires API keys for providers (OpenAI, Anthropic, etc.) in environment variables.
+
+---
+
+## Alibaba Qwen Code CLI
+
+### Basic Headless Usage
+```bash
+qwen -p "Your prompt here"
+```
+
+### Key Flags
+- `-p` or `--prompt`: Execute one-shot prompt
+- `--output-format <format>`: Output format (json)
+- `--model <model>`: Specify Qwen model variant
+- `--yolo`: Bypass confirmations (similar to other agents)
+
+### Examples
+```bash
+# Code review
+qwen -p "Review this code for potential bugs"
+
+# Generate tests
+qwen -p "Generate unit tests for utils.py"
+
+# Pipe diff for review
+git diff | qwen -p "Review this diff for errors"
+
+# JSON output
+qwen -p "List project files" --output-format json
+```
+
+### Authentication
+- First-time setup: Run `qwen` interactively to login with Qwen.ai OAuth
+- Cached credentials: Used automatically for subsequent `-p` calls
+- Local models: Set OPENAI_API_KEY and related env vars for local LLM servers
+
+---
+
+## Factory Droid CLI
+
+### Basic Headless Usage
+```bash
+droid exec "Your prompt here"
+```
+
+### Key Flags
+- `--auto <level>`: Set autonomy level (low, medium, high)
+- `--skip-permissions-unsafe`: Bypass all permission checks (use carefully)
+- `--cwd <path>`: Set working directory
+- `-f <file>`: Read prompt from file
+- `-o <format>`: Output format (json)
+
+### Autonomy Levels
+- **Default (no flag)**: Read-only mode, safe for analysis
+- `--auto low`: Allow low-risk file edits (documentation, simple refactors)
+- `--auto medium`: Allow development operations (install packages, run tests)
+- `--auto high`: Permit production-level changes (full access)
+
+### Examples
+```bash
+# Read-only analysis
+droid exec "List all TODO comments across the project"
+
+# Low-risk edits
+droid exec "Fix typos in README.md" --auto low
+
+# Development operations
+droid exec "Fix failing unit tests" --auto medium
+
+# High-risk changes
+droid exec "Implement OAuth2 migration" --auto high
+
+# Read prompt from file
+droid exec -f prompt.md
+
+# JSON output
+droid exec "Analyze codebase" -o json
+
+# Different working directory
+droid exec "Review this code" --cwd /path/to/project
+```
+
+### Safety Notes
+- Default mode is read-only for safety
+- Use `--skip-permissions-unsafe` only in sandboxed environments
+- Consider autonomy levels carefully based on use case
+
+---
+
+## Common Patterns
+
+### piping Input
+Most agents support piping input:
+```bash
+# Pipe file content
+cat file.txt | agent -p "Process this"
+
+# Pipe command output
+git log --oneline | agent -p "Summarize commits"
+```
+
+### Reading from Files
+```bash
+# Direct file reading (if supported)
+agent -f prompt.txt
+
+# Using cat and pipe
+cat prompt.txt | agent -p "-"
+```
+
+### JSON Output
+For scripting and automation:
+```bash
+# JSON output format
+agent -p "Query" --output-format json
+agent -p "Query" -f json
+agent -p "Query" -o json
+```
+
+### Automation Flags
+For completely unattended operation:
+```bash
+# Various automation flags per agent
+codex --full-auto "Task"
+droid --auto medium "Task"
+gemini --yolo "Task"  # if available
+```

references/api_reference.md

@@ -0,0 +1,34 @@
+# Reference Documentation for Headless Cli Agents
+
+This is a placeholder for detailed reference documentation.
+Replace with actual reference content or delete if not needed.
+
+Example real reference docs from other skills:
+- product-management/references/communication.md - Comprehensive guide for status updates
+- product-management/references/context_building.md - Deep-dive on gathering context
+- bigquery/references/ - API references and query examples
+
+## When Reference Docs Are Useful
+
+Reference docs are ideal for:
+- Comprehensive API documentation
+- Detailed workflow guides
+- Complex multi-step processes
+- Information too lengthy for main SKILL.md
+- Content that's only needed for specific use cases
+
+## Structure Suggestions
+
+### API Reference Example
+- Overview
+- Authentication
+- Endpoints with examples
+- Error codes
+- Rate limits
+
+### Workflow Guide Example
+- Prerequisites
+- Step-by-step instructions
+- Common patterns
+- Troubleshooting
+- Best practices

references/use-case-examples.md

@@ -0,0 +1,363 @@
+# CLI Agents Use Case Examples
+
+## CI/CD Pipeline Examples
+
+### GitHub Actions - Code Review
+
+```yaml
+name: AI Code Review
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  ai-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Claude Code CLI
+        run: |
+          curl -fsSL https://claude.ai/install.sh | sh
+          echo "$CLAUDE_API_KEY" | claude auth login
+        env:
+          CLAUDE_API_KEY: ${{ secrets.CLAUDE_API_KEY }}
+
+      - name: Review PR Changes
+        run: |
+          git diff origin/main...HEAD | claude -p "Review these changes for potential bugs, security issues, and best practices. Focus on: 1) Error handling 2) Performance 3) Security 4) Code quality"
+
+      - name: Check for TODO Comments
+        run: |
+          find . -name "*.py" -o -name "*.js" -o -name "*.ts" | xargs grep -l "TODO\|FIXME" | claude -p "Review these files containing TODO/FIXME comments and suggest implementation approaches"
+```
+
+### GitLab CI - Documentation Generation
+
+```yaml
+stages:
+  - analyze
+  - build
+
+code-analysis:
+  stage: analyze
+  image: node:18
+  before_script:
+    - npm install -g @anthropic-ai/claude-cli
+  script:
+    - |
+      claude -p "Generate comprehensive API documentation for this codebase. Focus on: 1) Endpoints 2) Request/response formats 3) Authentication 4) Error codes" > API_DOCUMENTATION.md
+      claude -p "Create a README with setup instructions, usage examples, and contribution guidelines" > README_ENHANCED.md
+  artifacts:
+    paths:
+      - API_DOCUMENTATION.md
+      - README_ENHANCED.md
+```
+
+### Jenkins Pipeline - Test Generation
+
+```groovy
+pipeline {
+    agent any
+
+    stages {
+        stage('AI Test Generation') {
+            steps {
+                script {
+                    sh '''
+                        # Generate unit tests for untested functions
+                        find src -name "*.py" -exec grep -L "def test_" {} \\; | codex exec --full-auto --skip-git-repo-check "Generate comprehensive unit tests for these files using pytest framework. Include edge cases and error handling."
+
+                        # Generate integration tests
+                        codex exec --full-auto "Create integration tests for the main API endpoints. Test authentication, data flow, and error scenarios."
+                    '''
+                }
+            }
+        }
+
+        stage('Run Tests') {
+            steps {
+                sh 'python -m pytest'
+            }
+        }
+    }
+}
+```
+
+## Shell Scripting Examples
+
+### Code Quality Check Script
+
+```bash
+#!/bin/bash
+
+# quality-check.sh - Automated code quality analysis
+
+set -e
+
+echo "🔍 Running AI-powered code quality checks..."
+
+# Check for security vulnerabilities
+echo "🔒 Checking for security issues..."
+find . -name "*.py" -o -name "*.js" -o -name "*.ts" | \
+  xargs grep -l "password\|secret\|token\|key" | \
+  claude -p "Analyze these files for potential security vulnerabilities. Look for: 1) Hardcoded credentials 2) Insecure data handling 3) Missing input validation 4) Authentication bypasses"
+
+# Check for performance issues
+echo "⚡ Analyzing performance patterns..."
+find . -name "*.py" | head -10 | \
+  claude -p "Review these files for performance bottlenecks. Focus on: 1) Database queries 2) Loops and recursion 3) Memory usage 4) Async operations"
+
+# Generate quality report
+echo "📋 Generating quality report..."
+claude -p "Create a comprehensive code quality report summarizing: 1) Security findings 2) Performance issues 3) Code style violations 4) Recommendations for improvement" > QUALITY_REPORT.md
+
+echo "✅ Quality check completed. See QUALITY_REPORT.md"
+```
+
+### Automated Refactoring Script
+
+```bash
+#!/bin/bash
+
+# refactor.sh - Automated code refactoring
+
+PROJECT_DIR=${1:-.}
+REFACTOR_TYPE=${2:-"general"}
+
+echo "🔧 Starting automated refactoring in $PROJECT_DIR..."
+
+cd "$PROJECT_DIR"
+
+case "$REFACTOR_TYPE" in
+  "security")
+    codex exec --full-auto "Review all files for security issues and implement fixes: 1) Input sanitization 2) Output encoding 3) Authentication improvements 4) Secure headers"
+    ;;
+  "performance")
+    codex exec --full-auto "Optimize code for performance: 1) Database query optimization 2) Caching strategies 3) Async/await patterns 4) Resource cleanup"
+    ;;
+  "documentation")
+    codex exec --full-auto "Add comprehensive documentation: 1) Function docstrings 2) Type hints 3) Usage examples 4) README updates"
+    ;;
+  *)
+    codex exec --full-auto "General code refactoring: 1) Improve naming conventions 2) Reduce complexity 3) Add error handling 4) Code organization"
+    ;;
+esac
+
+echo "✅ Refactoring completed"
+```
+
+### Dependency Update Script
+
+```bash
+#!/bin/bash
+
+# update-dependencies.sh - Smart dependency management
+
+echo "📦 Analyzing and updating dependencies..."
+
+# Check for security updates
+gemini -p "Analyze package.json/requirements.txt for security vulnerabilities and outdated dependencies. Suggest specific version updates with migration notes." > DEPENDENCY_ANALYSIS.md
+
+# Update packages (if safe)
+if [ "$1" = "--auto" ]; then
+  echo "🚀 Auto-updating dependencies..."
+  droid exec "Update all dependencies to latest safe versions. Create migration plan for breaking changes." --auto medium
+fi
+
+# Generate changelog
+claude -p "Create a changelog entry documenting dependency updates, security improvements, and potential breaking changes." > CHANGELOG.md
+
+echo "✅ Dependency analysis completed"
+```
+
+## Automation Workflow Examples
+
+### Pre-commit Hook
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+echo "🤖 Running AI pre-commit checks..."
+
+# Check commit message
+commit_msg=$(git log -1 --pretty=%B)
+echo "$commit_msg" | claude -p "Validate this commit message. Check for: 1) Clear description 2) Proper format 3) Issue references 4) Breaking change indicators"
+
+if [ $? -ne 0 ]; then
+  echo "❌ Commit message validation failed"
+  exit 1
+fi
+
+# Quick code review of staged changes
+git diff --cached | claude -p "Quick review of staged changes. Check for: 1) Obvious bugs 2) Syntax errors 3) Missing tests 4) Security issues"
+
+if [ $? -ne 0 ]; then
+  echo "❌ Code review found issues"
+  exit 1
+fi
+
+echo "✅ Pre-commit checks passed"
+```
+
+### Release Preparation Script
+
+```bash
+#!/bin/bash
+
+# prepare-release.sh - Automated release preparation
+
+VERSION=${1:-"patch"}
+RELEASE_BRANCH=${2:-"release"}
+
+echo "🚀 Preparing release for version bump: $VERSION"
+
+# Create release branch
+git checkout -b "$RELEASE_BRANCH"
+
+# Update version numbers
+codex exec --full-auto "Update all version numbers in the project for a $VERSION release: 1) package.json 2) __init__.py files 3) Docker files 4) Documentation"
+
+# Generate release notes
+git log --oneline $(git describe --tags --abbrev=0)..HEAD | \
+  qwen -p "Create comprehensive release notes from these commits. Categorize by: 1) Features 2) Bug fixes 3) Breaking changes 4) Security improvements" > RELEASE_NOTES.md
+
+# Update documentation
+droid exec "Update all documentation for new release: 1) API docs 2) README 3) Installation guides 4) Migration guides" --auto low
+
+echo "✅ Release preparation completed"
+echo "📋 Review RELEASE_NOTES.md and commit changes"
+```
+
+### Database Migration Helper
+
+```bash
+#!/bin/bash
+
+# migrate-db.sh - AI-assisted database migrations
+
+MIGRATION_NAME=${1:-"auto_migration"}
+
+echo "🗄️ Generating migration: $MIGRATION_NAME"
+
+# Analyze schema changes
+find models/ -name "*.py" | \
+  claude -p "Analyze these model files for schema changes since last migration. Identify: 1) New tables 2) Column changes 3) Index changes 4) Relationship updates"
+
+# Generate migration file
+codex exec --full-auto "Create a database migration file named ${MIGRATION_NAME}.py. Include: 1) Forward migration 2) Rollback migration 3) Data transformations 4) Safety checks"
+
+# Generate test data
+gemini -p "Generate test data and validation queries for the new migration. Include: 1) Sample records 2) Constraint tests 3) Performance test queries"
+
+echo "✅ Migration generated. Review and run: python manage.py migrate"
+```
+
+## Monitoring and Maintenance Examples
+
+### Log Analysis Script
+
+```bash
+#!/bin/bash
+
+# analyze-logs.sh - AI-powered log analysis
+
+LOG_FILE=${1:-"app.log"}
+TIMEFRAME=${2:-"24h"}
+
+echo "📊 Analyzing logs from $LOG_FILE (last $TIMEFRAME)..."
+
+# Extract errors and warnings
+grep -E "(ERROR|WARN|CRITICAL)" "$LOG_FILE" | \
+  qwen -p "Analyze these log entries for: 1) Error patterns 2) Root causes 3) Frequency analysis 4) Recommended fixes" > ERROR_ANALYSIS.md
+
+# Performance analysis
+grep -E "(slow|timeout|memory|performance)" "$LOG_FILE" | \
+  claude -p "Identify performance issues from these logs. Focus on: 1) Slow queries 2) Memory leaks 3) Timeout patterns 4) Resource bottlenecks" > PERFORMANCE_ISSUES.md
+
+# Generate summary
+gemini -p "Create an executive summary of log analysis including: 1) Critical issues 2) Performance impact 3) Security concerns 4) Action items" > LOG_SUMMARY.md
+
+echo "✅ Log analysis completed. Check *.md files"
+```
+
+### Health Check Automation
+
+```bash
+#!/bin/bash
+
+# health-check.sh - Automated system health analysis
+
+echo "🏥 Running AI-powered health checks..."
+
+# Code health
+find . -name "*.py" | head -20 | \
+  droid exec "Analyze code health indicators: 1) Code complexity 2) Test coverage gaps 3) Dead code 4) Anti-patterns" --auto low > CODE_HEALTH.md
+
+# Dependency health
+claude -p "Analyze project dependencies for: 1) Security vulnerabilities 2) License compliance 3) Version conflicts 4) Maintenance status" > DEPENDENCY_HEALTH.md
+
+# Architecture health
+gemini -p "Review project architecture for: 1) Design patterns 2) Coupling issues 3) Scalability concerns 4) Technical debt" > ARCHITECTURE_HEALTH.md
+
+# Generate actionable report
+claude -p "Create a prioritized action plan based on health checks. Include: 1) Critical fixes 2) Improvements 3) Technical debt roadmap 4) Resource allocation" > HEALTH_ACTION_PLAN.md
+
+echo "✅ Health check completed. Review generated reports"
+```
+
+## Integration Examples
+
+### Slack Integration
+
+```bash
+#!/bin/bash
+
+# slack-ai-notify.sh - Send AI analysis to Slack
+
+WEBHOOK_URL=${SLACK_WEBHOOK_URL}
+PROJECT_DIR=${1:-"."}
+
+cd "$PROJECT_DIR"
+
+# Analyze recent changes
+git diff HEAD~1 | \
+  claude -p "Analyze recent changes and create a concise summary for team notification. Include: 1) Key changes 2) Impact 3) Any action needed" > CHANGE_SUMMARY.txt
+
+# Send to Slack
+curl -X POST -H 'Content-type: application/json' \
+  --data "{\"text\":\"$(cat CHANGE_SUMMARY.txt)\"}" \
+  "$WEBHOOK_URL"
+
+echo "📢 AI summary sent to Slack"
+```
+
+### Email Reports
+
+```bash
+#!/bin/bash
+
+# email-ai-report.sh - Generate and email AI reports
+
+EMAIL=${1:-"team@example.com"}
+REPORT_TYPE=${2:-"weekly"}
+
+echo "📧 Generating $REPORT_TYPE report..."
+
+case "$REPORT_TYPE" in
+  "weekly")
+    git log --since="1 week ago" --oneline | \
+      qwen -p "Create a weekly development report. Include: 1) Features completed 2) Bugs fixed 3) Code quality metrics 4) Team achievements" > weekly_report.md
+    ;;
+  "security")
+    find . -name "*.py" -o -name "*.js" | \
+      claude -p "Generate a security audit report. Include: 1) Vulnerabilities found 2) Risk assessment 3) Remediation steps 4) Best practices" > security_report.md
+    ;;
+esac
+
+# Send email (using mail command or your preferred method)
+mail -s "AI-generated $REPORT_TYPE report" "$EMAIL" < "${REPORT_TYPE}_report.md"
+
+echo "✅ Report emailed to $EMAIL"
+```