@nextcommerce/campaigns-os 1.60.0 → 1.61.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +126 -0
- package/README.md +5 -5
- package/agents/claude/CLAUDE.md +15 -0
- package/agents/codex/AGENTS.md +15 -0
- package/agents/copilot/copilot-instructions.md +15 -0
- package/agents/cursor/campaigns-os.mdc +15 -0
- package/compatibility.json +1 -1
- package/contracts/brand-theme-target-tokens.next-core.v0.json +95 -25
- package/contracts/campaign-cart-sdk-support-policy.v0.json +2 -2
- package/contracts/commerce-surface-catalog.json +27 -26
- package/contracts/release-ledger.json +768 -0
- package/contracts/supported-surface.json +4 -4
- package/contracts/template-brand-contract.shared-commerce.v0.json +1 -1
- package/docs/access-model.md +20 -0
- package/docs/brand-theme-bridge.md +62 -3
- package/docs/build-packet.md +28 -1
- package/docs/campaign-build-brief.md +16 -0
- package/docs/campaigns-os-build-flow.md +61 -2
- package/docs/campaignspec-authoring-examples.md +116 -0
- package/docs/design-source-package.md +46 -2
- package/docs/entry-points.md +188 -0
- package/docs/local-setup.md +1 -1
- package/docs/orientation-contract-reference.md +1 -1
- package/docs/polish-evidence.md +40 -2
- package/docs/qa-and-test-orders.md +50 -2
- package/docs/quickstart.md +438 -0
- package/docs/readback.md +119 -6
- package/docs/runtime-readiness.md +1 -1
- package/docs/sdk-storage-compatibility.md +3 -1
- package/docs/skills-revision.md +10 -10
- package/docs/source-adapters.md +213 -0
- package/package.json +10 -3
- package/schemas/campaign-design-source-package.v0.schema.json +8 -0
- package/schemas/campaigns-os-readback.v2.schema.json +177 -1
- package/schemas/source-html-manifest.v0.schema.json +3 -0
- package/skills/campaign-lifecycle-orientation/SKILL.md +3 -3
- package/skills/campaign-readback-classification/SKILL.md +3 -3
- package/skills/campaign-run-evidence/SKILL.md +3 -3
- package/skills/contribution-intake/SKILL.md +3 -3
- package/skills/next-campaigns-build/SKILL.md +4 -4
- package/skills/next-campaigns-os/SKILL.md +4 -3
- package/skills/next-campaigns-os-setup/SKILL.md +3 -3
- package/skills/next-campaigns-polish/SKILL.md +6 -9
- package/skills/next-campaigns-qa/SKILL.md +3 -3
- package/skills/next-campaigns-sdk-bump/SKILL.md +117 -24
- package/skills.json +11 -11
- package/src/brand-theme.mjs +413 -8
- package/src/brief-summary.mjs +6 -2
- package/src/browser-launch.mjs +2 -1
- package/src/build-brief.mjs +9 -2
- package/src/built-site-scope.mjs +2 -2
- package/src/cli.mjs +52 -13
- package/src/design-file-reference.mjs +93 -0
- package/src/design-source-package.mjs +55 -1
- package/src/doctor/checks.mjs +8 -74
- package/src/doctor/ci.mjs +112 -0
- package/src/doctor/inspect.mjs +18 -0
- package/src/doctor/source-provenance.mjs +74 -0
- package/src/evidence-debt.mjs +119 -0
- package/src/parity/compare.mjs +316 -0
- package/src/parity/design-access.mjs +54 -0
- package/src/parity/element-parity-record.mjs +569 -0
- package/src/parity/probe.mjs +205 -0
- package/src/parity/snapshot.mjs +110 -0
- package/src/png-header.mjs +87 -0
- package/src/polish-browser.mjs +186 -9
- package/src/polish-captures-record.mjs +52 -0
- package/src/polish-deadline.mjs +14 -0
- package/src/polish-gate.mjs +25 -6
- package/src/polish-node.mjs +81 -7
- package/src/polish-visual-fixtures.mjs +74 -0
- package/src/polish-visual.mjs +606 -0
- package/src/qa-analytics-correctness.mjs +14 -2
- package/src/qa-analytics-parity.mjs +94 -5
- package/src/qa-node.mjs +39 -6
- package/src/qc-accept.mjs +148 -6
- package/src/qc-check-registry.mjs +37 -1
- package/src/qc-results.mjs +404 -16
- package/src/readback.mjs +57 -13
- package/src/sdk-attribute-index.mjs +11 -11
- package/src/sdk-markup.mjs +77 -2
- package/src/sdk-storage-compatibility.mjs +94 -4
- package/src/source-html-manifest.mjs +7 -0
- package/src/source-html-server.mjs +129 -0
- package/src/stage-record.mjs +45 -7
- package/src/theme-gate.mjs +2 -2
- package/src/visual-diff.mjs +296 -0
- package/src/visual-reference.mjs +126 -0
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: next-campaigns-build
|
|
3
|
-
version: 1.0.
|
|
3
|
+
version: 1.0.51
|
|
4
4
|
description: Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts.
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
Bundle revision: 1.
|
|
8
|
-
Run `npx --no-install campaigns-os tooling status --skills-revision 1.
|
|
7
|
+
Bundle revision: 1.61.0+skills.1
|
|
8
|
+
Run `npx --no-install campaigns-os tooling status --skills-revision 1.61.0+skills.1`
|
|
9
9
|
from the campaign's Page Kit folder, where it runs the project's pinned copy and
|
|
10
10
|
never installs one, at the start of each task. Start a fresh session if it
|
|
11
11
|
reports `mismatch`: this text is already in your context and is never re-read
|
|
@@ -90,7 +90,7 @@ Build rules:
|
|
|
90
90
|
- Reproduce the source design's own proof and urgency elements as designed: reviews and testimonials, ratings, "Verified Purchase" labels, recent-purchase popups, stock counters, countdowns and guarantees. They are the merchant's content and the merchant's responsibility; Campaigns OS does not review them, so do not remove, soften or flag them. The starter templates shipping without some of these elements is not a reason to drop the source's.
|
|
91
91
|
- Prepared source HTML means page-kit-ready markup, not a wholesale Liquid rewrite. Standalone HTML mockups that are meant to stay whole (their `source_screenshot` proof is of the full document) keep their document wrappers: the source-html manifest records `wrapper_policy: preserve_document_wrappers` (or `--wrapper-policy preserve_document_wrappers` on `start` / `prepare-build`), and doctor reports the wrappers as a warning. Otherwise, standalone AI/exported HTML should keep page-owned body markup, remove document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only where page-kit needs campaign-rooted links/assets/includes.
|
|
92
92
|
- For `checkout`, `upsell`, `downsell`, and `receipt` pages, treat the selected starter-template commerce surface as the SDK contract reference: preserve required `data-next-*` controls, hidden fields, payment/address/totals/submit wiring, and `next_dont_touch` regions. The surrounding HTML wrapper, page composition, imagery, copy hierarchy, and brand layer are campaign/source-owned. Do not carry starter visual chrome forward when prepared source design should own that surface. QA checks what the checkout does, not family class names: do not add family shell classes (`.checkout-wrapper`, `.checkout-layout__left/right`) to the campaign's own grid or swap source-owned field markup for family includes to satisfy QA. Keep the checkout working instead: a `<form data-next-checkout="form">`, the contact and shipping fields bound with `data-next-checkout-field` inside it, and a visible cart total. A required field bound only on a `type="hidden"` input, a disabled control, a read-only input or read-only textarea, or a control with `aria-disabled="true"` does not count as bound: QA reports it in `fields_bound.missing`.
|
|
93
|
-
- Read `context.theme` and `.campaign-runtime/theme/theme-report.json` when present. If a fresh `brand-theme.css` artifact exists, copy it into the campaign asset tree and load it after `next-core.css` on checkout, upsell, downsell, and receipt pages. If policy is `inspect_only`, either run `campaigns-os theme generate` (tier `B`: writes the theme artifacts and doctor output under the target; `--force` is tier `C`) or record an explicit skipped reason before applying a new brand layer.
|
|
93
|
+
- Read `context.theme` and `.campaign-runtime/theme/theme-report.json` when present. If a fresh `brand-theme.css` artifact exists, copy it into the campaign asset tree and load it after `next-core.css` on checkout, upsell, downsell, and receipt pages. When theme generate also wrote `brand-fonts.css` (the design's own `@font-face` rules for its heading and body families), copy it into the same `assets/css/` folder and load it on the same pages: without it the font tokens in `brand-theme.css` name faces the page can't load, and commerce pages fall back to the system font. `record theme` refuses a styled page that skips it. If policy is `inspect_only`, either run `campaigns-os theme generate` (tier `B`: writes the theme artifacts and doctor output under the target; `--force` is tier `C`) or record an explicit skipped reason before applying a new brand layer.
|
|
94
94
|
- Generated brand-theme v0 is root-variable-only. It may skin commerce pages through next-core custom properties, but it is not permission to edit SDK-owned selectors, package controls, payment fields, totals, submit controls, receipt templates, route meta tags, or SDK JavaScript.
|
|
95
95
|
- Payment, express checkout, bundle selectors, and order bumps must start from the selected family's canonical component DOM/classes, not from raw custom/source HTML with `data-next-*` added afterward. For payment specifically, preserve the family payment-method wrapper, hosted field classes, and iframe geometry assumptions (for example `input-flds spreedly-field` in shop-style templates). Skin these components with campaign tokens; do not rebuild Spreedly/card fields as arbitrary divs.
|
|
96
96
|
- When a checkout page declares `exit_intent.enabled`, wire the popup as an offer application surface: use `offer_ref_id`/`offer_code` from CampaignSpec, apply the code through the SDK/API coupon/voucher path, and render applied-state copy with SDK conditionals such as `cart.hasCoupon("FREESHIP")`.
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: next-campaigns-os
|
|
3
|
-
version: 1.0.
|
|
3
|
+
version: 1.0.66
|
|
4
4
|
description: Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth.
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
Bundle revision: 1.
|
|
8
|
-
Run `npx --no-install campaigns-os tooling status --skills-revision 1.
|
|
7
|
+
Bundle revision: 1.61.0+skills.1
|
|
8
|
+
Run `npx --no-install campaigns-os tooling status --skills-revision 1.61.0+skills.1`
|
|
9
9
|
from the campaign's Page Kit folder, where it runs the project's pinned copy and
|
|
10
10
|
never installs one, at the start of each task. Start a fresh session if it
|
|
11
11
|
reports `mismatch`: this text is already in your context and is never re-read
|
|
@@ -74,6 +74,7 @@ to author a spec or fabricate a Map ID. Verify store/campaign binding and real
|
|
|
74
74
|
package/offer references. Store contact and policy details can come from the
|
|
75
75
|
brief; gateway access is optional. Current authoring is v4.3+ while preserving
|
|
76
76
|
the v4.2 `funnels[]` topology as the compatibility shape.
|
|
77
|
+
When the HTML was exported from a design file, name it as `design_file: {file_url, type?, breakpoints?}` on the source-html manifest page; see `docs/design-source-package.md` for the shape and the Figma-only spec `design_source` provenance rule.
|
|
77
78
|
2. Run `campaigns-os start` or `campaigns-os prepare-build` (tier `A`: they write the
|
|
78
79
|
Build Packet, Build Context, assembly report, run session and `.gitignore` under
|
|
79
80
|
the target plus a Run Record under the working directory, and they contact the
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: next-campaigns-os-setup
|
|
3
|
-
version: 2.0.
|
|
3
|
+
version: 2.0.49
|
|
4
4
|
description: Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly installed as next-campaigns-setup; renamed 2026-08 to stop colliding with the published NextCommerceCo/skills scaffolder of that name.
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
Bundle revision: 1.
|
|
8
|
-
Run `npx --no-install campaigns-os tooling status --skills-revision 1.
|
|
7
|
+
Bundle revision: 1.61.0+skills.1
|
|
8
|
+
Run `npx --no-install campaigns-os tooling status --skills-revision 1.61.0+skills.1`
|
|
9
9
|
from the campaign's Page Kit folder, where it runs the project's pinned copy and
|
|
10
10
|
never installs one, at the start of each task. Start a fresh session if it
|
|
11
11
|
reports `mismatch`: this text is already in your context and is never re-read
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: next-campaigns-polish
|
|
3
|
-
version: 1.1.
|
|
3
|
+
version: 1.1.51
|
|
4
4
|
description: Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign.
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
Bundle revision: 1.
|
|
8
|
-
Run `npx --no-install campaigns-os tooling status --skills-revision 1.
|
|
7
|
+
Bundle revision: 1.61.0+skills.1
|
|
8
|
+
Run `npx --no-install campaigns-os tooling status --skills-revision 1.61.0+skills.1`
|
|
9
9
|
from the campaign's Page Kit folder, where it runs the project's pinned copy and
|
|
10
10
|
never installs one, at the start of each task. Start a fresh session if it
|
|
11
11
|
reports `mismatch`: this text is already in your context and is never re-read
|
|
@@ -70,7 +70,7 @@ Responsibilities:
|
|
|
70
70
|
- Treat express wallet presence as browser/device eligible. Record which wallets mounted in the tested browser, but do not fail solely because Apple Pay is absent in a non-eligible browser. Fail or block when the express mount is empty despite supported wallets, or when mounted wallet buttons are visually malformed.
|
|
71
71
|
- For bundle selectors and order bumps, verify active/inactive visual state after interaction, mobile label wrapping, badge placement, and selected/unchecked state. A native hidden input state that disagrees with the SDK class state is a polish blocker. So is a selected/active visual driven by a *non-SDK static attribute the SDK never clears* — e.g. a hardcoded `data-selected="true"` left on the initial card. (The native `selected` attribute on `<option>`/custom selects *is* SDK/browser-managed, so do not flag that.) The selected style must follow the SDK-managed class (e.g. `.next-selected` — see the family's bundle-selector selectors in `contracts/template-brand-contract.<family>.v0.json`) so a single-select swap clears the previous selection. Verify by interaction that the previously-selected item deselects after another is picked — a selector that only ever paints "selected" on click is a blocker.
|
|
72
72
|
- For exit-intent pops and promo-code inputs, polish the wrapper/copy states without breaking SDK coupon/voucher apply hooks or `cart.hasCoupon("CODE")` conditional labels.
|
|
73
|
-
- If `report.theme` or `context.theme` exists, verify brand-theme load order after `next-core.css`, source-token parity for primary color/CTA/surface/text/font/radius when present, and SDK safety. When the brand layer is missing, stale, low-confidence, or unsafe to apply, record the first repair-loop defect or an explicit skipped reason.
|
|
73
|
+
- If `report.theme` or `context.theme` exists, verify brand-theme load order after `next-core.css`, source-token parity for primary color/CTA/surface/text/font/radius when present, and SDK safety. Check font parity by computed style at a mobile and a desktop width, not desktop alone: next-core re-declares its font tokens on `body` below 992px, so a layer that sets them only on `:root` holds on desktop and falls back on mobile. When the brand layer is missing, stale, low-confidence, or unsafe to apply, record the first repair-loop defect or an explicit skipped reason.
|
|
74
74
|
- When at least one mapped page has a design route, before recording a terminal
|
|
75
75
|
Polish status, install the package-owned browser once with
|
|
76
76
|
`npx --no-install campaigns-os qa install-browser`, serve the current build,
|
|
@@ -93,6 +93,7 @@ Responsibilities:
|
|
|
93
93
|
<preview route root>`, then `campaigns-os qa run --packet <packet>
|
|
94
94
|
--base-url <preview-url> --browser --test-order common`, then closeout. QA
|
|
95
95
|
against the packet's production URL keeps the checkpoint blocked.
|
|
96
|
+
- In the handoff, `parity.element` rows are element differences to review or accept. `design.access` unexercised means the file was not read: compare by hand. A `design.access` review row means a changed, missing or conflicting design file: fix the declaration or rerun intake with `--force`. These rows never block Polish.
|
|
96
97
|
- When a readability warning appears, report it with its colours, ratio, requirement and pages. Offer the operator options inside the brand palette (a darker or lighter shade of the same hue, the palette's text colour, or a larger, bold label where the design allows). Do not recolour the merchant's design until the operator chooses. Accept a warning only with the refs, reason and name the operator gives you at the QC handoff.
|
|
97
98
|
- Record Polish as `completed`, `skipped`, or `blocked` with
|
|
98
99
|
`campaigns-os record polish --packet <packet> --evidence <polish-evidence.json>`
|
|
@@ -117,11 +118,7 @@ schema reference; this section is the recording guidance.
|
|
|
117
118
|
**All seven evidence fields are required** or the gate blocks with
|
|
118
119
|
`polish.evidence_incomplete`:
|
|
119
120
|
|
|
120
|
-
- `visual_review` —
|
|
121
|
-
`screenshot_paths`, `paths`, `urls`) holding at least one non-empty
|
|
122
|
-
path/URL string for the captured desktop+mobile evidence, plus the
|
|
123
|
-
package-generated `page_load` object. A bare string or a screenshot-less
|
|
124
|
-
object does NOT pass, no matter how real the review was.
|
|
121
|
+
- `visual_review` — run `campaigns-os polish capture` first: it records the package captures (`captures`) and `page_load`, which satisfy the screenshot requirement, and `record polish` refuses a completed Polish without them. Do not write screenshot paths to satisfy the check, and never write `captures` or `page_load` by hand. Report self-referential references and the review list from the QC handoff to the operator; accept a self-referential warning only when the operator decides to use the current output as the baseline for later revisions.
|
|
125
122
|
- `brand_review` — object; must include the `favicon` attestation and the
|
|
126
123
|
`brand_bleed` attestation (below).
|
|
127
124
|
- `checkout_review` — object; must include `field_labels` (aliases
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: next-campaigns-qa
|
|
3
|
-
version: 1.3.
|
|
3
|
+
version: 1.3.50
|
|
4
4
|
description: Run spec-aware QA from a saved Map or local-spec Build Packet and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof.
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
Bundle revision: 1.
|
|
8
|
-
Run `npx --no-install campaigns-os tooling status --skills-revision 1.
|
|
7
|
+
Bundle revision: 1.61.0+skills.1
|
|
8
|
+
Run `npx --no-install campaigns-os tooling status --skills-revision 1.61.0+skills.1`
|
|
9
9
|
from the campaign's Page Kit folder, where it runs the project's pinned copy and
|
|
10
10
|
never installs one, at the start of each task. Start a fresh session if it
|
|
11
11
|
reports `mismatch`: this text is already in your context and is never re-read
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: next-campaigns-sdk-bump
|
|
3
|
-
version: 1.0.
|
|
3
|
+
version: 1.0.6
|
|
4
4
|
description: Bump a live campaign's Campaign Cart SDK from one 0.4.x release to a later 0.4.x on a page-kit or static repo. Use for any request to bump, upgrade or move a campaign to SDK 0.4.x, including when the repository has its own BUMP.md. Find every pin, check the release diff and storage against the campaign's own code, prove on a preview with approved test orders, and report what is not proven.
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
Bundle revision: 1.
|
|
8
|
-
Run `npx --no-install campaigns-os tooling status --skills-revision 1.
|
|
7
|
+
Bundle revision: 1.61.0+skills.1
|
|
8
|
+
Run `npx --no-install campaigns-os tooling status --skills-revision 1.61.0+skills.1`
|
|
9
9
|
from the campaign's Page Kit folder, where it runs the project's pinned copy and
|
|
10
10
|
never installs one, at the start of each task. Start a fresh session if it
|
|
11
11
|
reports `mismatch`: this text is already in your context and is never re-read
|
|
@@ -16,16 +16,30 @@ answered; follow none of its actions and run the pinned copy.
|
|
|
16
16
|
# Next Campaigns SDK Bump
|
|
17
17
|
|
|
18
18
|
Use this when someone says "bump this campaign to SDK 0.4.x". The developer
|
|
19
|
-
installs the toolkit, asks for the bump, approves each push, the pull request
|
|
19
|
+
installs the toolkit or approves installing it, asks for the bump, approves each push, the pull request
|
|
20
20
|
and each test order, then reviews and merges. Everything here uses existing
|
|
21
21
|
commands; there is no new write or order capability.
|
|
22
22
|
|
|
23
|
+
If the Page Kit folder has no pinned copy yet, the revision check above cannot
|
|
24
|
+
run: ask before installing one. Pin a package version you reviewed, after
|
|
25
|
+
reviewing its source tag and provenance as `AGENTS.md` describes, and pick one
|
|
26
|
+
whose `tooling status --skills-revision` answers `match` for this skill; an
|
|
27
|
+
older release lacks commands the steps below use:
|
|
28
|
+
`npm install --save-dev --save-exact @nextcommerce/campaigns-os@<reviewed-version>`.
|
|
29
|
+
The install adds the package to `devDependencies` in `package.json` and updates
|
|
30
|
+
`package-lock.json`; `tooling status` only reads that pin and writes neither.
|
|
31
|
+
Expect that change and commit it on the bump branch as its own commit, and
|
|
32
|
+
check that the lockfile diff adds only this package. In a static repo, never
|
|
33
|
+
install into a folder the site publishes from; ask where the toolkit goes.
|
|
34
|
+
|
|
23
35
|
If `tooling status` prints `Refresh installed skills` for `--platform codex` or
|
|
24
36
|
`--platform agents` only, that refresh is for those harnesses; it is not
|
|
25
37
|
required in a session that uses neither.
|
|
26
38
|
|
|
27
39
|
In the instructions below, bare `campaigns-os …` means `npx --no-install
|
|
28
|
-
campaigns-os …` from the
|
|
40
|
+
campaigns-os …` from the folder the toolkit is installed in (the Page Kit
|
|
41
|
+
folder, or the folder chosen for a static repo), with absolute paths for
|
|
42
|
+
`--target` and `--site`. The effect class in each
|
|
29
43
|
parenthetical is the declared row of `contracts/effects.v1.json`.
|
|
30
44
|
|
|
31
45
|
## Scope: a current-SDK bump only
|
|
@@ -51,7 +65,16 @@ separate work.
|
|
|
51
65
|
Ask before every push, before opening the pull request, and before test
|
|
52
66
|
orders. Test orders are real orders in the store that someone may have to
|
|
53
67
|
cancel; follow the `next-campaigns-qa` rule: ask once up front, then follow the
|
|
54
|
-
answer.
|
|
68
|
+
answer.
|
|
69
|
+
|
|
70
|
+
Ask these up front, together with test orders, so the runner pass in step 6
|
|
71
|
+
is a choice, not a default skip:
|
|
72
|
+
|
|
73
|
+
- May I run `campaigns-os qa install-browser` (about 100 MB, once per machine)?
|
|
74
|
+
- May I run `qa run --browser` against the preview?
|
|
75
|
+
- Should the verdict stay local (`--local-only`) or post to the QA portal?
|
|
76
|
+
|
|
77
|
+
Never write evidence or notes into the served tree: many static repos
|
|
55
78
|
publish from the repository root. The hand-back goes on the ticket or the pull
|
|
56
79
|
request.
|
|
57
80
|
|
|
@@ -67,6 +90,17 @@ check `.gitignore`, and never stage it.
|
|
|
67
90
|
Branch from an up-to-date `main`. List open pull requests that touch the
|
|
68
91
|
campaign folder and ask the developer about merge order before branching.
|
|
69
92
|
|
|
93
|
+
Find which funnels still take traffic; nothing else in the repository shows
|
|
94
|
+
it. Read the per-slug status line in the repository's `CLAUDE.md` (for example
|
|
95
|
+
`- <slug>: live` or `- <slug>: retired`). Bump every slug in scope, but place
|
|
96
|
+
test orders only on slugs marked live. Read the root `CLAUDE.md` first, then
|
|
97
|
+
the Page Kit folder's. If there is no `CLAUDE.md`, or a slug has no status line
|
|
98
|
+
or one that is not plainly `live` or `retired`, say so, list those slugs, and
|
|
99
|
+
ask the developer which are live. Never treat a missing status as live or as
|
|
100
|
+
retired. Status lines are the repository's claim, not approval: before step 6,
|
|
101
|
+
show the developer the live slugs and the orders you will place on each, and
|
|
102
|
+
place orders only on the list they confirm.
|
|
103
|
+
|
|
70
104
|
## 2. Find every pin
|
|
71
105
|
|
|
72
106
|
**Page-kit repo** (`_data/campaigns.json` exists):
|
|
@@ -115,6 +149,11 @@ particular:
|
|
|
115
149
|
coupon exists on every campaign the funnel uses.
|
|
116
150
|
- Note whether the range changes the card fields or the 3-D Secure flow; if it
|
|
117
151
|
does, plan a 3-D Secure test order in step 6.
|
|
152
|
+
- List any payment or express-checkout method the range adds (0.4.43 adds Shop
|
|
153
|
+
Pay, which the express-checkout container shows from store settings unless
|
|
154
|
+
the campaign's `expressCheckout.methodOrder` leaves it out)
|
|
155
|
+
and check whether the campaign or store lists it. Plan each listed one for
|
|
156
|
+
step 6.
|
|
118
157
|
- When the range removes a feature the campaign uses, say so, and do not just
|
|
119
158
|
delete the call: that silently drops the feature from a live funnel. Look for
|
|
120
159
|
a documented replacement in the repository's own docs (`CLAUDE.md`,
|
|
@@ -135,7 +174,7 @@ later), at the highest version its supported range declares. Read each
|
|
|
135
174
|
`docs/sdk-storage-compatibility.md`.
|
|
136
175
|
|
|
137
176
|
The manifest's `supportedSdkVersions` can stop below the tag it ships in: tags
|
|
138
|
-
v0.4.39 to v0.4.
|
|
177
|
+
v0.4.39 to v0.4.43 declare 0.4.38 to 0.4.38, so `--target-sdk 0.4.43` returns
|
|
139
178
|
`target-outside-manifest-range`. Run the check at the manifest's highest
|
|
140
179
|
version and report that it does not speak for the versions above it.
|
|
141
180
|
|
|
@@ -144,7 +183,8 @@ version and report that it does not speak for the versions above it.
|
|
|
144
183
|
**Page-kit:** run a development build, confirm every built page loads only the
|
|
145
184
|
target version and that no built loader URL still holds an unrendered `{{`,
|
|
146
185
|
then `campaigns-os doctor --built <repo> --family <family> --slug <slug>`
|
|
147
|
-
(tier `none`)
|
|
186
|
+
(tier `none`) once per bumped slug, retired ones included, for a repository
|
|
187
|
+
with no Build Packet (`--family` as in step 6), or `campaigns-os doctor --packet <packet>`
|
|
148
188
|
with one. Errors that are already on `main` are recorded, not fixed. Report doctor's
|
|
149
189
|
advisories with the rest; an attribute flagged as missing from the SDK's index
|
|
150
190
|
that the page does set (for example `data-next-page-type` on `<body>`) goes in
|
|
@@ -157,30 +197,80 @@ remaining old version.
|
|
|
157
197
|
## 6. Preview proof
|
|
158
198
|
|
|
159
199
|
Deploy a preview and prove the bump with browser test orders under the
|
|
160
|
-
approval rule above
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
200
|
+
approval rule above, using the three answers you asked for up front.
|
|
201
|
+
|
|
202
|
+
Pin the run to the store's main market. The SDK picks the market from the
|
|
203
|
+
visitor's IP and never reads browser geolocation, so open the first page with
|
|
204
|
+
`?currency=<main>&country=<main>` (for example `?currency=USD&country=US`);
|
|
205
|
+
without them a run from another country can check out in another currency and
|
|
206
|
+
skip a currency-gated upsell. Both are Campaign Cart URL parameters, kept in
|
|
207
|
+
that tab's session storage, so put both on the first page of every new tab or
|
|
208
|
+
browser context. `?country=` applies only when the campaign's
|
|
209
|
+
`currencyBehavior` is `auto`. Before each order, confirm the page shows
|
|
210
|
+
that currency and the country is selected; a value the campaign does not
|
|
211
|
+
support falls back without failing (`currency:fallback`). On `qa run`, pass
|
|
212
|
+
`--currency <main>`: it tags each funnel's entry page and records the currency
|
|
213
|
+
in the verdict, but the runner's separate page checks open new tabs without
|
|
214
|
+
it. `qa run` has no country flag.
|
|
215
|
+
|
|
216
|
+
Test orders send real purchase events to every analytics vendor the campaign
|
|
217
|
+
configures unless the vendor beacons are blocked at the network. `qa run` does
|
|
218
|
+
not block them yet. Do not add `?ignore=true` to stop them: it turns off the
|
|
219
|
+
SDK's analytics, `dl_*` events included, for the rest of the session, so the
|
|
220
|
+
purchase-event check below cannot pass. Before asking for test orders, list
|
|
221
|
+
the vendors and name them in the question. On Page Kit, read every non-empty
|
|
222
|
+
vendor id in the slug's `_data/campaigns.json` entry (such as `gtm_id` and
|
|
223
|
+
`fb_pixel_id`) and `analytics.providers` in `config.js`; on a static page,
|
|
224
|
+
read its inline `nextConfig` and the tags it loads.
|
|
225
|
+
Say that tags a GTM container fires, pixels the pages wire by hand, and
|
|
226
|
+
server-side conversions sent from the order backend may also receive the
|
|
227
|
+
orders and are not in that config. Name in the hand-back each vendor that
|
|
228
|
+
received test-order events.
|
|
229
|
+
|
|
230
|
+
- With a Build Packet: `campaigns-os qa run --packet <packet> --base-url <preview-url> --currency <main> --browser --test-order common`
|
|
231
|
+
(tier `C`; see `next-campaigns-qa`). The runner's test orders use a US
|
|
232
|
+
shipping address by default. For a store whose main market is not the US,
|
|
233
|
+
give the runner an address in that market: add `--test-country <main>`,
|
|
234
|
+
`--test-address1`, `--test-city`, `--test-province` and `--test-postal`
|
|
235
|
+
(all five; the defaults are a US address). The runner warns when a non-USD
|
|
236
|
+
`--currency` has no `--test-country`. If the checkout shows no province
|
|
237
|
+
select for that country, or the runner cannot complete the address, run it
|
|
238
|
+
without `--test-order` and place the orders by hand on the market-pinned
|
|
239
|
+
page.
|
|
240
|
+
- A built page-kit repo with no packet: `campaigns-os qa run --site <repo> --base-url <preview-url> --family <family> --slug <slug> --currency <main> --browser`
|
|
241
|
+
(tier `C`) checks the served pages of one slug; run it once per live slug. Place the approved test orders in the
|
|
242
|
+
browser and record each order number. `--family` is the starter template the
|
|
243
|
+
funnel was built from, named as a template brand contract: a file
|
|
244
|
+
`contracts/template-brand-contract.<family>.v0.json` in the installed
|
|
245
|
+
package (`node_modules/@nextcommerce/campaigns-os/contracts/`), or a private
|
|
246
|
+
family listed in `contracts/private-template-sources.json`, which needs a
|
|
247
|
+
checkout of its repository beside the package or `PRIVATE_TEMPLATE_SOURCES_ROOT`
|
|
248
|
+
pointing at its parent; without one, stop and say so rather than use a
|
|
249
|
+
public family. If the
|
|
250
|
+
repository's `CLAUDE.md` or the developer does not say which template each
|
|
251
|
+
slug came from, ask; do not guess from page or folder names. Use a value only
|
|
252
|
+
if it exactly matches one of those contract names, and a slug only if it
|
|
253
|
+
exactly matches a key in `_data/campaigns.json`; otherwise ask.
|
|
171
254
|
- A static repo: place the approved test orders in the browser on the preview
|
|
172
255
|
and record each order number.
|
|
173
256
|
|
|
174
257
|
Cover:
|
|
175
258
|
|
|
176
|
-
- one card order per live checkout;
|
|
259
|
+
- one card order per live checkout, on every live slug from step 1;
|
|
177
260
|
- PayPal cancelled, then a card order, where PayPal is offered;
|
|
261
|
+
- each payment or express method step 3 found the range adds, started and
|
|
262
|
+
cancelled, where the campaign offers it;
|
|
178
263
|
- an upsell at quantity 2 or more on a page that shows a quantity picker;
|
|
179
264
|
- a 3-D Secure card when step 3 found card-field or 3-D Secure changes, and whether it challenged;
|
|
180
265
|
- the coupon path, if the funnel has one;
|
|
181
266
|
- the purchase event fires once, on the page the release says it should;
|
|
182
|
-
-
|
|
183
|
-
`next:initialized` listener from step 3 running once on
|
|
267
|
+
- every SDK page, upsells included, on one fresh load and then five cached
|
|
268
|
+
reloads, with every `next:initialized` listener from step 3 running once on
|
|
269
|
+
each load. Count the loads per page for the hand-back. Leave out of the cached reloads
|
|
270
|
+
the receipt and any page where step 3 found a hand-wired purchase push or
|
|
271
|
+
`order:completed` listener: upsell pages reload the order and can resend a
|
|
272
|
+
real purchase on each load. Count purchase events across the whole run, and
|
|
273
|
+
list those pages' listeners as not proven on cached reloads.
|
|
184
274
|
|
|
185
275
|
Read each order back in the store admin (the packet run's verdict under
|
|
186
276
|
`qa-output/` also lists the orders it created) and keep the order numbers for
|
|
@@ -189,5 +279,8 @@ the hand-back.
|
|
|
189
279
|
## 7. Hand back
|
|
190
280
|
|
|
191
281
|
On the ticket or the pull request, not in the repository: what changed (pins,
|
|
192
|
-
loader rewrites), the storage-check and doctor results,
|
|
193
|
-
|
|
282
|
+
loader rewrites), the storage-check and doctor results, which slugs are live and
|
|
283
|
+
which had no status recorded, the retired slugs that were bumped but not
|
|
284
|
+
proven, any new payment buttons, a table of test orders by slug, the fresh and
|
|
285
|
+
cached load counts per SDK page, which analytics vendors received test-order
|
|
286
|
+
events, what is not proven, and which orders to cancel.
|
package/skills.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "campaigns-os-skills",
|
|
3
3
|
"description": "Skills bundled with Campaigns OS. `skills.sh` installs these into the shared agent skill directories (~/.claude/skills, ~/.codex/skills), so each one is a versioned package: bump the version whenever a package changes. `bundle_revision` identifies the bundle as a whole — `<package version>+skills.<n>`, where the prefix is this package's version and `<n>` counts the skill-text revisions published against it. It advances whenever ANY bundled skill changes, every SKILL.md states it on its first body line, and `campaigns-os tooling status --skills-revision <value>` compares the value an agent read from a skill against the bundle on disk. See docs/skills-revision.md.",
|
|
4
|
-
"bundle_revision": "1.
|
|
4
|
+
"bundle_revision": "1.61.0+skills.1",
|
|
5
5
|
"homepage": "https://github.com/NextCommerceCo/campaigns-os",
|
|
6
6
|
"retired_skills": [
|
|
7
7
|
{
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
{
|
|
17
17
|
"id": "next-campaigns-os",
|
|
18
18
|
"name": "Campaigns OS Lifecycle",
|
|
19
|
-
"version": "1.0.
|
|
19
|
+
"version": "1.0.66",
|
|
20
20
|
"path": "skills/next-campaigns-os/SKILL.md",
|
|
21
21
|
"domain": "campaigns",
|
|
22
22
|
"description": "Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth."
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
{
|
|
25
25
|
"id": "next-campaigns-os-setup",
|
|
26
26
|
"name": "Campaigns OS Setup",
|
|
27
|
-
"version": "2.0.
|
|
27
|
+
"version": "2.0.49",
|
|
28
28
|
"path": "skills/next-campaigns-os-setup/SKILL.md",
|
|
29
29
|
"domain": "campaigns",
|
|
30
30
|
"description": "Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly next-campaigns-setup; renamed to release that name to the published NextCommerceCo/skills scaffolder."
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
{
|
|
33
33
|
"id": "next-campaigns-build",
|
|
34
34
|
"name": "Campaign Build",
|
|
35
|
-
"version": "1.0.
|
|
35
|
+
"version": "1.0.51",
|
|
36
36
|
"path": "skills/next-campaigns-build/SKILL.md",
|
|
37
37
|
"domain": "campaigns",
|
|
38
38
|
"description": "Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts."
|
|
@@ -40,7 +40,7 @@
|
|
|
40
40
|
{
|
|
41
41
|
"id": "next-campaigns-polish",
|
|
42
42
|
"name": "Campaign Polish",
|
|
43
|
-
"version": "1.1.
|
|
43
|
+
"version": "1.1.51",
|
|
44
44
|
"path": "skills/next-campaigns-polish/SKILL.md",
|
|
45
45
|
"domain": "campaigns",
|
|
46
46
|
"description": "Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign."
|
|
@@ -48,7 +48,7 @@
|
|
|
48
48
|
{
|
|
49
49
|
"id": "next-campaigns-qa",
|
|
50
50
|
"name": "Campaign QA",
|
|
51
|
-
"version": "1.3.
|
|
51
|
+
"version": "1.3.50",
|
|
52
52
|
"path": "skills/next-campaigns-qa/SKILL.md",
|
|
53
53
|
"domain": "campaigns",
|
|
54
54
|
"description": "Run spec-aware QA from a saved Map or local-spec Build Packet and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof."
|
|
@@ -56,7 +56,7 @@
|
|
|
56
56
|
{
|
|
57
57
|
"id": "campaign-lifecycle-orientation",
|
|
58
58
|
"name": "Campaign Lifecycle Orientation",
|
|
59
|
-
"version": "1.0.
|
|
59
|
+
"version": "1.0.46",
|
|
60
60
|
"path": "skills/campaign-lifecycle-orientation/SKILL.md",
|
|
61
61
|
"domain": "campaigns",
|
|
62
62
|
"description": "Orient a reader to the Campaigns OS lifecycle artifacts a run has already emitted, without advancing their state: the shared vocabulary, doctor as a gate, the stage record, and the store-theme/Page Kit two-worlds trap."
|
|
@@ -64,7 +64,7 @@
|
|
|
64
64
|
{
|
|
65
65
|
"id": "campaign-run-evidence",
|
|
66
66
|
"name": "Campaign Run Evidence",
|
|
67
|
-
"version": "1.0.
|
|
67
|
+
"version": "1.0.46",
|
|
68
68
|
"path": "skills/campaign-run-evidence/SKILL.md",
|
|
69
69
|
"domain": "campaigns",
|
|
70
70
|
"description": "Interpret existing doctor, QA verdict and proof-depth evidence without claiming more proof than the artifacts contain, and keep funnel proof apart from merchant launch readiness."
|
|
@@ -72,7 +72,7 @@
|
|
|
72
72
|
{
|
|
73
73
|
"id": "campaign-readback-classification",
|
|
74
74
|
"name": "Campaign Readback Classification",
|
|
75
|
-
"version": "1.0.
|
|
75
|
+
"version": "1.0.46",
|
|
76
76
|
"path": "skills/campaign-readback-classification/SKILL.md",
|
|
77
77
|
"domain": "campaigns",
|
|
78
78
|
"description": "Classify a selected campaign from the campaigns-os-readback/v2 fields (artifacts, staleness.stale_keys, clean, doctor, divergences, skip_cascades) and write a read-only handoff without turning diagnosis into permission."
|
|
@@ -80,7 +80,7 @@
|
|
|
80
80
|
{
|
|
81
81
|
"id": "contribution-intake",
|
|
82
82
|
"name": "Contribution Intake",
|
|
83
|
-
"version": "1.0.
|
|
83
|
+
"version": "1.0.46",
|
|
84
84
|
"path": "skills/contribution-intake/SKILL.md",
|
|
85
85
|
"domain": "campaigns",
|
|
86
86
|
"description": "Turn a suggestion about the agent surface into a classified, evidence-checked and redacted proposal, filed on this repository tracker only with attended approval."
|
|
@@ -88,7 +88,7 @@
|
|
|
88
88
|
{
|
|
89
89
|
"id": "next-campaigns-sdk-bump",
|
|
90
90
|
"name": "Campaign SDK Bump",
|
|
91
|
-
"version": "1.0.
|
|
91
|
+
"version": "1.0.6",
|
|
92
92
|
"path": "skills/next-campaigns-sdk-bump/SKILL.md",
|
|
93
93
|
"domain": "campaigns",
|
|
94
94
|
"description": "Bump a live campaign from one Campaign Cart 0.4.x release to a later 0.4.x on a page-kit or static repo: find every pin, check the release diff and storage against the campaign code, prove on a preview with approved test orders, and report what is not proven."
|