td-ai-tools 1.0.2

package/README.md

@@ -0,0 +1,49 @@
+# AgentToolkit
+
+## Project Overview
+This repository is a lightweight foundation for organizing reusable agent packs, skills, workflows, and evaluation assets.
+
+<!-- TODO: Add project mission, scope, and ownership details. -->
+
+## Repository Layout
+- `AGENTS.md`: Repository-specific operating instructions.
+- `agents/`: Reusable agent packs (`AGENTS.md` + helper assets per pack).
+- `skills/`: Reusable skills (`SKILL.md`, optional scripts/references, model metadata).
+- `workflows/`: Reusable multi-step orchestration workflows.
+- `evals/`: Evaluation cases, datasets, and runners.
+
+## Basic Usage
+1. Add agent packs in `agents/` and index them in `agents/README.md`.
+2. Add capability specifications in `skills/` and index them in `skills/README.md`.
+3. Define orchestrations in `workflows/` and index them in `workflows/README.md`.
+4. Maintain evaluation assets in `evals/`.
+
+## CLI Usage
+Run the packaged installer from inside a target project:
+
+```bash
+npx td-ai-tools
+```
+
+Useful commands:
+
+```bash
+npx td-ai-tools list
+npx td-ai-tools install
+npx td-ai-tools install --all
+npx td-ai-tools install pr-solver
+npx td-ai-tools install pr-solver horizon-component-library
+```
+
+The installer copies requested items into both agent layouts:
+
+- Skills: `.claude/skills/<name>/` and `.agents/skills/<name>/`
+
+This keeps the installed assets available to both Claude-style and `.agents`-style project conventions.
+
+## Local Verification
+Run the local smoke test to package the repo and verify installation into a throwaway project:
+
+```bash
+npm run smoke:install
+```

package/agents/README.md

@@ -0,0 +1,10 @@
+# agents
+
+## Available Agent Packs
+- `horizon-component-library/`: Theory Digital Horizon component-library agent rules, with guard script.
+
+## Pack Structure Convention
+- `<pack-name>/AGENTS.md`
+- `<pack-name>/README.md`
+- `<pack-name>/scripts/*` (optional)
+- `<pack-name>/assets/*` (optional)

package/agents/horizon-component-library/AGENTS.md

