pascalmartineau/claude-websimple-devops
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Initial Claude skills for websimple-devops

Browse Source
This commit is contained in:
Pascal Martineau
2026-05-26 10:42:20 -04:00
commit a37c19bb87
16 changed files with 2228 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

249
references/wp-kaliroots.md Normal file
View File

@@ -0,0 +1,249 @@
# WP Kaliroots
Use this skill when a Websimple WordPress site uses the `kaliroots` parent theme or when behavior may come from Kaliroots parent-theme code.
Kaliroots source of truth: `https://gitea.websimple.com/wp-themes/kaliroots`.
Use `references/wp-theme-dev.md` for general theme PHP conventions that do not conflict with Kaliroots. Use `references/wp-browser.md` for frontend checks and `references/wp-xdebug.md` when parent/child template resolution or hooks are unclear.
## Core rule
For Kaliroots child themes, do not apply generic WordPress template organization blindly. Kaliroots has its own wrapper and template lookup system.
Prefer child-theme overrides and additions. Treat parent theme changes as higher-risk because they can affect many sites.
## Confirm Kaliroots usage
Before applying Kaliroots conventions, confirm the active theme relationship:
```bash
wp theme list --status=active
wp theme get $(wp option get stylesheet) --field=template
```
Or inspect the child theme `style.css` for a parent declaration like:
```css
Template: kaliroots
```
Inspect the child theme first, then inspect the parent theme only when inherited behavior or helper functions matter.
## Parent theme structure
Kaliroots parent uses a compact structure:
```text
functions.php
includes/
core/
purgecss.php
theme-setup.php
theme-wrapper.php
helpers/
assets.php
attachment.php
datetime.php
html.php
input.php
mail.php
media.php
menu.php
meta.php
mutex.php
query.php
shortcodes.php
social.php
taxonomy.php
template.php
user.php
utilities.php
wpfs.php
vendors/
acf.php
gutenberg.php
wpbakery.php
templates/
html/
head.php
mail.php
wrap.php
content/
main.php
```
The parent `functions.php` is a loader for `includes/core`, `includes/helpers`, and `includes/vendors`.
Child themes may add their own `includes/`, `templates/`, and asset sources. Preserve existing child-theme conventions unless the user asks for cleanup.
## Template wrapper model
Kaliroots wraps base WordPress templates through the `template_include` filter.
The parent wrapper flow is:
1. `template_include` calls `kaliroots_wrap_base_template()`.
2. The wrapper locates `templates/html/wrap-{base}.php` through `kaliroots_locate_template()`.
3. `{base}` is expanded by `kaliroots_base_placeholders()` using WordPress conditional context.
4. `locate_template()` gives child themes priority over parent templates.
Parent default wrapper:
```php
<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<?= kaliroots_html_template( 'head' ); ?>
<body class="<?= join( ' ', get_body_class() ) ?>">
<div id="app">
<main>
<?= kaliroots_generic_template( '{base}' ) ?>
</main>
</div>
<?php wp_footer(); ?>
</body>
</html>
```
When changing page layout in a Kaliroots child theme, prefer overriding or adding wrapper/content templates in the child theme instead of replacing standard WordPress top-level templates without checking how Kaliroots resolves them.
## Template helper functions
Kaliroots provides template helper functions in `includes/helpers/template.php`.
Common helpers:
```php
kaliroots_generic_template( $template_path, $vars = [], $args = [] );
kaliroots_html_template( $template_name, $vars = [], $args = [] );
kaliroots_site_template( $template_name, $vars = [], $args = [] );
kaliroots_content_template( $template_name, $vars = [], $args = [] );
kaliroots_loop_template( $template_name, $vars = [], $args = [] );
kaliroots_section_template( $template_name, $vars = [], $args = [] );
kaliroots_shortcode_template( $template_name, $vars = [], $args = [] );
kaliroots_widget_template( $template_name, $vars = [], $args = [] );
```
These helpers locate templates through the Kaliroots lookup pipeline, inject `$vars` using `set_query_var()`, buffer template output, and can optionally cache rendered output.
Example:
```php
<?= kaliroots_content_template( 'hero', [ 'post_id' => get_the_ID() ] ); ?>
```
Inside the located template, read injected values with `get_query_var()` when needed:
```php
<?php $post_id = get_query_var( 'post_id' ); ?>
```
## Template naming and lookup
Kaliroots lookup supports placeholders:
- `{base}`: expanded using the current WordPress conditional/template context.
- `{post_type}`: expanded using `get_post_type()` when available.
Examples:
```php
kaliroots_html_template( 'head' );
// looks for templates/html/head-{base}.php, then falls back through base placeholder variants.
kaliroots_content_template( 'main' );
// looks for templates/content/main-{base}.php variants.
kaliroots_loop_template( 'default' );
// looks for templates/content/loops/default-{post_type}.php, then fallback variants.
```
When adding child-theme templates, prefer Kaliroots-compatible paths and names:
```text
templates/html/wrap-front-page.php
templates/html/wrap.php
templates/content/main-front-page.php
templates/content/main-single-project.php
templates/content/loops/default-project.php
```
Inspect the actual child theme before adding a new path; some projects may already have established naming.
## Extending template resolution
Kaliroots exposes filters for template lookup.
Use these only when adding a reusable lookup convention is clearer than adding explicit templates:
```php
add_filter( 'kaliroots_locate_templates', 'example_kaliroots_locate_templates' );
function example_kaliroots_locate_templates( array $templates ): array {
$templates[] = 'templates/content/custom-fallback';
return $templates;
}
```
```php
add_filter( 'kaliroots_base_placeholders', 'example_kaliroots_base_placeholders' );
function example_kaliroots_base_placeholders( array $templates ): array {
if ( is_post_type_archive( 'project' ) ) {
array_unshift( $templates, 'archive-project-featured' );
}
return $templates;
}
```
Keep these filters rare and well-named; they affect template resolution globally.
## Helpers and inherited behavior
Before reimplementing helper logic in a child theme, inspect Kaliroots helpers under `includes/helpers/`.
Useful parent helpers include:
- asset registration with filemtime cache busting;
- template loading and pagination;
- menu/media/meta/query helpers;
- HTML cleaning helpers;
- shortcode and utility helpers.
Do not assume helper behavior from memory. Inspect the parent helper before using or overriding it.
## Parent vs child changes
Default to child-theme changes:
- child template override;
- child `includes/` function/hook;
- child asset/source change;
- child-specific filter/action.
Only edit Kaliroots parent when the user explicitly asks to change shared parent behavior or the bug truly belongs in the parent.
Before parent edits, report blast radius:
- which projects/sites may inherit the change;
- whether a child override is safer;
- how behavior will be verified.
## Refactoring workflow
1. Confirm active child theme and Kaliroots parent.
2. Inspect child theme overrides first.
3. Inspect relevant Kaliroots parent files: usually `includes/core/theme-wrapper.php` and `includes/helpers/template.php`.
4. Choose child override vs parent change deliberately.
5. Keep changes small and reversible.
6. Run PHP lint/style checks via `references/wp-code-style.md` when PHP files changed.
7. Use `references/wp-browser.md` for frontend smoke checks.
8. Use `references/wp-xdebug.md` if template resolution/hook flow is unclear.
9. Inspect the diff before claiming success.
## Safety
- Do not apply generic `references/wp-theme-dev.md` template structure when Kaliroots lookup rules apply.
- Do not edit parent Kaliroots casually; prefer child overrides.
- Do not mass-reorganize child templates without approval.
- Do not touch core, vendor, uploads, caches, or compiled assets.
- Preserve existing project conventions when they are coherent.