Validate CI status Docs site deploy status Version 1.2.1 Generic and public standards

One repo that teaches Claude Code how to build WordPress and front-end projects, and keeps every machine in sync. Coding standards, SEO rules, writing voice, reference docs, slash commands, a reviewer agent and a drop-in deploy kit. Install once; every merge to main updates every Claude Code session automatically.

GitHub repo · Changelog · Maintained by Matt Hummel, full-stack & WordPress developer, Gettysburg, PA

🎯 Why this exists

Every always-on instruction costs tokens in every session, and standards that live in one project don't follow you to the next. This repo fixes both.

📍 One source of truthHow work gets done — standards, security, SEO, voice — in one place, for every project.
🪶 Loads only what's neededOne 0.9 KB core rule is always on. Everything else loads by file path or when a skill is used.
🔁 Auto-updatesA SessionStart hook pulls main and re-installs on every new Claude Code session.
🔓 Public and genericNo hosts, logins, client names or product data. Project facts stay in each project's CLAUDE.md.

🔁 How it works

Merge to main, and every Claude Code session on every machine picks it up. No manual copying, no stale rules.

Auto-update flow A pull request merges to main on GitHub. On the next Claude Code session, a SessionStart hook runs sync.sh, which git-pulls and copies rules, skills, commands, agents and hooks into the user's ~/.claude folder. Claude Code then loads them. GitHub: main PR merged SessionStart hook runs on every new session → scripts/sync.sh ~/.claude rules/playbook · skills commands/pb · agents · hooks Claude Code git pull --ff-only · copies (not symlinks) · silent when nothing changed
The sync happens at session start, so a change lands in the session after the one that pulled it. Run scripts/sync.sh and restart to apply now.

🪶 What loads when

Every always-on line costs tokens in every session. The playbook keeps one tiny core rule always on and loads everything else only when it's needed.

Loading layers by trigger Six layers from always-on to on-demand: the core rule loads every session; path rules load when a matching file is read or edited; skills load their description always and their body only when used; commands load only when typed; the project CLAUDE.md loads every session in that repo; project rules load by path in that repo. ALWAYS ON ON DEMAND core.md every session · < 1 KB CLAUDE.md every session in that repo path rules when a matching file is read project .claude/rules by path, private facts skills description always, body on use hook after every PHP edit /pb:* commands only when you type them wp-reviewer agent on request or before a PR Rule of thumb: true everywhere and one line → core; about a file type → path rule; a procedure → skill; triggered on purpose → command

RulesSkillsCommandsAgentHookProject / template

📐 Rules

Installed to ~/.claude/rules/playbook/. Only core.md is always on; the rest declare paths: and load when Claude reads or edits a matching file.

core.md

Answer first, then explain. Match length to the ask. Work on a branch; small PRs; conventional commits; a CHANGELOG line for visible changes. Read before editing; follow the project's existing patterns over these defaults. Security: sanitize input, escape output, nonces and capability checks on every form and admin action. Accessibility: WCAG 2.1 AA, one h1, sequential headings, visible focus. Never invent metrics, testimonials or client names. Token discipline: rg before opening big files; read only what you need; summarize logs; don't re-run passing checks. Verify versioned APIs (hooks, Tailwind v4, Next, Node) against official docs: doc-references skill. Ask only for DNS, PHP versions, production database writes, deletions, spending money and secrets.

Loads: every session · 906 bytes (budget 1 KB)

sage/sage.md

Sage (Roots) themes. Sage 10/11 themes: Blade, Acorn, Tailwind, Vite. Follow the official docs, not classic PHP themes or page builders.

Paths: app/**/*.php, resources/views/**/*.blade.php, resources/js/**, resources/css/**, vite.config.js

seo/seo-ai-search.md

Google AI Search Optimization (GEO) Standards. When writing, refactoring, or generating content, web pages, or components, strictly adhere to Google's official guidelines for Generative AI search features.

Paths: **/*.blade.php, **/seo*.php, **/templates/**/*.html, **/*.mdx

wordpress/wordpress.md

WordPress standards (wp-dev-kit). Security (escape, sanitize, nonces, `$wpdb->prepare`) lives in `wp-review.md`. This file covers the rest.

Paths: **/*.php, theme.json, **/block.json

wordpress/wp-review.md

Peer review workflow (wp-dev-kit). The owner works with several AI tools (Cursor, Claude, ChatGPT and others). All agents follow the same rules.