@@ -0,0 +1,184 @@
+# .codex/AGENTS.md — Theory Digital
+
+## Scope
+Default rules for Theory Digital component-library sections built with theme blocks.
+
+## Core Principles
+- Prefer isolated TD implementations over vendor patching.
+- Keep responsibilities separated:
+  - Liquid derives and normalizes state.
+  - Markup renders only the active structure.
+  - CSS handles layout and presentation.
+  - JavaScript handles behavior only.
+- Build the simplest implementation that satisfies the requirement.
+- Keep DOM, CSS, and JS minimal and maintainable.
+- Every change must be logged in `docs/changes.md`.
+
+## File Conventions
+- Custom code must live in `td-` or `_td-` prefixed files only.
+- Vendor files are READ-ONLY unless wrapped in TD CHANGE delimiters and documented in `docs/hotspots.md`.
+- Custom sections: `sections/td-*.liquid`
+- Custom blocks: `blocks/td-*.liquid`
+- Private blocks: `blocks/_td-*.liquid`
+- Custom snippets: `snippets/td-*.liquid`
+- Put generic, reusable styles in `assets/td-base.css`.
+- Every file that directly renders or calls the Swiper custom element must also include the Swiper assets.
+- Use vendor code only when it already solves the requirement as-is.
+- Otherwise, build an isolated TD implementation instead of patching vendor internals.
+
+## Forbidden
+- Never modify vendor section schemas.
+- Never use `{% include %}`. Use `{% render %}` only.
+- Never add inline scripts to `layout/` files.
+- Never import unapproved third-party JavaScript.
+- Never add non-`td`-prefixed custom CSS variables.
+- Never add non-`data-td-*` custom data attributes.
+- Never declare unnecessary Liquid variables for single-use values.
+- Never overload one setting to drive incompatible behaviors.
+- Never emit parallel desktop/mobile or alternate-mode structures unless needed.
+- Never rely on CSS alone to hide unused structural markup when Liquid can resolve it.
+- Never let invalid or legacy state leak into classes, attributes, or CSS variables.
+- Do not add redundant fallback guards or defensive reassignment for schema-backed primitive settings.
+- Avoid unnecessary conditionals, wrappers, and listeners.
+
+## Required Patterns
+
+### JavaScript
+- Author JavaScript via `{% javascript %}` and Web Components.
+- When creating or modifying JavaScript, load and follow the `$td-js-vanilla-rules` skill.
+- If `$td-js-vanilla-rules` is unavailable, enforce the JavaScript baseline rules in this file.
+- Always guard custom element registration:
+  - `if (!customElements.get(...))`
+- Always clean up in `disconnectedCallback`:
+  - event listeners
+  - timers
+  - observers
+  - external subscriptions
+- Keep JavaScript minimal, event-driven, and component-scoped.
+
+### CSS
+- Author CSS via `{% stylesheet %}` and CSS variables.
+- All custom properties must use the `--td-*` prefix.
+- Use BEM naming for all classes.
+- Use BEM modifier classes for discrete state:
+  - mode
+  - layout
+  - alignment
+  - position
+  - variant
+- Use CSS variables for dynamic values:
+  - sizes
+  - spacing
+  - offsets
+  - dimensions
+- Use inline CSS variables only when truly dynamic.
+- Keep CSS ordered as:
+  - shared/base rules
+  - mobile-only rules
+  - desktop-only rules
+
+### Liquid
+- Derive and normalize state at the top of the file before rendering.
+- Trust schema-backed primitive settings to provide valid values.
+- Normalize only values that are:
+  - derived
+  - cross-dependent
+  - legacy-sensitive
+  - conditionally invalid
+  - externally sourced
+- For straightforward values, prefer inline Liquid over one-time-use variables.
+- Only introduce variables when they improve reuse, clarity, or state normalization.
+- Use clear breakpoint-specific names when behavior differs by breakpoint.
+- Use `block.settings.<id>` directly when used once.
+- Use `default` only when truly needed.
+- Support deterministic fallbacks:
+  - explicit setting
+  - product/metafield
+  - placeholder
+- Do not output unresolved or invalid state into markup, classes, attributes, or CSS variables.
+
+### Markup
+- Render only the active structure.
+- Keep DOM output minimal.
+- Render only the wrappers required for the active mode.
+- In component-library sections built with theme blocks, parent/child composition must use `{% content_for 'blocks' %}` for nested private blocks.
+- Accessibility baseline:
+  - use real buttons/links for interaction
+  - keep `aria-expanded` and `aria-controls` synchronized in JS
+  - support Escape to close interactive UI
+  - respect `prefers-reduced-motion`
+
+## Section Architecture Rules
+- Resolve layout decisions in Liquid whenever possible.
+- If desktop and mobile behavior differ, use separate schema settings.
+- Use `visible_if` to improve settings organization only when the setting type supports it and the dependency is valid under Shopify schema rules.
+- Do not rely on `visible_if` for behavior enforcement, required logic, or unsupported setting relationships.
+- Normalize invalid settings defensively in Liquid.
+- Use BEM modifier classes for discrete state and CSS variables for dynamic values.
+
+## Schema Rules
+- All hardcoded values must be settings or metafields unless they are true implementation constants.
+- Schema labels, options, and headers should use translation keys (`t:*`) whenever possible.
+- Reuse existing `td` translation keys first.
+- New translation keys must be created under the `td` namespace when needed.
+- Keep new keys simple and reusable.
+- Add `info` text only when the setting is not self-explanatory.
+- Use `visible_if` only where supported and only for editor organization, not as a substitute for Liquid validation.
+- Model schema around actual user-facing behavior.
+
+## Global Schema Requirements
+- All sections must include padding settings.
+- All sections must include color scheme picker settings.
+- All sections must include custom ID settings.
+- All blocks must inherit the color scheme by default.
+- All blocks must provide a custom scheme override option.
+
+## Rendering Rules
+- Image URL width must be 2x the displayed maximum width.
+- Example:
+  - displayed max width `80px`
+  - `image_url: width: 160`
+- Render only the assets and markup required for the active implementation.
+
+## Performance Rules
+- Keep JavaScript minimal and event-driven.
+- Avoid unnecessary listeners, observers, timers, and DOM work.
+- Prefer solving state once in Liquid instead of repeatedly in CSS or JS.
+
+## Editor Rules
+- Add Shopify editor hooks when needed:
+  - `shopify:block:select`
+  - `shopify:block:deselect`
+- Interactive UI must work in both storefront and theme editor contexts.
+
+## Hard Output Gate
+- For any edits in `sections/td-*.liquid`, `blocks/td-*.liquid`, `blocks/_td-*.liquid`, or `snippets/td-*.liquid`, run `.claude/agents/horizon-component-library/scripts/td-guard.sh` before final output.
+- If `td-guard` fails, fix the code and rerun the guard before responding.
+
+## Guard Retry Budget
+- Auto-fix attempts after a failing required guard are capped at 2 retries per task.
+- If the guard still fails after 2 retries, stop and ask the user for direction.
+- Do not continue retrying without new user input.
+
+## Escalation Message Format
+- When retry budget is exhausted, report:
+  - failing check name
+  - exact failing files and lines
+  - fixes attempted
+  - one recommended next action
+
+## Pre-Output Checklist
+- Custom code is isolated in TD-prefixed files.
+- Vendor internals were not patched unless allowed and documented.
+- State is derived and normalized at the top of the file.
+- Schema-backed primitive settings are not wrapped in redundant fallback guards.
+- `.claude/agents/horizon-component-library/scripts/td-guard.sh` passes when TD Liquid files were changed.
+- Desktop/mobile differences use explicit settings where needed.
+- Invalid or legacy states are normalized defensively.
+- Markup renders only the active structure.
+- CSS uses BEM modifier classes for discrete state and variables for dynamic values.
+- Inline CSS variables are used only when necessary.
+- Accessibility requirements are satisfied.
+- Required assets are rendered where needed.
+- Schema follows translation and visibility rules.
+- All changes are logged in `docs/changes.md`.

package/agents/horizon-component-library/README.md

@@ -0,0 +1,10 @@
+# Horizon Component Library Agent
+
+This folder contains the reusable agent policy and helper script imported from `../HorizonComponentLibrary`.
+
+## Files
+- `AGENTS.md`: Theory Digital agent rules for Horizon component-library section work.
+- `scripts/td-guard.sh`: Guard script referenced by the agent rules.
+
+## Related Skill
+- `skills/td-js-vanilla-rules/`: JavaScript standards skill referenced by this agent (`$td-js-vanilla-rules`).

package/agents/horizon-component-library/scripts/td-guard.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR"
+
+if ! command -v rg >/dev/null 2>&1; then
+  echo "ERROR: ripgrep (rg) is required for td-guard checks."
+  exit 1
+fi
+
+changed_files=()
+while IFS= read -r file; do
+  changed_files+=("$file")
+done < <(
+  {
+    git diff --name-only --diff-filter=ACMRTUXB HEAD
+    git ls-files --others --exclude-standard
+  } | awk 'NF' | awk '!seen[$0]++'
+)
+
+td_targets=()
+for file in "${changed_files[@]}"; do
+  case "$file" in
+    sections/td-*.liquid|blocks/td-*.liquid|blocks/_td-*.liquid|snippets/td-*.liquid)
+      if [[ -f "$file" ]]; then
+        td_targets+=("$file")
+      fi
+      ;;
+  esac
+done
+
+if [[ "${#td_targets[@]}" -eq 0 ]]; then
+  echo "td-guard: no changed TD liquid files to validate."
+  exit 0
+fi
+
+schema_default_pattern='(section|block)\.settings\.[A-Za-z0-9_]+\s*\|\s*default\s*:'
+
+schema_default_hits="$(rg -n --pcre2 "$schema_default_pattern" "${td_targets[@]}" || true)"
+if [[ -n "$schema_default_hits" ]]; then
+  echo "td-guard: FAIL - redundant schema fallback detected in changed TD files."
+  echo "Rule: do not use '| default:' with schema-backed section/block settings."
+  echo ""
+  echo "$schema_default_hits"
+  exit 1
+fi
+
+echo "td-guard: PASS"

