Apply this contract to every audit, diagnosis, or test task.
Establish the target and safety boundary
- Start from the configured live URL and any repository explicitly named by the user or current workspace. Never substitute a target inferred from an authenticated connector.
- With a target repository, read the target repository's nearest
AGENTS.md, root guidance,README*, package/configuration files, Shopify CLI/TOML configuration, and environment templates or command references without exposing secrets. - With a target repository, record the target's install, preview, build, test, and validation commands. Search configuration and scripts for explicit store domains, preview URLs, theme IDs, and
--storearguments. Treat the user's explicit target as highest priority, then an unambiguous repository-local target. A folder name is not store identity. - Require only the configured HTTP(S) live URL. Recommend the GitHub-backed repository/theme path, GitHub, Shopify connection, and Google Analytics property as optional evidence sources. Continue independent Checks when those sources are unavailable. Bind each source to the same storefront before using it. Identify requested flows, target devices, primary conversion, and reporting timezone. When sources conflict, continue independent safe work and mark only the affected check blocked instead of guessing.
- With a target repository, inspect the working tree and preserve unrelated changes. Find prior reports, evidence, analytics windows, experiments, acceptance criteria, and any host-supplied human workflow or archive state. Revalidate drift-prone facts.
- Keep the audit read-only except for approved anonymous cart and synthetic-checkout state. Never edit source, commit, push, open a pull request, publish, deploy, purchase, message, create an account, submit payment, place an order, or mutate authenticated customer/store data.
- Use an existing development or unpublished theme for non-production verification when available. This skill does not create, upload, or publish themes.
Connection setup is separate from evaluation. Use the connection setup handoff only when a missing declared source is useful and the user agrees. Guarded read-only runners hand this off to their host; connection authorization does not permit business-data writes.
Target-bound connector gate
- Use only the optional GitHub-backed repository, its GitHub history and metadata, the required live storefront URL, the matching Shopify store, the matching Google Analytics property, prior compatible reports, current platform documentation, artifacts produced from those sources, and owner-supplied sanitized aggregate customer-research summaries under the customer-research workflow.
- Never call a generic identity operation or ambient current-shop command merely to discover which store or property happens to be connected. Establish the intended store and analytics property from the configured target, then verify permanent/primary domain or web-stream URI before querying business data.
- Use Shopify and GA4 read-only. Query the smallest aggregate scope needed for a check. Do not expose or retain customer identifiers, individual sessions, individual orders, addresses, contact details, or unrestricted event exports.
- Repository-defined read-only commands may validate the checked-out target. Reading setup or connection state never authorizes an upload, configuration change, analytics write, theme creation, or publish action.
- Do not request or consume Search Console, ads, CRM, email/SMS, reviews, session replay, sales, or other connected-data sources. Sanitized owner-supplied aggregate research summaries are optional artifacts, not permission to connect those services or read individual sessions/tickets. If an active check requires an excluded source and the permitted sources cannot independently decide it, treat that as a catalog defect rather than a target-wide blocker.
Check execution
Follow check selection and evaluation for catalog scope, batches, context records and terminal decisions. The selected Check owns its applicability, test procedure and outcome criteria.
Test-account secret gate
- Treat configured account credentials only as the non-secret capabilities
report-secret:account-emailandreport-secret:account-password. Never request, persist, echo, serialize, log, fixture, screenshot, or write either value to an artifact, repository file, command, prompt, or report. - Require host confirmation of both configured capabilities and guarded, target-bound secret handling before authenticated read-only inspection. In Glue, add
[use-report-secrets]only to the guarded browser task that needs it. Other hosts use an equivalent protected capability; the Glue marker itself grants no access elsewhere. The task remains bound to the configured target origin. - Without both capabilities, continue public and repository-backed evaluation. Mark an account-only check
Blockedonly when its required decision cannot be made from those safe sources, and name the missing authenticated state precisely. - Never create an account or change passwords, addresses, payment methods, profile data, newsletter or subscription settings, returns, cancellations, orders, or any other customer state.
Evidence contract
Required context comes from the selected Check's declared requirements and the evidence actually needed to decide its assertions. A generic instruction to inspect source, competitors or analytics does not promote a declared supporting source into a prerequisite. Use available permitted supporting evidence when useful; record the gap without blocking independently decidable observations. A reproduced defect remains a failure even when another required state cannot be inspected; retain the untested portion as a limitation of the evidence, without claiming broader completion. Only missing evidence necessary for an otherwise undecidable Check justifies Blocked.
For every reported Issue, capture:
- exact URL/state or file/line target;
- timestamp, viewport, browser, theme/commit when known, and authentication state;
- action or command that exposed the behavior;
- observed screenshot, DOM, console/network output, metric, test failure, or source evidence;
- expected behavior and the source of that expectation;
- scope, impact, priority, confidence, and a concrete change or next experiment.
Use these evidence labels consistently:
- Confirmed: directly reproduced or measured.
- Likely: supported by evidence but not reproduced end to end.
- Hypothesis: plausible and testable; include only when it supports a bounded experiment.
- Blocked: required access, data, environment, or reproduction state is unavailable and named precisely.
Do not turn pattern counts, Lighthouse scores, automated accessibility output, or generic best practices into confirmed defects without contextual verification.
The check evaluation workflow owns context availability, representative evidence and terminal-outcome handling. The reporting contract owns Issue eligibility and output reconciliation.
Execution loop
- Observe current behavior and preserve baseline evidence.
- Reproduce or measure through the real code path and a real browser when the claim is rendered or interactive.
- Localize the responsible source, content, configuration, third party, or data dependency.
- Validate with the target's existing syntax, schema, lint, test, build, Theme Check, or platform commands as applicable.
- Retest the original flow at the relevant viewport and one adjacent regression surface.
- Compare only against a compatible baseline, prior audit, or stated threshold.
- Record the terminal result, residual risk, and implementation handoff.
Human workflow state is historical context, never model output. When a prior experiment Issue is resolved, cancelled, or archived, preserve the learning and do not silently regenerate the same hypothesis from unchanged evidence. Report a comparable Improved, Regressed, or Resolved Change when the new measurement supports it; otherwise propose a distinct next hypothesis only when current target evidence justifies one. The audit never changes an Issue status or archive state.
Use the host's workbench for repository inspection, standard commands, existing tests, isolated builds, and evidence processing. Follow the repository discovery reference for Jevgrep-assisted behavioral questions when available and direct-read or rg fallback. Use the host's browser capability for rendered evidence. Store Skills does not supply executable audit commands.
Browser evidence
Use a real-browser capability for rendered or interactive claims. Follow browser testing for viewport verification and shared evidence collection; selected Checks determine required states and evidence. If a capability is unavailable, continue independent safe work and record only the affected decisions as blocked under the check evaluation workflow.
Approved anonymous cart and synthetic checkout
Before cart or checkout tests, verify that the host provides an owned, disposable anonymous context. A new tab may share existing cart or authenticated state and is not proof of isolation. If retained state is unrelated or of uncertain ownership, leave it unchanged and try a supported fresh context; never clear a user's cart or cookies to create one. If isolation is unavailable, record that exact capability limit and attempted safe acquisition, not a blanket claim that bounded cart tests are forbidden.
When checkout is in scope and the target permits an anonymous session, the audit may create disposable cart state, update quantities, remove and re-add items, begin checkout, and submit fictional contact/shipping details only until payment options render. Use:
storeskills-audit+<runId>@example.com, replacing<runId>with a lowercase alphanumeric host run identifier;- name
Store Skills Audit; 123 Test Street,New York,NY,10001,United States;2125550100only when required.
Keep marketing and account-creation options unchecked. Stop when payment options render. Never enter card or wallet credentials, invoke accelerated payment, click a pay/place-order action, or complete an order. Record the synthetic session boundary without treating the intentional stop as a Limitation.
Disposable cart cleanup is run hygiene, not check evidence. If a rendered cart defect prevents cleanup, report that defect and finalize the isolated browser session; do not use the cleanup failure to block unrelated cart checks. Checks about the broken cart path may Fail from direct evidence, optional absent cart features may be Not applicable, and only downstream states that genuinely cannot be observed may be Blocked.
Shopify gate
For Shopify theme audits:
- Inspect the actual theme architecture and source of truth.
- Use the pinned Shopify developer documentation MCP before judging unfamiliar Liquid, schema, object, filter, API, or CLI behavior.
- Evaluate section/block nesting and settings against the target theme and current platform contract, not memory or an example alone.
- Run applicable non-mutating target commands, including existing tests,
shopify theme check, and Shopify CLI validation. - Test an existing development or unpublished preview in a real browser when available.
- Do not invoke upload or publish commands.
Artifact handling
- Keep generated artifacts in a host-provided external location, outside Store Skills and the target repository unless the user explicitly requests a report file.
- Treat screenshots, console output, network URLs, headers, analytics exports, and browser state as potentially sensitive. Inspect artifacts before sharing.
- Do not expose credentials, private customer data, order details, or secret-bearing URLs.
Completion
Use the check evaluation workflow and reporting contract before returning results.