proagents 1.6.20 → 1.6.21

package/.proagents/pm-integration/sync-config.md

@@ -1,533 +0,0 @@
-# Synchronization Configuration
-
-Configure how ProAgents syncs with project management platforms.
-
----
-
-## Sync Overview
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Sync Architecture                         │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  ProAgents                         PM Platform              │
-│  ┌─────────┐                      ┌─────────┐              │
-│  │ Feature │ ──── Push ────────►  │  Issue  │              │
-│  │  State  │ ◄─── Pull ─────────  │  State  │              │
-│  └─────────┘                      └─────────┘              │
-│       │                                │                    │
-│       │         ┌─────────┐           │                    │
-│       └────────►│  Sync   │◄──────────┘                    │
-│                 │ Engine  │                                 │
-│                 └─────────┘                                 │
-│                      │                                      │
-│              ┌───────┴───────┐                             │
-│              │ Conflict      │                             │
-│              │ Resolution    │                             │
-│              └───────────────┘                             │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Sync Modes
-
-### Push Mode (ProAgents → PM)
-
-ProAgents pushes changes to PM platform:
-
-```yaml
-integrations:
-  sync:
-    mode: "push"
-
-    # What to push
-    push:
-      feature_start: true
-      phase_changes: true
-      pr_creation: true
-      feature_complete: true
-      comments: true
-      time_tracking: true
-
-    # When to push
-    triggers:
-      on_event: true      # Push on each event
-      on_commit: false    # Push on git commit
-      scheduled: false    # Push on schedule
-```
-
-### Pull Mode (PM → ProAgents)
-
-ProAgents pulls changes from PM platform:
-
-```yaml
-integrations:
-  sync:
-    mode: "pull"
-
-    # What to pull
-    pull:
-      new_issues: true
-      status_changes: true
-      assignments: true
-      comments: true
-      priority_changes: true
-
-    # When to pull
-    schedule: "*/5 * * * *"  # Every 5 minutes
-```
-
-### Bi-Directional Mode
-
-Full two-way sync:
-
-```yaml
-integrations:
-  sync:
-    mode: "bidirectional"
-
-    # Conflict resolution
-    conflicts:
-      strategy: "pm_wins"  # pm_wins, proagents_wins, manual, latest_wins
-
-      # Manual resolution
-      manual:
-        notify: true
-        timeout: "1h"
-        default_action: "pm_wins"
-```
-
----
-
-## Sync Events
-
-### Feature Lifecycle Events
-
-```yaml
-integrations:
-  sync:
-    events:
-      # Feature started
-      feature_start:
-        action: "create_or_link"
-        fields:
-          - title
-          - description
-          - assignee
-          - labels
-
-      # Phase changed
-      phase_change:
-        action: "update_status"
-        add_comment: true
-        fields:
-          - status
-          - custom_phase_field
-
-      # PR created
-      pr_created:
-        action: "link_pr"
-        add_comment: true
-        fields:
-          - pr_url
-          - branch_name
-
-      # Feature completed
-      feature_complete:
-        action: "close_issue"
-        add_comment: true
-        fields:
-          - resolution
-          - time_spent
-          - summary
-```
-
-### Custom Events
-
-```yaml
-integrations:
-  sync:
-    custom_events:
-      # Sync on test completion
-      tests_passed:
-        action: "add_comment"
-        template: "All tests passed. Coverage: {{coverage}}%"
-
-      # Sync on security scan
-      security_scan_complete:
-        action: "update_field"
-        field: "security_status"
-        value: "{{scan_result}}"
-
-      # Sync on deployment
-      deployed:
-        action: "add_comment"
-        template: |
-          Deployed to {{environment}}
-          URL: {{deployment_url}}
-```
-
----
-
-## Field Mapping
-
-### Standard Fields
-
-```yaml
-integrations:
-  sync:
-    field_mapping:
-      # ProAgents field: PM field
-      standard:
-        feature_name: "title"
-        feature_description: "description"
-        current_phase: "status"
-        assignee: "assignee"
-        priority: "priority"
-        labels: "labels"
-        due_date: "due_date"
-        estimate: "estimate"
-```
-
-### Custom Fields
-
-```yaml
-integrations:
-  sync:
-    field_mapping:
-      custom:
-        # Map to custom fields
-        branch_name:
-          jira: "customfield_10001"
-          linear: "custom_field_branch"
-
-        test_coverage:
-          jira: "customfield_10002"
-          linear: "custom_field_coverage"
-
-        pr_link:
-          jira: "customfield_10003"
-          linear: "custom_field_pr"
-
-        deployment_url:
-          jira: "customfield_10004"
-          linear: "custom_field_deploy"
-```
-
-### Field Transformations
-
-```yaml
-integrations:
-  sync:
-    field_mapping:
-      transformations:
-        # Transform phase to status
-        current_phase:
-          transform: "status_map"
-          map:
-            init: "To Do"
-            analysis: "In Progress"
-            implementation: "In Development"
-            testing: "In QA"
-            deployed: "Done"
-
-        # Transform priority
-        priority:
-          transform: "priority_map"
-          map:
-            critical: 1
-            high: 2
-            medium: 3
-            low: 4
-
-        # Custom transformation
-        estimate:
-          transform: "function"
-          function: |
-            (value) => {
-              // Convert hours to story points
-              return Math.ceil(value / 4);
-            }
-```
-
----
-
-## Conflict Resolution
-
-### Resolution Strategies
-
-```yaml
-integrations:
-  sync:
-    conflicts:
-      # Default strategy
-      default_strategy: "latest_wins"
-
-      # Per-field strategies
-      field_strategies:
-        status: "pm_wins"      # PM status takes precedence
-        description: "merge"   # Merge descriptions
-        labels: "union"        # Combine all labels
-        assignee: "proagents_wins"  # ProAgents assignee wins
-
-      # Strategies explained:
-      # - pm_wins: PM platform value wins
-      # - proagents_wins: ProAgents value wins
-      # - latest_wins: Most recent change wins
-      # - merge: Attempt to merge values
-      # - union: Combine values (for arrays)
-      # - manual: Require manual resolution
-```
-
-### Conflict Notification
-
-```yaml
-integrations:
-  sync:
-    conflicts:
-      notification:
-        enabled: true
-        channels:
-          - "slack:#dev-sync"
-          - "email:team@company.com"
-
-        template: |
-          **Sync Conflict Detected**
-
-          Feature: {{feature_name}}
-          Issue: {{issue_id}}
-          Field: {{field_name}}
-
-          ProAgents value: {{proagents_value}}
-          PM value: {{pm_value}}
-
-          Resolution: {{resolution_strategy}}
-```
-
-### Manual Resolution
-
-```yaml
-integrations:
-  sync:
-    conflicts:
-      manual_resolution:
-        enabled: true
-
-        # UI for resolution
-        ui: "cli"  # cli, web, notification
-
-        # Timeout for manual resolution
-        timeout: "4h"
-
-        # Action on timeout
-        timeout_action: "pm_wins"
-```
-
----
-
-## Sync Schedule
-
-### Real-Time Sync
-
-```yaml
-integrations:
-  sync:
-    realtime:
-      enabled: true
-
-      # Use webhooks when available
-      webhooks: true
-
-      # Fallback polling interval
-      fallback_interval: "30s"
-```
-
-### Scheduled Sync
-
-```yaml
-integrations:
-  sync:
-    schedule:
-      enabled: true
-
-      # Full sync schedule
-      full_sync: "0 */6 * * *"  # Every 6 hours
-
-      # Incremental sync schedule
-      incremental_sync: "*/5 * * * *"  # Every 5 minutes
-
-      # Sync on specific events
-      on_events:
-        - "git_push"
-        - "pr_merge"
-```
-
-### Manual Sync
-
-```bash
-# Sync current feature
-proagents pm sync
-
-# Sync all features
-proagents pm sync --all
-
-# Sync specific feature
-proagents pm sync --feature user-auth
-
-# Force full sync (ignore cache)
-proagents pm sync --force
-```
-
----
-
-## Sync Filtering
-
-### Include/Exclude Filters
-
-```yaml
-integrations:
-  sync:
-    filters:
-      # Only sync these issue types
-      include_types:
-        - "Story"
-        - "Bug"
-        - "Task"
-
-      # Exclude these
-      exclude_types:
-        - "Epic"
-        - "Initiative"
-
-      # Only sync issues with these labels
-      include_labels:
-        - "proagents"
-        - "automated"
-
-      # Exclude issues with these labels
-      exclude_labels:
-        - "manual-only"
-        - "no-sync"
-
-      # Only sync issues assigned to team
-      team_only: true
-```
-
-### Project Filters
-
-```yaml
-integrations:
-  sync:
-    filters:
-      # Only sync from these projects
-      projects:
-        - "Backend"
-        - "Frontend"
-
-      # Exclude these projects
-      exclude_projects:
-        - "Archive"
-        - "Experimental"
-```
-
----
-
-## Error Handling
-
-### Retry Configuration
-
-```yaml
-integrations:
-  sync:
-    error_handling:
-      # Retry on failure
-      retry:
-        enabled: true
-        max_attempts: 3
-        backoff: "exponential"  # linear, exponential, fixed
-        initial_delay: "1s"
-        max_delay: "1m"
-
-      # On persistent failure
-      on_failure:
-        action: "queue"  # queue, skip, alert
-        notify: true
-```
-
-### Error Notifications
-
-```yaml
-integrations:
-  sync:
-    error_handling:
-      notifications:
-        enabled: true
-
-        # Notify on these errors
-        on:
-          - "connection_failed"
-          - "auth_failed"
-          - "rate_limited"
-          - "sync_conflict"
-
-        channels:
-          - "slack:#dev-alerts"
-```
-
----
-
-## Sync Status & Monitoring
-
-### View Sync Status
-
-```bash
-# Show sync status
-proagents pm sync-status
-
-# Output:
-┌─────────────────────────────────────────────────────────────┐
-│ Sync Status                                                 │
-├─────────────────────────────────────────────────────────────┤
-│ Platform: Jira                                              │
-│ Mode: Bidirectional                                         │
-│ Last Sync: 2 minutes ago                                    │
-│ Status: Healthy                                             │
-├─────────────────────────────────────────────────────────────┤
-│ Synced Features: 12                                         │
-│ Pending Changes: 0                                          │
-│ Conflicts: 0                                                │
-├─────────────────────────────────────────────────────────────┤
-│ Recent Activity:                                            │
-│ • PROJ-123: Status updated (1 min ago)                     │
-│ • PROJ-456: Comment added (5 min ago)                      │
-│ • PROJ-789: PR linked (10 min ago)                         │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Sync Logs
-
-```bash
-# View sync logs
-proagents pm logs
-
-# View errors only
-proagents pm logs --errors
-
-# Export logs
-proagents pm logs --export sync-log.json
-```
-
----
-
-## Best Practices
-
-1. **Start with Push Mode**: Begin with one-way sync, then enable bidirectional
-2. **Use Webhooks**: Enable webhooks for real-time sync when available
-3. **Define Clear Mappings**: Map fields explicitly to avoid confusion
-4. **Handle Conflicts**: Choose appropriate conflict resolution strategies
-5. **Monitor Sync Health**: Regularly check sync status and logs
-6. **Test Before Production**: Test sync configuration in staging first
-7. **Document Mappings**: Keep field mappings documented for team reference

package/.proagents/pm-integration/trello.md

@@ -1,159 +0,0 @@
-# Trello Integration
-
-Visual board integration with Trello for agile workflows.
-
----
-
-## Setup
-
-### 1. Get API Credentials
-
-1. Go to [Trello Developer Portal](https://trello.com/power-ups/admin)
-2. Create a new Power-Up or get API key
-3. Generate token with necessary permissions
-
-### 2. Configure Connection
-
-```yaml
-# proagents.config.yaml
-
-integrations:
-  trello:
-    enabled: true
-    api_key_env: "TRELLO_API_KEY"
-    token_env: "TRELLO_TOKEN"
-
-    # Board settings
-    board_id: "your-board-id"
-
-    # List mapping
-    lists:
-      backlog: "Backlog"
-      in_progress: "In Progress"
-      review: "In Review"
-      done: "Done"
-```
-
-### 3. Set Environment Variables
-
-```bash
-export TRELLO_API_KEY="your-api-key"
-export TRELLO_TOKEN="your-token"
-```
-
-### 4. Verify Connection
-
-```bash
-proagents pm connect trello
-proagents pm status
-```
-
----
-
-## List Mapping
-
-Map ProAgents phases to Trello lists:
-
-```yaml
-integrations:
-  trello:
-    list_mapping:
-      # ProAgents phase: Trello list name
-      init: "Backlog"
-      analysis: "In Progress"
-      requirements: "In Progress"
-      design: "In Progress"
-      planning: "In Progress"
-      implementation: "In Progress"
-      testing: "In Review"
-      review: "In Review"
-      documentation: "In Review"
-      deployment: "Done"
-      deployed: "Done"
-```
-
----
-
-## Card Configuration
-
-### Card Template
-
-```yaml
-integrations:
-  trello:
-    card_template:
-      name: "{{feature_name}}"
-      description: |
-        ## Description
-        {{feature_description}}
-
-        ## Acceptance Criteria
-        {{acceptance_criteria}}
-
-        ---
-        *Managed by ProAgents*
-
-      # Labels
-      labels:
-        feature: "green"
-        bug: "red"
-        refactor: "yellow"
-        proagents: "purple"
-
-      # Checklist
-      checklist:
-        name: "Tasks"
-        items:
-          - "Analysis complete"
-          - "Implementation complete"
-          - "Tests passing"
-          - "Code reviewed"
-          - "Documentation updated"
-```
-
-### Auto-Actions
-
-```yaml
-integrations:
-  trello:
-    on_feature_start:
-      action: "create_card"
-      list: "In Progress"
-      add_labels: ["proagents"]
-
-    on_phase_change:
-      action: "move_card"
-      add_comment: true
-
-    on_feature_complete:
-      action: "move_to_done"
-      check_all_items: true
-      add_comment: true
-```
-
----
-
-## Commands
-
-```bash
-# Link to existing card
-proagents pm link --card "card-id"
-
-# Create new card
-proagents pm create --title "Feature name"
-
-# Move card
-proagents pm move --list "In Review"
-
-# Add comment
-proagents pm comment "Status update"
-```
-
----
-
-## Best Practices
-
-1. **Use Labels**: Color-code by type (feature, bug, etc.)
-2. **Checklists**: Track phase completion with checklists
-3. **Due Dates**: Set target completion dates
-4. **Attachments**: Link PRs and documentation