Campaigns OS is the developer toolkit for agent-assisted campaign builds on Next Commerce, a full-stack ecommerce platform for direct-response brands. A campaign is a short, conversion-focused funnel — landing page, checkout, optional upsells/downsells, receipt — wired to live products, price tiers, shipping, and payments.
This toolkit gives campaign developers and AI coding tools a clear path for assembling one from prepared page files:
- Configure the campaign in the Next Commerce dashboard (Campaigns App).
- Create or review the Campaign Map in Campaign Map Builder.
- Export a local CampaignSpec JSON.
- Bring prepared HTML/CSS/assets for the campaign pages.
- Create and doctor a Build Packet.
- Hand off to
next-campaigns-build. - Run build/lint, then
next-campaigns-polish. - Deploy a preview.
- Install the Campaigns OS Playwright browser once with
npm run qa:install-browser, then runnext-campaigns-qa. - Record launch blockers and follow-up work.
The toolkit is contract-backed: starter templates describe which parts are reusable page structure, which parts are live commerce wiring, and which demo values must be replaced for a real campaign. That helps AI tools avoid common mistakes like carrying over sample package IDs, copying shipping options from the wrong template shape, or editing SDK-owned checkout surfaces as plain HTML.
Run these commands from a local checkout of the public toolkit repo
(https://github.com/NextCommerceCo/campaigns-os):
npm install
npm run campaigns-os -- start \
--spec examples/campaignspec.v42.basic.json \
--source examples/source-html \
--target examples/target-page-kit \
--template-family olympusThe command writes these target-repo artifacts:
campaign-runtime.build.json.campaign-runtime/build-context.json.campaign-runtime/assembly-report.json.campaign-runtime/doctor-output.json.campaign-runtime/agent-context/*
Then ask your AI tool to continue from the emitted handoff. Fresh target repos usually start with next-campaigns-setup; existing campaign directories can move directly to next-campaigns-build.
The current source adapter is html_funnel: bring prepared HTML/CSS/assets for the campaign pages, plus a local exported CampaignSpec from Campaign Map Builder.
For raw AI-generated or exported static HTML, "prepared" means page-kit-ready
source, not a browser document dropped in unchanged and not a wholesale Liquid
rewrite. Page Kit source is HTML with YAML frontmatter and optional Liquid
helpers. Convert standalone HTML into the target page format first: remove outer
<html>, <head>, and <body> wrappers, add page frontmatter, move shared
CSS/assets into the campaign asset tree when useful, root links/assets with
campaign_link and campaign_asset when needed, and keep landing/presell
design markup separate from SDK-owned commerce controls.
npm run campaigns-os -- install-skills --dry-run
npm run campaigns-os -- install-skills --platform codex --dry-run
npm run skills -- status
npm run campaigns-os -- prepare-build --spec <spec.json> --source <html-dir> --target <page-kit-repo> --template-family <family>
npm run campaigns-os -- doctor --packet <page-kit-repo>/campaign-runtime.build.json
npm run campaigns-os -- next setup --packet <page-kit-repo>/campaign-runtime.build.json
npm run campaigns-os -- next build --packet <page-kit-repo>/campaign-runtime.build.json
npm run campaigns-os -- next polish --packet <packet.json> --report <assembly-report.json>
npm run campaigns-os -- next qa --packet <packet.json> --report <assembly-report.json>
npm run qa:install-browser
npm run campaigns-os -- qa resolve --packet <packet.json>
npm run campaigns-os -- qa run --packet <packet.json> --base-url <preview-url> --browser
npm run campaigns-os -- findings add --stage overall --kind positive_signal --summary "..."
npm run campaigns-os -- findings export --summaryRun npm run qa:install-browser once after install/update and before any QA
command that uses --browser or --test-order. It installs the Chromium binary
used by the package-owned Playwright flow; Campaigns OS QA should not depend on
external browser skills.
The starter-template catalog snapshot lives in contracts/commerce-surface-catalog.json.
For each selected family, the agent must read:
families[family].agentContractsharedFrontmatterVocabularyfrontmatter.demoOnlyValuesfrontmatter.replaceFromSpecOrApifrontmatter.removeWhenUnsupported
Shipping is family-specific. Families whose contracts include shipping_methods
or shipping_method must source those refs from CampaignSpec/API. Families that
do not own explicit shipping frontmatter, including shop-single-step, should
not receive copied Olympus-style shipping_methods blocks. Special case:
shop-three-step uses dynamic shipping through window.next.getShippingMethods().
When bootstrapping a family such as demeter, copy the family as an atomic
page-kit slice. Checkout/receipt pages depend on matching _includes/,
_layouts/, assets/css/, and assets/js/; copying only individual page files
is not a valid minimum file set.
- Quickstart
- Access Model
- Build Packet
- Campaigns OS Build Flow
- Entry Points — five intake shapes (template-stock, Figma-driven, AI-generated, hand-authored, mixed) and which producer / manifest each one ships with
- Source Adapters
- Developer Evaluation
- QA And Test Orders
- Workflow Findings Sidecar — local-first capture of workflow signals (the Learning Trail), separate from the formal proof trail; never phones home
- Versioning
Developer preview. Build output still needs the normal launch gates: build/lint evidence, polish, preview deploy, Playwright browser QA, and typed-card test-order proof when the deployed domain is allowlisted and the order count/path depth is approved.