105 lines
8.6 KiB
Markdown
105 lines
8.6 KiB
Markdown
---
|
|
name: websimple-devops
|
|
description: 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:
|
|
|
|
```bash
|
|
# 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`.
|
|
|
|
```bash
|
|
# 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.
|