proagents 1.0.0

package/proagents/approval-workflows/approval-stages.md

@@ -0,0 +1,503 @@
+# Approval Stages
+
+Define and configure multi-stage approval workflows.
+
+---
+
+## Stage Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Approval Pipeline                         │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌────────┐  │
+│  │  Stage 1 │──▶│  Stage 2 │──▶│  Stage 3 │──▶│ Deploy │  │
+│  │  Review  │   │ Security │   │ Manager  │   │        │  │
+│  └──────────┘   └──────────┘   └──────────┘   └────────┘  │
+│                                                             │
+│  Each stage can have:                                       │
+│  • Required approvers                                       │
+│  • Auto-approval rules                                      │
+│  • Timeout settings                                         │
+│  • Escalation paths                                         │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Stage Configuration
+
+### Defining Stages
+
+```yaml
+approvals:
+  stages:
+    # Stage 1: Code Review
+    - name: "code_review"
+      display_name: "Code Review"
+      order: 1
+
+      # Who can approve
+      approvers:
+        roles: ["senior_developer", "tech_lead"]
+        teams: ["core-team"]
+        minimum_approvals: 1
+
+      # Conditions
+      conditions:
+        applies_to:
+          - "all_features"
+          - "all_bug_fixes"
+
+      # Timing
+      timeout: "24h"
+      reminder_after: "4h"
+
+    # Stage 2: Security Review
+    - name: "security_review"
+      display_name: "Security Review"
+      order: 2
+
+      approvers:
+        roles: ["security_engineer"]
+        teams: ["security-team"]
+        minimum_approvals: 1
+
+      conditions:
+        applies_when:
+          - "touches_auth_code"
+          - "touches_payment_code"
+          - "modifies_user_data"
+          - "adds_dependencies"
+
+      # Skip if not applicable
+      skip_if_not_applicable: true
+
+    # Stage 3: Manager Approval
+    - name: "manager_approval"
+      display_name: "Manager Approval"
+      order: 3
+
+      approvers:
+        roles: ["engineering_manager", "director"]
+        minimum_approvals: 1
+
+      conditions:
+        applies_when:
+          - "production_deployment"
+          - "breaking_change"
+          - "large_feature"
+```
+
+---
+
+## Stage Types
+
+### Sequential Stages
+
+```yaml
+approvals:
+  flow: "sequential"  # Stages must complete in order
+
+  stages:
+    - name: "review"
+      order: 1
+      # Must complete before stage 2
+
+    - name: "security"
+      order: 2
+      depends_on: ["review"]
+
+    - name: "manager"
+      order: 3
+      depends_on: ["security"]
+```
+
+### Parallel Stages
+
+```yaml
+approvals:
+  flow: "parallel"  # Some stages can run simultaneously
+
+  stages:
+    - name: "code_review"
+      order: 1
+      parallel_group: "technical"
+
+    - name: "security_review"
+      order: 1
+      parallel_group: "technical"
+      # Runs in parallel with code_review
+
+    - name: "manager_approval"
+      order: 2
+      depends_on: ["code_review", "security_review"]
+      # Runs after both parallel stages complete
+```
+
+### Conditional Stages
+
+```yaml
+approvals:
+  stages:
+    - name: "legal_review"
+      display_name: "Legal Review"
+
+      # Only applies under certain conditions
+      conditional: true
+
+      applies_when:
+        any:
+          - "changes_terms_of_service"
+          - "changes_privacy_policy"
+          - "adds_third_party_integration"
+
+        file_patterns:
+          - "src/legal/**"
+          - "docs/legal/**"
+          - "content/policies/**"
+
+      # If conditions not met, skip stage
+      skip_if_not_applicable: true
+```
+
+---
+
+## Approver Rules
+
+### Role-Based Approvers
+
+```yaml
+approvals:
+  stages:
+    - name: "technical_review"
+      approvers:
+        # Require specific roles
+        roles:
+          - "senior_developer"
+          - "tech_lead"
+          - "architect"
+
+        # Minimum approvals needed
+        minimum_approvals: 2
+
+        # All must approve
+        require_all: false
+
+        # Cannot approve own changes
+        exclude_author: true
+```
+
+### Team-Based Approvers
+
+```yaml
+approvals:
+  stages:
+    - name: "team_review"
+      approvers:
+        teams:
+          - name: "frontend-team"
+            applies_to: "src/frontend/**"
+          - name: "backend-team"
+            applies_to: "src/backend/**"
+          - name: "devops-team"
+            applies_to: "infrastructure/**"
+
+        # At least one from applicable team
+        minimum_approvals: 1
+```
+
+### Individual Approvers
+
+```yaml
+approvals:
+  stages:
+    - name: "architect_review"
+      approvers:
+        individuals:
+          - "alice@company.com"
+          - "bob@company.com"
+
+        # Require specific person
+        require_specific:
+          - user: "alice@company.com"
+            when: "architecture_change"
+```
+
+### CODEOWNERS Integration
+
+```yaml
+approvals:
+  stages:
+    - name: "codeowner_review"
+      approvers:
+        # Use CODEOWNERS file
+        from_codeowners: true
+
+        # Require codeowner approval
+        codeowner_required: true
+
+        # Additional approvers
+        additional_roles:
+          - "tech_lead"
+```
+
+---
+
+## Auto-Approval Rules
+
+### Automatic Approvals
+
+```yaml
+approvals:
+  stages:
+    - name: "code_review"
+
+      auto_approve:
+        enabled: true
+
+        conditions:
+          all:
+            - "all_tests_pass"
+            - "no_security_issues"
+            - "no_breaking_changes"
+            - "coverage_meets_threshold"
+
+          any:
+            - "documentation_only"
+            - "config_change_only"
+            - "test_files_only"
+
+        # File pattern rules
+        file_patterns:
+          auto_approve:
+            - "*.md"
+            - "docs/**"
+            - "*.test.ts"
+
+          never_auto_approve:
+            - "src/auth/**"
+            - "src/payments/**"
+            - "*.env*"
+```
+
+### Bot Approvals
+
+```yaml
+approvals:
+  stages:
+    - name: "automated_checks"
+
+      bot_approvals:
+        enabled: true
+
+        bots:
+          - name: "security-scanner"
+            approves_when: "no_vulnerabilities"
+
+          - name: "coverage-bot"
+            approves_when: "coverage >= 80%"
+
+          - name: "lint-bot"
+            approves_when: "no_lint_errors"
+```
+
+---
+
+## Timing & Escalation
+
+### Timeout Configuration
+
+```yaml
+approvals:
+  stages:
+    - name: "code_review"
+
+      timing:
+        # Maximum time for stage
+        timeout: "24h"
+
+        # Reminder before timeout
+        reminder_at:
+          - "4h"
+          - "12h"
+          - "20h"
+
+        # Business hours only
+        business_hours_only: true
+        business_hours:
+          start: "09:00"
+          end: "18:00"
+          timezone: "America/New_York"
+          days: ["mon", "tue", "wed", "thu", "fri"]
+```
+
+### Escalation Rules
+
+```yaml
+approvals:
+  stages:
+    - name: "manager_approval"
+
+      escalation:
+        enabled: true
+
+        levels:
+          - after: "24h"
+            escalate_to: ["director"]
+            action: "notify"
+
+          - after: "48h"
+            escalate_to: ["vp_engineering"]
+            action: "notify"
+
+          - after: "72h"
+            escalate_to: ["cto"]
+            action: "auto_approve_with_audit"
+
+        # Escalation message
+        message: |
+          Approval pending for {{feature.name}}
+          Awaiting since: {{pending_since}}
+          Original approvers: {{original_approvers}}
+```
+
+---
+
+## Stage Actions
+
+### Pre-Stage Actions
+
+```yaml
+approvals:
+  stages:
+    - name: "security_review"
+
+      pre_actions:
+        - type: "run_scan"
+          command: "security-scan"
+          must_pass: true
+
+        - type: "generate_report"
+          template: "security-report"
+
+        - type: "notify"
+          channel: "security-team"
+          message: "Security review required for {{feature.name}}"
+```
+
+### Post-Stage Actions
+
+```yaml
+approvals:
+  stages:
+    - name: "code_review"
+
+      post_actions:
+        on_approve:
+          - type: "update_status"
+            status: "review_complete"
+          - type: "notify"
+            message: "Code review approved"
+
+        on_reject:
+          - type: "update_status"
+            status: "changes_requested"
+          - type: "notify"
+            message: "Changes requested in code review"
+          - type: "assign_back"
+            to: "author"
+```
+
+---
+
+## Rejection Handling
+
+### Rejection Flow
+
+```yaml
+approvals:
+  stages:
+    - name: "code_review"
+
+      rejection:
+        # Require reason
+        require_reason: true
+
+        # Actions on rejection
+        actions:
+          - notify_author: true
+          - reset_stage: true
+          - create_task: true
+
+        # Re-review after changes
+        re_review:
+          required: true
+          same_reviewer: "preferred"
+
+        # Maximum rejections
+        max_rejections: 3
+        on_max_rejections: "escalate_to_manager"
+```
+
+### Rejection Reasons
+
+```yaml
+approvals:
+  rejection_reasons:
+    predefined:
+      - id: "code_quality"
+        label: "Code quality issues"
+      - id: "missing_tests"
+        label: "Missing or inadequate tests"
+      - id: "security_concern"
+        label: "Security concerns"
+      - id: "architecture"
+        label: "Architecture concerns"
+      - id: "documentation"
+        label: "Missing documentation"
+      - id: "other"
+        label: "Other (please specify)"
+
+    require_comment: true
+```
+
+---
+
+## Stage Dashboard
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Feature: user-authentication                                │
+│ Status: Awaiting Approval                                   │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Stage 1: Code Review                                        │
+│ Status: ✅ Approved                                          │
+│ Approved by: alice@company.com (2h ago)                     │
+│                                                             │
+│ Stage 2: Security Review                                    │
+│ Status: 🔄 Pending                                          │
+│ Awaiting: security-team                                     │
+│ Time remaining: 22h                                         │
+│                                                             │
+│ Stage 3: Manager Approval                                   │
+│ Status: ⏳ Waiting for previous stage                        │
+│                                                             │
+│ [Remind] [Escalate] [Skip (requires justification)]         │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Best Practices
+
+1. **Minimize Stages**: Only add necessary approval stages
+2. **Clear Criteria**: Define when each stage applies
+3. **Reasonable Timeouts**: Set realistic time limits
+4. **Auto-Approve When Possible**: Reduce manual overhead
+5. **Escalation Paths**: Always have escalation defined
+6. **Track Metrics**: Monitor approval times and bottlenecks