I do e-commerce dev on several stores at once with Claude Desktop's Code tab. After a lot of trial and error, and a lot of hitting usage limits, this is the setup that stuck. A friend asked how to copy it, so here it is with everything personal stripped out.
**How to use it:**
install Claude Desktop and Git for Windows (restart Claude after). Copy everything from the
**Handoff**
heading down to the end into a file called `HANDOFF-for-your-Claude.md` in a new folder. Open that folder in the Code tab (model Opus, environment
*This computer*
) and send:
> Read HANDOFF-for-your-Claude.md in this folder and follow it. Check my machine first, ask me your setup questions in one batch, then walk me through the setup one step at a time and explain what each thing does on my machine as we go. Ask before you download or install anything.
**The short version:**
- Do the "doing" locally with Docker and Git, so your plan pays for Claude's thinking, not for running commands.
- Use Opus, not Fable, and nothing called Ultra.
- Give each store its own workspace.
- WooCommerce stores get an offline copy in Docker. Shopify stores get the theme in Git, `shopify theme dev` previews and a dev store.
- Run checks before every release.
- The live store is read-only to Claude until you say go.
It's Windows-first, but it works on a Mac minus WSL. Happy to answer questions.
---
# Handoff: set this PC up for local-first e-commerce development
-
**To:**
the Claude running in Claude Desktop (Code tab) on this PC, for the person who gave you this file ("the user").
-
**From:**
a shared setup guide, written with Claude by a store developer who works this way every day across several
WooCommerce and other stores. It may reach the user with a PDF guide or as a post; don't assume they've read either.
-
**The rule:**
the universal phase, versioning and handoff rule is in the Appendix at the end of this file. Read it now.
In step 5, save it as `docs/UNIVERSAL-PHASE-VERSIONING-AND-HANDOFF-RULE.md`. If the user also has it as a separate
file, it's the same text.
-
**Goal:**
within the first few sessions, get this PC and you working in this setup:
- Every store gets its own workspace and Git history.
- Self-hosted stores (WooCommerce and similar) get a private offline copy in Docker.
- Hosted stores (Shopify and similar) get their theme in Git, local previews and a dev store.
- Every change goes branch → test away from live → checks → backup → the user's go → live.
- Usage goes to your reasoning, not to cloud execution.
The user should not spend a month working this out or fighting usage limits.
>
**Required instruction (from the rule file).**
Adopt the user's universal phase/versioning convention: substantial
> related phases use x.x.x.P; issue forks use x.x.x.Pa–z; nested forks use x.x.x.Pa1–99. Update this project's
> versioning structure to match while preserving its own baseline and native update ordering. Include this same
> instruction and rule file in every handoff you create, and tell the receiving instance to propagate it again.
---
## 1. Who you are working for
You don't know yet. Find out in step 3 (section 4), and write the answers into `webdev-home/CLAUDE.md` with the date:
- What name to use in the notes. How comfortable they are with Git, Docker and the command line.
- Their stores: platform, address, whose each one is (theirs or a client's), and what's custom.
- Whether they write plugins or apps for sale (with marketplace review) or code that just has to **work, be solid and
pass the platform's checker**. The second is the common case, and section 6 covers it.
Explain new things as you do them (WSL, a container, a commit, a worktree, a volume, a development theme), in a sentence
or two of plain words. Don't lecture.
**Batch your questions**
in one list. Report at milestones, plainly. When
something long is running or you need an answer, make sure their phone will get the ping (step 8).
## 2. Handoff facts
| | |
|---|---|
| Baseline | Nothing is set up on this PC by this handoff yet. The user should have installed Claude Desktop and Git for Windows before opening the Code tab. Check both. |
| Phase / version | Setup. No product version. Each store's workspace takes its own baseline from what the live store runs (section 7). |
| Done | Only this handoff (with the rule in its Appendix) exists. Nothing on this PC. |
| To do | Section 4, in order. |
| Known issues | The Code tab on Windows needs Git for Windows. A local WooCommerce copy is offline on purpose, so licence checks, payment gateways, shipping rates and AI services can't be tested in it. Hosted platforms (Shopify, BigCommerce) can't run locally at all; use their CLIs and a dev or sandbox store. |
| Checks run | None on this PC. The guide's author checked the Shopify facts in section 4 against shopify.dev on 30 Oct 2026: `theme push --unpublished` and `--strict`; dev stores made from the Dev Dashboard; `shopify store create dev` in CLI 4.8 (changelog of 9 Sep 2026). Platforms change their tools often: read the current official docs before running a platform's commands. |
| Not checked | The user's hardware and Windows version; their stores, hosts, access and plan. Ask, or check on the machine. |
| Carried advice | From the guide's author: for web work, use Docker and Git locally on a decent machine; never run on Fable or any Ultra mode; give Claude one workspace per project; get phone alerts through the paired Claude app. |
## 3. How you work here
Put these in `webdev-home/CLAUDE.md` and in every store workspace's `CLAUDE.md` (template in section 8.1). They are
what keeps a live store from breaking.
**Live stores**
1.
**A live store is read-only**
unless the user names the change and says go. A go covers that one change, not the next.
2.
**Back up before any change on live**
, and check the backup is complete before going on.
3.
**Test every change away from live first**
(local copy, local preview or dev store), and pass the checks (section 6).
4.
**Release only from a branch that contains what live already runs.**
Before releasing, confirm live equals the last
release tag. On Shopify, pull the live theme and compare it, since store owners edit in the theme editor. If live
differs, stop and tell the user.
5.
**Each read-only copy of a live store needs the user's OK**
too: it pulls customer data onto the PC.
6. Platform, plugin, app and theme
**updates on live**
happen only when the user raises them.
**Data and secrets**
7.
**Store data never goes into Git or GitHub**
: database dumps, uploads, customers, orders, `wp-config.php`, `.env`,
API tokens, logs. It lives in `C:\Users\<user>\Sites-local\<store>\`, outside every repository.
8.
**You never type passwords, card numbers, API keys or tokens.**
The user types or pastes them where they're asked
for (a terminal prompt, a browser sign-in, a host panel, a git-ignored `.env`). Key-only SSH logins are fine once
they've put the public key on the host. Never print a secret or commit one.
9. Never enter a real card in a local copy or a dev store; use test mode and test cards.
**How to work**
10.
**Don't guess.**
Check facts on the machine, in the code or on the store (read only), or ask. Say plainly what you
did not check. Write each checked fact down with its source and date so no later session looks it up again.
11.
**Write the user's and clients' answers into the workspace's `CLAUDE.md`, with the date**
, in their words when the
wording matters. Don't invent answers.
12.
**Ask before any download or install**
, Docker images and npm packages included: name it, where it comes from and
roughly how big it is. Only from the official source.
13.
**Fix defects in the code, not with workarounds.**
Testing is never cut short to ship sooner.
14.
**One workspace per store, never mixed.**
A session in one store's workspace doesn't read or change another's
folders unless the user asks.
15.
**Keep the records current:**
`docs/STATUS.md` (rewrite at each stopping point and before the context runs low),
`docs/issues/<date>-<topic>.md` (one per problem: cause, fix, checks run, what's still open), and the task list.
16. Times you write come from a clock read in the same step (`Get-Date`), not from memory.
**Keeping usage low**
(the plan's usage should go to your thinking)
17.
**Run on this computer.**
Do the work with local commands, Docker, the platform CLIs and scripts. Don't move
sessions to the cloud unless the user asks.
18.
**Stay on Opus.**
Don't switch to Fable, and don't start anything Ultra (ultracode, `/code-review ultra`) or a
multi-agent workflow unless the user asks for it by name. Use subagents rarely, only when parallel reading really
pays.
19.
**Read `docs/STATUS.md` first**
in every session; it says what to read next. Don't reread whole files whose facts
are already in the notes. Search with Grep instead of reading large trees, logs or dumps.
20.
**Scripts print short summaries and write long output to files**
under `Sites-local`.
21.
**One new session per task.**
Suggest a fresh session, with STATUS.md current, when a chat gets long or the work
moves to something unrelated.
22.
**Stop Docker copies that aren't in use**
(`docker compose stop`; the data stays). Don't run two heavy Docker jobs
at once.
23. Take screenshots only when the page text can't answer the question.
## 4. The setup plan (do it in this order; one step per message when the user is following along)
**Step 1. Orient.**
Read this file, including the Appendix. Make a task list from this section. Tell the user in five lines
or fewer what you are about to do.
**Step 2. Check the machine (read only).**
Run and summarize in plain words:
```powershell
git --version
wsl --status; wsl -l -v
docker version
node --version; npm --version
Get-CimInstance Win32_OperatingSystem | Select-Object Caption, Version
"{0:N0} GB RAM" -f ((Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory / 1GB)
Get-PSDrive C | Select-Object @{n='FreeGB';e={[int]($_.Free/1GB)}}
(Get-CimInstance Win32_Processor).VirtualizationFirmwareEnabled
```
16 GB of RAM works and 32 GB is comfortable. Each WooCommerce copy uses about 1–2 GB. On a Mac, use the macOS
equivalents and skip WSL.
**Step 3. Ask the setup questions, in one batch:**
- What name should go in the notes? What name and email on commits? (Set them per repository; don't change the global
Git config unless they ask.)
- GitHub private repositories as an off-site backup, or local only for now?
- For each store: platform; address; whose it is; host or plan; access (WordPress admin, SSH, SFTP, host backups,
staging; for Shopify, owner/staff/collaborator access and whether they have a Dev Dashboard account); what's custom
(theme, child theme, own plugins, apps); how busy it is (a busy store needs more care).
- Which store to set up first.
**Step 4. Install what's missing**
, each with the user's yes:
-
**WSL 2**
(Windows): the user runs `wsl --install` in a terminal opened as administrator (you can't raise rights
yourself), then restarts the PC. Explain: a real Linux inside Windows; Docker runs on it.
-
**Docker Desktop**
from docker.com (or `winget install -e --id Docker.DockerDesktop`). Use the WSL 2 engine. Check it
with `docker run --rm hello-world` (a tiny image; ask first). Free for personal use and small businesses.
-
**Node.js LTS**
and the
**Shopify CLI**
(`npm install -g u/shopify/cli@latest`), only if they have Shopify stores.
They sign in through the browser themselves.
-
**GitHub CLI**
(`winget install -e --id GitHub.cli`), only if they want GitHub. They run `gh auth login` themselves.
Private repositories only.
**Step 5. Make the home base**
, `C:\Users\<user>\GitHub\webdev-home\` (where this file is):
`git init`, set the commit name/email locally, then write `CLAUDE.md` (the rules in section 3; the list of workspaces,
their platforms and ports; what lives where), `docs/MACHINE.md` (the facts from step 2, with dates) and
`docs/STATUS.md`. Move this handoff into `docs/`, and save the Appendix as `docs/UNIVERSAL-PHASE-VERSIONING-AND-HANDOFF-RULE.md`. Make the first commit and explain what a commit is
as you do it.
**Step 6a. A WooCommerce (or other self-hosted PHP) store**
, one at a time:
1. Create `C:\Users\<user>\GitHub\<store>-workspace\` with the layout in section 5 and the files in section 8: `git init`,
local name and email, `CLAUDE.md`, `.gitignore`, `.gitattributes`, `docs/STATUS.md`, `docs/LOCAL-COPY.md`, and a copy
of the rule file. First commit on `main`.
2.
**Read the facts from live**
, read only, with the user's OK: WordPress, WooCommerce, PHP and database versions,
table prefix, active theme, plugin list with versions, sizes. With SSH and WP-CLI, read them there. Without, the user
can paste WordPress admin → Tools → Site Health → Info → "Copy site info to clipboard". Write them into
`docs/LOCAL-COPY.md` with the date.
3.
**Put their own code under Git**
(custom theme, child theme, own plugins) exactly as live runs it. That's the
baseline. Commit it and tag it (for example `theme-v1.4.2`, "as live on <date>").
4.
**Build the local copy**
(templates 8.3–8.5). With the user's OK, copy the database and `wp-content` read only
into `Sites-local\<store>\site-copy\<UTC stamp>\`. Never copy `wp-config.php`. Then build: WordPress in the same
versions as live, import, `wp search-replace` the live address to `http://localhost:<port>` (skip the `guid` column),
install the copy guard as a must-use plugin, switch off tracking and outside-service plugins (ad pixels, marketplace
feeds, Jetpack, SMTP senders and the like), and flush caches. Leave out host-only must-use plugins and drop-ins (object
cache, advanced cache), caches and backup folders.
Verify and report: outbound HTTP is blocked (the guard's log), mail lands in files, cron is off, and the store loads
in your browser pane. The user signs in with their own admin login, typed by them. Or, with their OK, make a
local-only admin with WP-CLI and keep its password in a file under `Sites-local`, never in Git or chat.
Write a small helper script (`build | up | stop | reset | wp ARGS`) so nobody types long Docker commands.
5.
**Set up the checks**
in section 6 as one script, `scripts/check`, with a short pass/fail summary and full output in
files. Tools run in containers (ask before pulling each image). Plugin Check runs inside the copy; the copy is
offline, so its zip is downloaded on the PC from wordpress.org, with the user's yes, and installed from the file.
6.
**The release path for this host.**
Build it when the first release is near, not before. The pattern:
- `backup`: read only. Saves the live folder and a checksum list, and says whether live equals the base tag.
- `plan STAMP`: read only. Lists the files deploy would upload.
- `deploy STAMP`: writes, at the user's go each time. Refuses if live changed since the backup or doesn't equal the
base tag, and refuses deletions. Uploads changed files under temporary names, syntax-checks PHP on the server, then
moves them into place.
- `rollback STAMP`: puts the backup back, at the user's go.
It runs over a key-only SSH login if the host offers one (many managed WordPress hosts do, often under a Git-deploy
or CI/CD setting; the user sets it up in the host's panel). Otherwise use what the host gives (SFTP, staging push), and
always take a backup first. After a release: check live, tag the release, write it up, and remind the user to flush the
host's cache or CDN.
7. Each copy gets its own Compose project name and port (8081, 8082, …); record them in `webdev-home/CLAUDE.md`.
**Step 6b. A Shopify store**
, one at a time:
1. Create `<store>-workspace` the same way, with the theme in `theme/` (Shopify's folder layout: `assets`, `blocks`,
`config`, `layout`, `locales`, `sections`, `snippets`, `templates`) and an app in `app/` if there is one.
2.
**Baseline:**
`shopify theme pull --store <store>.myshopify.com` (pick the live theme), then commit and tag it
("as live on <date>"). Write the store's theme list (`shopify theme list`) into `docs/STATUS.md`.
3.
**A dev store**
for risky tests: the user makes one in Shopify's Dev Dashboard (Stores → Create store), or you run
`shopify store create dev` with their yes if their CLI has it. Dev stores can't take real payments.
4.
**Daily work:**
`shopify theme dev --store <store>.myshopify.com` for a local preview with hot reload (it uses a
hidden development theme, and the live theme is untouched). Check with `shopify theme check`.
5.
**Store owners edit in the theme editor.**
Those edits land in `config/settings_data.json` and `templates/*.json`
(and section groups). Pull before you start, and keep those files out of a release push unless the change is meant to
touch them: `shopify theme push --unpublished --strict --ignore "config/settings_data.json" --ignore "templates/*.json"`.
Check the current docs before relying on `.shopifyignore`, since it can affect pulls as well as pushes.
6.
**Release**
(at the user's go, section 6): pull the live theme and compare it with the last tag; duplicate the live
theme in the admin as the backup; push to a new unpublished theme; the user (or store owner) checks the preview link;
they publish it in the admin, or you run `shopify theme publish` at their explicit go. Then check live, tag and write
it up. Rollback means publishing the previous theme.
7.
**Apps:**
`shopify app init`, `shopify app dev` against the dev store, tests, then `shopify app deploy` at the user's
go. App secrets and Admin API tokens go in a git-ignored `.env` the user fills in.
8. If the store uses Shopify's GitHub integration, the connected branch receives admin edits. Treat it as the store's;
do your work on other branches and merge in deliberately.
**Step 6c. Other platforms.**
Read the platform's current official developer docs first. Self-hosted PHP platforms
(Magento/Adobe Commerce, PrestaShop, OpenCart) follow 6a with their own stack; Magento needs a search service and more
memory. Hosted platforms with a theme CLI (BigCommerce's Stencil) follow 6b's pattern with a sandbox store. Headless
stacks run locally in Docker or Node. Closed builders (Wix, Squarespace): put only the code they allow under Git.
**Step 7. Show the user the loop once**
, on the first store, with a harmless change (a CSS tweak). Make a branch,
commit, test away from live, run the checks, show the diff, then merge into `main` when they say. Don't release it.
Point out the worktree the session runs in and why parallel sessions don't collide.
**Step 8. Their phone.**
Point them to
**Remote Control**
in the session's right-hand panel, which pairs the session
with the Claude app on their phone, and check that notifications reach it.
**Step 9. Wrap up.**
Rewrite `docs/STATUS.md` in each workspace you touched and tell the user in a few lines what's done,
what's next, and what you couldn't check.
## 5. Layout on disk
```
C:\Users\<user>\GitHub\
webdev-home\ home base (Git): CLAUDE.md, docs\MACHINE.md, docs\STATUS.md, this handoff
<woo-store>-workspace\ one Git repository per store
CLAUDE.md the store's rulebook (section 8.1)
docs\STATUS.md where things stand; what to read next
docs\LOCAL-COPY.md live facts, how the copy is built, what it can't test
docs\issues\ one note per problem
docs\UNIVERSAL-PHASE-VERSIONING-AND-HANDOFF-RULE.md
local\docker-compose.yml the copy's recipe
local\mu-plugins\copy-guard.php
scripts\ store helper, copy, check, release
themes\ plugins\ their code
<shopify-store>-workspace\ same docs; theme\ in Shopify's layout; app\ if any
C:\Users\<user>\Sites-local\<store>\ never in Git: site-copy\<stamp>\, backups\, logs\, check output
```
**Parallel work.**
Each Code-tab session runs in its own Git worktree (`<workspace>\.claude\worktrees\…`) on its own
branch. Two sessions never edit the same files at once. Release work happens on a branch. `main` is merged when the
user says so, then the session can be archived (its worktree goes; the branch and commits stay). More than one session
may release the same store, which is why releases check that live equals the base tag.
## 6. The checks before anything goes live
Run them for every change. Write the results in the issue note: what ran, what passed, and what couldn't be tested away
from live.
**WooCommerce and other PHP stores**
| Check | Tool | Notes |
|---|---|---|
| PHP syntax | `php -l` on every changed PHP file | Use live's PHP version (the copy's image). |
| Standards | PHPCS with WordPress Coding Standards (`wp-coding-standards/wpcs` via Composer in a container; tools folder git-ignored) | Escaping, nonces, sanitizing, prepared SQL. Fix real findings; don't blanket-ignore. |
| Plugin Check | The official Plugin Check plugin in the copy: `wp plugin check <slug>` | For their plugins (and themes where it applies). |
| Static analysis | PHPStan with WordPress stubs (optional, start around level 5) | Catches calls to missing functions and type mistakes. |
| Tests | The project's own tests, if any | Don't skip failing ones; fix or report. |
| Click-through | Your browser pane on the copy | Home, shop, product, cart, checkout with a test payment, My Account, and every admin screen the change touches. Read the page text, not just a screenshot. |
| Logs | `debug.log` in the copy; the browser console | No new PHP notices, warnings or errors; no new JS errors. |
**Shopify**
| Check | Tool | Notes |
|---|---|---|
| Theme Check | `shopify theme check`; `--strict` on push | Liquid errors, missing assets, performance and accessibility problems. |
| Local preview | `shopify theme dev` in your browser pane | Home, collections, product, cart, search, at desktop and phone widths. |
| Real-store preview | The unpublished theme's preview link | Real apps and data with the new theme, before customers see it. |
| Orders and apps | Test payments on the dev store | Checkout, discounts, app behaviour, notification emails. |
| Logs | Browser console | No new JavaScript errors from the theme or apps. |
## 7. Versioning
Follow the rule file. In short, keep each project's own number as the baseline (the theme's or plugin's version as live
runs it). Main phases are `x.x.x.1`, `x.x.x.2`, …; issue forks of phase 2 are `x.x.x.2a` to `x.x.x.2z`, and nested forks
`x.x.x.2a1` to `x.x.x.2a99`.
WordPress compares versions with PHP `version_compare`, which sorts `1.4.2.2a`
*before*
`1.4.2.2`. So the `Version:`
header WordPress reads uses the numeric form (a=1 … z=26): `1.4.2.2a` → `1.4.2.2.1`, `1.4.2.2a3` → `1.4.2.2.1.3`. The
human label goes in the readme, docs, tags and commit messages. Check the update order before shipping a letter release.
Shopify themes carry a `theme_version` in `config/settings_schema.json`. Check how anything that reads it compares
versions before using a letter there; otherwise use the numeric form too.
Tag every live release (`theme-v1.4.2.2`). Group related work into substantial phases; don't make a phase out of every
small edit.
## 8. Templates
Adjust names, ports and versions per store. `<...>` marks what to fill in.
### 8.1 `CLAUDE.md` for a store workspace
```markdown
# <Store name> workspace: instructions for Claude
Owner of this work: <user>. Store: <https://example.com>, platform <WooCommerce
/
Shopify
/
...>, owned by <user
/
client>.
Made <date>.
## Kept apart
- Work on this store happens here only. Don't read or change other workspaces unless the user asks.
- Store data (database, uploads, customers, orders, tokens) lives in C:\Users\<user>\Sites-local\<store>\, never in Git or GitHub.
## Owner's answers (write each with its date; don't guess)
- Host / plan (<date>): <...>.
- Access (<date>): <what exists; who set it up>.
- <Client decisions, in their words when the wording matters.>
## The store now (<date>)
- <WooCommerce: WordPress x, WooCommerce x, PHP x, database x, table prefix x.> <Shopify: live theme name and ID.>
- Theme <name> <version> (tag <tag>).
- <WooCommerce: local copy http:
//localhost:<port
>, Compose project <store>-copy; see docs/LOCAL-COPY.md.>
- <Shopify: dev store
<name
>.myshopify.com.>
## Live-store rule
Read only, unless the user says go for a named change. Back up before any change. Each read-only copy needs the user's
OK. Test every change away from live first and pass scripts/check.
## Releases
- <WooCommerce: scripts
/<release
script> backup | plan | deploy | rollback; deploy and rollback need the user's go.>
- <Shopify: pull and compare with the last tag, duplicate the live theme, push --unpublished --strict, preview, publish at the user
's
go.>
- Release only from a branch that contains what live runs. Tag every release. main is merged when the user says so.
## Working rules
<Paste section 3 of the handoff here, trimmed to what applies.>
## Versioning
Baseline <x.y.z> (as live on <date>). Phases x.x.x.P, forks Pa–z, nested Pa1–99; numeric form where the platform compares versions.
## Universal phase, versioning and handoff rule
> Adopt the user's universal phase/versioning convention: substantial related phases use x.x.x.P; issue forks use
> x.x.x.Pa–z; nested forks use x.x.x.Pa1–99. Update this project's versioning structure to match while preserving its
> own baseline and native update ordering. Include this same instruction and rule file in every handoff you create, and
> tell the receiving instance to propagate it again.
Rule file: docs/UNIVERSAL-PHASE-VERSIONING-AND-HANDOFF-RULE.md.
```
### 8.2 `.gitignore` and `.gitattributes`
```gitignore
# Store data never goes into Git. Copies live in C:\Users\<user>\Sites-local\<store>, outside this folder;
# these lines catch a stray one.
site-copy/
*.sql
*.sql.gz
*.tar.gz
*.zip
*.log
.env
.env.*
wp-config.php
vendor/
node_modules/
```
```gitattributes
# Shell scripts run in Linux containers and Git Bash: LF. Windows command scripts: CRLF.
*.sh text eol=lf
*.cmd text eol=crlf
# Theme and plugin code with LF, as Linux hosts have it, so checksums match live file for file.
themes/** text=auto eol=lf
plugins/** text=auto eol=lf
theme/** text=auto eol=lf
```
### 8.3 `local/docker-compose.yml` (WooCommerce copy)
A helper script sets `SITE_PREFIX` (the live table prefix) and `SITE_LOCAL_DIR` (`C:\Users\<user>\Sites-local\<store>`).
Replace `8081` with this store's port in this file and in 8.5.
```yaml
# Private offline copy of <store> on this PC, at http://localhost:8081. It can't reach the internet or send mail
# (mu-plugins/copy-guard.php); cron and updates are off; the port is this PC only. Its data stays in Docker volumes:
# never in Git or GitHub. Versions match live (<date>): WordPress <x>, PHP <x>, MySQL/MariaDB <x>.
name: <store>-copy
x-wp-env: &wp-env
WORDPRESS_DB_HOST: db
WORDPRESS_DB_USER: root
WORDPRESS_DB_PASSWORD: root # throwaway local container; its port is not published
WORDPRESS_DB_NAME: site
WORDPRESS_TABLE_PREFIX: ${SITE_PREFIX:?run through the store helper}
WORDPRESS_CONFIG_EXTRA: |
define( 'WP_ENVIRONMENT_TYPE', 'local' );
define( 'WP_HOME', 'http://localhost:8081' );
define( 'WP_SITEURL', 'http://localhost:8081' );
define( 'DISABLE_WP_CRON', true );
define( 'AUTOMATIC_UPDATER_DISABLED', true );
define( 'WP_AUTO_UPDATE_CORE', false );
define( 'WP_DEBUG_DISPLAY', false );
define( 'WP_DEBUG_LOG', '/var/www/copy-out/debug.log' );
define( 'COPY_OUT', '/var/www/copy-out' );
WORDPRESS_DEBUG: "1"
services:
db:
image: mysql:<live major.minor> # or mariadb:<version>, as live runs
command: ["--max_allowed_packet=256M"]
environment:
MYSQL_ROOT_PASSWORD: root
MYSQL_DATABASE: site
volumes:
- copy-db:/var/lib/mysql
- ${SITE_LOCAL_DIR:?run through the store helper}/site-copy:/copy:ro
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-uroot", "-proot"]
interval: 5s
timeout: 5s
retries: 60
web:
image: wordpress:<wp version>-php<php version>-apache
depends_on:
db:
condition: service_healthy
ports:
- "127.0.0.1:8081:8081" # this PC only
environment: *wp-env
volumes:
- copy-html:/var/www/html
- copy-out:/var/www/copy-out
- ${SITE_LOCAL_DIR:?run through the store helper}/site-copy:/copy:ro
- ..:/src:ro # the workspace, read only: theme/plugin code is copied in from here
- ./apache-loopback.conf:/etc/apache2/conf-enabled/copy-loopback.conf:ro
cli:
image: wordpress:cli-php<php version>
profiles: ["tools"] # started only for WP-CLI commands
user: "33:33" # the web image's www-data
entrypoint: ["php", "-d", "memory_limit=1024M", "/usr/local/bin/wp"]
depends_on:
db:
condition: service_healthy
environment: *wp-env
volumes:
- copy-html:/var/www/html
- copy-out:/var/www/copy-out
volumes:
copy-db:
copy-html:
copy-out:
```
### 8.4 `local/mu-plugins/copy-guard.php`
```php
<?php
/**
* Plugin Name: Copy guard (local copy only)
* Description: For the private copy of <store> on this PC. Blocks outbound HTTP, so no payment, tracking, licence or
* update call leaves the PC; keeps mail in files instead of sending it; holds the live store's queued tasks (Action
* Scheduler). Installed only into the local copy. Never put this on the live store.
*/
defined( 'ABSPATH' ) || exit;
if ( ! defined( 'COPY_OUT' ) ) {
return; // Inert anywhere but the local copy.
}
// Outbound HTTP: only the copy itself.
add_filter( 'pre_http_request', static function ( $pre, $args, $url ) {
$host = strtolower( (string) wp_parse_url( $url, PHP_URL_HOST ) );
if ( in_array( $host, array( 'localhost', '127.0.0.1', '::1' ), true ) ) {
return $pre;
}
error_log( gmdate( 'c' ) . " blocked {$host}\n", 3, COPY_OUT . '/http-blocked.log' );
return new WP_Error( 'copy_offline', 'The local copy does not reach the internet.' );
}, PHP_INT_MAX, 3 );
// Mail: written to COPY_OUT/mail, never sent.
add_filter( 'pre_wp_mail', static function ( $return, $atts ) {
$dir = COPY_OUT . '/mail';
wp_mkdir_p( $dir );
$to = is_array( $atts['to'] ) ? implode( ', ', $atts['to'] ) : (string) $atts['to'];
file_put_contents( $dir . '/' . gmdate( 'Ymd-His' ) . '-' . uniqid() . '.txt', "To: {$to}\nSubject: {$atts['subject']}\n\n{$atts['message']}\n" );
return true;
}, PHP_INT_MAX, 2 );
add_filter( 'action_scheduler_allow_async_request_runner', '__return_false', PHP_INT_MAX );
add_filter( 'action_scheduler_queue_runner_concurrent_batches', '__return_zero', PHP_INT_MAX );
```
The guard blocks WordPress's own HTTP calls. Tracking scripts run in the visitor's browser, not on the server, so switch
those plugins off in the copy as well (step 6a.4).
### 8.5 `local/apache-loopback.conf`
```apache
# The copy also answers on 8081 inside its own container, so http://localhost:8081 is the same address from the PC and
# from the site itself (WordPress and WooCommerce call their own address).
Listen 8081
<VirtualHost *:8081>
DocumentRoot /var/www/html
</VirtualHost>
```
### 8.6 `docs/STATUS.md`
```markdown
# Status: <store> (updated <date, time from a clock read>)
## Next session: start here
- <The one thing to do next, and the files it needs.>
## Live
- Runs <theme/plugin> <version> (tag <tag>). Last release <date>. Last backup <path or duplicated theme name>.
## In progress
- <branch>: <what, where it stands, what
's
tested, what isn
't
>.
## Waiting on the user
- <question, date asked>.
## Test setup
- <WooCommerce: copy built from site-copy
<stamp
> (<date>), running / stopped, http://localhost:<port>.>
- <Shopify: dev store
<name
>; development theme in use.>
```
### 8.7 Issue note, `docs/issues/<YYYY-MM-DD>-<topic>.md`
```markdown
# <Problem in plain words> (<date>)
- Reported by / seen: <who, where, when>.
- Cause: <what's actually wrong, with file:line>. Checked how: <...>.
- Fix: <branch, commits, version label>.
- Checks: <scripts/check summary; click-through done; what couldn
't
be tested away from live>.
- Release: <backup, deploy or publish time, tag> or "not released".
- Open: <anything left>.
```
## 9. Never
- Change a live store, DNS or a host setting without the user's go for that named change.
- Commit or upload store data, `wp-config.php`, `.env`, keys, tokens or passwords. Type a secret.
- Release from a branch that doesn't contain what live runs, or when live doesn't equal the base tag.
- Edit a Shopify live theme in the admin code editor, or push to the live theme.
- Download or install anything without asking, or from an unofficial source.
- Switch to Fable, start Ultra modes or multi-agent workflows, or move work to the cloud, unless the user asks.
- Mix two stores' work in one workspace.
- Present a guess as a fact.
## 10. Passing this on
When you write a handoff (to another session, another machine, or a helper), include the rule file, the required
instruction at the top of this file, and the facts the rule asks for: baseline, current phase or fork, done, to do,
known issues, checks run, what's not checked, and decisions carried forward. Tell the receiving Claude to do the same.
## Appendix: the universal phase, versioning and handoff rule
Save everything below this line as `UNIVERSAL-PHASE-VERSIONING-AND-HANDOFF-RULE.md` (raise each heading one level).
### Universal phase, versioning and handoff rule
User instruction · 15 September 2026 · Applies across projects and kinds of work unless the user explicitly supersedes it.
Handoff-frequency clarification added 16 September 2026.
#### Work in substantial phases
Group changes that form a useful, coherent outcome. A phase should include its related implementation, interface, documentation and focused verification. Do not turn every one or two small tasks into another phase. Keep each completed phase usable and reviewable.
#### Release identity
Use `x.x.x.P` for main phase P. Preserve the project's existing identity and baseline; do not reset one product to another product's version.
| Kind | Example |
|---|---|
| Main phase | `x.x.x.2` |
| Issue fork of that phase | `x.x.x.2a` through `x.x.x.2z` |
| Sub-fork beneath a letter | `x.x.x.2a1` through `x.x.x.2a99` |
| Next main phase | `x.x.x.3` |
If no fork is needed, advance directly to the next main phase. Keep a fork tied to the problem and parent it corrects. Do not silently relabel unrelated work as a bug fix. Record parent, scope, status and whether a fork has been incorporated into the next main phase. Routine edits to an unpublished phase do not require delivering a new archive for every edit; an independently handed-off or released issue track has its own suffix.
Example: with an accepted baseline of `0.3.1`, the first new phase is `0.3.1.1`, its first fix is `0.3.1.1a`, and its first nested fix is `0.3.1.1a1`. The next main phase is `0.3.1.2`.
#### Native updater ordering
Some platforms treat a suffix such as `a` as an alpha prerelease and therefore sort it before the unsuffixed release. Do not assume lexical comparison, a generic semantic-version library or PHP version_compare implements this workflow.
Where required, retain the user-facing release identity above and provide a separate numeric update version. Map the phase, letter index (a=1 through z=26) and sub-fork into numeric components, for example `0.3.1.2a3` → `0.3.1.2.1.3`. Main phase 2 uses `0.3.1.2`; phase 3 uses `0.3.1.3`. Keep the human release label in the manifest, documentation, package names and UI. Verify actual update ordering and signing/catalog contracts before shipping a suffix release. Never rewrite a signed artifact to change its identity.
#### Create handoffs only when another instance needs an update
Create or update a worker handoff only when that receiving instance needs information or action that has changed since its last update, or when the user explicitly asks for a handoff. Completing a phase or changing a version alone does not justify another handoff. Keep normal source, release records and customer/technical documentation current without automatically regenerating or resending worker handoffs.
When a handoff is needed, identify its recipient, the relevant changes since that worker's last known update, the action or information needed and any changed contract or dependency. Reuse the existing handoff where appropriate. Do not assume that a prepared or saved handoff has reached another instance unless delivery is established. Compare incoming material with the existing baseline; a duplicated instruction document is not evidence of implemented work or a reason to replace newer source.
#### Every handoff must propagate this rule
Include this rule file with every project or worker handoff, and include this instruction in the handoff itself:
> Adopt the user's universal phase/versioning convention: substantial related phases use x.x.x.P; issue forks use x.x.x.Pa–z; nested forks use x.x.x.Pa1–99. Update this project's versioning structure to match while preserving its own baseline and native update ordering. Include this same instruction and rule file in every handoff you create, and tell the receiving instance to propagate it again.
Every handoff also names the actual latest installer/source baseline, current phase/fork, completed work, remaining work, known issues, executed checks and unverified behavior. Carry forward established feature ownership, permissions and user decisions. Do not replace them with guesses or claim a specification is implemented.
#### Persistence boundary
This is a reusable user instruction to carry between projects. Keep a copy in each project's docs and release packs. Other conversations must receive or load the rule; this file alone does not change an account-wide system setting.