claude-websimple-devops/SKILL.md

name, description

name

description

websimple-devops

Operate the Websimple WordPress development environment — the local websimple-stack Docker Compose project, WordPress site lifecycle (create, sync, reset), Composer dependencies, Kaliroots child themes, ACF conventions, asset build pipelines, browser/Xdebug debugging, and Gitea metadata lookups. Use whenever the user mentions a Websimple WordPress site, a `wp-sites` Gitea repository, the `ledevsimple.ca` local domain (or another `WEBSIMPLE_STACK_DOMAIN`), `websimple-stack`, `wp-apache2`, Kaliroots, ACF in a Websimple context, or any local WordPress dev task on a developer machine configured for Websimple. Also use when a request implies operations on a Websimple project even without naming it explicitly — for example "spin up a local copy of example.com", "pull production into local for site X", "fix the Composer install for this site", "what's the production URL for client Y".

Websimple DevOps

Operate Websimple's local WordPress development environment: the websimple-stack Docker Compose project, the WordPress sites it serves, the Composer-managed plugins/themes inside them, and the Gitea metadata that holds deployment values.

This skill packages a router (this file) plus 13 topic-specific reference files under references/ and a Bash wrapper for Gitea API reads under scripts/. The reference files contain the operational detail — read them when a task lands in their area. Don't try to remember their content; resolve the topic, then read the file.

Required environment variables

These must be set in the user's shell before any operation that needs them. Fail fast and ask the user to export them if they're missing — do not guess defaults.

Variable	Meaning
WEBSIMPLE_STACK_PATH	Absolute path to the local websimple-stack Docker Compose checkout.
WEBSIMPLE_STACK_PROTOCOL	http or https — protocol used by local Traefik routing.
WEBSIMPLE_STACK_DOMAIN	Local domain suffix Traefik routes wildcard subdomains for (e.g. ledevsimple.ca).
WP_LOCAL_ROOT_PATH	Absolute path to the shared WordPress root path served by the wp-apache2 service.
WEBSIMPLE_GITEA_API_TOKEN	Read-only Gitea API token for metadata lookups.

Treat all of these as sensitive in the sense that the token must never be echoed back in chat. The paths and domain are not secrets, but still read them from the environment rather than hard-coding so the skill stays portable across user setups.

Cowork session bootstrap

The Cowork bash sandbox does not inherit the user's host .bashrc/.profile, and the skill's own discovery directory (~/.config/Claude/.../skills/websimple-devops) is a symlink whose target (~/Projects/AI/claude-websimple-devops) lives outside the sandbox — bash can't follow it. So at the start of any bash call that runs skill scripts or needs the env vars, resolve both via the session's mount paths:

# Env vars (shared with the host shell via ~/.config/cowork/env.sh)
COWORK_ENV="$(ls /sessions/*/mnt/cowork/env.sh 2>/dev/null | head -1)"
[ -n "$COWORK_ENV" ] && . "$COWORK_ENV"

# Skill root — canonical home of this skill, mounted into the sandbox
SKILL_ROOT="$(ls -d /sessions/*/mnt/claude-websimple-devops 2>/dev/null | head -1)"

If either lookup comes up empty, the corresponding host folder isn't mounted into this Cowork session. Ask the user to approve mounting ~/.config/cowork/ (for env vars) or ~/Projects/AI/claude-websimple-devops (for the skill itself). Then invoke scripts via "$SKILL_ROOT/scripts/..." — never via the symlinked discovery path, which is dangling from inside the sandbox.

Reference index — read the file that matches the task

For any non-trivial task, read the matching reference file first before producing commands or making changes. The reference files encode conventions that aren't obvious from the codebase and that the user expects to be followed.

Concern	Reference file
Host environment, Docker Compose, Traefik, required executables, MySQL/WP-CLI defaults	references/websimple-stack.md
Websimple Gitea conventions, repository URLs, Actions variables, token usage	references/websimple-gitea.md
WordPress project naming, slug derivation, local/remote URL/DB/path conventions	references/wp-project.md
Local site lifecycle — create, clone, provision from remote, reset, delete	references/wp-local-site.md
Composer dependency management, Satis private repo, plugin/theme integrity	references/wp-composer.md
General WordPress theme PHP conventions (non-Kaliroots)	references/wp-theme-dev.md
Kaliroots parent/child theme conventions and overrides	references/wp-kaliroots.md
ACF field groups, local JSON, options pages, naming, output	references/wp-acf.md
Theme asset source, Vite/Tailwind build, enqueue integration	references/wp-assets.md
Lovable → WordPress conversion (Lovable React export into Websimple theme)	references/wp-lovable.md
Browser-based smoke checks, navigation, SSRF allowlisting	references/wp-browser.md
Autonomous Xdebug runtime debugging	references/wp-xdebug.md
PHPCS/PHPCBF tooling and coding-standard checks	references/wp-code-style.md

Many tasks touch more than one area. For example, "sync example.com's production database into my local site" needs wp-project.md (to resolve names and paths), websimple-gitea.md (to read WP_SITE_URL and SSH metadata), and wp-local-site.md (the synchronize-from-remote workflow). Read all three before starting.

Gitea API access — use the bundled script

Three read-only Gitea operations are available via scripts/gitea.sh. They replace what used to be OpenClaw plugin tools and require WEBSIMPLE_GITEA_API_TOKEN plus jq and curl.

# List repositories in the wp-sites org (default org is wp-sites)
bash "${SKILL_ROOT}/scripts/gitea.sh" repos-list

# List Actions variables for a repository
bash "${SKILL_ROOT}/scripts/gitea.sh" vars-list wp-sites example

# Get one Actions variable
bash "${SKILL_ROOT}/scripts/gitea.sh" var-get wp-sites example WP_SITE_URL

Each prints a JSON envelope on stdout and exits non-zero with a stderr message on failure. See references/websimple-gitea.md for the full operation set and output shapes.

${SKILL_ROOT} here is the directory containing this SKILL.md. Resolve it from the path of this file when invoking the script.

Safety defaults

These apply across every reference file. They override anything in a reference that conflicts.

• Prefer read-only inspection before changing anything. Before deleting, dropping a database, overwriting files, or running broad updates, show the resolved values (path, DB name, URL) and ask for confirmation.
• Treat remote hosts as read-only. Production/staging WordPress sites should only be read from (database export, file rsync) — never written to, never updated, never have plugins deactivated, never have WP-CLI mutations run against them. The only approved remote action shapes are read-only WP-CLI commands (e.g. wp option get, wp db export -), rsync from remote to local, and SSH connection tests.
• Never echo secrets. Do not print WEBSIMPLE_GITEA_API_TOKEN, admin passwords, or anything from ~/.my.cnf or ~/.wp-cli/config.yml back in chat. When using them, reference them by variable name.
• Preserve source-controlled files. When repairing Composer-managed plugins/themes, never delete directories that are tracked in Git — only ignored/disposable install artifacts. See references/wp-composer.md for the integrity-check pattern.
• Use recoverable deletion where possible. Prefer moving files to the user's trash over rm -rf when shelling out, especially for project directories.

Workflow shape

For a typical request:

1. Identify which reference(s) the task falls under from the table above.
2. Read those reference file(s) — fully, not just headings.
3. Resolve the WordPress project's slug, paths, domain, and DB name using references/wp-project.md conventions and the relevant environment variables.
4. If remote metadata is needed (production URL, SSH host/port/user/path), prefer scripts/gitea.sh var-get against the matching wp-sites/<slug> repository before falling back to SSH inspection.
5. Run small read-only checks before any change.
6. Make the smallest change that accomplishes the request, asking for confirmation before destructive steps.
7. Verify with a small post-change check.

When in doubt about which reference applies, the simple rule: the file's name describes its concern. wp-acf.md is for ACF questions, wp-xdebug.md is for Xdebug-driven debugging, and so on.