claude-code-agents-orchestra

### **Automated Workflow: Sync Sortd Shared Inboxes with GitHub Issues**

**Objective**: Automate the transfer of customer support tickets from Sortd’s shared inbox to GitHub Issues while maintaining status tracking and ownership.

---

#### **Workflow Overview**
1. **Trigger**: A new email arrives in Sortd’s shared inbox (`[email protected]`).
2. **Processing**: The email is parsed to extract:
   - Subject → GitHub Issue title
   - Body → GitHub Issue description
   - Sender email → Assignee (if mapped to a GitHub user)
   - Labels (e.g., "urgent", "bug") → GitHub labels
3. **Action**: A GitHub Issue is created in the `customer-support` repository.
4. **Sync**: The GitHub Issue URL is appended to the original email in Sortd.
5. **Status Tracking**: GitHub’s project board (`Support Triage`) reflects the issue status (e.g., "To Do", "In Progress", "Resolved").

---

#### **Agent Roles**
| Agent | Responsibility | Tools Used |
|-------|----------------|------------|
| **Email Parser** | Extracts email metadata and content | Sortd API, Python (email parsing) |
| **GitHub Issue Creator** | Creates GitHub Issue with extracted data | GitHub API, Python (requests) |
| **Status Sync Agent** | Updates Sortd email with GitHub Issue URL | Sortd API, GitHub API |
| **Error Handler** | Manages API failures and retries | Retry logic, logging |

---

#### **Dependencies & Prerequisites**
- **Sortd API Access**: Requires admin permissions to enable webhooks for new emails.
- **GitHub API Token**: A personal access token with `repo` and `project` scopes.
- **Mapping Table**: A CSV/JSON file mapping Sortd sender emails to GitHub usernames (e.g., `[email protected]` → `@john-doe`).
- **GitHub Repository**: Must exist with a project board named `Support Triage`.

---

#### **Step-by-Step Execution**
1. **Webhook Setup**: Configure Sortd to send a POST request to a Claude Code agent endpoint (`https://your-domain.com/sortd-webhook`) when a new email arrives in `[email protected]`.
2. **Email Parsing**: The agent extracts:
   ```python
   {
     "subject": "Urgent: Payment Failed for Invoice #12345",
     "body": "Customer reported a failed payment...",
     "sender": "[email protected]",
     "labels": ["urgent", "payment"]
   }
   ```
3. **GitHub Issue Creation**: The agent creates an issue using the GitHub API:
   ```bash
   curl -X POST \
     -H "Authorization: token YOUR_GITHUB_TOKEN" \
     -H "Accept: application/vnd.github.v3+json" \
     https://api.github.com/repos/company/customer-support/issues \
     -d '{"title":"Urgent: Payment Failed for Invoice #12345", "body":"Customer reported...", "labels":["urgent","payment"], "assignee":"alice"}'
   ```
4. **URL Sync**: The agent updates the original email in Sortd with the GitHub Issue URL:
   ```python
   sortd.update_email(
     email_id="12345",
     metadata={"github_issue_url": "https://github.com/company/customer-support/issues/42"}
   )
   ```
5. **Status Sync**: The agent monitors GitHub Issues for status changes (e.g., "In Progress" → "Resolved") and updates the Sortd email label accordingly.

---

#### **Error Handling**
| Failure Point | Solution |
|---------------|----------|
| **API Rate Limits** | Implement exponential backoff (e.g., retry after 1s, 2s, 4s). |
| **Missing GitHub Assignee** | Default to a team lead (e.g., `@support-lead`) and log a warning. |
| **Email Parsing Failure** | Fall back to manual review and notify the team via Slack. |
| **GitHub Project Board Missing** | Automatically create the project board if it doesn’t exist. |

---

#### **Success Criteria**
- **95% of emails** are automatically converted to GitHub Issues within 5 minutes.
- **100% of GitHub Issues** are linked back to the original email in Sortd.
- **Status updates** in GitHub are reflected in Sortd within 2 minutes.
- **Zero manual intervention** required for standard workflows.

---

#### **Monitoring & Alerts**
- **Dashboard**: Use a tool like Grafana to track:
  - Number of emails processed/hour
  - Average time to GitHub Issue creation
  - Error rates per agent
- **Alerts**: Slack notifications for:
  - Failed API calls (after 3 retries)
  - Unassigned issues
  - Stale issues (no updates for 48 hours)

---

#### **Next Steps**
1. Deploy the workflow using Claude Code Orchestra’s agent orchestration.
2. Test with 10 sample emails to validate parsing and GitHub sync.
3. Gradually expand to additional shared inboxes (e.g., `[email protected]`).
4. Add AI-powered triage to auto-label emails based on sentiment analysis (e.g., "complaint" → "urgent").

---

**Total Estimated Setup Time**: 4-6 hours (including testing and documentation).
**Maintenance Overhead**: 1-2 hours/week (monitoring and updates).