Reading this as an agent? This page's markdown twin is at https://voxgig.com/sdk/agents.md. The complete end-to-end build guide is AGENTS.md in create-sdkgen: start there, and use this page for the runbook and the map. The site's own machine surface (MCP server, llms.txt, catalog API) is described at /developers.

Why generation and agents fit#

An agent hand-writing six SDKs has all the maintenance problems a human team has, at higher speed. Driving a deterministic generator removes them. Six properties do the removing.

Deterministic output

Same spec, same SDK, byte for byte, every run. An agent can regenerate freely and the diff shows only what actually changed, so a human review stays possible.

The work is declarative

An agent shapes the SDK by editing the model, which is data, not by authoring N codebases. A three-line declaration can change every language at once, and a contradictory edit fails the model build instead of shipping.

Regeneration cannot lose work

Project decisions are declared in the model and re-read every time. Generation diff-merges into existing files. Running generate twice, or after an upgrade, is safe, which is what makes an iterate loop possible at all.

Drift is machine-checkable

voxgig-sdkgen doctor reports every forked component, edited template and stale file, and exits non-zero. An agent can verify the project state instead of inferring it.

Verification is offline

Every SDK generates with its own test suite, and the test and netsim features mock the API and inject failures deterministically. An agent can prove its work with no network, no credentials and no wall clock.

Guides where agents look

Every generated SDK ships its own AGENTS.md. Each toolchain repo carries one. This page has a markdown twin at /sdk/agents.md, and the site publishes /AGENTS.md, /llms.txt and an MCP server.

The runbook: spec to tested SDKs#

Four commands take an OpenAPI 3 description to generated, tested SDKs. Everything needs Node, and nothing needs a network beyond npm.

# 1. Scaffold a project from the user's OpenAPI 3 description
npm create @voxgig/sdkgen -- my-api -d ./openapi.yaml -o ./my-api-sdk

# 2. Add language targets, plus the offline test feature
cd my-api-sdk/.sdk
npx voxgig-sdkgen target add ts py go
npx voxgig-sdkgen feature add test

# 3. Generate every SDK from the model
npm run generate

# 4. Verify a target the way its ecosystem would
cd ../ts && npm install && npm run build && npm test

From there the loop is: edit, regenerate, verify. The place to edit is the model in .sdk/model/, entities, operations, fields, project decisions, because everything under the language directories (ts/, py/, go/) is generated output and regeneration overwrites or merges it. When the output itself needs to change shape, use the customization levers: templates, components, custom features, custom targets.

Before committing, ask the toolchain rather than guessing:

npx voxgig-sdkgen doctor    # reports drift, exits non-zero for CI

The rules an agent should hold#

Do

Edit the model. It is the source of truth, and a declaration there survives every regeneration and upgrade.
Treat .sdk/model/project.aon as the project's own file: the toolchain creates it once and never overwrites it.
Prove behaviour with the generated offline tests. They need no server and no credentials, so they run anywhere the agent does.
Run doctor before committing, and treat a non-zero exit as a finding to act on.

Do not

Do not hand-edit generated output to fix a bug. The fix belongs in the model, a template or a component, where regeneration reads it. An edit in the output is gone or merged on the next run.
Do not edit the toolchain-derived model files beside project.aon: they are refreshed so toolchain fixes propagate.
Do not hand-edit vendored templates without telling the user, and without doctor in CI: the next resync reverts silent edits.

Where the deeper guides are#

This page is the front door. The depth is versioned with the code it describes.

The end-to-end build guide

AGENTS.md in the create-sdkgen repo: spec to scaffold to generate to test to publish, what to edit versus what is generated, and the known gotchas. The authoritative runbook this page summarises.

create-sdkgen AGENTS.md

Shaping the output

The six customization levers, from model declarations to entirely custom language targets, with a worked demo repo. Read it when the stock output is not quite what the user needs.

Customization

Modifying the generator itself

AGENTS.md in sdkgen covers templates, components and targets from the inside, and AGENTS.md in apidef covers how the OpenAPI description becomes the model.

sdkgen AGENTS.md apidef AGENTS.md

Hand your agent the spec#

One scaffold command, a declarative model, and a doctor that checks the work. The generated SDK arrives with the tests to prove it.

Read the demo repo Talk to Voxgig