Skip to main content

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:

PathPurpose
src/Site/**Etch presentation builders and site composition.
cms/acf-json/**Field group JSON that can be synced through WordPress.
tests/**Project-local test support.
AGENTS.project.mdProject 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, and runs PHPStan with a default 1G memory limit when the project has PHPStan configuration.

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.

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.