Paths: **/*.php

🧠 Skills

Installed to ~/.claude/skills/<name>/. Claude sees every description at all times and loads the full body only when the task matches.

content-writer

Editorial voice, readability and multi-pass editing for site copy, posts and emails.

Use when writing or editing visitor-facing text, or when asked to edit someone's writing (adds Editor's Notes).

doc-references

Canonical reference docs for Matt's stack (WordPress, Roots, Tailwind, web platform, TypeScript, React/Next/Node/Nest, accessibility, SEO) and the rule for verifying against them.

Use before writing code that touches an API you have not checked this session, when a hook, class, CSS feature or browser-support question comes up, or when asked which source to trust.

geo-blog-post

Draft a blog post for Google AI Overviews and LLM search: BLUF, E-E-A-T proof, FAQ, Article JSON-LD.

Use when writing or outlining a blog post.

growth-design

Growth, CRO, brand design and front-end guardrails as three expert personas (marketer, graphic designer, web designer).

Use for landing pages, conversion copy, visual polish or a design review.

portfolio-seo

Portfolio and service-site SEO: dual audience (shops and developers), skill-first keywords, case-study layout, strict on-page limits.

Use when writing or auditing portfolio, service or project pages.

sage-architecture

Bespoke Sage/Roots architecture: ACF Pro field groups registered in PHP, a Customizer-driven dark-mode default, branch hygiene, security, the theme.json/Tailwind token bridge, and CI/CD for built theme deploys.

Use when adding ACF fields, Customizer settings, new architecture, or touching deploy workflows.

⌨️ Commands

Namespaced as /pb:… so they never shadow a project's own commands. They load only when typed.

/pb:fix <what's wrong or what to change>

Fix a bug or make a small change end to end, then ship it (any project)

/pb:new-project [theme slug] [site url]

Set up a new or existing repo with the playbook project template (CLAUDE.md, settings, ship workflow)

/pb:plan <what you want to build>

Plan an L-size change before coding (any project)

/pb:review [PR number]

Senior WordPress/Sage review of the current branch or a PR (any project)

/pb:ship

Checks, commit, push, PR with auto-merge (any project)

🕵️ Agent & hook

agents/wp-reviewer.md

Senior WordPress/Sage code reviewer. Reviews the diff against the WordPress Developer Handbook and this repo's rules.

Use proactively after writing or changing PHP, Blade, JS, or CSS, and before opening a pull request. · Tools: Read, Grep, Glob, Bash

hooks/phpcs-on-edit.sh

PostToolUse hook: runs PHPCS (errors only) on each PHP file Claude edits and sends problems straight back so Claude fixes them before moving on. Warnings are left to wp-review and CI.

Runs: after every Edit / Write of a .php file

📁 Project template

templates/project/ is a drop-in kit for a theme repo. /pb:new-project copies it in. Project facts go in these files; the generic standards stay in the playbook.

CLAUDE.md

Agent brief under 2 KB: stack, how work ships, commands, project facts and hard no's, what to ask first, a pointer to doc-references.

.claude/settings.json

Permissions: allow safe git/gh/npm/composer/phpcs; ask for wp and PR reviews; deny force-push, pushes to main, DB resets, rm -rf, reading .env. WebFetch allowed on every doc-references domain. PHPCS hook wired in.

.github/workflows/deploy.yml

Build on the runner (npm ci && npm run build, composer install --no-dev), upload one complete theme, swap folders over SSH, health-check homepage/REST/CSS, auto-rollback on failure.

tools/ & .github/scripts/

github-setup.sh, hostinger-secrets.sh, pack-theme.sh, server-deploy.sh, health-check.sh.

🚀 Ship workflow

The daily loop once a project has the template. Full guide: playbook/automated-ship-workflow.md.

Ship workflow Describe the change, run /pb:fix or /pb:ship, a PR opens with auto-merge, CI passes, squash-merge, deploy.yml builds and swaps the theme over SSH, a health check runs, and the deploy rolls back automatically if unhealthy. /pb:fix · /pb:ship PR opensauto-merge on CI green squash-merge deploy.ymlbuild · swap over SSH health check unhealthy → automatic rollback to previous build

🛠 Install

Git Bash (Windows), WSL or macOS. Two minutes, once per machine.

git clone https://github.com/matthummel-pa/ai-dev-standards-playbook.git ~/code/ai-dev-standards-playbook
bash ~/code/ai-dev-standards-playbook/scripts/install.sh

Then in any project:

cd ~/code/my-theme
claude
/pb:new-project my-theme https://example.com

Scripts

ScriptDoes
scripts/install.shCopies the playbook into ~/.claude and adds the SessionStart hook (backup at settings.json.bak-playbook).
scripts/sync.shPulls main and re-copies rules, skills, commands, agents and hooks. Run by the hook; run by hand to apply right away.
scripts/new-project.shCopies the project template into the current repo without overwriting anything.
scripts/build-docs.pyRenders this site from docs/src/template.html plus the frontmatter of every rule, skill, command and agent. Runs in CI on every push to main.
scripts/validate.pyCI check: frontmatter, core-rule size budget, private-detail scan, CHANGELOG discipline.

Change a rule

  1. Branch. Edit. Add a CHANGELOG.md line; bump VERSION if behavior changes.
  2. Open a PR. validate.yml checks frontmatter, size budgets, private details and shell scripts.
  3. Merge. Every machine picks it up on its next session.

Before adding a rule, read rules-architecture.md. Most new guidance belongs in a skill, not an always-on rule.

🆕 What's new

Generated from CHANGELOG.md. Full history on GitHub.

VersionDateHighlights
1.2.12026-10-14README.md: banner (light/dark), status badges, section nav, mermaid diagrams for auto-update, ship workflow and loading layers, collapsible skills/commands/layout tables, version…
1.2.02026-10-14docs/: GitHub Pages site. scripts/build-docs.py renders docs/src/template.html with one card per rule, skill, command and agent read from their frontmatter, so a new SKILL.md appe…
1.1.02026-10-14skills/doc-references/: canonical reference docs for the stack (WordPress, Roots/Bedrock, Tailwind, MDN, WHATWG, W3C/ARIA APG, web.dev, Modern CSS, caniuse, cssdb, JavaScript.info…
1.0.02026-10-11rules/: always-on core.md (< 1 KB) plus path-scoped WordPress, Sage and AI-search rules.