aios-core 2.1.0

package/.aios-core/development/tasks/ci-cd-configuration.md

@@ -0,0 +1,764 @@
+---
+id: ci-cd-configuration
+name: Configure CI/CD Pipeline
+agent: github-devops
+category: devops
+complexity: high
+tools:
+  - github-cli       # Manage workflows and repository settings
+  - coderabbit-free  # Automated code review (FREE tier)
+checklists:
+  - github-devops-checklist.md
+---
+
+# Configure CI/CD Pipeline
+
+## Purpose
+
+To set up a complete, production-ready CI/CD pipeline for a repository, including linting, testing, building, code review (CodeRabbit Free), and deployment automation.
+
+## Supported CI Providers
+
+- **GitHub Actions** (primary, recommended)
+- **GitLab CI/CD**
+- **CircleCI**
+- **Jenkins** (basic support)
+
+## Input
+
+### Required Parameters
+
+- **repository_path**: `string`
+  - **Description**: Local path or GitHub URL of the repository
+  - **Example**: `/path/to/project` or `https://github.com/user/repo`
+  - **Validation**: Must be valid Git repository
+
+- **ci_provider**: `string`
+  - **Description**: CI/CD provider to configure
+  - **Options**: `"github-actions"`, `"gitlab-ci"`, `"circleci"`, `"jenkins"`
+  - **Default**: `"github-actions"`
+
+- **project_type**: `string`
+  - **Description**: Type of project (determines pipeline stages)
+  - **Options**: `"nodejs"`, `"python"`, `"fullstack"`, `"monorepo"`
+  - **Required**: true
+
+### Optional Parameters
+
+- **testing_framework**: `string`
+  - **Description**: Primary testing framework
+  - **Examples**: `"jest"`, `"pytest"`, `"vitest"`, `"mocha"`
+  - **Auto-detect**: true (scans package.json or requirements.txt)
+
+- **deployment_target**: `string`
+  - **Description**: Where to deploy
+  - **Options**: `"vercel"`, `"netlify"`, `"aws"`, `"none"`
+  - **Default**: `"none"`
+
+- **enable_coderabbit**: `boolean`
+  - **Description**: Enable CodeRabbit Free for automated code review
+  - **Default**: `true`
+  - **Note**: **FREE tier** - No cost, no API keys needed for public repos
+
+- **branch_protection**: `boolean`
+  - **Description**: Enable branch protection rules
+  - **Default**: `true`
+  - **Rules**: Require PR, require status checks, no force push
+
+- **required_checks**: `array<string>`
+  - **Description**: Status checks that must pass
+  - **Default**: `["lint", "test", "build"]`
+
+- **secrets**: `object`
+  - **Description**: Environment secrets (will be stored securely)
+  - **Example**: `{ VERCEL_TOKEN: "xxx", DATABASE_URL: "postgres://..." }`
+
+## Output
+
+- **workflow_files**: `array<string>`
+  - **Description**: Created workflow/config files
+  - **Example**: `[".github/workflows/ci.yml", ".github/workflows/deploy.yml"]`
+
+- **branch_protection_rules**: `object`
+  - **Description**: Applied branch protection settings
+  - **Structure**: `{ branch, required_checks, enforce_admins, allow_force_push }`
+
+- **coderabbit_config**: `object` (if enabled)
+  - **Description**: CodeRabbit configuration
+  - **Structure**: `{ enabled: true, config_file: ".coderabbit.yaml", integration_status: "active" }`
+
+- **secrets_configured**: `array<string>`
+  - **Description**: List of secrets successfully stored
+  - **Note**: Values not included (security)
+
+- **pipeline_url**: `string`
+  - **Description**: URL to view pipeline runs
+  - **Example**: `"https://github.com/user/repo/actions"`
+
+- **README_section**: `string`
+  - **Description**: Markdown section to add to README.md
+  - **Content**: CI/CD badges, status, setup instructions
+
+## Process
+
+### Phase 1: Repository Analysis & Validation (2 min)
+
+1. **Validate Repository**
+   - Check if valid Git repository
+   - Verify remote origin exists
+   - Check CI provider compatibility
+
+2. **Detect Project Structure**
+   - Auto-detect project type (if not provided)
+   - Scan for package.json, requirements.txt, pom.xml, etc.
+   - Identify testing framework
+   - Identify build commands
+
+3. **Check Existing CI Configuration**
+   - Look for existing workflows
+   - Warn if overwriting: "⚠️ Found existing CI config. Backup created at: {path}"
+
+### Phase 2: CodeRabbit Free Setup (2 min) 🆓
+
+**Note**: CodeRabbit Free is **100% FREE** for public repositories. No API keys, no credit card, no costs.
+
+4. **Install CodeRabbit GitHub App**
+   - Guide user: "To enable CodeRabbit Free:
+     1. Visit: https://github.com/apps/coderabbitai
+     2. Click 'Install' (FREE for public repos)
+     3. Grant access to repository: {repo_name}
+     4. Return here when done"
+   - Wait for user confirmation
+   - Verify installation via GitHub API
+
+5. **Create CodeRabbit Configuration**
+   - Generate `.coderabbit.yaml`:
+     ```yaml
+     # CodeRabbit Free Configuration
+     # 🆓 FREE for public repositories - No costs, no limits
+     
+     language: "en-US"
+     
+     reviews:
+       profile: "chill"  # balanced review depth
+       request_changes_workflow: false
+       high_level_summary: true
+       poem: false
+       review_status: true
+       collapse_walkthrough: false
+       auto_review:
+         enabled: true
+         ignore_title_keywords:
+           - "WIP"
+           - "DO NOT REVIEW"
+       
+     chat:
+       auto_reply: true
+     
+     # Focus areas (adjust based on project type)
+     focus:
+       - security
+       - performance
+       - best_practices
+       - testing
+       - documentation
+     
+     # Ignore patterns
+     ignore:
+       - "**/*.min.js"
+       - "**/*.min.css"
+       - "**/dist/**"
+       - "**/build/**"
+       - "**/.next/**"
+       - "**/node_modules/**"
+       - "**/.git/**"
+     ```
+   - Commit and push `.coderabbit.yaml`
+   - Log: "✅ CodeRabbit Free configured (Focus: security, performance, best practices)"
+
+6. **Add CodeRabbit Commands to README**
+   - Document available commands:
+     ```markdown
+     ## Code Review (CodeRabbit Free 🆓)
+     
+     **Automatic Reviews**: CodeRabbit automatically reviews all PRs
+     
+     **Manual Commands** (comment on PR):
+     - `@coderabbitai review` - Request full review
+     - `@coderabbitai summary` - Get PR summary
+     - `@coderabbitai resolve` - Mark suggestions as resolved
+     - `@coderabbitai help` - Show available commands
+     
+     **Local Pre-Commit Check** (optional):
+     ```bash
+     # Install CodeRabbit CLI (optional, for local checks)
+     npm install -g @coderabbitai/cli
+     
+     # Run pre-commit review
+     coderabbit --prompt-only -t uncommitted
+     ```
+     
+     [CodeRabbit Docs](https://docs.coderabbit.ai)
+     ```
+
+### Phase 3: GitHub Actions Workflow Creation (5 min)
+
+7. **Create Lint + Test + Build Workflow**
+   - Generate `.github/workflows/ci.yml`:
+
+     ```yaml
+     name: CI Pipeline
+     
+     on:
+       push:
+         branches: [ main, develop ]
+       pull_request:
+         branches: [ main, develop ]
+     
+     jobs:
+       lint:
+         runs-on: ubuntu-latest
+         steps:
+           - uses: actions/checkout@v4
+           
+           - name: Setup Node.js
+             uses: actions/setup-node@v4
+             with:
+               node-version: '20'
+               cache: 'npm'
+           
+           - name: Install dependencies
+             run: npm ci
+           
+           - name: Run linter
+             run: npm run lint
+       
+       test:
+         runs-on: ubuntu-latest
+         needs: lint
+         steps:
+           - uses: actions/checkout@v4
+           
+           - name: Setup Node.js
+             uses: actions/setup-node@v4
+             with:
+               node-version: '20'
+               cache: 'npm'
+           
+           - name: Install dependencies
+             run: npm ci
+           
+           - name: Run tests
+             run: npm test -- --coverage
+           
+           - name: Upload coverage
+             uses: codecov/codecov-action@v3
+             with:
+               files: ./coverage/coverage-final.json
+       
+       build:
+         runs-on: ubuntu-latest
+         needs: test
+         steps:
+           - uses: actions/checkout@v4
+           
+           - name: Setup Node.js
+             uses: actions/setup-node@v4
+             with:
+               node-version: '20'
+               cache: 'npm'
+           
+           - name: Install dependencies
+             run: npm ci
+           
+           - name: Build project
+             run: npm run build
+           
+           - name: Upload build artifacts
+             uses: actions/upload-artifact@v3
+             with:
+               name: build
+               path: dist/
+     ```
+
+8. **Create Deployment Workflow** (if deployment_target provided)
+   - Generate `.github/workflows/deploy.yml`:
+
+     ```yaml
+     name: Deploy
+     
+     on:
+       push:
+         branches: [ main ]
+       workflow_dispatch:
+     
+     jobs:
+       deploy:
+         runs-on: ubuntu-latest
+         environment: production
+         steps:
+           - uses: actions/checkout@v4
+           
+           - name: Setup Node.js
+             uses: actions/setup-node@v4
+             with:
+               node-version: '20'
+               cache: 'npm'
+           
+           - name: Install dependencies
+             run: npm ci
+           
+           - name: Build
+             run: npm run build
+           
+           - name: Deploy to {deployment_target}
+             uses: {deployment_action}
+             with:
+               token: ${{ secrets.DEPLOY_TOKEN }}
+     ```
+
+### Phase 4: Branch Protection Rules (3 min)
+
+9. **Configure Branch Protection** (if enabled)
+   - Use GitHub API to set rules on `main`:
+     - Require pull request reviews (1 approval)
+     - Require status checks to pass:
+       - `lint`
+       - `test`
+       - `build`
+       - `coderabbitai` (CodeRabbit review)
+     - Enforce for administrators: false (for emergency fixes)
+     - Require linear history: true
+     - Allow force pushes: false
+     - Allow deletions: false
+
+10. **Store Secrets** (if provided)
+    - Use GitHub CLI to set secrets:
+      ```bash
+      gh secret set VERCEL_TOKEN --body="xxx"
+      gh secret set DATABASE_URL --body="postgres://..."
+      ```
+    - Verify secrets stored: `gh secret list`
+
+### Phase 5: Documentation & Testing (3 min)
+
+11. **Update README.md**
+    - Add CI/CD badges:
+      ```markdown
+      [![CI Pipeline](https://github.com/user/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/user/repo/actions/workflows/ci.yml)
+      [![CodeRabbit](https://img.shields.io/badge/CodeRabbit-Free-brightgreen)](https://github.com/apps/coderabbitai)
+      ```
+    - Add CI/CD section (from output)
+
+12. **Create Test PR**
+    - Create branch: `ci-cd-test-{timestamp}`
+    - Make trivial change (e.g., update README)
+    - Push and create PR
+    - Verify:
+      - CI workflow triggers
+      - All checks run
+      - CodeRabbit reviews PR
+      - Branch protection enforced
+    - Close PR after validation
+
+13. **Generate Setup Report**
+    - Document what was configured
+    - List workflow files created
+    - Show pipeline URL
+    - Confirm CodeRabbit active
+    - List next steps
+
+## Checklist
+
+### Pre-conditions
+
+- [ ] Repository is valid Git repository
+  - **Validation**: `.git` directory exists
+  - **Error**: "Not a Git repository"
+
+- [ ] CI provider is supported
+  - **Validation**: `ci_provider in ["github-actions", "gitlab-ci", "circleci", "jenkins"]`
+  - **Error**: "CI provider '{provider}' not supported"
+
+- [ ] Project has package.json or equivalent
+  - **Validation**: File exists at root
+  - **Error**: "Cannot detect project type. Add package.json or specify project_type manually"
+
+### Post-conditions
+
+- [ ] Workflow files created and committed
+  - **Validation**: Files exist and are tracked by Git
+  - **Test**: `git ls-files | grep -E "\.github/workflows|\.gitlab-ci\.yml"`
+
+- [ ] CodeRabbit configuration valid (if enabled)
+  - **Validation**: `.coderabbit.yaml` is valid YAML
+  - **Test**: `yamllint .coderabbit.yaml`
+
+- [ ] Branch protection active (if enabled)
+  - **Validation**: GitHub API returns protection rules
+  - **Test**: `gh api repos/{owner}/{repo}/branches/main/protection`
+
+- [ ] Test PR passes all checks
+  - **Validation**: All required checks green
+  - **Manual Check**: true
+
+### Acceptance Criteria
+
+- [ ] CI pipeline runs on every push
+  - **Type**: acceptance
+  - **Test**: Push to branch → workflow triggers
+
+- [ ] CodeRabbit reviews all PRs automatically (if enabled)
+  - **Type**: acceptance
+  - **Manual Check**: true
+  - **Test**: Create PR → CodeRabbit comments within 2 min
+
+- [ ] Branch protection prevents direct pushes to main
+  - **Type**: acceptance
+  - **Test**: Try `git push origin main` → rejected
+
+## Templates
+
+### README CI/CD Section
+
+```markdown
+## CI/CD Pipeline
+
+This repository uses automated CI/CD with {ci_provider}.
+
+### Status
+
+[![CI Pipeline](https://github.com/{owner}/{repo}/actions/workflows/ci.yml/badge.svg)](https://github.com/{owner}/{repo}/actions/workflows/ci.yml)
+{deployment_badge if applicable}
+
+### Pipeline Stages
+
+1. **Lint**: ESLint + Prettier
+2. **Test**: {testing_framework} with coverage
+3. **Build**: Production build
+{4. **Deploy**: Automatic deployment to {deployment_target} (main branch only) if applicable}
+
+### Code Review (CodeRabbit Free 🆓)
+
+Every PR is automatically reviewed by [CodeRabbit](https://github.com/apps/coderabbitai):
+- Security vulnerabilities
+- Performance issues
+- Best practices
+- Test coverage
+- Documentation
+
+**Commands** (comment on PR):
+- `@coderabbitai review` - Request review
+- `@coderabbitai summary` - Get summary
+- `@coderabbitai resolve` - Mark as resolved
+
+### Branch Protection
+
+- `main` branch requires:
+  - ✅ 1 PR approval
+  - ✅ All CI checks passing
+  - ✅ CodeRabbit review complete
+  - ❌ No direct pushes
+  - ❌ No force pushes
+
+### Setup Instructions
+
+1. Clone repository
+2. Install dependencies: `npm install`
+3. Run tests locally: `npm test`
+4. Create feature branch: `git checkout -b feature/my-feature`
+5. Make changes and commit
+6. Push and create PR
+7. Wait for CI + CodeRabbit review
+8. Merge after approval
+```
+
+## Tools
+
+- **github-cli**:
+  - **Version**: 2.0.0
+  - **Used For**: Manage workflows, secrets, branch protection
+  - **Required**: true (for GitHub Actions)
+
+- **coderabbit-free**:
+  - **Version**: Latest (GitHub App)
+  - **Used For**: Automated code review on every PR
+  - **Cost**: $0 (FREE for public repositories)
+  - **Setup**: Install GitHub App (one-time, 2 minutes)
+  - **Features**:
+    - Automatic PR reviews
+    - Security scanning
+    - Performance analysis
+    - Best practices checks
+    - Interactive chat
+  - **Limitations**: None for open-source (FREE tier is full-featured)
+
+## Performance
+
+- **Duration Expected**: 15 minutes (including CodeRabbit setup)
+- **Cost Estimated**: $0 (CodeRabbit Free is free, GitHub Actions has 2,000 free minutes/month)
+- **Cacheable**: false (configuration is per-repository)
+- **Parallelizable**: false (sequential setup required)
+
+## Error Handling
+
+- **Strategy**: retry + fallback
+- **Fallback**: If CodeRabbit setup fails, continue without it (can add later)
+- **Retry**:
+  - **Max Attempts**: 3
+  - **Backoff**: exponential
+  - **Backoff MS**: 2000
+- **Abort Workflow**: false (continue even if optional features fail)
+- **Notification**: log + setup report
+
+## Metadata
+
+- **Story**: Epic 10 (Critical Dependency Resolution)
+- **Version**: 1.0.0
+- **Dependencies**: `github-cli` tool
+- **Author**: Brad Frost Clone
+- **Created**: 2025-11-13
+- **Updated**: 2025-11-13
+- **Breaking Changes**: None (new task)
+
+---
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: ciCdConfiguration()
+responsável: Gage (Automator)
+responsavel_type: Agente
+atomic_layer: Organism
+
+**Entrada:**
+- campo: task
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must be registered task
+
+- campo: parameters
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Valid task parameters
+
+- campo: mode
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: yolo|interactive|pre-flight
+
+**Saída:**
+- campo: execution_result
+  tipo: object
+  destino: Memory
+  persistido: false
+
+- campo: logs
+  tipo: array
+  destino: File (.ai/logs/*)
+  persistido: true
+
+- campo: state
+  tipo: object
+  destino: State management
+  persistido: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Task is registered; required parameters provided; dependencies met
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check task is registered; required parameters provided; dependencies met
+    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Task completed; exit code 0; expected outputs created
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify task completed; exit code 0; expected outputs created
+    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Task completed as expected; side effects documented
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert task completed as expected; side effects documented
+    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
+```
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** execute-task.js
+  - **Purpose:** Generic task execution wrapper
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/execute-task.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Task Not Found
+   - **Cause:** Specified task not registered in system
+   - **Resolution:** Verify task name and registration
+   - **Recovery:** List available tasks, suggest similar
+
+2. **Error:** Invalid Parameters
+   - **Cause:** Task parameters do not match expected schema
+   - **Resolution:** Validate parameters against task definition
+   - **Recovery:** Provide parameter template, reject execution
+
+3. **Error:** Execution Timeout
+   - **Cause:** Task exceeds maximum execution time
+   - **Resolution:** Optimize task or increase timeout
+   - **Recovery:** Kill task, cleanup resources, log state
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 5-15 min (estimated)
+cost_estimated: $0.003-0.010
+token_usage: ~3,000-10,000 tokens
+```
+
+**Optimization Notes:**
+- Break into smaller workflows; implement checkpointing; use async processing where possible
+
+---
+
+
+## Usage Examples
+
+### Example 1: Node.js Project with CodeRabbit
+
+```bash
+aios activate Otto  # github-devops agent
+aios ci-cd setup \
+  --repo="." \
+  --provider="github-actions" \
+  --type="nodejs" \
+  --enable-coderabbit=true \
+  --deploy="vercel"
+```
+
+**Output**: Complete CI/CD with CodeRabbit Free, Vercel deployment
+
+### Example 2: Python Project (GitLab CI)
+
+```bash
+aios ci-cd setup \
+  --repo="/path/to/python-project" \
+  --provider="gitlab-ci" \
+  --type="python" \
+  --testing="pytest"
+```
+
+**Output**: GitLab CI pipeline with pytest
+
+### Example 3: Monorepo with Turborepo
+
+```bash
+aios ci-cd setup \
+  --repo="." \
+  --provider="github-actions" \
+  --type="monorepo" \
+  --enable-coderabbit=true \
+  --branch-protection=true
+```
+
+**Output**: Optimized monorepo pipeline with caching
+
+---
+
+## CodeRabbit Free: Key Benefits 🆓
+
+1. **Zero Cost**: FREE forever for public repos
+2. **No Setup Complexity**: Just install GitHub App (2 minutes)
+3. **Automatic Reviews**: Every PR reviewed within minutes
+4. **Security Focus**: Catches vulnerabilities early
+5. **Performance Insights**: Identifies bottlenecks
+6. **Best Practices**: Enforces code quality standards
+7. **Interactive**: Chat with CodeRabbit about suggestions
+
+**Why CodeRabbit Free?**
+- Competitor (Copilot, CodeGuru) costs $10-19/month/user
+- CodeRabbit Free: $0 for open-source
+- Better security coverage than most paid tools
+- Integrated with GitHub (no external tools needed)
+
+---
+
+**Related Tasks:**
+- `release-management` - Automate releases after CI passes
+- `pr-automation` - Help users create PRs with proper format
+- `setup-repository` - Initialize repository with best practices
+