Theme Factory Docs

Getting Started

Prerequisites

Claude Authentication

Theme Factory agents run via the Claude Agent SDK. You need one of:

• Local (recommended): Claude Code installed and logged in — uses your Claude subscription
• Cloud / CI: Set the ANTHROPIC_API_KEY environment variable — uses API billing

$ claude login

Shopify CLI

Install and authenticate the Shopify CLI:

$ npm install -g @shopify/cli
$ shopify auth login --store your-store.myshopify.com

Git Access

Your machine needs SSH or HTTPS access to the GitHub repos you'll be working with. The pipeline clones repos via the URL in your input file.

Installation

Follow the installation guide or ask Jarvis for help:

Verify installation:

$ tf --version
$ tf --help

Update to latest:

$ tf update

Or use the built-in update command:

$ tf update

Authentication

Google (Required)

Theme Factory requires Google authentication with an @anattadesign.com account. This is used for identity tracking and telemetry.

$ tf auth login

# Check status
$ tf auth status

# Logout
$ tf auth logout

Figma

Required for Figma-linked tasks. Run the OAuth flow once per user:

$ tf auth figma

This opens your browser to authorize Theme Factory with your Figma account. Tokens auto-refresh — no manual renewal needed.

Shopify Admin Token

Required for each Shopify store you work with. Follow these steps to get the admin token for a store:

How to Get a Shopify Token

1. Install the Theme Factory app — Open the Theme Factory install link in your browser and follow the prompts to install the custom app on your store.
2. Copy the admin token — Once installed, go to the app's home page in your Shopify admin. You'll see the admin API access token displayed there.
3. Save the token immediately — Copy the token and store it somewhere safe. You can only view it once. If you lose it, you'll need to contact support to regenerate it.

Once you have the token, save it with Theme Factory:

# Save a token for a store
$ tf auth shopify --store my-store.myshopify.com --token shpat_xxxxx

# List stored tokens
$ tf auth shopify --list

# Remove a store's token
$ tf auth shopify --remove my-store.myshopify.com

First Run

1. Create an Input File

Create a markdown file anywhere on your machine:

# GIT repo
https://github.com/your-org/your-theme.git

# Store
your-store.myshopify.com

# Task ID
my-first-task

# Theme Base
Horizon

# Task
Build a hero banner section with a background image,
headline, and CTA button.

# Acceptance Criteria
- Hero section renders full-width on desktop
- CTA button links to configurable URL via section schema
- Mobile layout stacks vertically

2. Run the Pipeline

# Full run — builds, commits, pushes to GitHub + Shopify
$ tf run ./my-first-task.md

# Local only — skip pushing
$ tf run ./my-first-task.md --no-push

3. Check the Output

• Logs: A log file is created next to your input file
• Git: Changes committed on a feature branch
• Shopify: Theme pushed as unpublished (unless --no-push)

CLI Reference

Quick Reference

# Authenticate
$ tf auth login
$ tf auth figma
$ tf auth shopify --store my-store.myshopify.com --token shpat_xxxxx

# Run pipeline
$ tf run my-task.md
$ tf run my-batch/ --from 2 --to 4

# Interactive super agent
$ tf chat --latest
$ tf chat --repo my-store-theme
$ tf chat --repo 3

# Split large tasks
$ tf split my-task.md
$ tf split my-task.md --text

# Push changes
$ tf push git my-repo
$ tf push shopify my-repo --store my-store.myshopify.com

# List repos & history
$ tf list
$ tf list my-repo
$ tf list my-repo --logs

# Revert last run
$ tf revert --latest

# Clear session memory or Figma cache
$ tf clear memory --latest
$ tf clear figma --latest

# Delete a repo
$ tf delete my-repo --hard

# Audit & auto-fix translation keys
$ tf translations my-repo
$ tf translations my-repo --fix

# Update CLI (optionally pick a channel)
$ tf update
$ tf update alpha
$ tf update beta

tf auth

Authenticate with external services.

tf auth login

