td-ai-tools 1.2.1 → 1.2.3

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.
+
 `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,7 @@ 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 } from './project-hooks.js';
 
 /** @typedef {import('./catalog.js').Ctx} Ctx */
 /** @typedef {import('./catalog.js').Target} Target */
@@ -66,7 +67,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 +77,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 +160,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;
 }

package/lib/project-hooks.js

@@ -0,0 +1,171 @@
+/**
+ * @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';
+
+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 }] });
+}
+
+/**
+ * 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;
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "td-ai-tools",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "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,6 +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…
 - `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

@@ -0,0 +1,53 @@
+---
+name: shopify-lint
+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.
+---
+
+# Shopify Lint
+
+## Setup
+
+The bundled `theme-check-theory` custom-check package ships as TypeScript source only; its `node_modules` and compiled `dist/` are not committed. Run setup once before the first run (and after upgrading the skill):
+
+```bash
+bash .agents/skills/shopify-lint/scripts/setup.sh
+```
+
+Installing with `td-ai-tools install --setup shopify-lint` runs this automatically. The script:
+
+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.
+
+## Usage
+
+Run the bundled Python script from the Shopify theme root:
+
+```bash
+python3 .agents/skills/shopify-lint/scripts/shopify_lint.py --path .
+```
+
+The script runs `shopify theme check --output json`, identifies files changed since the current branch's merge-base, adds staged, unstaged, and untracked files, and emits only reports whose paths are in that set. The root `.theme-check.yml` directly requires the bundled `theme-check-theory` package from this skill directory.
+
+## Workflow
+
+1. Confirm `shopify` and `python3` are available.
+2. Run the bundled script instead of calling `shopify theme check` directly.
+3. Treat exit code `0` as no failing offenses in modified files, `1` as filtered offenses at or above the fail level, and `2` as a Git, CLI, or JSON-processing error.
+4. Fix reported issues and rerun until the command passes. Do not fix offenses in untouched files unless the user expands the scope.
+5. Keep custom-check dependencies inside `theme-check-theory/node_modules`. Do not install Node dependencies at the theme root.
+
+The default base is `origin/HEAD`, then `origin/main`, `main`, `origin/master`, or `master`. Override it when needed:
+
+```bash
+python3 .agents/skills/shopify-lint/scripts/shopify_lint.py --path . --base-ref origin/develop
+```
+
+Set `SHOPIFY_LINT_BASE_REF` for the same override in automation. Use `--format json` for machine-readable filtered output and `--fail-level warning` or `--fail-level info` for stricter runs. When passing `--config <path>`, preserve the bundled package's `require` entry or the Theory checks will not load.
+
+Do not use Theme Check auto-correction through this workflow because it can modify untouched files before filtering.

package/skills/shopify-lint/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Shopify Lint"
+  short_description: "Lint modified theme files with Theory checks"
+  default_prompt: "Use $shopify-lint to run Theme Check for files modified on my current branch."

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

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shopify-lint setup
+#
+# Run automatically by the installer (`--setup`) from the installed skill
+# directory, or manually with `bash scripts/setup.sh`. It:
+#   1. Builds the bundled `theme-check-theory` custom-check package
+#      (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"
+
+# 1. Build the bundled custom-check package.
+echo "shopify-lint setup: building theme-check-theory in $PKG_DIR"
+cd "$PKG_DIR"
+npm install
+npm run build
+
+# 2. Generate the project-root .theme-check.yml.
+#
+# The installed layout is <project>/<.agents|.claude>/skills/shopify-lint, so
+# the project root is three levels above the skill directory. Guard against
+# running outside that layout (e.g. from the catalog repo) to avoid writing the
+# config into an unexpected directory.
+TARGET_DIR="$(cd "$SKILL_DIR/../.." && pwd)"
+TARGET_BASE="$(basename "$TARGET_DIR")"
+if [[ "$TARGET_BASE" != ".agents" && "$TARGET_BASE" != ".claude" ]]; then
+  echo "shopify-lint setup: unrecognized install layout ($TARGET_DIR); skipping .theme-check.yml generation." >&2
+  exit 0
+fi
+
+PROJECT_ROOT="$(dirname "$TARGET_DIR")"
+THEME_CHECK_FILE="$PROJECT_ROOT/.theme-check.yml"
+
+if [[ -f "$THEME_CHECK_FILE" ]]; then
+  echo "shopify-lint setup: $THEME_CHECK_FILE already exists; leaving it unchanged."
+  echo "  Ensure its 'require:' list includes ./.agents/skills/shopify-lint/theme-check-theory"
+  exit 0
+fi
+
+cat > "$THEME_CHECK_FILE" <<'YAML'
+extends:
+  - theme-check:recommended
+
+require:
+  - ./.agents/skills/shopify-lint/theme-check-theory
+
+UnusedSectionSettings:
+  enabled: true
+  severity: warning
+
+UnguardedTextSetting:
+  enabled: true
+  severity: warning
+YAML
+
+echo "shopify-lint setup: wrote $THEME_CHECK_FILE"