diff --git a/deco/AGENTS.md b/deco/AGENTS.md new file mode 100644 index 00000000..2151cab5 --- /dev/null +++ b/deco/AGENTS.md @@ -0,0 +1,224 @@ +# AGENTS.md — Deco + +> Deco is one theme inside the **Fifty monorepo**. The monorepo lives one directory up; its `AGENTS.md` (`../AGENTS.md`) and `README.md` (`../README.md`) describe the layout and the rules that apply to every theme. Read this file for Deco-specific rules. Tooling lives in `../bin/`. + +Instructions for AI coding agents working on the Deco theme. Read this file in full before making any changes. Human-oriented docs live in `README.md` and the [project wiki](https://github.com/RegionallyFamous/Fifty/wiki). + +## Required reading order + +1. **`INDEX.md`** -- auto-generated map of every template, part, pattern, style variation, design token, and block style entry. Read this first; it tells you what exists without reading individual files. +2. This file (constraints + workflow). +3. `README.md` (human-facing overview with the project quickstart and links to deeper docs). + +For deeper task-specific reference, read the wiki on demand. The relevant pages are listed below under "Where to find more detail". + +## Tools you should use + +| Command | What it does | +|---|---| +| `python3 ../bin/check.py` | Run every project check. Use this before declaring "done". | +| `python3 ../bin/check.py --quick` | Same, skipping the network-dependent block-name check. | +| `python3 ../bin/check.py --visual` | Run the static checks AND the snap-gated visual regression sweep (`snap.py shoot + diff + report --strict`). Tiered gate; exits 1 only on `fail`. Recommended pre-commit gate after any change to templates, parts, patterns, theme.json, or playground content. | +| `python3 ../bin/snap.py doctor` | One-time check that Pillow, Playwright/Chromium, npx, axe-core, and baseline coverage are all wired up. Run after a fresh clone or Python upgrade. | +| `python3 ../bin/snap.py shoot --routes --viewports ` | Capture a single (route × viewport) PNG into `tmp/snaps/` for the inner edit loop. `Read` the resulting PNG to verify the change. | +| `python3 ../bin/snap.py serve` | Boot this theme's WordPress Playground locally on `http://localhost:9400/` so you can drive it interactively (admin auto-login enabled). | +| `python3 ../bin/build-index.py` | Regenerate `INDEX.md` after adding/removing files or editing `theme.json`. | +| `python3 ../bin/list-tokens.py` | Print every design token in `theme.json`. (`INDEX.md` already contains this; use this script for fresh output if `INDEX.md` is stale.) | +| `python3 ../bin/validate-theme-json.py` | Verify every `core/*` and `woocommerce/*` block name in `theme.json` against trunk. | +| `python3 ../bin/clone.py NEW_NAME` | Clone Deco into a new theme folder, renaming all identifiers. | +| `python3 ../bin/list-templates.py` | Print every template file alongside the WordPress URL it handles. Paste output into LLM context to find the right file without reading the directory. | + +If you remember nothing else from this file: **read `INDEX.md` first, run `python3 ../bin/check.py --visual` last** (or `--quick` for a fast offline subset that skips the visual sweep). + +## What this project is + +Deco is a block-only WooCommerce starter theme for WordPress. It is intended to be copied (use `python3 ../bin/clone.py NEW_NAME`) and then customized by editing `theme.json` and adding project-specific patterns. The framework itself is deliberately small. + +## Hard rules — never violate + +These rules are not preferences. They define what this theme *is*. Do not break them, even if the user's request would be easier to fulfill by breaking them. If a request requires breaking a rule, push back and propose an alternative. + +1. **No CSS files.** `style.css` exists only for the WordPress theme header. Do not create any other `.css` file. Do not add `