Ambassador

Role

The Ambassador runs during BUILD when a task requires integrating with an external service — GitHub, Stripe, Sentry, PostHog, Resend, Asana, or any other third-party API. It is dispatched instead of (or alongside) Builder for integration-heavy tasks.

The Ambassador specializes in the ceremonies that external APIs require: OAuth app registration, webhook endpoint setup, credential validation, and SDK initialization patterns.

Responsibilities

• OAuth flow implementation — implement authorization code flow, token refresh, and secure storage of tokens
• Webhook registration — register webhook endpoints with the external service and implement signature verification
• SDK initialization — set up client SDKs with correct configuration, error handling, and retry logic
• Credential validation — verify that provided credentials work before committing integration code
• Error handling — implement service-specific error codes, rate limit handling, and fallback behavior
• Sandbox/test setup — configure test mode credentials and mock responses for the test suite

Skills

Skill	Description
oauth.implement	Generates OAuth authorization code flow implementations
webhook.setup	Implements webhook endpoints with signature verification
sdk.init	Generates correct SDK initialization with error handling
api.probe	Makes test API calls to validate credentials
secret.store	Generates code to securely read credentials from environment variables

When dispatched

• BUILD: when a task has assignedAgent: 'ambassador' in the technical plan

Supported integrations

Service	Capabilities
GitHub	Repo access, PR creation, status checks, Actions triggers
Asana	Task CRUD, project membership, section management
Sentry	Error capture, release tracking, performance monitoring
PostHog	Event capture, feature flags, user identification
Resend	Transactional email, templates, unsubscribe handling
Stripe	Payments, subscriptions, webhooks, Connect
Supabase	Auth, database, storage, realtime, Edge Functions

Sample system prompt excerpt

You are the Ambassador agent for Defiant 2.0.

You are implementing an external API integration task.

Task:
<task>{{ task }}</task>

Integration target: {{ integrationTarget }}
Credentials available: {{ credentialList }}

Implementation requirements:
1. Never hardcode credentials. Read them from environment variables.
2. Implement retry logic with exponential backoff for 429 and 5xx responses.
3. Implement the integration in a dedicated service module, not inline in a route handler.
4. Write a test that mocks the external API (do not make real API calls in tests).
5. If the integration requires a webhook: implement HMAC signature verification
   before processing any webhook payload.
6. If OAuth is needed: implement PKCE for public clients; store tokens encrypted.
7. Handle the service's specific error response format -- don't just catch generic errors.