Daily Workflow

The LocalWP Devkit is file-first. Build in the project folder, check the project, sync the runtime plugin copy into LocalWP, then verify against the bound Local site.

Edit Project Source

Work under:

projects/<slug>

Common project source paths are:

Path	Purpose
src/Site/**	Typed Etch presentation builders and site composition, authored with honestlydesign/etch-builders.
cms/acf-json/**	Field group JSON that can be synced through WordPress.
tests/**	Project-local test support.
AGENTS.project.md	Project brief, Local binding notes, and user-owned runtime expectations.

Do not use the synced Local plugin copy as the source of truth. It is replaced by sync.

Check Before Sync

Run the project verification gate:

bun run project:check -- --project <slug>

This validates the runtime surface, rejects unsafe links, lints PHP files, runs PHPStan with a default 1G memory limit, and compiles the exact project site definition without writing to WordPress.

If the check reports missing PHPStan dependencies, run the exact composer install --working-dir=... command it prints, then rerun project:check.

Sync to LocalWP

Only sync after the check passes:

bun run localwp:sync -- --project <slug>

Sync writes the project runtime plugin surface into the bound Local site:

wp-content/plugins/oh-my-idetch

It does not sync project notes, tests, tools, package metadata, agent files, local environment files, or user-owned premium plugins.

Sync reruns the no-write project check, copies the runtime surface, and applies the compiled site definition in WordPress. It fails closed when the check, the runtime preflight, the copy, or the apply fails, and a successful sync prints exact applied and unchanged evidence.

Verify After Sync

Run the fast read-only runtime verification after every successful sync:

bun run localwp:verify -- --project <slug>

It checks the compiled entity/resource digests, recorded ownership, required active capabilities, and the installed Builder contract, without browser E2E. Add a single lightweight frontend availability check only when it is part of the task:

bun run localwp:verify -- --project <slug> --path /

Verify Runtime Behavior

Use the bound LocalWP domain shown by Local or recorded in project.json. Do not assume a fixed localhost port.

Use WP-CLI through the devkit wrapper:

bun run localwp:wp -- --project <slug> -- plugin list
bun run localwp:wp -- --project <slug> -- option get home

Check site readiness:

bun run localwp:doctor -- --project <slug>

Inspect runtime capabilities:

bun run localwp:capabilities -- --project <slug>

For visual or interactive work, verify in the browser after sync. OhMyEtch CSS, JavaScript, dropdowns, drawers, facets, Woo Store API behavior, checkout gateways, and fixed runtime styles need the active LocalWP site; project checks alone do not prove those runtime behaviors.

Safe Agent Handoff

When handing a project to an agent, include:

• the devkit root path;
• the project slug;
• the exact Local site name;
• the current build brief;
• user-owned dependencies that should be active;
• whether browser automation is available;
• the last project:check, localwp:sync, localwp:doctor, and localwp:capabilities result.

The agent should start in the devkit root and treat projects/<slug> as the editable source.