feat: Initial Claude skills for websimple-devops

2026-05-26 10:42:20 -04:00
commit a37c19bb87
16 changed files with 2228 additions and 0 deletions
--- a/references/wp-xdebug.md
+++ b/references/wp-xdebug.md
@@ -0,0 +1,140 @@
+# WP Xdebug
+
+Use this skill when the agent should debug local Websimple WordPress PHP execution autonomously. Prefer `references/wp-project.md` first when you need to resolve the site slug, local URL, or project path. Use `references/wp-browser.md` only when browser interaction is needed to understand or reproduce the behavior.
+
+The expected path is autonomous debugging with `koriym/xdebug-mcp`; do not require the user to have VS Code open or listening for Xdebug connections.
+
+## Scope and safety
+
+- Use Xdebug only for local Websimple development sites unless the user explicitly confirms otherwise.
+- Do not install tools, enable/reconfigure Xdebug, restart services, or modify project files unless requested.
+- Avoid sending public/production form submissions or external-effect requests while debugging.
+- Prefer deterministic local reproductions: PHP script, WP-CLI command, PHPUnit command, safe curl/API request, or a minimal reproducer.
+- If autonomous runtime debugging cannot be performed because `xdebug-mcp` or Xdebug is missing, report that as a blocker and suggest the smallest next setup step.
+
+## Required autonomous debugger
+
+Use `koriym/xdebug-mcp` to provide Xdebug-backed tools with structured JSON output for AI analysis:
+
+- `xtrace`: trace execution flow.
+- `xstep`: stop at breakpoints and inspect variables.
+- `xprofile`: collect performance profiling data.
+- `xcoverage`: collect coverage data.
+- `xback`: capture call stack/backtrace at a breakpoint.
+- `xcompare`: compare variable states across runs; CLI-only.
+
+Check availability before relying on it:
+
+```bash
+command -v xtrace xstep xprofile xcoverage xback
+```
+
+If Composer global binaries are not on `PATH`, locate them with:
+
+```bash
+composer global config bin-dir --absolute --quiet
+```
+
+Installation, only when explicitly requested:
+
+```bash
+composer global require koriym/xdebug-mcp
+```
+
+## Preconditions
+
+Before triggering a debug run, confirm or infer:
+
+- The target is local code/site, normally `${WEBSIMPLE_STACK_PROTOCOL}://${slug}.${WEBSIMPLE_STACK_DOMAIN}` and `${WP_LOCAL_ROOT_PATH}/${slug}`.
+- Xdebug 3.x is installed for the PHP runtime used by the debug command.
+- `xdebug-mcp` CLI tools are available, or MCP exposes the equivalent tools.
+- The reproduction command actually executes the PHP code being investigated.
+
+For Websimple WordPress, remember that the served document root inside the PHP container is normally `/var/www/html`; map that mentally to the local WordPress project root when interpreting file paths.
+
+## Autonomous workflow
+
+1. Resolve the project slug, local URL, and local path with `references/wp-project.md` conventions.
+2. Identify the code path and the safest reproduction strategy:
+   - WP-CLI command when WordPress bootstrap/state is needed.
+   - PHP script or small throwaway reproducer for isolated functions/classes.
+   - PHPUnit or project test command when a test exists.
+   - curl/API request only when it safely and actually triggers the PHP code under debug.
+   - Browser only to discover state, cookies, nonces, or the user flow; then reduce to a deterministic command when possible.
+3. Pick the xdebug-mcp tool:
+   - Need execution path? Use `xtrace`.
+   - Need variable state at a line? Use `xstep --break='file.php:line'`.
+   - Need caller chain? Use `xback --break='file.php:line'`.
+   - Need slowness data? Use `xprofile --json`.
+   - Need coverage? Use `xcoverage`.
+4. Run the smallest safe command that captures runtime data.
+5. Analyze the JSON output and inspect source files as needed.
+6. Iterate with narrower breakpoints/traces until the cause is clear.
+7. Report evidence: command shape, breakpoint/trace target, observed runtime data, conclusion, and any blockers.
+
+## Example commands
+
+Script or isolated command:
+
+```bash
+xtrace -- php path/to/script.php
+xstep --break='path/to/file.php:42' -- php path/to/script.php
+xback --break='path/to/file.php:42' -- php path/to/script.php
+xprofile --json -- php path/to/script.php
+```
+
+WP-CLI reproduction from the local WordPress root. When using the `/usr/local/bin/wp` PHAR, invoke it explicitly through PHP so `xdebug-mcp` can determine the target script:
+
+```bash
+cd "${WP_LOCAL_ROOT_PATH}/${slug}"
+xtrace -- php /usr/local/bin/wp --path="${WP_LOCAL_ROOT_PATH}/${slug}" eval '/* minimal safe reproduction */'
+xstep --break='wp-content/themes/theme/file.php:42' -- php /usr/local/bin/wp --path="${WP_LOCAL_ROOT_PATH}/${slug}" eval '/* minimal safe reproduction */'
+xback --break='wp-content/themes/theme/file.php:42' -- php /usr/local/bin/wp --path="${WP_LOCAL_ROOT_PATH}/${slug}" eval '/* minimal safe reproduction */'
+```
+
+Test reproduction:
+
+```bash
+xtrace -- vendor/bin/phpunit --filter 'RelevantTest'
+xcoverage -- vendor/bin/phpunit --filter 'RelevantTest'
+```
+
+Containerized reproduction, if the PHP code must run inside the Websimple stack, should use the actual service names after inspection. Standard PHP is `wp-php`; browser-triggered Xdebug requests are routed to `wp-php-xdebug` when the `XDEBUG_SESSION=vscode` cookie is present.
+
+```bash
+xtrace -- docker compose exec -T wp-php php /var/www/html/${slug}/path/to/script.php
+xstep --break='/var/www/html/${slug}/wp-content/themes/theme/file.php:42' -- docker compose exec -T wp-php php /var/www/html/${slug}/path/to/script.php
+```
+
+Only use command forms that match the actual Websimple stack project layout after inspecting the project/stack.
+
+## Browser and HTTP flows
+
+For browser-only bugs:
+
+- Use `references/wp-browser.md` to reproduce the UI and inspect the request details.
+- Avoid relying on a human IDE listener.
+- Prefer converting the observed request into a safe deterministic command: WP-CLI, script, test, or curl with required cookies/nonces.
+- Be careful: wrapping `curl` with `xtrace` only debugs PHP if the Xdebug capture is attached to the PHP runtime handling the request. If the PHP executes in Apache/FPM separately, use a supported xdebug-mcp/container strategy or reduce the behavior to WP-CLI/script instead.
+
+Do not use Xdebug triggers on production/remote URLs.
+
+## Common WordPress targets
+
+- Frontend template load: theme template, `template_redirect`, query hooks, block rendering.
+- wp-admin page: menu page callbacks, list tables, metaboxes, save handlers.
+- REST API: route callback and permission callback.
+- admin-ajax: `wp_ajax_*` / `wp_ajax_nopriv_*` handlers.
+- Forms: validation/submission hooks, but do not submit externally-effectful forms unless explicitly requested.
+- Cron-like handlers: only trigger explicitly requested local code paths; do not run destructive jobs by accident.
+
+## Troubleshooting
+
+If no runtime data appears:
+
+- Confirm `xtrace`/`xstep`/`xback` is installed and on `PATH`.
+- Confirm the command after `--` actually runs PHP and reaches the code path.
+- Confirm Xdebug 3.x is installed for that PHP binary/container.
+- Confirm paths in breakpoints match the runtime paths shown in traces, often `/var/www/html/...` inside containers.
+- Confirm the request/command is local, not production.
+- If browser navigation is blocked by policy, use `references/wp-browser.md`’s browser SSRF prerequisite for `${WEBSIMPLE_STACK_DOMAIN}` local sites.