proagents 1.0.0

package/proagents/approval-workflows/notifications.md

@@ -0,0 +1,320 @@
+# Approval Notifications
+
+Configure notifications for approval workflow events.
+
+---
+
+## Notification Events
+
+| Event | Description | Default |
+|-------|-------------|---------|
+| `approval_requested` | New approval needed | Notify approvers |
+| `approval_granted` | Approval given | Notify requester |
+| `approval_rejected` | Approval denied | Notify requester |
+| `approval_reminder` | Pending reminder | Notify approvers |
+| `approval_escalated` | Escalated to next level | Notify escalation target |
+| `approval_expired` | Timeout reached | Notify all parties |
+
+---
+
+## Configuration
+
+### Notification Setup
+
+```yaml
+approvals:
+  notifications:
+    enabled: true
+
+    # Default channels
+    default_channels:
+      - "email"
+      - "slack"
+
+    # Event-specific settings
+    events:
+      approval_requested:
+        channels: ["slack", "email"]
+        template: "approval_request"
+        priority: "high"
+
+      approval_granted:
+        channels: ["slack"]
+        template: "approval_granted"
+        priority: "normal"
+
+      approval_rejected:
+        channels: ["slack", "email"]
+        template: "approval_rejected"
+        priority: "high"
+
+      approval_reminder:
+        channels: ["slack"]
+        template: "approval_reminder"
+        schedule:
+          - after: "4h"
+          - after: "12h"
+          - after: "20h"
+```
+
+### Channel Configuration
+
+```yaml
+approvals:
+  notifications:
+    channels:
+      slack:
+        webhook_url_env: "SLACK_WEBHOOK_URL"
+        default_channel: "#approvals"
+
+        # Channel routing
+        routing:
+          security_review: "#security-approvals"
+          production_deploy: "#prod-approvals"
+
+      email:
+        smtp:
+          host: "smtp.company.com"
+          port: 587
+          from: "approvals@company.com"
+
+      teams:
+        webhook_url_env: "TEAMS_WEBHOOK_URL"
+
+      pagerduty:
+        api_key_env: "PAGERDUTY_API_KEY"
+        service_id: "P123ABC"
+        # Only for urgent approvals
+        events: ["approval_escalated"]
+```
+
+---
+
+## Notification Templates
+
+### Slack Templates
+
+```yaml
+approvals:
+  notifications:
+    templates:
+      approval_request:
+        slack:
+          blocks:
+            - type: "header"
+              text: "🔔 Approval Required"
+            - type: "section"
+              fields:
+                - "*Feature:*\n{{feature.name}}"
+                - "*Requester:*\n{{requester.name}}"
+                - "*Stage:*\n{{stage.name}}"
+            - type: "section"
+              text: "{{description}}"
+            - type: "actions"
+              elements:
+                - type: "button"
+                  text: "Review"
+                  url: "{{review_url}}"
+                  style: "primary"
+```
+
+### Email Templates
+
+```yaml
+approvals:
+  notifications:
+    templates:
+      approval_request:
+        email:
+          subject: "[Action Required] Approval needed: {{feature.name}}"
+          body: |
+            Hi {{approver.name}},
+
+            Your approval is required for:
+
+            **Feature:** {{feature.name}}
+            **Requester:** {{requester.name}}
+            **Stage:** {{stage.name}}
+
+            **Description:**
+            {{description}}
+
+            Please review and approve at:
+            {{review_url}}
+
+            This request will expire in {{timeout}}.
+
+            ---
+            ProAgents Approval System
+```
+
+---
+
+## Reminder Configuration
+
+### Reminder Schedule
+
+```yaml
+approvals:
+  notifications:
+    reminders:
+      enabled: true
+
+      schedule:
+        # First reminder
+        - after: "4h"
+          message: "Reminder: Approval pending for {{feature.name}}"
+
+        # Second reminder
+        - after: "12h"
+          message: "Second reminder: Approval still pending"
+          escalate: false
+
+        # Final reminder before escalation
+        - after: "20h"
+          message: "Final reminder: Will escalate in 4 hours"
+          escalate_warning: true
+
+      # Business hours only
+      business_hours:
+        enabled: true
+        start: "09:00"
+        end: "18:00"
+        timezone: "America/New_York"
+        skip_weekends: true
+```
+
+---
+
+## Escalation Notifications
+
+### Escalation Setup
+
+```yaml
+approvals:
+  notifications:
+    escalation:
+      # Notify when escalating
+      notify_original_approvers: true
+      notify_escalation_target: true
+      notify_requester: true
+
+      template:
+        subject: "⚠️ Escalated: {{feature.name}} approval"
+        message: |
+          This approval has been escalated due to timeout.
+
+          Original approvers: {{original_approvers}}
+          Escalated to: {{escalation_target}}
+          Pending since: {{pending_duration}}
+```
+
+---
+
+## Recipient Configuration
+
+### Dynamic Recipients
+
+```yaml
+approvals:
+  notifications:
+    recipients:
+      # Always notify
+      always:
+        - "{{requester.email}}"
+
+      # Based on stage
+      by_stage:
+        code_review:
+          - "{{codeowners}}"
+          - "@tech-leads"
+
+        security_review:
+          - "@security-team"
+
+        production_deploy:
+          - "@devops"
+          - "{{manager.email}}"
+
+      # Escalation chain
+      escalation:
+        - level: 1
+          recipients: ["@tech-leads"]
+        - level: 2
+          recipients: ["@engineering-managers"]
+        - level: 3
+          recipients: ["@directors"]
+```
+
+---
+
+## Notification Preferences
+
+### User Preferences
+
+```yaml
+approvals:
+  notifications:
+    user_preferences:
+      enabled: true
+
+      # Users can configure
+      configurable:
+        - channels      # Which channels to use
+        - frequency     # Immediate vs digest
+        - quiet_hours   # Do not disturb
+
+      defaults:
+        channels: ["slack", "email"]
+        frequency: "immediate"
+        quiet_hours:
+          enabled: false
+```
+
+### Digest Mode
+
+```yaml
+approvals:
+  notifications:
+    digest:
+      enabled: true
+
+      # Combine notifications
+      schedule: "0 9 * * *"  # Daily at 9 AM
+
+      template:
+        subject: "Daily Approval Summary"
+        include:
+          - pending_approvals
+          - completed_approvals
+          - upcoming_deadlines
+```
+
+---
+
+## Commands
+
+```bash
+# Test notification
+proagents approvals test-notification --event approval_requested
+
+# View notification history
+proagents approvals notifications --last 24h
+
+# Configure preferences
+proagents approvals preferences set --channel slack --frequency immediate
+
+# Mute notifications temporarily
+proagents approvals mute --duration 2h
+```
+
+---
+
+## Best Practices
+
+1. **Don't Over-Notify**: Balance urgency with noise
+2. **Use Right Channels**: Urgent → Slack/PagerDuty, Normal → Email
+3. **Clear Templates**: Include all needed context
+4. **Respect Time Zones**: Send during business hours
+5. **Allow Preferences**: Let users configure their notifications
+6. **Track Delivery**: Monitor notification delivery rates

