If the request is already bounded to one phase and that phase skill is available, route there instead of inlining the full runbook here.

Once site-analysis.json indicates Shopify, keep discovery and grouping shared, then let tracking-shopify own the Shopify-specific branch.

Shared Contract

• Use the repo-local wrapper ./event-tracking in this repository. If dist/cli.js is missing, run npm run build first.
• For public/ClawHub installs, you must run this first before any event-tracking command: npx skills add jtrackingai/analytics-tracking-automation.
• Keep one artifact directory per site at <output-root>/<url-slug>.
• If the user already provides an artifact directory or one of its files, resume from the earliest unmet prerequisite instead of restarting from analyze.
• Use ./event-tracking status <artifact-dir-or-file> whenever the current checkpoint or next step is unclear.
• Use ./event-tracking runs <output-root> when the artifact directory is unknown but the output root is known.
• Prefer high-level entry commands for user-facing flows: run-new-setup, run-tracking-update, run-upkeep, run-health-audit.
• Before first workflow command, honor the telemetry consent gate. Treat telemetry consent as a required user-choice checkpoint for the session. Follow telemetry-consent.md as the single-source interaction contract. If consent is missing or invalid, explain both outcomes before asking: yes stores local consent and enables high-level anonymous usage diagnostics for future runs, while no stores local decline and continues the workflow without sending diagnostics.
• Never decide telemetry consent on the user's behalf. Telemetry consent is recorded only in the local telemetry config file, not through enable/disable environment-variable overrides.
• If the user agrees, continue through the interactive prompt so it can record local consent. If the user declines, continue through the prompt so it can record the local decline. The workflow can continue either way, but the choice must come from the user.
• If the current run surfaces a telemetry prompt and the user has not answered it yet, stop and follow telemetry-consent.md before asking for a choice. Explain the purpose, what yes does, what no does, and the remaining privacy tradeoff before asking the user to reply yes or no. Do not ask a bare yes/no question with no context, do not answer the prompt for them, and do not continue to the next workflow command until the user makes that choice.
• Treat workflow mode metadata as an internal workflow-state layer, not a user-facing command surface.
• Treat Playwright-backed and OAuth-prompting steps as non-sandbox commands by default. In practice: analyze, validate-schema --check-selectors, preview, and sync.
• Run prompt-driven GTM sync with an interactive TTY from the start unless exact --account-id, --container-id, and --workspace-id values are already confirmed.
• Never auto-select a GTM account, container, or workspace on the user's behalf.
• Do not continue past the phase boundary the user asked for.

Conversation Intake

When the user enters through chat and has not yet provided a bounded phase, artifact directory, or exact command, start with an intent-first intake.

Classify the request into one of these entry intents:

• resume_existing_run: the user already has an artifact directory or one of its files; inspect the artifacts and use status
• new_setup: net-new tracking implementation from scratch; prefer run-new-setup, then follow its recommended next step
• tracking_update: revise or extend an existing implementation; prefer run-tracking-update
• upkeep: routine maintenance, review, or incremental QA on an existing setup; prefer run-upkeep
• tracking_health_audit: audit-only assessment of current live tracking; prefer run-health-audit
• analysis_only: crawl/bootstrap/discovery only without committing to the full workflow yet; route to tracking-discover and stop after analyze

Rules:

• Do not ask the user to choose between internal workflow metadata flags and analyze.
• If intent is ambiguous, ask one short plain-language intake question using user-facing terms such as "new setup", "update existing tracking", "upkeep", "health audit", "analyze only", or "resume an existing run".
• If the user gives a fresh URL and asks to set up tracking, default to new_setup.
• If the user gives a fresh URL and only asks to inspect the site, analyze structure, or review current tracking signals, default to analysis_only.
• If the user gives an artifact directory or workflow file, default to resume_existing_run instead of restarting from analyze.

Routing Rules

Route by user intent and current artifacts:

