proagents 1.0.0

package/proagents/pm-integration/asana.md

@@ -0,0 +1,346 @@
+# Asana Integration
+
+Task management integration with Asana for cross-functional teams.
+
+---
+
+## Setup
+
+### 1. Create Personal Access Token
+
+1. Go to [Asana Developer Console](https://app.asana.com/0/developer-console)
+2. Create a Personal Access Token
+3. Copy the token
+
+### 2. Configure Connection
+
+```yaml
+# proagents.config.yaml
+
+integrations:
+  asana:
+    enabled: true
+    token_env: "ASANA_TOKEN"
+
+    # Workspace and project
+    workspace_gid: "your-workspace-gid"
+    project_gid: "your-project-gid"
+
+    # Optional: Team
+    team_gid: "your-team-gid"
+```
+
+### 3. Set Environment Variable
+
+```bash
+export ASANA_TOKEN="your-personal-access-token"
+```
+
+### 4. Verify Connection
+
+```bash
+proagents pm connect asana
+proagents pm status
+```
+
+---
+
+## Section Mapping
+
+Map ProAgents phases to Asana sections:
+
+```yaml
+integrations:
+  asana:
+    sections:
+      # Section mapping
+      mapping:
+        backlog: "Backlog"
+        in_progress: "In Progress"
+        review: "In Review"
+        done: "Done"
+
+      # Phase to section
+      phase_mapping:
+        init: "Backlog"
+        analysis: "In Progress"
+        implementation: "In Progress"
+        testing: "In Review"
+        review: "In Review"
+        deployed: "Done"
+```
+
+---
+
+## Task Configuration
+
+### Task Template
+
+```yaml
+integrations:
+  asana:
+    task_template:
+      name: "{{feature_name}}"
+
+      notes: |
+        ## Description
+        {{feature_description}}
+
+        ## Acceptance Criteria
+        {{acceptance_criteria}}
+
+        ---
+        Managed by ProAgents
+
+      # Custom fields
+      custom_fields:
+        - name: "Phase"
+          value: "{{current_phase}}"
+        - name: "Type"
+          value: "Feature"
+        - name: "Branch"
+          value: "{{branch_name}}"
+
+      # Tags
+      tags:
+        - "proagents"
+        - "{{entry_mode}}"
+
+      # Due date
+      due_on: "{{due_date}}"
+
+      # Assignee
+      assignee: "{{asana_user_gid}}"
+```
+
+### Subtasks
+
+```yaml
+integrations:
+  asana:
+    subtasks:
+      enabled: true
+      template:
+        - name: "Analysis complete"
+          completed: false
+        - name: "Implementation complete"
+          completed: false
+        - name: "Tests passing"
+          completed: false
+        - name: "Code reviewed"
+          completed: false
+        - name: "Documentation updated"
+          completed: false
+```
+
+---
+
+## Auto-Actions
+
+### On Feature Start
+
+```yaml
+integrations:
+  asana:
+    on_feature_start:
+      action: "create_task"
+
+      task:
+        name: "{{feature_name}}"
+        notes: "{{task_template}}"
+        section: "In Progress"
+        assignee: "{{user}}"
+        tags: ["proagents"]
+
+      # Create subtasks
+      create_subtasks: true
+```
+
+### On Phase Change
+
+```yaml
+integrations:
+  asana:
+    on_phase_change:
+      # Move to appropriate section
+      move_section: true
+
+      # Update custom field
+      update_field:
+        name: "Phase"
+        value: "{{current_phase}}"
+
+      # Add comment (story)
+      add_comment: |
+        **Phase Update**: {{current_phase}}
+        {{phase_summary}}
+
+      # Update subtask if applicable
+      complete_subtask: "{{completed_subtask}}"
+```
+
+### On Feature Complete
+
+```yaml
+integrations:
+  asana:
+    on_feature_complete:
+      # Move to done
+      move_section: "Done"
+
+      # Complete task
+      complete_task: true
+
+      # Add final comment
+      add_comment: |
+        **Completed**
+
+        - Duration: {{total_duration}}
+        - PR: {{pr_link}}
+        - Coverage: {{test_coverage}}%
+
+      # Complete remaining subtasks
+      complete_all_subtasks: true
+```
+
+---
+
+## Portfolio Integration
+
+### Project Portfolios
+
+```yaml
+integrations:
+  asana:
+    portfolios:
+      enabled: true
+      portfolio_gid: "portfolio-gid"
+
+      # Status updates
+      status_updates:
+        frequency: "weekly"
+        include:
+          - features_completed
+          - features_in_progress
+          - blockers
+```
+
+### Goals Integration
+
+```yaml
+integrations:
+  asana:
+    goals:
+      enabled: true
+
+      # Link features to goals
+      goal_mapping:
+        - feature_type: "user_growth"
+          goal_gid: "goal-1"
+        - feature_type: "performance"
+          goal_gid: "goal-2"
+```
+
+---
+
+## Custom Fields
+
+### Define Custom Fields
+
+```yaml
+integrations:
+  asana:
+    custom_fields:
+      phase:
+        gid: "field-gid-1"
+        type: "enum"
+        options:
+          - "Analysis"
+          - "Implementation"
+          - "Testing"
+          - "Review"
+          - "Done"
+
+      type:
+        gid: "field-gid-2"
+        type: "enum"
+        options:
+          - "Feature"
+          - "Bug Fix"
+          - "Refactor"
+
+      branch:
+        gid: "field-gid-3"
+        type: "text"
+
+      pr_link:
+        gid: "field-gid-4"
+        type: "text"
+
+      test_coverage:
+        gid: "field-gid-5"
+        type: "number"
+```
+
+---
+
+## Commands
+
+```bash
+# Link to existing task
+proagents pm link --task "task-gid"
+
+# Create new task
+proagents pm create --title "Feature name"
+
+# Update task
+proagents pm update --section "In Review"
+
+# Complete task
+proagents pm complete
+
+# Add comment
+proagents pm comment "Status update"
+
+# List tasks
+proagents pm list --section "In Progress"
+```
+
+---
+
+## Webhooks
+
+### Configure Webhooks
+
+```yaml
+integrations:
+  asana:
+    webhooks:
+      enabled: true
+      endpoint: "/webhooks/asana"
+
+      # Events to listen for
+      events:
+        - "changed"
+        - "added"
+        - "removed"
+
+      # Actions
+      actions:
+        on_task_completed:
+          action: "mark_feature_complete"
+
+        on_task_assigned:
+          action: "notify_assignee"
+```
+
+---
+
+## Best Practices
+
+1. **Use Sections**: Organize by workflow stage
+2. **Custom Fields**: Track phase and metadata
+3. **Subtasks**: Break down into trackable items
+4. **Tags**: Categorize for filtering
+5. **Dependencies**: Link related tasks
+6. **Portfolios**: Roll up to project level

package/proagents/pm-integration/github-issues.md

@@ -0,0 +1,308 @@
+# GitHub Issues Integration
+
+Native integration with GitHub Issues and Projects.
+
+---
+
+## Setup
+
+### 1. Authentication
+
+GitHub integration uses your existing GitHub authentication:
+
+```yaml
+# proagents.config.yaml
+
+integrations:
+  github:
+    enabled: true
+    # Uses GITHUB_TOKEN or gh CLI authentication
+
+    # Repository
+    owner: "your-org"
+    repo: "your-repo"
+
+    # Optional: GitHub Projects
+    project_number: 1  # Project board number
+```
+
+### 2. Verify Connection
+
+```bash
+proagents pm connect github
+proagents pm status
+```
+
+---
+
+## Issue Configuration
+
+### Label Mapping
+
+```yaml
+integrations:
+  github:
+    labels:
+      # Entry mode labels
+      feature: "enhancement"
+      bug_fix: "bug"
+      quick_change: "quick-fix"
+      refactor: "refactor"
+
+      # Phase labels
+      phases:
+        analysis: "phase:analysis"
+        implementation: "phase:implementation"
+        testing: "phase:testing"
+        review: "phase:review"
+
+      # ProAgents label
+      managed: "proagents-managed"
+```
+
+### Issue Template
+
+```yaml
+integrations:
+  github:
+    issue_template:
+      title: "{{feature_name}}"
+      body: |
+        ## Description
+        {{feature_description}}
+
+        ## Acceptance Criteria
+        {{acceptance_criteria}}
+
+        ## Tasks
+        - [ ] Analysis complete
+        - [ ] Implementation complete
+        - [ ] Tests passing
+        - [ ] Code reviewed
+
+        ---
+        *Managed by ProAgents*
+
+      labels:
+        - "enhancement"
+        - "proagents-managed"
+
+      assignees:
+        - "{{github_username}}"
+```
+
+---
+
+## Auto-Actions
+
+### On Feature Start
+
+```yaml
+integrations:
+  github:
+    on_feature_start:
+      # Create or link issue
+      action: "create_or_link"
+
+      # If creating new issue
+      create:
+        title: "{{feature_name}}"
+        body: "{{issue_template}}"
+        labels: ["enhancement", "proagents-managed"]
+        assignees: ["{{user}}"]
+
+      # Add to project board
+      add_to_project: true
+      project_column: "In Progress"
+```
+
+### On Phase Change
+
+```yaml
+integrations:
+  github:
+    on_phase_change:
+      # Update labels
+      update_labels:
+        remove: ["phase:*"]  # Remove old phase label
+        add: ["phase:{{current_phase}}"]
+
+      # Add comment
+      add_comment: |
+        **Phase Update**: {{current_phase}}
+
+        {{phase_summary}}
+
+      # Move in project
+      move_in_project:
+        column: "{{phase_to_column}}"
+```
+
+### On PR Created
+
+```yaml
+integrations:
+  github:
+    on_pr_created:
+      # Link PR to issue
+      link_to_issue: true
+
+      # Add comment to issue
+      add_comment: |
+        PR created: #{{pr_number}}
+
+      # Update project
+      move_in_project:
+        column: "In Review"
+```
+
+### On Feature Complete
+
+```yaml
+integrations:
+  github:
+    on_feature_complete:
+      # Close issue
+      close_issue: true
+
+      # Add final comment
+      add_comment: |
+        **Feature Completed**
+
+        - Duration: {{total_duration}}
+        - PR: #{{pr_number}}
+        - Test Coverage: {{test_coverage}}%
+
+      # Move in project
+      move_in_project:
+        column: "Done"
+```
+
+---
+
+## GitHub Projects Integration
+
+### Project Board Setup
+
+```yaml
+integrations:
+  github:
+    projects:
+      enabled: true
+      project_number: 1
+
+      # Column mapping
+      columns:
+        backlog: "Backlog"
+        in_progress: "In Progress"
+        review: "In Review"
+        done: "Done"
+
+      # Custom fields (Projects V2)
+      fields:
+        phase:
+          name: "Phase"
+          type: "single_select"
+        priority:
+          name: "Priority"
+          type: "single_select"
+```
+
+### Auto-Move Cards
+
+```yaml
+integrations:
+  github:
+    projects:
+      auto_move:
+        # Move on issue events
+        on_issue_opened: "Backlog"
+        on_issue_assigned: "In Progress"
+        on_pr_opened: "In Review"
+        on_pr_merged: "Done"
+        on_issue_closed: "Done"
+```
+
+---
+
+## Smart Linking
+
+### Branch to Issue
+
+```yaml
+integrations:
+  github:
+    smart_linking:
+      # Extract issue number from branch name
+      branch_pattern: "^(?:feature|fix)/(?:GH-)?(\d+)"
+
+      # Auto-link PR to issue
+      auto_link_pr: true
+
+      # Close issue on PR merge
+      close_on_merge: true
+```
+
+### Commit Messages
+
+```yaml
+integrations:
+  github:
+    commits:
+      # Reference issue in commits
+      template: "{{message}}\n\nRefs: #{{issue_number}}"
+
+      # Close keywords
+      close_keywords: ["fixes", "closes", "resolves"]
+```
+
+---
+
+## Commands
+
+```bash
+# Link to existing issue
+proagents pm link --issue 123
+
+# Create new issue
+proagents pm create --title "Feature name"
+
+# Update issue
+proagents pm update --labels "phase:testing"
+
+# Close issue
+proagents pm close --issue 123
+
+# List issues
+proagents pm list --state open --label "proagents-managed"
+
+# Move in project
+proagents pm move --column "In Review"
+```
+
+---
+
+## GitHub CLI Integration
+
+ProAgents uses `gh` CLI when available:
+
+```bash
+# Authenticate
+gh auth login
+
+# ProAgents uses gh for:
+# - Creating issues
+# - Creating PRs
+# - Managing projects
+# - Querying issues
+```
+
+---
+
+## Best Practices
+
+1. **Use Labels**: Consistent labeling for filtering
+2. **Link Everything**: Connect issues, PRs, and commits
+3. **Project Boards**: Use for visual tracking
+4. **Templates**: Create issue templates for consistency
+5. **Automation**: Combine with GitHub Actions