Help us improve
Share bugs, ideas, or general feedback.
From oagen
Runs a generate-verify loop to iteratively fix an emitter until smoke tests pass. Use after smoke tests are created or when debugging smoke test failures.
npx claudepluginhub workos/oagenHow this skill is triggered — by the user, by Claude, or both
Slash command
/oagen:verify-smoke-testThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Run `oagen generate` → `oagen verify` in a loop, diagnosing and fixing the emitter (or smoke script) after each iteration until verify exits 0.
Creates a wire-level HTTP smoke test script for a new SDK language, verifying request/response parity against OpenAPI specs and live API baselines.
Diagnoses root causes of Speakeasy SDK generation failures from OpenAPI specs using linting and provides fix strategies like overlays or spec changes. Triggers on 'generation failed', 'speakeasy run failed', or build errors.
Enforces strict verification methodology for code quality, requiring actual evidence of working code before shipping. Used with claudikins-kernel:verify and cross-command gates.
Share bugs, ideas, or general feedback.
Run oagen generate → oagen verify in a loop, diagnosing and fixing the emitter (or smoke script) after each iteration until verify exits 0.
This is the final phase of /generate-sdk setup — after the emitter, extractor, compat overlay, and smoke tests are all scaffolded, this loop gets the emitter actually producing correct output.
node, ruby, python)sdk-{language}-surface.jsonGeneratedFile shape/generate-smoke-test completes and you need to iterate the emitter to passingoagen verify exits 1 (findings) or 2 (compile errors) and you want to fix and retryCollect these values. Use arguments if provided, otherwise ask:
language — target language (e.g., node, ruby, python)spec — path to the OpenAPI spec (e.g., ../openapi.yaml)output — path to the generated SDK output directoryproject — path to the emitter project (often the parent of output)namespace — SDK namespace/package name (e.g., WorkOS)Optional (Scenario A only):
sdk_path — path to the live SDK for target integrationapi-surface — path to sdk-{language}-surface.json for compat overlayCheck if a previous findings file exists — this indicates a prior loop iteration:
ls {output}/smoke-diff-findings.json {output}/smoke-compile-errors.json 2>/dev/null
If findings exist, read them to understand the starting state before running the first iteration.
oagen generate --spec {spec} --lang {language} --output {output} --namespace {namespace}
If Scenario A (compat overlay + live SDK integration), include:
oagen generate --spec {spec} --lang {language} --output {output} --namespace {namespace} --api-surface {api-surface} --target {sdk_path}
oagen verify --spec {spec} --lang {language} --output {output}
If Scenario A, include:
oagen verify --spec {spec} --lang {language} --output {output} --api-surface {api-surface}
| Exit | Meaning | Output file | Next action |
|---|---|---|---|
| 0 | Clean | — | Done — go to Exit |
| 1 | Findings | smoke-diff-findings.json | Go to Step 4 |
| 2 | Compile error | smoke-compile-errors.json | Go to Step 5 |
Read {output}/smoke-diff-findings.json. It contains:
criticalFindings — CRITICAL-severity mismatches (blocking)warningFindings — WARNING-severity mismatches (review)infoFindings — INFO-severity observations (non-blocking)missingFromSdk — operations the SDK didn't attemptmissingFromRaw — operations missing from baseline (non-blocking)coverage — summary statsFocus on CRITICAL findings first. Use the remediation table to locate the fix:
| Finding | Fix location |
|---|---|
| "HTTP method differs" | Emitter's resources.ts — method generation |
| "Request path structure differs" | Emitter's resources.ts — path interpolation |
| "Query parameters differ" | Emitter's resources.ts — query param serialization |
| "Request body key sets differ" | Emitter's models.ts or resources.ts — serializers |
| "Skipped in SDK" | Smoke runner smoke/sdk-{lang}.ts — method resolution |
| "Missing from SDK" | Smoke runner smoke/sdk-{lang}.ts — method mapping |
After fixing, go back to Step 1.
Read {output}/smoke-compile-errors.json. These are TypeScript type errors in the generated SDK. Common causes:
type-map.ts or model generatorsmodels.tsAfter fixing, go back to Step 1.
Track the count of CRITICAL findings between iterations. If the count doesn't decrease after three consecutive iterations, stop and report:
Stall detected: {N} CRITICAL findings remain after {iteration} iterations.
Remaining findings:
- {finding summary}
- ...
These may require a structural emitter change rather than a targeted fix.
Present the remaining findings to the user and ask how to proceed.
When verify exits 0:
# Run the full validation suite
cd {project} && npx vitest run test/{language}/
npx tsc --noEmit
Report the result:
=== verify-smoke-test: COMPLETE ===
Iterations: {N}
Final verify: exit 0 (clean)
Unit tests: {pass/fail}
Type check: {pass/fail}
The findings file (smoke-diff-findings.json or smoke-compile-errors.json) is the primary handoff state. If resuming from a previous session: