Provider Builder

Provider Builder

Author a declarative adapter manifest from a vendor name, a capability id, and a docs URL. Drafts YAML, smoke-tests against the live vendor, and only then registers the file under ~/.gtm-os/adapters/. Built on the manifest schema in src/lib/providers/declarative/types.ts and the adapters:smoke runner. Never writes secrets into the manifest, never prints API keys back to the user, never reads ~/.gtm-os/.env.

When to use

• "Add Apollo as a second provider for icp-company-search"
• "Wire up PeopleDataLabs for people-enrich"
• "Try Brevo instead of Instantly for email-campaign-create"
• Hot-patching a broken built-in by dropping a YAML with the same provider id

Don't use when: the vendor needs OAuth, request signing (Sigv4 / HMAC), gRPC / websockets, an SDK-only client, or two-call flows (/token then /search). All of those are out of scope for declarative v1 — exit with a stub TS template (see Failure mode 2 below).

Pre-flight (do this before step 1)

1. Onboarding interruption guard. Run:

   test -f ~/.gtm-os/.in-flight-setup && echo "BLOCKED" || echo "OK"

   If BLOCKED, stop. Tell the user: "Setup is mid-flight. Finish yalc-gtm start first, then re-invoke me." Exit cleanly. This skill writes to the adapter registry from Step 5 onward, so it must not race the onboarding flow.

2. Confirm the trigger is in scope. If the user mentioned OAuth, an SDK, gRPC, or signed requests, jump to Failure mode 2 and exit cleanly.

3. Confirm pnpm cli adapters:list works in the cwd. If not, the package isn't built or the user is in the wrong directory — surface that and stop.

4. Resolve the env var name with the user (e.g., APOLLO_API_KEY). Do not open ~/.gtm-os/.env. Use process.env only — node -e "console.log(process.env.APOLLO_API_KEY ? 'set' : 'unset')" is the maximum disclosure allowed (prints set / unset, never the value).

Workflow

Step 0 — Greet + state scope

Greet the user briefly and state what this skill will and won't do, so they can correct course before any work starts:

"I'll author a declarative YAML adapter for <vendor> against the <capability> capability — draft the manifest from vendor docs, smoke-test it against the live endpoint, and only register it under ~/.gtm-os/adapters/ once smoke is green. I won't read or print any API keys, won't touch ~/.gtm-os/.env, and won't draft anything for OAuth / SDK-only / signed-request vendors (those need a TS adapter). Roughly five minutes if the vendor's REST docs are clean."

Confirm the vendor + capability id with the user before moving to Step 1. If either is missing, ask for it now — one question at a time.

Step 1 — Discover

Resolve the capability id with fuzzy matching. Examples:

• "find emails", "enrich people", "get email" → people-enrich
• "find companies", "ICP search", "company search" → icp-company-search
• "send email campaign", "cold email" → email-campaign-create
• "deploy landing page" → landing-page-deploy

pnpm cli adapters:list

Pick the capability id from the output. Then surface its input/output schema to the user so they understand what the manifest must produce. Schemas live in src/lib/providers/capabilities.ts and the per-capability adapter files under src/lib/providers/adapters/<capability>-*.ts. Read the capability's inputSchema + outputSchema and present the required fields.

If the requested capability id does not exist, stop. Tell the user a new capability requires a TS change (out of scope for this skill) and offer to file that as a follow-up.

Step 2 — Read vendor docs

WebFetch (preferred for stable docs) or use the web-browsing skill (Firecrawl) for JS-heavy docs sites. Pull these from the docs page:

• Endpoint — full URL, HTTP method.
• Auth method — header / query / bearer. Note the header or query-param name. If you see Authorization: Bearer …, use bearer. If you see X-Api-Key: …, use header with name: X-Api-Key.
• Request shape — query params (GET) or JSON body (POST). Note required fields.
• Response shape — top-level wrapper ({ data: [...] }, { results: [...] }, etc.) and the per-item field names.
• Error envelope — how errors look when the HTTP status is 200 but the call failed (some vendors do this).
• Pagination — cursor vs page. Skip on first pass; add later only if needed.

Detect out-of-scope flows up front (see Failure mode 2). If the docs reference any of: "OAuth", "authorization code", "refresh_token", "client_secret" + browser redirect, AWS Sigv4, HMAC signature, gRPC, websockets, an official SDK with no documented REST endpoint — exit cleanly.

If the docs page is incomplete (no example response, no error envelope), ask the user for one missing piece at a time. Never guess.

Step 3 — Draft manifest

Write the YAML to /tmp/yalc-builder/{capability}-{provider}.yaml. Do not write directly to ~/.gtm-os/adapters/ — that comes after smoke green.

mkdir -p /tmp/yalc-builder

Start from references/yaml-template.yaml. Required fields:

manifestVersion: 1
capability: <id>           # from step 1, exact match
provider: <vendor-id>      # short kebab-case, e.g. "apollo"
version: 0.1.0
auth:
  type: header             # or bearer / query
  name: X-Api-Key          # omit for bearer
  value: ${env:APOLLO_API_KEY}
endpoint:
  method: POST
  url: https://api.example.com/v1/search
request:
  contentType: application/json
  bodyTemplate: |
    { "q": "{{input.keywords}}", "limit": {{input.limit | default: 25}} }
response:
  rootPath: results
  mappings:
    "companies[].name": "$.name"
    "companies[].domain": "$.primary_domain"
  errorEnvelope:
    matchPath: $.error
    messagePath: $.error
smoke_test:
  input:
    keywords: "saas"
    limit: 5
  expectNonEmpty: ["companies[0].domain"]

Mapping rules (see src/lib/providers/declarative/compiler.ts):

• Targets like companies[].domain iterate over rootPath array; targets without [] are scalars.
• Source $.field reads from the current row (or root for scalars).
• Source null emits literal null.
• Prefix-literal source like "https://$.url" keeps the prefix and substitutes the path.
• Equality: "$.readyState == 'READY'" returns boolean.

Template scope (Mustache-flavour):

• {{input.foo}} — the runtime input passed to the capability
• {{env.VAR}} — process env
• {{auth.value}} / {{auth.name}} / {{auth.type}} — resolved auth
• Filters: | default: 25, | default: "x", | json
• Unknown roots fail at compile time, not runtime.

Show the draft to the user before moving on.