Author a provider

A Bahama provider connects one infrastructure service to the standard Bahama workflow. It teaches coding agents when the service fits, contributes a reviewable plan, executes approved operations, and verifies the live result.

Providers live in the open monorepo under providers/<id>. During the alpha, official providers are bundled into the CLI’s static registry rather than downloaded as external plugins.

Start with one complete outcome

Do not mirror the provider’s entire API. Begin with one thing a user should be able to ask their coding agent to accomplish, then agree on the smallest useful version with the human reviewing the work.

Use current official provider documentation to establish:

• what Bahama will manage—and what it will not;
• authentication and account selection;
• resource identity, creation, exact adoption, and readiness;
• values the resource produces or consumes;
• test versus production behavior; and
• secrets, cost, quotas, and destructive or externally visible actions.

“Support Supabase” or “support Stripe” is not specific enough. Decide whether the first slice is Postgres, Storage, restricted test credentials, webhook configuration, or something else. The descriptor and docs should state that boundary plainly.

Fit it into Bahama

New application hosts need the environment role for the current manifest. A provider may fill several roles, but it should advertise only behavior that works end to end.

Providers connect through provider-neutral capabilities. A database might produce connectionUrl; an environment consumes variables. Storage might produce a bucket name, endpoint, and scoped credentials. Name capabilities by what the application receives, mark secrets accurately, and never add provider-pair wiring.

Prefer an official provider CLI with its own login and credential store. API-only providers need a deliberate protected credential or OAuth design in the Bahama CLI. Tokens never belong in bahama.yaml, provider config, command arguments, or an improvised plaintext file.

If the provider needs a new role, effect, secret shape, credential flow, manifest concept, or destruction lifecycle, change the shared contract first. Do not hide a missing Bahama primitive inside one driver.

Implement the contract

Implement these in order. probe and plan are always read-only and non-interactive. Missing tools and sessions become typed requirements. A real account choice becomes a decision instead of an ambient default.

The descriptor is product behavior: coding agents read it through bahama providers <id> --format agent. Do not advertise a role, framework, engine, product, or capability until implementation, tests, skill guidance, and public documentation all support it.

Keep operations safe

Each planned step needs a stable ID, namespaced action, clear summary, truthful effects, non-secret inputs, dependencies, capabilities, and an observable postcondition. Providers declare effects; Bahama core decides what requires approval.

Resolved account and resource IDs belong in the plan and bahama.lock, not the manifest. Exact-name adoption must remain inside the selected account. Bahama does not currently have a destroy command, so removing intent never authorizes remote deletion.

All external authority comes through ProviderContext:

• ctx.run for official CLI commands;
• ctx.http for provider requests;
• ctx.secrets and SecretRef for secret values;
• reviewed ctx.credentials suppliers when available; and
• ctx.signal for cancellation and bounded polling.

Never put raw secrets in argv, plans, identity, receipts, logs, errors, fixtures, or returned JSON. Secret-producing steps must be able to re-derive their value after a fresh-process resume.

After mutation, read the provider again and verify the intended account, resource, configuration, readiness, or public health signal. A successful command or HTTP response alone is not verification. Discover before create so retries cannot duplicate billable resources.

Integrate the whole provider

A normal contribution includes:

• provider package, TypeScript project, implementation, tests, README, and provider-specific AGENTS.md;
• root and CLI TypeScript references, CLI workspace dependency, lockfile, and static registry entry;
• CLI coverage for provider listing, setup, doctor, auth, and init when applicable;
• a provider-selection update and focused provider reference in the Bahama skill;
• root README and public provider index/page updates; and
• public/llms.txt plus any shared workflow or troubleshooting guidance the provider changes.

The workspace remains private and ships inside the published bahama CLI.

Test before claiming support

Cover the cases that matter for this provider: config validation, missing tool or auth, account decisions, deterministic plans, create/adopt/reconcile, effects and capabilities, postcondition failure, safe retry, secrets, resume, health, and drift. Shared contract changes also require test-provider and affected core/provider coverage.

npm run build -w @bahama/provider-<id>
npx vitest run providers/<id>

Before handoff, run the full checks:

npm run version:check
npm run build
npm test
npm run typecheck
npm run lint
npm pack -w bahama --dry-run

Live tests require explicit authorization. Confirm the account, test/live mode, resources, possible cost, and cleanup plan first. Never send real email, move money, modify production data, or delete existing resources as a generic smoke test.