package/bin/cli.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const TOOLKIT_ROOT = path.resolve(__dirname, '..');
+const SKILLS_DIR = path.join(TOOLKIT_ROOT, 'skills');
+const AGENTS_DIR = path.join(TOOLKIT_ROOT, 'agents');
+const TARGET_ROOT = process.cwd();
+const INSTALL_TARGETS = [
+  { label: 'claude', root: '.claude' },
+  { label: 'agents', root: '.agents' }
+];
+
+function copyDir(src, dest) {
+  const srcStat = fs.statSync(src);
+  fs.mkdirSync(dest, { recursive: true, mode: srcStat.mode });
+  for (const entry of fs.readdirSync(src)) {
+    const srcPath = path.join(src, entry);
+    const destPath = path.join(dest, entry);
+    const entryStat = fs.statSync(srcPath);
+    if (entryStat.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      fs.chmodSync(destPath, entryStat.mode);
+    }
+  }
+}
+
+function getAvailable(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter(d =>
+    fs.statSync(path.join(dir, d)).isDirectory()
+  );
+}
+
+function readFrontmatterField(mdPath, field) {
+  if (!fs.existsSync(mdPath)) return '';
+  const content = fs.readFileSync(mdPath, 'utf8');
+  const match = content.match(new RegExp(`^${field}:\\s*(.+)$`, 'm'));
+  return match ? match[1].trim() : '';
+}
+
+function installSkill(name) {
+  const src = path.join(SKILLS_DIR, name);
+  if (!fs.existsSync(src)) {
+    console.error(`  [error] Skill "${name}" not found.`);
+    return false;
+  }
+  for (const target of INSTALL_TARGETS) {
+    const dest = path.join(TARGET_ROOT, target.root, 'skills', name);
+    copyDir(src, dest);
+    console.log(`  [skill] ${name} -> ${target.root}/skills/${name}/`);
+  }
+  return true;
+}
+
+function installAgent(name) {
+  const src = path.join(AGENTS_DIR, name);
+  if (!fs.existsSync(src)) {
+    console.error(`  [error] Agent pack "${name}" not found.`);
+    return false;
+  }
+  for (const target of INSTALL_TARGETS) {
+    const dest = path.join(TARGET_ROOT, target.root, 'agents', name);
+    copyDir(src, dest);
+    console.log(`  [agent] ${name} -> ${target.root}/agents/${name}/`);
+  }
+  return true;
+}
+
+function printList() {
+  const skills = getAvailable(SKILLS_DIR);
+  const agents = getAvailable(AGENTS_DIR);
+
+  console.log('\nSkills:');
+  for (const name of skills) {
+    const desc = readFrontmatterField(path.join(SKILLS_DIR, name, 'SKILL.md'), 'description');
+    const truncated = desc.length > 72 ? desc.slice(0, 72) + '...' : desc;
+    console.log(`  ${name}`);
+    if (truncated) console.log(`    ${truncated}`);
+  }
+
+  console.log('\nAgent Packs:');
+  for (const name of agents) {
+    console.log(`  ${name}`);
+  }
+  console.log('');
+}
+
+function buildMenu() {
+  const skills = getAvailable(SKILLS_DIR).map(name => ({ type: 'skill', name }));
+  const agents = getAvailable(AGENTS_DIR).map(name => ({ type: 'agent', name }));
+  return [...skills, ...agents];
+}
+
+function installItems(items) {
+  for (const item of items) {
+    if (item.type === 'skill') installSkill(item.name);
+    else installAgent(item.name);
+  }
+}
+
+async function interactiveInstall() {
+  const menu = buildMenu();
+  if (menu.length === 0) {
+    console.log('No skills or agent packs available.');
+    return;
+  }
+
+  console.log('\nAvailable (enter numbers separated by spaces, or "all"):\n');
+  menu.forEach((item, i) => {
+    const label = item.type === 'skill' ? 'skill' : 'agent';
+    console.log(`  [${i + 1}] ${label}: ${item.name}`);
+  });
+  console.log('');
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question('Select items to install: ', answer => {
+      rl.close();
+      const trimmed = answer.trim().toLowerCase();
+      let selected;
+      if (trimmed === 'all') {
+        selected = menu;
+      } else {
+        const indices = trimmed.split(/\s+/).map(n => parseInt(n, 10) - 1);
+        selected = indices.filter(i => i >= 0 && i < menu.length).map(i => menu[i]);
+      }
+      console.log('');
+      installItems(selected);
+      resolve();
+    });
+  });
+}
+
+function resolveNames(names) {
+  const skills = getAvailable(SKILLS_DIR);
+  const agents = getAvailable(AGENTS_DIR);
+  const items = [];
+  for (const name of names) {
+    if (skills.includes(name)) {
+      items.push({ type: 'skill', name });
+    } else if (agents.includes(name)) {
+      items.push({ type: 'agent', name });
+    } else {
+      console.error(`  [error] "${name}" not found as a skill or agent pack.`);
+    }
+  }
+  return items;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+Usage:
+  npx td-ai-tools                     Interactive install
+  npx td-ai-tools list                List available skills and agent packs
+  npx td-ai-tools install             Interactive install
+  npx td-ai-tools install --all       Install everything
+  npx td-ai-tools install <name...>   Install specific skills or agent packs
+
+Skills are installed to:   .claude/skills/<name>/
+                         .agents/skills/<name>/
+Agent packs installed to:  .claude/agents/<name>/
+                         .agents/agents/<name>/
+`);
+    return;
+  }
+
+  const cmd = args[0];
+  console.log('AgentToolkit');
+  console.log('------------');
+
+  if (!cmd || cmd === 'install' && args.length === 1) {
+    await interactiveInstall();
+    return;
+  }
+
+  if (cmd === 'list') {
+    printList();
+    return;
+  }
+
+  if (cmd === 'install') {
+    const rest = args.slice(1);
+    if (rest[0] === '--all') {
+      console.log('');
+      installItems(buildMenu());
+    } else {
+      console.log('');
+      installItems(resolveNames(rest));
+    }
+    return;
+  }
+
+  console.error(`Unknown command: "${cmd}". Run with --help for usage.`);
+  process.exit(1);
+}
+
+main().catch(err => {
+  console.error(err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "td-ai-tools",
+  "version": "1.0.2",
+  "description": "Install agent skills and packs into your project",
+  "scripts": {
+    "smoke:install": "./scripts/smoke-install.sh"
+  },
+  "bin": {
+    "td-ai-tools": "bin/cli.js",
+    "agent-toolkit": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "skills/",
+    "agents/"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": ["claude", "agents", "skills", "shopify", "theory-digital"],
+  "license": "MIT"
+}

package/scripts/smoke-install.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+tmpdir="$(mktemp -d "${TMPDIR:-/tmp}/agent-toolkit-smoke.XXXXXX")"
+cache_dir="$tmpdir/npm-cache"
+project_dir="$tmpdir/project"
+
+cleanup() {
+  rm -rf "$tmpdir"
+}
+
+trap cleanup EXIT
+
+mkdir -p "$project_dir"
+
+pushd "$tmpdir" >/dev/null
+tarball="$(npm pack --quiet --cache "$cache_dir" "$repo_root")"
+popd >/dev/null
+
+tarball_path="$tmpdir/$tarball"
+
+pushd "$project_dir" >/dev/null
+npm exec --yes --cache "$cache_dir" --package "$tarball_path" td-ai-tools install pr-solver horizon-component-library
+popd >/dev/null
+
+required_paths=(
+  "$project_dir/.claude/skills/pr-solver/SKILL.md"
+  "$project_dir/.agents/skills/pr-solver/SKILL.md"
+  "$project_dir/.claude/agents/horizon-component-library/AGENTS.md"
+  "$project_dir/.agents/agents/horizon-component-library/AGENTS.md"
+)
+
+for required_path in "${required_paths[@]}"; do
+  if [[ ! -f "$required_path" ]]; then
+    echo "Missing expected installed file: $required_path" >&2
+    exit 1
+  fi
+done
+
+required_executables=(
+  "$project_dir/.claude/agents/horizon-component-library/scripts/td-guard.sh"
+  "$project_dir/.agents/agents/horizon-component-library/scripts/td-guard.sh"
+)
+
+for required_executable in "${required_executables[@]}"; do
+  if [[ ! -x "$required_executable" ]]; then
+    echo "Expected executable bit on: $required_executable" >&2
+    exit 1
+  fi
+done
+
+echo "Smoke install passed."
+echo "Verified packaged install into:"
+echo "  $project_dir/.claude"
+echo "  $project_dir/.agents"

package/skills/README.md

@@ -0,0 +1,15 @@
+# skills
+
+## Available Skills
+- `cache-reset`: Clear and warm Laravel and Statamic caches after content/template changes.
+- `horizon-component-migration`: Bundle Horizon components and recursive dependencies into a migration package for another theme.
+- `pr-solver`: Resolve unresolved GitHub PR review threads with GraphQL-driven workflow.
+- `pull-request`: Generate structured pull request descriptions for Shopify theme work.
+- `td-js-vanilla-rules`: Theory Digital vanilla JavaScript standards for Shopify themes.
+- `td-review`: Multi-agent PR review that produces a findings report with TD compliance scoring.
+
+## Skill Structure Convention
+- `<skill-name>/SKILL.md`
+- `<skill-name>/agents/openai.yaml`
+- `<skill-name>/scripts/*` (optional)
+- `<skill-name>/references/*` (optional)

package/skills/cache-reset/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: cache-reset
+description: Clear and warm Laravel and Statamic caches after content or template changes.
+alwaysApply: false
+---
+
+Use this skill when the user asks to reset cache, clear stale Statamic output, or warm cache after deployments.
+
+Run from project root in this order:
+
+```bash
+php artisan cache:clear
+php artisan config:cache
+php artisan route:cache
+php please stache:warm
+```
+
+After running, report which commands succeeded and include any failing command output verbatim.

package/skills/cache-reset/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Cache Reset"
+  short_description: "Reset Laravel and Statamic caches"
+  default_prompt: "Reset Laravel and Statamic caches"