oc-integrations-engineer

# Integrations Engineer

**On first invocation, read `references/orchestrator.md` and follow its welcome protocol.**

Tri-agent integration harness: Planner designs the connection architecture → Builder
implements the client, auth, and error handling → Tester verifies the integration works
against the real (sandbox) API with edge cases the Builder didn't consider.

**Boundary:** this skill is the *consumer* side — building clients for someone else's
API (Stripe, Slack, Salesforce, Google APIs, OAuth providers). For designing or
building **your own** first-party API that other clients will consume (OpenAPI /
GraphQL authoring, versioning, SDK generation), use `oc-api-dev` instead. Webhook
*receivers* tied to a single integration (`POST /webhooks/stripe`) stay here;
public/product API surfaces belong in `oc-api-dev`.

## /oc-integrate — Command Reference

```
INTEGRATIONS ENGINEER COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  TRI-AGENT HARNESS
  /oc-integrate plan       Design an integration (Planner agent)
  /oc-integrate build      Build an integration (Builder → Tester loop)
  /oc-integrate test       Run Tester against an existing integration

  QUICK BUILD
  /oc-integrate connect    Guided build for a single integration (streamlined)
  /oc-integrate webhook    Set up inbound or outbound webhook
  /oc-integrate oauth      Implement OAuth 2.0 flow

  OPERATE
  /oc-integrate health     Check health of all active integrations
  /oc-integrate secrets    Audit secret storage and rotation
  /oc-integrate retry      Configure retry/backoff for an integration

  UTILITIES
  /oc-integrate list       Show all integrations with status
  /checkpoint           Show checkpoint status

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Type any command to begin. /oc-integrate to see this again.
```

---

## Tri-Agent Architecture

```
INTEGRATION REQUIREMENT
        │
        ▼
┌──────────────────┐
│   INTEGRATION    │  Reads service docs, designs architecture
│   PLANNER        │  Outputs: integration-spec.md per service
└────────┬─────────┘
         │
         ▼
┌──────────────────────────────────────────────┐
│     BUILD LOOP (per integration)             │
│                                              │
│  ┌────────────┐  contract   ┌─────────────┐  │
│  │ INTEGRATION│◄─negotiate──►│ INTEGRATION │  │
│  │  BUILDER   │             │  TESTER     │  │
│  │            │──code──────►│             │  │
│  │  Builds    │             │  Hits real  │  │
│  │  client    │◄──failures──│  sandbox    │  │
│  └────────────┘             └─────────────┘  │
│       │                           │          │
│       │    All tests pass?        │          │
│       └───────────────────────────┘          │
└──────────────────────────────────────────────┘
         │
         └──► Health monitoring (ongoing)
```

### Why Three Agents for Integrations?

1. **Optimistic builder bias** — The Builder writes a client and mentally tests
   it against the happy path. The Tester hits the real sandbox API with malformed
   inputs, expired tokens, rate limit conditions, and timeout scenarios that the
   Builder didn't consider.

2. **Documentation drift** — The Planner reads the service's actual API docs
   (via web search) and designs the integration against reality. The Builder
   might rely on cached knowledge about an API that has changed. The separation
   forces fresh research.

3. **Mock ≠ real** — The Builder writes MSW mocks for unit tests. The Tester
   hits the real sandbox endpoint. Mocks pass when the real API would return 422
   because the request body was slightly wrong. Only real-API testing catches this.

---

## Phase 1: Integration Planner (`/oc-integrate plan`)

### Planner Persona

The Planner is a senior backend architect who has wired dozens of third-party APIs.
Key behaviors:
- **Read the actual docs.** Web search the service's API documentation. Don't rely
  on training data — APIs change frequently.
- **Map every endpoint you'll use.** Not "we'll call their API" — which exact
  endpoints, with which HTTP methods, with which auth headers.
- **Design for failure.** What happens when the API is down? When the token expires?
  When you hit the rate limit? When the response shape changes?
- **Minimal surface area.** Use the fewest endpoints possible. Every endpoint is
  a maintenance burden and a failure point.

### Planner Workflow

1. Identify service and use case
2. Web search for current API documentation
3. Read rate limits, auth requirements, sandbox availability
4. Produce integration spec

### Integration Spec Template

```markdown
## Integration Spec: [Service Name]

### Overview
- **Direction:** Inbound / Outbound / Both
- **Auth:** API key / OAuth 2.0 / Webhook secret / Bearer token
- **Base URL:** https://oc-api.service.com/v2
- **Sandbox:** [URL or "not available"]
- **Rate limits:** [requests per minute/hour]
- **SDK:** [available? use it or build typed client?]
- **Docs:** [URL to current API documentation]

### Endpoints

| Method | Path | Purpose | Auth | Rate Limit | Idempotent |
|---|---|---|---|---|---|
| GET | /contacts | List contacts | Bearer | 100/min | Yes |
| POST | /opportunities | Create opp | Bearer | 50/min | No (needs key) |

### Data Flow
[ASCII diagram showing request/response flow]

### Error Handling Matrix

| Status | Meaning | Action |
|---|---|---|
| 401 | Token expired | Refresh, retry once |
| 429 | Rate limited | Respect Retry-After, backoff |
| 500 | Server error | Retry with backoff, max 3 |
| 503 | Maintenance | Retry with longer delays |

### Secrets Required

| Secret | Storage | Rotation |
|---|---|---|
| Client ID | wrangler secret | Static |
| Client Secret | wrangler secret | Yearly |
| Access Token | KV | Auto-refresh on 401 |

### Test Plan
- **Unit tests:** Mock with MSW, test happy + error paths
- **Sandbox tests:** Hit real sandbox endpoint, verify response shapes
- **Edge cases:** Expired token, rate limit, malformed response, timeout
```

### Gate: