td-ai-tools 1.2.2 → 1.2.4

package/README.md

@@ -57,6 +57,8 @@ This keeps the installed assets available to both Claude-style and `.agents`-sty
 
 Some skills provide a recognized setup command (`setup.sh`, `scripts/setup.sh`, or `package.json` with `scripts.setup`). Non-interactive installs and updates run setup only when you pass `--setup`; interactive installs/updates ask for confirmation only when the selected skills include a recognized setup command. Accepted setup runs once inside each installed copy: `.claude/skills/<name>/` and `.agents/skills/<name>/`.
 
+Skills can also declare reusable project-hook setup in `hooks/manifest.json`. The shared installer in `lib/project-hooks.js` copies listed hook assets and merges each registration into its Claude or Codex JSON settings file, preserving unrelated configuration and updating an existing hook with the same `type` and `command` instead of duplicating it. A hook manifest counts as a recognized setup even when the skill has no setup script, so future skills only need to provide their assets and declarative registrations. Deleting the skill removes unchanged manifest-owned registrations and assets; user-modified hooks and invalid settings files are left untouched with a warning.
+
 `install` now errors when the target item already exists. Use `update` to replace an existing installed skill or agent pack.
 
 `delete` removes installed items from both `.claude/` and `.agents/` target directories, and works on any installed skill or agent pack regardless of whether it is in the catalogue.

package/lib/installer.js

@@ -9,6 +9,11 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { copyDir } from './fs-utils.js';
 import { bundledAgentsIn } from './catalog.js';
+import {
+  hasProjectHooks,
+  installProjectHooks,
+  uninstallProjectHooks,
+} from './project-hooks.js';
 
 /** @typedef {import('./catalog.js').Ctx} Ctx */
 /** @typedef {import('./catalog.js').Target} Target */
@@ -66,7 +71,8 @@ export function findSkillSetup(skillDir) {
  * @returns {boolean}
  */
 export function skillHasSetup(ctx, name) {
-  return Boolean(findSkillSetup(path.join(ctx.skillsDir, name)));
+  const skillDir = path.join(ctx.skillsDir, name);
+  return Boolean(findSkillSetup(skillDir)) || hasProjectHooks(skillDir);
 }
 
 /**
@@ -75,28 +81,36 @@ export function skillHasSetup(ctx, name) {
  * @param {string} name - Skill name.
  * @param {Target} target - The destination layout.
  * @param {string} dest - Installed skill directory.
+ * @param {string} projectRoot - Root of the project receiving the skill.
  * @param {ReportFn} report
  * @returns {boolean} Whether setup succeeded or no setup existed.
  */
-function runSkillSetup(name, target, dest, report) {
+function runSkillSetup(name, target, dest, projectRoot, report) {
   const setup = findSkillSetup(dest);
-  if (!setup) return true;
-
-  report('step', `setup: ${name} running ${setup.command} ${setup.args.join(' ')} in ${target.root}/skills/${name}/`);
-  const result = spawnSync(setup.command, setup.args, {
-    cwd: dest,
-    stdio: 'inherit',
-    shell: false,
-  });
-  if (result.error) {
-    report('error', `setup: ${name} failed in ${target.root}/skills/${name}/: ${result.error.message}`);
-    return false;
+  if (setup) {
+    report('step', `setup: ${name} running ${setup.command} ${setup.args.join(' ')} in ${target.root}/skills/${name}/`);
+    const result = spawnSync(setup.command, setup.args, {
+      cwd: dest,
+      stdio: 'inherit',
+      shell: false,
+    });
+    if (result.error) {
+      report('error', `setup: ${name} failed in ${target.root}/skills/${name}/: ${result.error.message}`);
+      return false;
+    }
+    if (result.status !== 0) {
+      report('error', `setup: ${name} failed in ${target.root}/skills/${name}/ with exit code ${result.status}`);
+      return false;
+    }
+    report('success', `setup: ${name} completed in ${target.root}/skills/${name}/`);
   }
-  if (result.status !== 0) {
-    report('error', `setup: ${name} failed in ${target.root}/skills/${name}/ with exit code ${result.status}`);
+
+  try {
+    installProjectHooks(projectRoot, dest, { report });
+  } catch (error) {
+    report('error', `setup: ${name} hook installation failed: ${error.message}`);
     return false;
   }
-  report('success', `setup: ${name} completed in ${target.root}/skills/${name}/`);
   return true;
 }
 
@@ -150,7 +164,7 @@ export function installSkill(ctx, name, { replaceExisting = false, runSetup = fa
     copyDir(src, dest);
     report('success', `skill: ${name} ${replaceExisting ? 'updated' : 'installed'} → ${target.root}/skills/${name}/`);
     registerBundledAgents(ctx, target, src, report);
-    if (runSetup && !runSkillSetup(name, target, dest, report)) ok = false;
+    if (runSetup && !runSkillSetup(name, target, dest, ctx.targetRoot, report)) ok = false;
   }
   return ok;
 }
@@ -169,6 +183,17 @@ export function installSkill(ctx, name, { replaceExisting = false, runSetup = fa
  */
 export function deleteSkill(ctx, name, { report = noop } = {}) {
   let deletedAny = false;
+  const hookSource = ctx.installTargets
+    .map(target => path.join(ctx.targetRoot, target.root, 'skills', name))
+    .find(hasProjectHooks);
+  if (hookSource) {
+    try {
+      uninstallProjectHooks(ctx.targetRoot, hookSource, { report });
+    } catch (error) {
+      report('error', `skill: ${name} hook cleanup failed: ${error.message}`);
+    }
+  }
+
   for (const target of ctx.installTargets) {
     const dest = path.join(ctx.targetRoot, target.root, 'skills', name);
     const bundledAgents = bundledAgentsIn(path.join(dest, 'agents'));

package/lib/project-hooks.js

@@ -0,0 +1,338 @@
+/**
+ * @file Declarative, non-destructive project hook installation for skills.
+ *
+ * Skills opt in by shipping `hooks/manifest.json`. Hook assets are copied from
+ * that directory and registrations are merged into runtime JSON settings.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+
+const MANIFEST_PATH = path.join('hooks', 'manifest.json');
+
+/** @type {(kind: 'success'|'warn'|'info', message: string) => void} */
+const noop = () => {};
+
+/**
+ * Whether a skill directory contains a project hook manifest.
+ *
+ * @param {string} skillDir
+ * @returns {boolean}
+ */
+export function hasProjectHooks(skillDir) {
+  return fs.existsSync(path.join(skillDir, MANIFEST_PATH));
+}
+
+/**
+ * Resolve a manifest path while preventing traversal outside its allowed root.
+ *
+ * @param {string} root
+ * @param {string} relativePath
+ * @param {string} label
+ * @returns {string}
+ */
+function resolveWithin(root, relativePath, label) {
+  if (typeof relativePath !== 'string' || !relativePath || path.isAbsolute(relativePath)) {
+    throw new Error(`${label} must be a non-empty relative path`);
+  }
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(resolvedRoot, relativePath);
+  const relation = path.relative(resolvedRoot, resolved);
+  if (relation === '..' || relation.startsWith(`..${path.sep}`) || path.isAbsolute(relation)) {
+    throw new Error(`${label} resolves outside the project root: ${relativePath}`);
+  }
+  return resolved;
+}
+
+/**
+ * Merge one runtime hook into a settings object.
+ *
+ * Command hooks are identified by `type` + `command`. Reinstalling updates the
+ * managed hook in place while preserving unrelated settings, event groups,
+ * group fields, hook fields, and sibling hooks.
+ *
+ * @param {Record<string, any>} settings
+ * @param {string} event
+ * @param {Record<string, any>} hook
+ * @param {Record<string, any>} [group]
+ * @returns {void}
+ */
+export function mergeHookRegistration(settings, event, hook, group = {}) {
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+    throw new Error('hook settings must be a JSON object');
+  }
+  if (typeof event !== 'string' || !event) {
+    throw new Error('hook event must be a non-empty string');
+  }
+  if (!hook || typeof hook !== 'object' || Array.isArray(hook)
+    || typeof hook.type !== 'string' || typeof hook.command !== 'string') {
+    throw new Error('hook must define string type and command fields');
+  }
+  if (!group || typeof group !== 'object' || Array.isArray(group)) {
+    throw new Error('hook group must be a JSON object');
+  }
+
+  if (settings.hooks === undefined) settings.hooks = {};
+  if (!settings.hooks || typeof settings.hooks !== 'object' || Array.isArray(settings.hooks)) {
+    throw new Error('settings.hooks must be a JSON object');
+  }
+  if (settings.hooks[event] === undefined) settings.hooks[event] = [];
+  if (!Array.isArray(settings.hooks[event])) {
+    throw new Error(`settings.hooks.${event} must be an array`);
+  }
+
+  for (const existingGroup of settings.hooks[event]) {
+    if (!existingGroup || !Array.isArray(existingGroup.hooks)) continue;
+    const existingHook = existingGroup.hooks.find(candidate => (
+      candidate?.type === hook.type && candidate?.command === hook.command
+    ));
+    if (!existingHook) continue;
+    Object.assign(existingGroup, group);
+    Object.assign(existingHook, hook);
+    return;
+  }
+
+  settings.hooks[event].push({ ...group, hooks: [{ ...hook }] });
+}
+
+/**
+ * Remove one unchanged, manifest-owned runtime hook group from settings.
+ *
+ * The complete group must still equal the manifest declaration. This avoids
+ * deleting a hook or group that a user customized after setup.
+ *
+ * @param {Record<string, any>} settings
+ * @param {string} event
+ * @param {Record<string, any>} hook
+ * @param {Record<string, any>} [group]
+ * @returns {boolean} Whether an exact registration was removed.
+ */
+export function removeHookRegistration(settings, event, hook, group = {}) {
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+    throw new Error('hook settings must be a JSON object');
+  }
+  if (typeof event !== 'string' || !event) {
+    throw new Error('hook event must be a non-empty string');
+  }
+  if (!hook || typeof hook !== 'object' || Array.isArray(hook)
+    || typeof hook.type !== 'string' || typeof hook.command !== 'string') {
+    throw new Error('hook must define string type and command fields');
+  }
+  if (!group || typeof group !== 'object' || Array.isArray(group)) {
+    throw new Error('hook group must be a JSON object');
+  }
+  if (settings.hooks === undefined) return false;
+  if (!settings.hooks || typeof settings.hooks !== 'object' || Array.isArray(settings.hooks)) {
+    throw new Error('settings.hooks must be a JSON object');
+  }
+  if (settings.hooks[event] === undefined) return false;
+  if (!Array.isArray(settings.hooks[event])) {
+    throw new Error(`settings.hooks.${event} must be an array`);
+  }
+
+  const expectedGroup = { ...group, hooks: [{ ...hook }] };
+  const index = settings.hooks[event].findIndex(candidate => (
+    isDeepStrictEqual(candidate, expectedGroup)
+  ));
+  if (index === -1) return false;
+  settings.hooks[event].splice(index, 1);
+  return true;
+}
+
+/**
+ * Whether settings still contain a hook with the manifest hook's identity.
+ *
+ * @param {Record<string, any>} settings
+ * @param {string} event
+ * @param {Record<string, any>} hook
+ * @returns {boolean}
+ */
+function hasHookIdentity(settings, event, hook) {
+  const groups = settings.hooks?.[event];
+  if (!Array.isArray(groups)) return false;
+  return groups.some(existingGroup => (
+    Array.isArray(existingGroup?.hooks)
+    && existingGroup.hooks.some(candidate => (
+      candidate?.type === hook.type && candidate?.command === hook.command
+    ))
+  ));
+}
+
+/**
+ * Read JSON settings, backing up malformed input before starting a clean file.
+ *
+ * @param {string} settingsPath
+ * @param {(kind: 'success'|'warn'|'info', message: string) => void} report
+ * @returns {Record<string, any>}
+ */
+function readSettings(settingsPath, report) {
+  if (!fs.existsSync(settingsPath)) return {};
+  try {
+    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+      throw new Error('root value is not an object');
+    }
+    return settings;
+  } catch (error) {
+    const backupPath = `${settingsPath}.bak`;
+    fs.copyFileSync(settingsPath, backupPath);
+    report('warn', `hooks: ${settingsPath} was invalid JSON; backed up to ${backupPath}`);
+    return {};
+  }
+}
+
+/**
+ * Install the hook assets and registrations declared by a skill.
+ *
+ * Manifest shape:
+ * `{ files: [{ source, destination }], registrations: [{ settings, event,
+ * hook, group? }] }`. File sources are relative to `hooks/`; destinations and
+ * settings paths are relative to the installing project.
+ *
+ * @param {string} projectRoot
+ * @param {string} skillDir
+ * @param {object} [options]
+ * @param {(kind: 'success'|'warn'|'info', message: string) => void} [options.report]
+ * @returns {boolean} Whether a manifest was found and installed.
+ */
+export function installProjectHooks(projectRoot, skillDir, { report = noop } = {}) {
+  const manifestPath = path.join(skillDir, MANIFEST_PATH);
+  if (!fs.existsSync(manifestPath)) return false;
+
+  const hooksDir = path.dirname(manifestPath);
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    throw new Error(`hook manifest must be a JSON object: ${manifestPath}`);
+  }
+
+  for (const file of manifest.files || []) {
+    const source = resolveWithin(hooksDir, file.source, 'hook source');
+    const destination = resolveWithin(projectRoot, file.destination, 'hook destination');
+    if (!fs.existsSync(source) || !fs.statSync(source).isFile()) {
+      throw new Error(`hook source does not exist: ${source}`);
+    }
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.copyFileSync(source, destination);
+    fs.chmodSync(destination, fs.statSync(source).mode);
+    report('success', `hooks: installed ${file.destination}`);
+  }
+
+  for (const registration of manifest.registrations || []) {
+    const settingsPath = resolveWithin(projectRoot, registration.settings, 'hook settings path');
+    const settings = readSettings(settingsPath, report);
+    mergeHookRegistration(
+      settings,
+      registration.event,
+      registration.hook,
+      registration.group || {},
+    );
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+    report('success', `hooks: merged ${registration.event} into ${registration.settings}`);
+  }
+
+  return true;
+}
+
+/**
+ * Remove unchanged hook assets and registrations declared by a skill.
+ *
+ * User-modified files, registrations, and malformed settings files are left
+ * untouched with a warning. Settings keys and directories are retained even
+ * when their managed entries are removed so unrelated structure is preserved.
+ *
+ * @param {string} projectRoot
+ * @param {string} skillDir
+ * @param {object} [options]
+ * @param {(kind: 'success'|'warn'|'info', message: string) => void} [options.report]
+ * @returns {boolean} Whether a manifest was found and processed.
+ */
+export function uninstallProjectHooks(projectRoot, skillDir, { report = noop } = {}) {
+  const manifestPath = path.join(skillDir, MANIFEST_PATH);
+  if (!fs.existsSync(manifestPath)) return false;
+
+  const hooksDir = path.dirname(manifestPath);
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    throw new Error(`hook manifest must be a JSON object: ${manifestPath}`);
+  }
+
+  const files = (manifest.files || []).map(file => {
+    const source = resolveWithin(hooksDir, file.source, 'hook source');
+    const destination = resolveWithin(projectRoot, file.destination, 'hook destination');
+    if (!fs.existsSync(source) || !fs.statSync(source).isFile()) {
+      throw new Error(`hook source does not exist: ${source}`);
+    }
+    const exists = fs.existsSync(destination);
+    const unchanged = exists
+      && fs.statSync(destination).isFile()
+      && fs.readFileSync(destination).equals(fs.readFileSync(source));
+    return { file, destination, exists, unchanged };
+  });
+  const preserveRegistrations = files.some(file => file.exists && !file.unchanged);
+  let preserveHookFiles = preserveRegistrations;
+
+  for (const registration of manifest.registrations || []) {
+    const settingsPath = resolveWithin(projectRoot, registration.settings, 'hook settings path');
+    if (!fs.existsSync(settingsPath)) continue;
+
+    let settings;
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+        throw new Error('root value is not an object');
+      }
+    } catch {
+      report('warn', `hooks: ${registration.settings} is invalid JSON; leaving it unchanged`);
+      preserveHookFiles = true;
+      continue;
+    }
+
+    if (preserveRegistrations
+      && hasHookIdentity(settings, registration.event, registration.hook)) {
+      report('warn',
+        `hooks: leaving ${registration.event} registration in ${registration.settings} because a hook file was modified`);
+      preserveHookFiles = true;
+      continue;
+    }
+
+    let removed = false;
+    try {
+      removed = removeHookRegistration(
+        settings,
+        registration.event,
+        registration.hook,
+        registration.group || {},
+      );
+    } catch (error) {
+      report('warn', `hooks: could not safely inspect ${registration.settings}: ${error.message}`);
+      preserveHookFiles = true;
+      continue;
+    }
+
+    if (removed) {
+      fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+      report('success', `hooks: removed ${registration.event} from ${registration.settings}`);
+    } else if (hasHookIdentity(settings, registration.event, registration.hook)) {
+      report('warn',
+        `hooks: leaving modified ${registration.event} registration in ${registration.settings}`);
+      preserveHookFiles = true;
+    }
+  }
+
+  for (const { file, destination, exists, unchanged } of files) {
+    if (!exists) continue;
+    if (!unchanged) {
+      report('warn', `hooks: leaving modified hook file ${file.destination}`);
+      continue;
+    }
+    if (preserveHookFiles) {
+      report('warn', `hooks: leaving hook file ${file.destination} because a registration was preserved`);
+      continue;
+    }
+    fs.rmSync(destination);
+    report('success', `hooks: removed ${file.destination}`);
+  }
+
+  return true;
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "td-ai-tools",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Install agent skills and packs into your project",
   "type": "module",
   "scripts": {
-    "test": "node --test",
+    "test": "node --test test/*.test.js",
     "readmes": "node scripts/sync-readmes.js",
     "readmes:check": "node scripts/sync-readmes.js --check",
     "smoke:install": "./scripts/smoke-install.sh"

package/skills/README.md

@@ -6,10 +6,8 @@
 - `basecamp`: Interact with Basecamp via the Basecamp CLI.
 - `browser-validation`: Before completing a task validate frontend or template changes in a real browser with the Playwright-CLI…
 - `cache-reset`: Clear and warm Laravel and Statamic caches (including Statamic Glide image caches) after content or template…
-- `car-ticket-generator`: Generate a ticket for the codex-auto-runner queue
 - `client-overview`: Generate a client-facing markdown report that summarizes all changes on the current branch against the…
 - `debugging-ios-webkit`: Debugs iOS Safari/Chrome-iOS rendering bugs — stale paints, viewport/browser-chrome clipping, mobile-only CSS…
-- `everhour-basecamp-estimates`: Bulk update Everhour task estimates from a Basecamp todo or todolist URL, then append bracketed hours to the…
 - `forge-cli`: Manage Laravel Forge servers, sites, and provisioned resources from the terminal with the Laravel Forge CLI,…
 - `horizon-component-migration`: Bundle Shopify Horizon components into a migration package for a different theme, including recursive…
 - `playwright-cli`: Automates browser interactions for web testing, screenshots, and data extraction.
@@ -18,7 +16,7 @@
 - `pull-request-statamic`: Generates GitHub pull request descriptions for Statamic and Laravel development by analyzing git diffs and…
 - `record-changes`: Update `docs/changes.md` by summarizing the current branch against the primary development branch.
 - `shopify-cli`: Shopify CLI workflows for theme development.
-- `shopify-lint`: Run Shopify CLI Theme Check with Theory Digital's bundled custom checks while reporting and failing only on offenses in files modified on the current Git branch.
+- `shopify-lint`: Run Shopify CLI Theme Check with Theory Digital's bundled custom checks while reporting and failing only on…
 - `stylesheet-migration`: Migrate Shopify Liquid `{% stylesheet %}` blocks into theme CSS assets using bundled Python scripts.
 - `td-js-vanilla-rules`: Theory Digital vanilla JavaScript standards for Shopify theme work.
 - `td-review`: Run parallel code review agents on a PR (including TD theme compliance) and produce a synthesized findings…

package/skills/shopify-lint/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: shopify-lint
-version: 1.0.0
+version: 1.1.0
 description: Run Shopify CLI Theme Check with Theory Digital's bundled custom checks while reporting and failing only on offenses in files modified on the current Git branch. Use when Codex needs to lint a Shopify theme, validate branch-scoped Liquid or theme changes, enforce Theory theme rules, or avoid surfacing pre-existing Theme Check offenses from untouched files.
 ---
 
@@ -18,6 +18,9 @@ Installing with `td-ai-tools install --setup shopify-lint` runs this automatical
 
 1. Runs `npm install && npm run build` inside `theme-check-theory/`, producing `dist/index.js` — the CommonJS entry point the root `.theme-check.yml` requires.
 2. Writes a `.theme-check.yml` at the project root wiring in the bundled checks. If one already exists it is left untouched; ensure its `require:` list includes `./.agents/skills/shopify-lint/theme-check-theory`.
+3. Through the installer's shared project-hook setup, installs matching Claude and Codex Stop hooks and merges their registrations into `.claude/settings.json` and `.codex/hooks.json` without replacing unrelated settings or hooks. Re-running setup updates the Shopify Lint hook in place instead of duplicating it.
+
+The Stop hooks run this skill's branch-scoped lint before handoff, return modified-file offenses to the agent, and allow handoff after three unsuccessful fix rounds. They require `jq`, `python3`, and Shopify CLI to be available when the hook runs. Directly running `scripts/setup.sh` performs the package build and Theme Check configuration; use `td-ai-tools install --setup` or `td-ai-tools update --setup` to apply the shared hook manifest as well.
 
 Keep these dependencies inside `theme-check-theory/node_modules`; do not install Node dependencies at the theme root.
 

package/skills/shopify-lint/hooks/claude-stop.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Stop hook: run Theory's branch-scoped Shopify Theme Check before the agent
+# hands off. Blocks the stop (feeding offenses back to the agent) when lint
+# finds offenses in files modified on the current branch.
+set -u
+
+input=$(cat)
+session_id=$(printf '%s' "$input" | jq -r '.session_id // "unknown"')
+
+root="${CLAUDE_PROJECT_DIR:-$PWD}"
+cd "$root" || exit 0
+
+# Only lint when this checkout is a Shopify theme with the skill installed.
+lint_script=".agents/skills/shopify-lint/scripts/shopify_lint.py"
+[ -f "$lint_script" ] || exit 0
+
+# Cap consecutive blocks so an offense the agent can't fix doesn't loop forever.
+counter_file="${TMPDIR:-/tmp}/claude-shopify-lint-stop-${session_id}.count"
+
+output=$(python3 "$lint_script" --path . 2>&1)
+status=$?
+
+if [ "$status" -eq 0 ]; then
+  rm -f "$counter_file"
+  exit 0
+fi
+
+if [ "$status" -eq 1 ]; then
+  count=0
+  [ -f "$counter_file" ] && count=$(cat "$counter_file" 2>/dev/null || echo 0)
+  count=$((count + 1))
+  printf '%s' "$count" > "$counter_file"
+
+  if [ "$count" -gt 3 ]; then
+    rm -f "$counter_file"
+    jq -n --arg msg "Shopify lint still failing after 3 fix rounds — allowing handoff. Remaining offenses:\n$output" \
+      '{systemMessage: $msg}'
+    exit 0
+  fi
+
+  jq -n --arg reason "Shopify Theme Check found offenses in files modified on this branch. Fix these before finishing (leave offenses in unmodified files alone — they are pre-existing), then stop again and the check will re-run:
+
+$output" '{decision: "block", reason: $reason}'
+  exit 0
+fi
+
+# Exit 2 = Git/CLI/JSON tooling error. Don't block handoff on a broken toolchain.
+jq -n --arg msg "Shopify lint hook could not run (exit $status): $output" '{systemMessage: $msg}'
+exit 0

package/skills/shopify-lint/hooks/codex-stop.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Stop hook: run Theory's branch-scoped Shopify Theme Check before the agent
+# hands off. Continues the turn with offenses from files modified on the
+# current branch so Codex can fix them before trying to stop again.
+set -u
+
+input=$(cat)
+session_id=$(printf '%s' "$input" | jq -r '.session_id // "unknown"' | tr -cd '[:alnum:]_-')
+
+root=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+cd "$root" || exit 0
+
+# Only lint when this checkout is a Shopify theme with the skill installed.
+lint_script=".agents/skills/shopify-lint/scripts/shopify_lint.py"
+[ -f "$lint_script" ] || exit 0
+
+# Cap consecutive continuations so an offense the agent can't fix doesn't loop forever.
+counter_file="${TMPDIR:-/tmp}/codex-shopify-lint-stop-${session_id:-unknown}.count"
+
+output=$(python3 "$lint_script" --path . 2>&1)
+status=$?
+
+if [ "$status" -eq 0 ]; then
+  rm -f "$counter_file"
+  exit 0
+fi
+
+if [ "$status" -eq 1 ]; then
+  count=0
+  [ -f "$counter_file" ] && count=$(cat "$counter_file" 2>/dev/null || echo 0)
+  count=$((count + 1))
+  printf '%s' "$count" > "$counter_file"
+
+  if [ "$count" -gt 3 ]; then
+    rm -f "$counter_file"
+    jq -n --arg msg "Shopify lint still failing after 3 fix rounds — allowing handoff. Remaining offenses:\n$output" \
+      '{systemMessage: $msg}'
+    exit 0
+  fi
+
+  jq -n --arg reason "Shopify Theme Check found offenses in files modified on this branch. Fix these before finishing (leave offenses in unmodified files alone — they are pre-existing), then stop again and the check will re-run:
+
+$output" '{continue: false, stopReason: $reason}'
+  exit 0
+fi
+
+# Exit 2 = Git/CLI/JSON tooling error. Don't continue the turn on a broken toolchain.
+jq -n --arg msg "Shopify lint hook could not run (exit $status): $output" '{systemMessage: $msg}'
+exit 0

package/skills/shopify-lint/hooks/manifest.json

@@ -0,0 +1,34 @@
+{
+  "files": [
+    {
+      "source": "claude-stop.sh",
+      "destination": ".claude/hooks/shopify-lint-stop.sh"
+    },
+    {
+      "source": "codex-stop.sh",
+      "destination": ".codex/hooks/td-shopify-lint-stop.sh"
+    }
+  ],
+  "registrations": [
+    {
+      "settings": ".claude/settings.json",
+      "event": "Stop",
+      "hook": {
+        "type": "command",
+        "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/shopify-lint-stop.sh\"",
+        "timeout": 300,
+        "statusMessage": "Running Shopify Theme Check on branch changes..."
+      }
+    },
+    {
+      "settings": ".codex/hooks.json",
+      "event": "Stop",
+      "hook": {
+        "type": "command",
+        "command": "bash \"$(git rev-parse --show-toplevel)/.codex/hooks/td-shopify-lint-stop.sh\"",
+        "timeout": 300,
+        "statusMessage": "Running Shopify Theme Check on branch changes..."
+      }
+    }
+  ]
+}

package/skills/shopify-lint/scripts/setup.sh

@@ -9,6 +9,8 @@ set -euo pipefail
 #      (its node_modules and dist/ are intentionally not committed).
 #   2. Writes a `.theme-check.yml` at the project root that wires the bundled
 #      checks into Shopify CLI Theme Check.
+#   3. When run by td-ai-tools, its shared setup stage installs the hook assets
+#      declared in hooks/manifest.json and merges their Stop registrations.
 
 SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 PKG_DIR="$SKILL_DIR/theme-check-theory"