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

1. Use the repo-local wrapper ./event-tracking for CLI commands in this repository. If the wrapper reports that dist/cli.js is missing, run npm run build first.
2. Keep one artifact directory per site (<output-root>/<url-slug>). Each iteration inside that artifact should use a distinct run ID with snapshots under versions/<run-id>/.
3. If the user already provides an artifact directory or one of its files, resume from the earliest unmet prerequisite instead of restarting from analyze.
4. Use ./event-tracking status <artifact-dir-or-file> whenever the current checkpoint or next step is unclear.
5. Use ./event-tracking runs <output-root> when the user wants to find recent site runs and does not remember the artifact directory.
6. Google OAuth client metadata is embedded in the CLI and may be overridden with GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET.
7. Any Playwright-backed or OAuth-triggering step must run outside a sandboxed environment by default. In practice, treat analyze, validate-schema --check-selectors, preview, and sync as non-sandbox commands, and do not first attempt them in the sandbox before retrying after interception.
8. Never auto-select a GTM account, GTM container, or GTM workspace on the user's behalf. Always show candidates and require explicit confirmation unless the user already provided the exact ID for that step.
9. Prefer scenario-first entry commands for user-facing flows: run-new-setup, run-tracking-update, run-upkeep, run-health-audit. Use start-scenario when the user wants a labeled scenario run without immediate template execution.
10. Use ./event-tracking scenario <artifact-dir> --set <scenario> [--sub-scenario ...] [--new-run] for metadata-only adjustments when you should not alter execution flow.
11. Use ./event-tracking scenario-check <artifact-dir> when the question is "is this scenario ready" rather than "what is the next workflow checkpoint".
12. Use ./event-tracking scenario-transition <artifact-dir> --to <scenario> [--reason ...] when the user wants an auditable handoff between scenarios.
13. Do not continue past the phase boundary the user asked for. Stop after the requested phase unless the user explicitly asks to continue.

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 scenario and analyze. scenario is run-intent orchestration metadata; analyze is only one execution step.
• 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.
• 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 scenario. 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, summarize:

• artifact directory
• current checkpoint from workflow-state.json
• key output files from the completed phase
• next recommended command, if any
• remaining manual actions, especially for custom dimensions, Shopify install, tracking health, preview QA, or publish approval

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

git clone https://github.com/jtrackingai/event-tracking-skill.git
cd event-tracking-skill
npm run install:skills

That installs event-tracking-skill into the default skills directory with installer-managed auto-update metadata. You do not need npm ci just to install the exported skill bundles.

If you already know you want the full phase-oriented family installed together, make that explicit:

npm run install:skills -- --with-phases

This is the recommended install path for Codex and also the most portable path for other agent environments that can load skills from a local directory.

Codex defaults:

• $CODEX_HOME/skills when CODEX_HOME is set
• otherwise ~/.codex/skills

For other agent runtimes, point the installer at that runtime's skills directory:

npm run install:skills -- --target-dir /path/to/agent/skills

If you also want the phase skills in a custom directory:

npm run install:skills -- --target-dir /path/to/agent/skills --with-phases

For local development only, if you want the installed skills to stay pointed at local exported bundles:

npm run install:skills -- --mode link

To link the full skill family during local iteration:

npm run install:skills -- --mode link --with-phases

Auto-update behavior:

• copy installs are the recommended user path and can self-check for newer GitHub versions
• link installs are for local development only and intentionally do not auto-update from GitHub
• older installer-managed copies need one reinstall through npm run install:skills before they gain the installed auto-update bootstrap

Use docs/README.codex.md for Codex-specific defaults, update notes, and troubleshooting. Use docs/README.install.md for the full shared agent-install guide.

Install with skills.sh (Alternative)

Use this if you want to install the skill into your local agent skills directory without cloning the repository first.

npx skills add jtrackingai/event-tracking-skill

This portable install can self-check for updates too. On the first successful self-update it rewrites the installed copy into the repo's normal copy-mode layout.

If you want the full umbrella + phase-skill family installed together from the start, use npm run install:skills -- --with-phases.

If you want the repo-local CLI, contributor setup, or local development workflow, use DEVELOPING.md instead of treating README as a maintainer guide.

Documentation Map