• fresh URL, crawl request, or no artifacts yet: start with tracking-discover
• site-analysis.json with missing or unconfirmed pageGroups: route to tracking-group
• confirmed site-analysis.json with detected live GTM container IDs but no live baseline review yet: route to tracking-live-gtm
• confirmed site-analysis.json or an in-progress event-schema.json: route to tracking-schema
• gtm-config.json: route to tracking-sync
• gtm-context.json: route to tracking-verify, with publish treated as a separate explicit action
• Shopify platform confirmation: keep shared early stages, then hand off to tracking-shopify

If only the root skill is available, follow the same routing logic directly and stop at the matching phase boundary.

Stop Rules

• Do not bypass page-group approval before prepare-schema.
• For key decision checkpoints, always require explicit user confirmation before continuing:
  • pageGroups (before confirm-page-groups and before prepare-schema)
  • event-schema.json (before confirm-schema and before generate-gtm)
  • GTM target selection (account/container/workspace during sync)
  • publish decision (before publish)
• If confirmation is missing or ambiguous, stop and ask; do not auto-proceed.
• Treat telemetry consent the same way as other explicit approval gates: if the user has not chosen yes or no, stop and ask instead of making the decision for them.
• A broad request such as "full workflow", "全流程", "end-to-end", or "continue all the way" is scope authorization only. It does not count as checkpoint approval.
• Never record checkpoint approval on the user's behalf with confirm-page-groups --yes or confirm-schema --yes unless the user explicitly confirms that checkpoint in the current turn.
• When live GTM containers are detected on the site, do not bypass the live baseline review before schema generation.
• Do not bypass schema approval before generate-gtm unless the user explicitly wants --force.
• Treat preview QA and publish as separate decisions.
• Treat tracking-health.json as the publish gate; do not jump to publish when health is missing, manual-only, or blocked unless the user explicitly wants --force.
• Treat Shopify manual verification as the expected path for Shopify runs, not as a fallback error case.
• Treat tracking_health_audit as an audit-only workflow mode. Do not run GTM deployment actions (generate-gtm, sync, publish) unless the user explicitly asks to override.

Resume And Closeout

When resuming:

• prefer workflow-state.json when present
• still inspect the real artifact set if warnings indicate stale gates
• use status when the next step is unclear

When a phase or the full workflow ends, keep the closeout answer-first:

• lead with a compact, decision-ready summary in plain language
• do not dump raw JSON, raw URL lists, or artifact inventory before the summary
• list files, checkpoint, and next command only after the human-readable summary

References

• skill-map.md for the umbrella / phase skill map
• architecture.md for lifecycle, checkpoints, and resume semantics
• output-contract.md for artifact files and gate semantics
• shopify-workflow.md for Shopify-specific branch expectations
• telemetry-consent.md for the telemetry consent gate wording and behavior contract

• docs/README.install.md
• docs/skills.md

ClawHub Publish

If you are publishing this skill to ClawHub, publish the exported public bundle instead of the full repository:

npm run export:skills:clawhub

Then upload dist/clawhub-skill-bundles/analytics-tracking-automation.

That public bundle is a publish-safe skill bundle. It keeps the agent-facing skill docs and references while stripping bundled executable runtime files (CLI bootstrap, packaged node modules, telemetry transport, and updater runtime) that tend to trigger stricter marketplace security scans.

When users install/use this public ClawHub bundle, they must run this prerequisite first (before any event-tracking command):

npx skills add jtrackingai/analytics-tracking-automation

Quick Start

Use It As A Skill

The intended experience is simple: tell your agent what you want in plain language.

Good requests usually include one or more of:

• the site URL
• whether this is a new setup, update, upkeep, or audit
• the output root for a new site run, such as ./output or /tmp/output
• an existing site artifact directory if you already have one, such as ./output/example_com
• GA4 measurement ID or GTM context when you already know them
• any scope boundary such as "stop after schema review"

For a new setup, the output root is not the artifact directory itself. The agent/CLI creates one artifact directory per site under that root, for example ./output/example_com.