Sign in via Google OAuth. Restricts to @anattadesign.com accounts. Also registers with the TF backend for run telemetry.

$ tf auth login

tf auth status

Show current Google authentication status.

$ tf auth status

tf auth logout

Clear stored Google authentication.

$ tf auth logout

tf auth figma

Run the Figma OAuth flow. Opens your browser to authorize Theme Factory with your Figma account. Tokens auto-refresh — no manual renewal needed.

$ tf auth figma

tf auth shopify

Manage per-store Shopify admin access tokens.

$ tf auth shopify --store my-store.myshopify.com --token shpat_xxxxx
$ tf auth shopify --list
$ tf auth shopify --remove my-store.myshopify.com

tf run

Execute a task file or batch directory through the full agent pipeline.

tf run <file-or-dir> [options]

Single vs Batch mode is auto-detected: a file runs in single mode, a directory runs in batch mode (sub-tasks sequentially).

Auto-resume — In batch mode, completed sub-tasks are tracked. Re-running the same directory skips completed tasks. Use --from 1 to force a full restart.

Interactive Mode

When --interactive is set, the pipeline pauses after the Analyzer Agent creates the implementation plan. You can review and provide feedback before development begins.

$ tf run ./my-task.md --interactive

▶ Phase 2/4: Creating implementation plan...
✔ Plan created — 5 file changes (4m 46s)

📋 Plan Review
  Enter feedback to revise, or press Enter to approve.

