Skip to content

0005. Standard AI-assisted framework for onboarding a new POS

  • Status: Accepted
  • Date: 2026-06-09
  • Deciders: POS Integration team

Context

Connecting a new POS (the immediate driver is the Indonesian POS iSeller) has, until now, been an ad-hoc effort: someone reads the vendor's API docs and hand-writes scripts. There was no standard answer to "what do we need from the vendor before we can start?", no defined order of work, and no shared definition of done. The architecture doc even left POS Knowledge Management as an open question ("Needs Discussion").

Meanwhile the pieces of an answer already exist in the codebase:

  • central.knowledge_bases — registered GitHub repos of POS API docs per provider.
  • central.adapter_generation_jobs + AdapterGenerateService (uses the Anthropic SDK) — an AI pipeline with stages gathering → generating → testing and a needs_clarification status carrying the AI's question (clarification) and the human's answer (human_response).
  • Fixed per-topic contracts (adapter-script-contracts.md) and the candidate → active review lifecycle (ADR 0001).

What was missing is the framework that ties them together and the intake questionnaire that feeds them.

Decision

Adopt a standard, intake-gated, AI-assisted onboarding framework for every new POS. It produces the five required adapter scripts — test_connection, list_remote_outlets, sync_products, order_dispatch, order_status_update — with sync_outlet and snooze_items as optional, provider-dependent extras.

The framework, in brief (full how-to in onboarding-new-pos.md):

  1. Intake. The agent runs a structured questionnaire (auth model, connectivity, data formats, and per-topic endpoints + a sample payload for each topic). The questionnaire is the front door — the human supplies a vendor API-docs URL and/or sample payloads.
  2. Knowledge. Provider docs are registered as a central.knowledge_bases entry (a GitHub repo of API docs/samples), and a curated knowledge pack is drafted at docs/guides/adapters/<slug>.md (ADR 0004).
  3. Generate. Scripts are generated one topic at a time, in dependency order, each as a candidate. Generation runs through the existing pipeline; when the AI lacks a fact it moves the job to needs_clarification and waits for human_response rather than guessing.
  4. Test. Each candidate is validated against its sample payload and the topic contract, and against the real POS using a sandbox tenant's provider_connections.
  5. Review & activate. A human promotes candidate → active.
  6. Document. Update the knowledge pack, changelog, feature-parity, and mkdocs nav.

Knowledge model — resolving the open question: the inputs Claude needs are a hybrid: (a) API-doc links / registered knowledge_bases repos, (b) human clarifications captured via the needs_clarification loop, and (c) sample payload pairs, which are treated as authoritative when they conflict with prose docs. Sample payloads are a hard gate: we do not generate a topic's script before we have a sample for it.

Consequences

Positive

  • A repeatable path from "we want POS X" to five reviewed scripts, with a clear checklist and a defined order of work.
  • Uses machinery that already exists rather than inventing a parallel process.
  • The intake gate (no sample → no script) prevents the most common failure mode: a plausible-looking script generated against guessed field shapes.
  • The needs_clarification loop makes "the AI asks, the human answers" an explicit, tracked step instead of a Slack thread.

Negative / costs

  • Onboarding is front-loaded: collecting samples and answering clarifications is real work before any script exists. This is deliberate.
  • Quality still depends on human review at candidate → active; the framework organizes the work, it doesn't remove the reviewer.
  • Generation needs ANTHROPIC_API_KEY and a sandbox tenant with valid credentials for the testing stage.

Alternatives considered

  • Hand-write each provider, no framework. Status quo. Inconsistent, slow, and unrepeatable. Rejected.
  • Fully automated generation, no human gate. Faster but unsafe — order dispatch and auth are too high-stakes to ship un-reviewed. Rejected; we keep candidate → active review.
  • Docs-only intake (no sample payloads). Cheaper intake, but vendor prose routinely disagrees with what the API actually returns; we'd generate against fiction. Rejected — samples are the gate.

References