Example Prompts

New setup from scratch:

Use analytics-tracking-automation to plan GA4 + GTM tracking for https://www.example.com.
Use ./output as the output root; create the site artifact directory under it.
Start from a fresh run and stop after the event schema is ready for review.

New setup with implementation context:

Use analytics-tracking-automation to set up tracking for https://www.example.com.
Use /tmp/output as the output root, so this site's artifacts go under /tmp/output/www_example_com.
GA4 Measurement ID is G-XXXXXXXXXX.
We care most about signup, pricing, contact, and demo intent.

Audit only:

Use analytics-tracking-automation to run a tracking health audit for https://www.example.com.
I only want to understand the current live GTM setup and whether we should repair or rebuild.
Do not continue into deployment work.

Routine upkeep:

Use analytics-tracking-automation to do an upkeep review for this existing run:
./output/example_com
Tell me what is still healthy, what drifted, and what needs repair.

Update an existing artifact:

Use analytics-tracking-automation to resume this artifact directory:
./output/example_com
Tell me the current checkpoint and continue only through schema review.

Page-group review only:

Use analytics-tracking-automation to review and refine the page groups in:
./output/example_com/site-analysis.json
Focus on business intent, not just URL shape.

Shopify branch:

Use analytics-tracking-automation for this Shopify storefront:
https://store.example.com
I want the Shopify-specific tracking path, not the generic website flow.

How To Think About It

This skill is best when you want the agent to act like a tracking lead, not just a command runner.

A typical conversation flow is:

1. inspect the site or resume an existing run
2. group pages in a reviewable way
3. draft or revise the event plan
4. review what should be reused, repaired, added, or dropped
5. continue into GTM generation and verification only when you explicitly want that

Where To Go Next

• Installation details: docs/README.install.md
• Skill family map: docs/skills.md
• Agent-facing workflow contract: SKILL.md
• CLI and maintainer workflow: DEVELOPING.md

Quick Debug Tips

If preview troubleshooting points to selector mismatch or page-load/navigation issues, these Playwright CLI helpers are faster than repeatedly re-running the full flow:

npm run debug:open -- https://www.example.com
npm run debug:codegen -- https://www.example.com

• debug:open: headed browser for quick visual checks (redirect loops, WAF pages, blocked content).
• debug:codegen: interactive selector capture for fixing event-schema.json selectors.

Product Boundary

• the workflow runs locally
• browser-backed steps rely on Playwright Chromium; npm install triggers the package postinstall step that installs the browser binary
• GTM sync uses Google OAuth
• OAuth credentials are cached in the artifact directory for the current site run
• generic sites use automated preview verification
• Shopify uses the Shopify-specific branch and manual post-install validation
• optional anonymous usage diagnostics are opt-in and the first explicit choice is stored in local user config; if enabled, future runs send high-level workflow data such as command name, success/failure status, rough counts, site hostname, detected platform, and broad workflow checkpoints so operators can improve the product and troubleshoot reliability; if declined, future runs continue normally without sending diagnostics until the user changes that local config choice; diagnostics do not send full URLs, page paths, query strings, file paths, GTM/GA IDs, selectors, OAuth data, raw errors, or page content; the remaining privacy risk is that the site hostname and workflow metadata still reveal which domain was worked on and broad usage patterns; if a workflow prompt asks for telemetry consent and no stored preference exists, the operator must stop and let the user choose yes or no instead of answering on the user's behalf
• installed copy bundles can self-check GitHub for updates and reinstall the same selected bundle set

Need A More Advanced Setup?

This skill reflects the implementation workflow behind JTracking.

If you need a more advanced setup, JTracking also supports:

• richer tracking design based on concrete business flows
• server-side tracking and custom loaders
• more destination and ad-platform integrations
• longer-term tracking operations and maintenance

License

This project is licensed under the Apache License, Version 2.0. See LICENSE for the full text.

Use of the JTracking name, logo, and other brand assets is not granted under this license.