Feedback> move the hero into a snippet instead
▶ Revising implementation plan (revision #1)...
✔ Plan revised — 6 file changes (45s)

Feedback>
✔ Plan approved — proceeding to development

• Conversational revisions — each round continues the same session
• Approve by pressing Enter, or typing approve, yes, ok, lgtm
• Not available in batch mode

tf chat

Interactive super agent — a Claude session with full read/write access to your theme.

tf chat [target] [options]

By default, the agent automatically commits and pushes to GitHub after every change. Use --no-push to auto-commit but require confirmation before pushing.

# Super agent on the latest repo
$ tf chat --latest

# Target by name or number
$ tf chat --repo my-store-theme
$ tf chat --repo 3

# Show more recent tasks in the picker
$ tf chat --latest --limit 25

# Auto-commit, ask before push
$ tf chat --latest --no-push

# Create a new task file interactively
$ tf chat --new

tf split

Break a large task into ordered sub-tasks. Defaults to Figma-based splitting when Figma URLs are present.

tf split <file> [--figma|--text] [--new-theme]

The split directory is created next to the input file. Inspect the generated tasks, then execute the batch:

$ tf split ./full-redesign.md
$ tf run full-redesign/

tf push

tf push git

Push workspace commits to GitHub.

tf push git <repo> [--branch <name>]
tf push git --latest

tf push shopify

Push theme to a Shopify store. If a theme with the same name already exists, it updates it. Otherwise, it creates a new unpublished theme.

tf push shopify <repo> --store <store> [--name <name>] [--publish]
tf push shopify --latest

tf translations

Audit translation key usage in a theme. Scans every .liquid file for {{ 'key' | t }} references, marks each as resolved against locales/en.default.json, and flags Liquid antipatterns that produce visible "Translation missing" errors on the storefront. With --fix, infers English defaults via LLM, rewrites the antipatterns, commits, pushes to git, and deploys to Shopify in one shot.

tf translations <repo> [--missing] [--fix] [--store <store>] [--name <name>] [--no-shopify]

What --fix does

1. Rewrites | default: '...' | t antipatterns. The chain {{ section.settings.x | default: 'some.key' | t }} looks reasonable but is a bug: when the merchant has set the variable, its value (not the key) gets fed to | t, producing Translation missing: en.<value> on the storefront. Each occurrence is rewritten to an explicit if/else so the merchant's value is shown verbatim, falling back to the translated default only when blank. Deterministic — no LLM call.
2. Fills missing keys by reading 2 lines of context around each | t reference, then asking the configured dev model for short English defaults. Output is cached to .tf-translations-cache.json before the merge so a failed write never costs you a second LLM call.
3. Merges into locales/en.default.json while preserving CLDR pluralization objects ({ one: "...", other: "..." }) — these are recognized as already-present leaves rather than false-flagged as missing.
4. Commits with a chore: prefix, pushes to the current git branch, and deploys to Shopify. Store and theme name are auto-resolved from the most recent session metadata — pass --store/--name to override, or --no-shopify to skip the deploy.

# Audit only — print the listing, no changes
$ tf translations my-store-theme

# Show only missing keys
$ tf translations my-store-theme --missing

# Full fix: rewrite antipatterns, fill missing keys, commit, push, deploy
$ tf translations my-store-theme --fix

# Repo number works too
$ tf translations 3 --fix

# Deploy to a different store than the last run used
$ tf translations my-store-theme --fix --store other-store.myshopify.com

# Local cleanup only — skip the Shopify deploy
$ tf translations my-store-theme --fix --no-shopify

tf list

List repos in the workspace, or show run history for a specific repo. Alias: tf ls

tf list
tf list <repo>
tf list --latest
tf list <repo> --logs [N]

tf delete

Delete a repo from the workspace. Accepts a repo name or number from tf list.

tf delete <repo-or-number> [--hard]

Without --hard, only the workspace folder is removed. Session data is preserved so you can re-clone and resume later.

tf revert

Undo the last pipeline run. Resets the branch to its pre-run state, then force-pushes to GitHub and re-pushes to Shopify if they were pushed in the original run.

tf revert --latest [--no-push]

Constraints:

• Only the latest run can be reverted
• Only one revert per run
• Reverted runs appear dimmed in tf list output

tf clear

Clear session memory or Figma cache for a repo. Useful when agents are repeating mistakes from stale context, or when Figma designs have changed significantly.

tf clear memory <repo-or-number>
tf clear memory --latest
tf clear figma <repo-or-number>
tf clear figma --latest

When to use:

• Clear memory — when agents keep making the same mistakes based on stale learnings
• Clear figma — when Figma designs have been updated and you need fresh data

tf update

Update Theme Factory to the latest version.

$ tf update

Equivalent to npm install -g @anattadesign/theme-factory@<tag>. Valid tags: latest, alpha, beta.

$ tf update           # latest stable
$ tf update alpha     # latest alpha release
$ tf update beta      # latest beta release

Running a Task

Task File Format

Tasks are defined as markdown files that tell the pipeline what to build. Each file uses # headings as section keys — ## and deeper are treated as body content within their parent section.

Required Sections

Optional Sections

Custom Theme Base Repo

If your team uses a modified version of a base theme (e.g., a cloned and customized Horizon), you can override the scaffolding repo while keeping the original theme's rules:

# Theme Base
Horizon => git@github.com:my-org/my-custom-horizon.git

This tells Theme Factory to:

• Apply Horizon's theme rules (schema standards, block patterns, section conventions)
• Scaffold from your custom repo instead of the official Horizon repository

Without the => override, the standard syntax still works:

# Theme Base
Horizon

Task Example

# GIT repo
https://github.com/my-org/my-store.git

# Store
my-store.myshopify.com

# Theme Base
Horizon

# Task ID
homepage-hero

# Theme Name
My Store Theme

# Git Branch
feature/homepage-hero

# Task
Build a full-width hero banner section with:
- Background image from Figma
- Headline and subheadline text
- CTA button linking to a collection
- Mobile-responsive layout

# Acceptance Criteria
- Hero section renders full-width on desktop
- Text overlays are readable on all backgrounds
- CTA button links to configurable URL via section schema
- Mobile layout stacks vertically

Split Task Example

Same format, but with a larger # Task section. The task splitter decomposes it into sub-tasks automatically.

# GIT repo
https://github.com/my-org/my-store.git

# Store
my-store.myshopify.com

# Theme Base
Horizon

# Git Branch
feature/full-homepage

# Task
Build the complete homepage with these sections:

## Hero Banner
Full-width hero with background image, headline, CTA button.

## Featured Collections
Two collection cards side by side with product previews.

## Testimonials
Customer testimonial carousel with star ratings.

## Footer
Multi-column footer with newsletter signup form.

# Acceptance Criteria
- All sections render correctly on desktop and mobile
- Colors and typography match Figma design
- All sections are configurable via theme customizer

Figma Split Config

Used with tf split to auto-generate task files from a Figma design. Label each URL with Desktop or Mobile prefix for automatic pairing.

# GIT repo
https://github.com/my-org/my-store.git

# Store
my-store.myshopify.com

# Theme Base
Dawn

# Task ID Prefix
MYSTORE

# Theme Name
my-store-redesign

# Git Branch
feature/full-redesign

# Figma
Desktop Homepage: https://figma.com/design/ABC123/...?node-id=10-100
Mobile Homepage: https://figma.com/design/ABC123/...?node-id=10-200
Desktop PLP: https://figma.com/design/ABC123/...?node-id=20-100
Mobile PLP: https://figma.com/design/ABC123/...?node-id=20-200

# Context
Full site redesign. Build the homepage and product listing
page. Includes new header, footer, hero, featured
collections, and product grid.

Figma URLs

Figma URLs can be provided in an explicit # Figma section (one URL per line), or inline in the # Task body (auto-extracted).

https://www.figma.com/design/<fileKey>/<fileName>?node-id=<nodeId>

• With ?node-id= — fetches the specific node tree (recommended)
• Without ?node-id= — fetches file-level overview (depth=2, no frame images)

URLs are deduplicated by fileKey:nodeId pair.

Split Modes

The # Split section in the input file controls how tf split decomposes the task:

When # Split is omitted, the splitter defaults to text mode.

Generated sub-task files are placed next to the input file. Each inherits shared metadata and gets its own # Task, # Task ID, and # Acceptance Criteria.

Super Agent

What Is It

The Super Agent is an interactive Claude session with full read/write access to your theme. Instead of writing a task file and running the 4-agent pipeline, you talk to Claude directly — describe what you want, paste screenshots, and it edits files, validates, commits, and pushes in real time.

It's the fastest way to make small changes, fix bugs, and iterate on a theme.

# Open super agent on the repo from your last pipeline run
$ tf chat --latest

# Or target a specific repo
$ tf chat --repo my-store-theme
$ tf chat --repo 3

# Auto-commit, ask before push
$ tf chat --latest --no-push

By default, the agent automatically commits and pushes to GitHub after every change. Use --no-push to auto-commit but require confirmation before pushing.

How it differs from tf run:

When to Use

The Super Agent is ideal for smaller, quicker work where the full pipeline would be overkill:

• Visual tweaks — spacing, colors, font sizes, alignment
• Bug fixes — broken layouts, missing elements, CSS issues
• Quick iterations — adjusting what the pipeline built
• Content updates — copy changes, link updates, schema tweaks
• Experimentation — try ideas without writing a formal task

For large features (new sections, full page builds, complex logic), use tf run with a task file — the multi-agent pipeline provides structured planning and validation.

Typical Workflow

# 1. Run the pipeline to build a feature
$ tf run my-task.md

# 2. Open super agent to fix/tweak the result
$ tf chat --latest

# 3. Describe issues or paste screenshots
You: The hero section has too much padding on mobile

# 4. Agent edits the file, validates, and shows preview
✔ Updated sections/hero.liquid — reduced mobile padding

# 5. Use --no-push to keep changes local
$ tf chat --latest --no-push

Fixing with Screenshots

One of the most powerful features — paste or drag a screenshot directly into the terminal. The agent analyzes the image visually, identifies the problem, finds the responsible file, and fixes it.

How it works:

1. Take a screenshot of the visual issue in your browser
2. Paste it into the terminal (or drag the image file in)
3. Optionally describe what's wrong — or let the agent figure it out
4. The agent cross-references the screenshot with the actual theme files
5. It edits the code, runs shopify theme check, and pushes

This makes the Super Agent especially effective for QA workflows — review the theme in the browser, screenshot any issues, and the agent fixes them one by one.

Capabilities

The Super Agent is loaded with full context about your repo and has access to everything it needs:

What It Can Do

• Read and edit any file — Liquid, CSS, JS, JSON, schemas
• Run theme check — shopify theme check for validation
• Commit and push to GitHub — with branch awareness
• Push to Shopify — and show a preview URL after each push
• Fetch Figma data — if authenticated, inspect designs and download images
• Upload images to Shopify — from Figma exports or local files
• Analyze screenshots — visual debugging from pasted images

What It Knows

• Learnings — accumulated knowledge from all previous pipeline runs and chat sessions
• Theme inventory — complete file listing with section schemas and capabilities
• Agent rules — CSS, Liquid, JS, and responsive design standards
• TF rules — client-specific component specs from the repo's .tf-rules/ directory

Revert Safety

Before the Super Agent starts, a revert pointer is saved. If anything goes wrong, tf revert --latest resets to the state before the chat session — not the entire repo history.

# Undo everything the super agent changed
$ tf revert --latest

TF Rules

What Are TF Rules

TF Rules are markdown files that live inside your client's theme repository. They teach Theme Factory about client-specific components, patterns, and requirements — so the agents don't have to figure them out from scratch every time.

When you run a task, Theme Factory reads the .tf-rules/ directory in the repo and injects relevant rules into the agent's context based on keyword matching.

Theme Factory assembles every agent prompt from 4 layers, from universal to specific:

1. Identity — core agent role (built into Theme Factory)
2. Agent Rules — universal coding standards for all themes (built into Theme Factory)
3. Theme Rules — base-theme-specific rules, e.g. Dawn vs Horizon (built into Theme Factory)
4. TF Rules — your client-specific rules (lives in the client repo)

Layers 1-3 are maintained by Theme Factory. Layer 4 is yours — it's where you capture everything unique about a client's theme.

Setting Up

Create a .tf-rules/ directory in the root of your client's theme repository:

$ mkdir -p .tf-rules/shared .tf-rules/dev-agent .tf-rules/validator-agent

No rebuilds needed. Rules are read at runtime from markdown files — just commit them to the repo and they're active on the next run.

Rule Format

Each rule is a markdown file with YAML frontmatter that controls when it gets loaded:

---
alwaysApply: false
triggers:
  - header
  - navigation
  - nav
  - sticky
  - mega-menu
---

# Header Component

The header uses sections/header.liquid with sticky positioning.
It has a mega-menu powered by a nested block structure.

Key files: sections/header.liquid, assets/header.js
Mobile: collapses to hamburger at 990px breakpoint.

The sticky behavior uses position: sticky with a
100px offset. Do not change to position: fixed.

Triggers

The triggers field contains lowercase keywords. When your task description mentions any of these words, the rule is automatically injected into the agent's prompt.

• Case-insensitive — triggers are lowercased for matching
• Multi-word triggers work — "sticky header" matches if the task contains that phrase
• Per-task filtering — different rules load for different tasks, keeping context focused
• Set alwaysApply: true for rules that should load on every task (e.g., global design system conventions)
• Files without frontmatter are treated as alwaysApply: true

What to Define

Good candidates for TF Rules:

Learnings

Theme Factory also stores a learnings.md file inside .tf-rules/. This file is automatically populated with knowledge discovered during pipeline runs and chat sessions.

• Pipeline adds schema constraints (valid value ranges, select options) when it encounters errors
• Super Agent adds conventions and client preferences when you correct it during a chat session

[pipeline] Setting 'popover_border_radius' range is 0-16, clamp values exceeding this
[chat] Client uses scheme-3 for green backgrounds, scheme-1 for white

Since it's committed to git, learnings are shared with anyone cloning the repo. All agents read this file on every run.