• README.md for installation, quick start, and the public command surface
• docs/README.install.md for the shared agent-install flow, copy vs link behavior, and auto-update notes
• ARCHITECTURE.md for artifact lifecycle, branch behavior, and system boundaries
• DEVELOPING.md for maintainer commands, edit rules, and release checks
• docs/README.codex.md for Codex-specific defaults and troubleshooting on top of the generic installer flow
• docs/skills.md for the umbrella skill and phase-skill map
• SKILL.md for the agent-facing workflow contract

Skill Family

The repository now has:

• one umbrella skill: event-tracking-skill
• seven phase-oriented subskills under skills/: tracking-discover, tracking-group, tracking-live-gtm, tracking-schema, tracking-sync, tracking-verify, tracking-shopify

Use the umbrella skill for end-to-end or ambiguous requests. Use the phase skills when the user clearly wants only one part of the workflow, such as discovery, grouping, live GTM baseline review, schema review, GTM sync, preview QA, or Shopify-specific handling.

See docs/skills.md for the full map.

Root skill UI metadata now lives in agents/openai.yaml.

Exported Skill Bundles

If you need to package these skills outside this repository, generate self-contained bundles with:

npm run export:skills

That writes per-skill bundles to dist/skill-bundles/<skill-name>/.

Each exported bundle includes:

• SKILL.md
• agents/openai.yaml
• the references/ files that the skill may need, including exported architecture.md and skill-map.md where relevant

The exported bundles rewrite command examples to the public event-tracking command name. Inside this repository, keep using ./event-tracking.

Quick Start

Scenario-First (Recommended)

Use scenario templates when you already know the delivery intent and want versioned run history grouped by scenario from the start. For a brand-new URL with no artifacts yet, run-new-setup is a labeled entry point, not a replacement for analyze; it will usually point you to analyze as the first execution command.

# New implementation from scratch
./event-tracking run-new-setup ./output/example_com

# Incremental update for existing tracking
./event-tracking run-tracking-update ./output/example_com --baseline-schema ./output/example_com/schema-restore/confirmed-<hash>.json

# Routine upkeep check
./event-tracking run-upkeep ./output/example_com --baseline-schema ./output/example_com/schema-restore/confirmed-<hash>.json

# Audit-only health assessment before deciding rebuild
./event-tracking run-health-audit ./output/example_com --live-gtm-analysis ./output/example_com/live-gtm-analysis.json

Use these helpers when needed:

• ./event-tracking scenario <artifact-dir> --set <scenario> --new-run [--sub-scenario ...] [--input-scope ...] to relabel or branch a run without executing a workflow step
• ./event-tracking scenario-check <artifact-dir> to validate scenario-required artifacts and return the next scenario step
• ./event-tracking scenario-transition <artifact-dir> --to <scenario> --reason "<why>" to record scenario handoff decisions
• ./event-tracking runs <output-root> --json to inspect recent runs with scenario summary

Scenario guardrails:

• tracking_health_audit is audit-only. generate-gtm, sync, and publish are blocked by default unless explicitly forced.
• Scenario report commands are intent-gated (for example, upkeep report commands require upkeep).
• scenario-check is a readiness check for the current scenario contract; use status when you need checkpoint, warning, and gate details.

Use It As A Skill

In an agent conversation, the first turn should be an intent-first intake, not a CLI choice. Do not ask the user whether they want scenario or analyze; ask which of these plain-language entry paths they need:

• new setup from scratch
• update existing tracking
• upkeep or routine review
• health audit only
• analyze only
• resume an existing artifact directory

Internal mapping:

• full workflow intents map to scenario templates such as run-new-setup, run-tracking-update, run-upkeep, and run-health-audit
• analyze only maps to tracking-discover / analyze and stops after discovery
• an existing artifact directory maps to status and resume-from-current-checkpoint behavior

If you are using this in an agent environment, call it in natural language and provide the current workflow inputs:

Use event-tracking-skill to set up GA4 / GTM tracking for https://www.example.com.
Use ./output as the output root directory.
GA4 Measurement ID is G-XXXXXXXXXX.
Google tag ID is GT-XXXXXXX if needed.

The skill creates the run artifact directory as <output-root>/<url-slug> and then walks through grouping, conditional live GTM baseline review, schema review, GTM generation, sync, preview, and publish.

Use It As A CLI

Start with site analysis:

./event-tracking analyze https://www.example.com --output-root ./output

The CLI creates the artifact directory automatically as <output-root>/<url-slug>, for example ./output/example_com.

After filling and reviewing pageGroups in ./output/example_com/site-analysis.json, continue with the same artifact directory:

./event-tracking conf