Files

Pascal Martineau a37c19bb87 feat: Initial Claude skills for websimple-devops

2026-05-26 10:42:20 -04:00

7.7 KiB

Raw Permalink Blame History

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:

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:

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:

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:

template_include calls kaliroots_wrap_base_template().
The wrapper locates templates/html/wrap-{base}.php through kaliroots_locate_template().
{base} is expanded by kaliroots_base_placeholders() using WordPress conditional context.
locate_template() gives child themes priority over parent templates.

Parent default wrapper:

<!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:

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:

<?= kaliroots_content_template( 'hero', [ 'post_id' => get_the_ID() ] ); ?>

Inside the located template, read injected values with get_query_var() when needed:

<?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:

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:

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:

add_filter( 'kaliroots_locate_templates', 'example_kaliroots_locate_templates' );
function example_kaliroots_locate_templates( array $templates ): array {
    $templates[] = 'templates/content/custom-fallback';

    return $templates;
}

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

Confirm active child theme and Kaliroots parent.
Inspect child theme overrides first.
Inspect relevant Kaliroots parent files: usually includes/core/theme-wrapper.php and includes/helpers/template.php.
Choose child override vs parent change deliberately.
Keep changes small and reversible.
Run PHP lint/style checks via references/wp-code-style.md when PHP files changed.
Use references/wp-browser.md for frontend smoke checks.
Use references/wp-xdebug.md if template resolution/hook flow is unclear.
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.

7.7 KiB Raw Permalink Blame History