Operating Contract

Apply this contract to every audit, diagnosis, or test task.

Establish the target and safety boundary

1. 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.
2. 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.
3. With a target repository, record a relevant existing validation command only when selected evidence needs source validation; do not inventory every install, build and test command by default. Search configuration and scripts for explicit store domains, preview URLs, theme IDs, and --store arguments. Treat the user's explicit target as highest priority, then an unambiguous repository-local target. A folder name is not store identity.
4. 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.
5. 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.
6. Keep Core read-only on public homepage, collection and product pages. Do not submit add-to-cart, cart-edit, checkout, login or account forms. 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.
7. 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 within this contract's public-browse boundary.

Some mirrored Checks describe broader procedures for Comprehensive. In Core, exercise only applicable public homepage, collection and product browse states. Repository/component inspection and authoritative catalog context may use available supporting evidence; they are not prerequisites when rendered evidence independently decides the Check. Do not request signed-in states, submit purchase actions or test search-only behavior to complete a Core procedure. Missing optional sources or excluded states cannot make an otherwise decidable public-browse Check Blocked; unresolved price or product truth that actually prevents a decision still can. Record the evaluated states and scope explicitly rather than claiming the broader procedure was completed.

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

1. Observe current behavior and preserve baseline evidence.
2. Reproduce or measure through the real code path and a real browser when the claim is rendered or interactive.
3. Localize the responsible source, content, configuration, third party, or data dependency.
4. Validate with the target's existing syntax, schema, lint, test, build, Theme Check, or platform commands as applicable.
5. Retest the original flow at the relevant viewport and one adjacent regression surface.
6. Compare only against a compatible baseline, prior audit, or stated threshold.
7. 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.

Public session boundary

Use an owned anonymous browser context when the host supports one. A new tab may share cookies/cart state; never assume it is an isolated session. Do not inspect an unrelated signed-in account or change an existing cart. Core's checks stop before purchase submission and do not require clearing carts, creating checkout state or requesting customer credentials.

If the host cannot provide a safe public context, document that exact capability limit and safe attempts, then block only the decisions it prevents. A missing cart-testing capability cannot block a Core Check because cart submission is outside its scope.

Shopify gate

When a selected Check needs Shopify source validation:

1. Inspect the actual theme architecture and source of truth.
2. Use the pinned Shopify developer documentation MCP before judging unfamiliar Liquid, schema, object, filter, API, or CLI behavior.
3. Evaluate section/block nesting and settings against the target theme and current platform contract, not memory or an example alone.
4. Run a relevant existing non-mutating check only when it can resolve that selected decision. Do not run the full test suite or Theme Check by default for a browser-supported browse audit.
5. Test an existing development or unpublished preview in a real browser when available.
6. 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.