package/proagents/automation/README.md

@@ -0,0 +1,38 @@
+# Automation
+
+Configure AI behavior and automated decision-making in the workflow.
+
+---
+
+## Overview
+
+Control how the AI makes decisions, handles ambiguity, and automates routine tasks.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Auto Decisions](./auto-decisions.md) | Configure automatic decision-making |
+| [AI Behavior Rules](./ai-behavior-rules.md) | Define AI behavior constraints |
+| [AI Prompt Injection](./ai-prompt-injection.md) | Custom context injection for AI |
+
+## Quick Start
+
+```yaml
+# proagents.config.yaml
+automation:
+  auto_decisions:
+    enabled: true
+    confidence_threshold: 0.8
+
+  behavior:
+    ask_before_destructive: true
+    prefer_existing_patterns: true
+```
+
+## Key Features
+
+- **Auto-Decisions**: Let AI make routine decisions automatically
+- **Behavior Rules**: Define constraints for AI actions
+- **Context Injection**: Add project-specific context to AI prompts
+- **Confidence Thresholds**: Control when AI asks vs decides

package/proagents/automation/ai-behavior-rules.md

@@ -0,0 +1,339 @@
+# AI Behavior Rules for Automation
+
+Instructions for AI to maintain uninterrupted workflow execution.
+
+---
+
+## Core Principle
+
+**NEVER ASK QUESTIONS DURING AUTOMATED WORKFLOWS**
+
+Instead of asking:
+- Check pre-configured decisions
+- Use inference rules
+- Apply defaults
+- Log the decision
+- Continue working
+
+---
+
+## Decision Resolution Flow
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ AI needs to make a decision                             │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  1. Check explicit config                               │
+│     └─ decisions.yaml has answer? → Use it             │
+│                                                         │
+│  2. Check project type defaults                         │
+│     └─ Project type defines it? → Use it               │
+│                                                         │
+│  3. Check codebase patterns                             │
+│     └─ Similar pattern exists? → Follow it             │
+│                                                         │
+│  4. Check inference rules                               │
+│     └─ Can infer from context? → Use inference         │
+│                                                         │
+│  5. Use global default                                  │
+│     └─ Default exists? → Use it                        │
+│                                                         │
+│  6. Use safest option                                   │
+│     └─ Pick most conservative choice                   │
+│                                                         │
+│  NEVER reach step 7: Ask user                           │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Rules for AI
+
+### Rule 1: No Questions in Full Automation
+
+```
+❌ WRONG:
+"Should I use REST or GraphQL for this API?"
+
+✅ CORRECT:
+[Check config: api_style = "rest"]
+"Creating REST API endpoint as per project configuration."
+[Continue working]
+```
+
+### Rule 2: State Decisions, Don't Ask
+
+```
+❌ WRONG:
+"Where should I put this component? Options:
+1. src/components/
+2. src/features/auth/components/"
+
+✅ CORRECT:
+"Placing component in src/components/auth/ following existing project structure."
+[Continue working]
+```
+
+### Rule 3: Log Uncertain Decisions
+
+```
+❌ WRONG:
+"I'm not sure if this should be a hook or a utility function. What do you think?"
+
+✅ CORRECT:
+"Creating as custom hook (useAuth) - matches similar patterns in codebase."
+[Log: decision=hook, confidence=medium, reason=pattern_match]
+[Continue working]
+```
+
+### Rule 4: Use Defaults for Ambiguous Situations
+
+```
+❌ WRONG:
+"There are multiple ways to implement this. Which approach do you prefer?"
+
+✅ CORRECT:
+"Implementing using [default approach] as per project settings."
+[Continue working]
+```
+
+### Rule 5: Follow Existing Patterns
+
+```
+❌ WRONG:
+"I see you have both class and functional components. Which should I use?"
+
+✅ CORRECT:
+[Analyze: 90% functional components]
+"Using functional component to match project conventions."
+[Continue working]
+```
+
+---
+
+## Decision Templates
+
+### When Creating Components
+
+```yaml
+auto_decide:
+  location: "src/components/[category]/"
+  style: "functional"
+  naming: "PascalCase"
+  test: "colocated"
+  export: "named"
+
+action:
+  1. Create component file
+  2. Create test file
+  3. Update index exports
+  4. Log decision
+  5. Continue
+```
+
+### When Creating API Endpoints
+
+```yaml
+auto_decide:
+  style: "{{config.api_style}}"
+  validation: "zod"
+  error_handling: "centralized"
+  documentation: "auto_generate"
+
+action:
+  1. Create route file
+  2. Create controller
+  3. Create service
+  4. Add validation
+  5. Generate docs
+  6. Log decision
+  7. Continue
+```
+
+### When Choosing Libraries
+
+```yaml
+auto_decide:
+  rule: "Use already installed, or project default"
+
+  priority:
+    1. Already in package.json
+    2. Project type default
+    3. Global default
+    4. Most popular stable option
+
+action:
+  1. Check package.json
+  2. Use found or default
+  3. Log decision
+  4. Continue
+```
+
+### When Naming Things
+
+```yaml
+auto_decide:
+  components: "PascalCase"
+  hooks: "useCamelCase"
+  services: "camelCaseService"
+  utils: "camelCase"
+  constants: "UPPER_SNAKE_CASE"
+  files:
+    components: "PascalCase.tsx"
+    others: "camelCase.ts"
+
+action:
+  1. Determine type
+  2. Apply naming rule
+  3. Continue
+```
+
+---
+
+## Confidence Levels
+
+When making auto-decisions, assess confidence:
+
+### High Confidence (Just do it)
+- Explicit config exists
+- Clear project pattern exists
+- Standard best practice
+
+```
+"Using Zustand for state management (configured in project settings)."
+[confidence: high]
+```
+
+### Medium Confidence (Do it, flag for review)
+- Inferred from context
+- Multiple valid options
+- Slight uncertainty
+
+```
+"Creating separate service file for API calls (inferred from similar features)."
+[confidence: medium, flagged_for_review: true]
+```
+
+### Low Confidence (Do safest, definitely flag)
+- No clear guidance
+- Novel situation
+- Potential impact
+
+```
+"Using default error handling pattern (no specific guidance found)."
+[confidence: low, flagged_for_review: true, requires_post_review: true]
+```
+
+---
+
+## Communication Style
+
+### During Execution
+
+```
+✅ DO:
+"Creating UserProfile component in src/components/user/..."
+"Adding Zod validation schema..."
+"Generating tests with 85% coverage target..."
+
+❌ DON'T:
+"Should I create this in components or features?"
+"Do you want me to add validation?"
+"What coverage target should I aim for?"
+```
+
+### Decision Announcements
+
+```
+Format:
+"[Action] [what] [where/how] [reason if non-obvious]"
+
+Examples:
+"Creating AuthService in src/services/ following existing service pattern."
+"Using React Query for server state as configured."
+"Adding error boundary wrapper (standard for page components)."
+```
+
+### Uncertainty Handling
+
+```
+Format:
+"[Action] using [choice] ([brief reason]). Flagged for review."
+
+Examples:
+"Implementing pagination using cursor-based approach (better for large datasets). Flagged for review."
+"Splitting into micro-components (file was getting large). Flagged for review."
+```
+
+---
+
+## Post-Workflow Summary
+
+After completing automated workflow, provide:
+
+```markdown
+## Workflow Complete
+
+### Summary
+- Feature: User Authentication
+- Files created: 12
+- Files modified: 3
+- Tests added: 8
+
+### Decisions Made
+| Decision | Choice | Confidence | Rule Applied |
+|----------|--------|------------|--------------|
+| State management | Zustand | High | Explicit config |
+| Component location | src/components/auth | High | Pattern match |
+| API style | REST | High | Explicit config |
+| Error handling | Error boundary | Medium | Inference |
+
+### Flagged for Review (2)
+1. **Token storage**: Used httpOnly cookies (security best practice)
+   - Alternative: localStorage (faster but less secure)
+
+2. **Session duration**: Set to 7 days
+   - Based on: Default config
+   - Consider: Shorter for sensitive apps
+
+### No Issues Found
+✅ All decisions within confidence thresholds
+✅ No blocking questions needed
+✅ Automation completed successfully
+```
+
+---
+
+## Emergency Override
+
+If AI truly cannot proceed without input:
+
+```yaml
+emergency_protocol:
+  condition: "Truly ambiguous AND high-impact decision"
+
+  actions:
+    1. Try harder to find a default
+    2. Use safest/most conservative option
+    3. Mark as "CRITICAL_REVIEW_NEEDED"
+    4. Continue with safest option
+    5. Do NOT block workflow
+
+  example:
+    situation: "Delete user data permanently vs soft delete"
+    action: "Use soft delete (safer), flag as CRITICAL_REVIEW_NEEDED"
+    reason: "Data deletion is irreversible, chose conservative option"
+```
+
+---
+
+## Slash Commands for AI
+
+| Command | Description |
+|---------|-------------|
+| `[AUTO-DECIDE]` | Marker in logs for auto-decisions |
+| `[FLAGGED]` | Decision flagged for review |
+| `[CONFIDENCE:HIGH/MEDIUM/LOW]` | Decision confidence level |
+| `[RULE:rule_name]` | Which rule was applied |