@linchpinagency/skills 0.1.0

package/skills/wp-audit/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: wp-audit
+description: Audit a WordPress site for performance, accessibility, and visible frontend quality, then report prioritized fixes and re-measure after changes. Use when asked to review, optimize, QA, or "check why the site is slow", when Core Web Vitals or Lighthouse scores come up, when a client asks about accessibility or WCAG, or before handing a build back to a client. Measures locally via the Studio MCP; production numbers require the live site. Not for fixing lint or tests — use `quality-gates`.
+version: 1.0.0
+---
+
+# WordPress audit
+
+An audit is only worth what its evidence is worth. The job is to **measure what can be
+measured, inspect what can't, and never blur the line between them** — an agency report that
+implies a tool ran when a model eyeballed a screenshot is worse than no report.
+
+Start with the smallest audit that answers the question actually asked.
+
+## When to use
+
+- "Why is the site slow?", Core Web Vitals, Lighthouse, or page-weight questions.
+- Accessibility questions — contrast, focus states, readability, WCAG.
+- Frontend QA or a polish pass before handing work back to a client.
+- Verifying that a fix actually improved things (before/after).
+
+**Not this skill:** lint, PHPCS, PHPStan, or tests — [`quality-gates`](../quality-gates/SKILL.md).
+Performance *techniques* (caching, asset strategy) — the upstream `wp-performance` skill.
+Operating the local site — [`wp-studio-cli`](../wp-studio-cli/SKILL.md). Operating a live
+server — [`wp-pressable`](../wp-pressable/SKILL.md).
+
+## Owns
+
+Canonical for: audit scope selection, the measurement loop, the thresholds below, evidence
+honesty, and the before/after comparison. Defers the fixes themselves to the skill that owns
+the code being changed.
+
+## Preflight — what are you actually measuring?
+
+| Target | How | Caveat |
+| --- | --- | --- |
+| Local Studio site | [`wp-studio-cli`](../wp-studio-cli/SKILL.md) → `need_for_speed`, `take_screenshot`, `inspect_design` | **Synthetic.** PHP-WASM + SQLite, no CDN, no production cache — good for diagnosis and before/after, not a production claim |
+| Production / staging | Real-browser tooling against the live URL; server state via [`wp-pressable`](../wp-pressable/SKILL.md) read-only commands | The only numbers you can quote to a client as real |
+| Legacy local (wp-env / LocalWP) | Browser tooling against the local URL | Studio MCP tools won't apply |
+
+Resolve two things before measuring: **which environment**, and **which URL path** (default
+`/` if unspecified). State both in the report — an audit without them isn't reproducible.
+
+## Procedure
+
+1. **Pick the scope** — performance, accessibility, visual QA, or a named combination. Say
+   which you chose when the request was ambiguous. → The user knows what's being measured.
+2. **Measure** with the tools the environment offers. Take a screenshot for anything visual
+   so findings are anchored to evidence. → Raw numbers and images captured, not recalled.
+3. **Interpret against the thresholds** below rather than by feel. → Every finding is
+   Good / Needs improvement / Poor, with the measured value shown.
+4. **Diagnose in WordPress terms.** A number is not a finding; "LCP 4.1s because the hero
+   image is an unresized 2.4 MB PNG" is. Inspect the theme, plugins, and block markup to get
+   from symptom to cause. → Each finding names a probable cause and where it lives.
+5. **Prioritize ruthlessly.** A short list ordered by impact-per-effort beats an exhaustive
+   one. → Top findings first; the long tail summarized, not enumerated.
+6. **Re-measure after fixes**, same environment and path, and report what moved, what didn't,
+   and any tradeoff taken. → Before/after pairs for every metric you claimed to improve.
+
+## Thresholds
+
+Google's Core Web Vitals bands — these are the public standard, not house opinion:
+
+| Metric | Good | Needs improvement | Poor |
+| --- | --- | --- | --- |
+| TTFB | < 800 ms | 800–1800 ms | > 1800 ms |
+| FCP | < 1800 ms | 1800–3000 ms | > 3000 ms |
+| LCP | < 2500 ms | 2500–4000 ms | > 4000 ms |
+| CLS | < 0.1 | 0.1–0.25 | > 0.25 |
+
+Page-composition warning signs: DOM > 1500 elements · page weight > 3 MB · > 80 requests ·
+scripts > 20 files or 500 KB · stylesheets > 10 files or 200 KB.
+
+Common WordPress causes worth checking before anything exotic: oversized or unresized
+images, heavy or duplicated plugins, render-blocking and duplicated font loads, unused theme
+CSS shipped in full, and wrapper-heavy block layouts inflating the DOM.
+
+## Accessibility — say what you actually did
+
+Without a dedicated scanner, this pass is **visual review plus code inspection**, and the
+report must say so. Never describe it as a WCAG audit, never assign a conformance level, and
+never imply a client is compliant on this basis. When a real conformance claim is needed,
+say that a dedicated accessibility audit is required — that's a different engagement.
+
+What this pass reliably catches: low text/background contrast, weak or ambiguous CTA states,
+missing or invisible focus states, animation with no `prefers-reduced-motion` fallback,
+readability problems from font size / line height / density, and meaning carried by color
+alone. Use `inspect_design` for computed styles when it beats reading the CSS.
+
+## Guardrails
+
+- **Never present synthetic local numbers as production performance.** Label the environment
+  on every number you report.
+- **Never claim a check ran that didn't.** If a conclusion came from looking at a screenshot
+  or reading code, say so in the finding.
+- **Never assert WCAG conformance** from this pass — see above.
+- **Never change code during an audit** unless the user asked for fixes too; an audit that
+  quietly edits things can't be trusted as a baseline.
+- **Never run mutating commands against production** to gather evidence — read-only
+  diagnostics via [`wp-pressable`](../wp-pressable/SKILL.md), and confirm before anything else.
+- **Don't over-optimize one dimension silently.** When performance, accessibility, and design
+  conflict, surface the tradeoff and let the user choose.
+- Don't pad the report. Ten low-impact nitpicks buried around two real problems is a worse
+  deliverable than the two real problems.
+
+## Done
+
+- [ ] Environment and URL path stated, and the environment's limits noted.
+- [ ] Scope stated, and it matches what was asked.
+- [ ] Every metric reported with its measured value and threshold band.
+- [ ] Every finding has a probable cause and a location, not just a symptom.
+- [ ] Evidence source labeled per finding — measured, inspected, or observed visually.
+- [ ] No WCAG conformance claim; accessibility limits stated plainly.
+- [ ] Findings ordered by impact; the top fixes are actionable as written.
+- [ ] If fixes were made, before/after numbers from the same environment and path.

package/skills/wp-block-conventions/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: wp-block-conventions
+description: Build and edit custom Gutenberg blocks the way Linchpin structures them — apiVersion 3 under the `linchpin/` namespace, dynamic `render.php` plus Interactivity API `view.js`, parent/child blocks wired through block context, and the shared wp-scripts build with `--blocks-manifest --webpack-copy-php --experimental-modules`. Use when creating a custom block, editing an existing one, deciding whether a block belongs in the shared linchpin-blocks plugin or a project's functionality plugin, or reviewing block code. Not for authoring page content from blocks — use `wordpress-blocks`.
+version: 1.0.0
+---
+
+# Linchpin block conventions
+
+Linchpin blocks are **dynamic, Interactivity-API blocks** built with `wp-scripts` inside a
+nested `blocks/` workspace. The structure is consistent across the shared block library and
+project functionality plugins, so a block written to these conventions can move between them.
+
+This skill is the house layer. Generic "how blocks work" is the upstream
+`wp-block-development` skill — don't restate it here; read it for the underlying APIs.
+
+## When to use
+
+- Creating a new custom block, or extending an existing one.
+- Deciding where a block belongs — shared library vs one project.
+- Reviewing block code for house consistency.
+- A block builds but doesn't register, or the editor shows it as invalid.
+
+**Not this skill:** composing page/post content out of existing blocks —
+[`wordpress-blocks`](../wordpress-blocks/SKILL.md). Choosing whether the request even needs
+a block — [`wp-implementation-choice`](../wp-implementation-choice/SKILL.md). Block theme
+templates and `theme.json` — upstream `wp-block-themes`.
+
+## Owns
+
+Canonical for: where blocks live, the file layout, house `block.json` fields, the
+dynamic-render + Interactivity pattern, parent/child context, and the build/registration
+chain. Defers block *semantics* to upstream and content authoring to `wordpress-blocks`.
+
+## Preflight — which home does this block belong in?
+
+| Question | Home |
+| --- | --- |
+| Reusable across clients (accordion, tabs, cards, slider, counter)? | **`linchpin/linchpin-blocks`** — the shared plugin, `blocks/src/<slug>/` |
+| Specific to one site's content model or design (a client grid, a bespoke hero)? | That project's functionality plugin — `plugins/<project>-functionality/blocks/src/<slug>/` |
+| Could core or an installed plugin already do it? | Neither — see [`wp-implementation-choice`](../wp-implementation-choice/SKILL.md) |
+
+Putting a client-specific block in the shared library is the mistake that costs later: every
+other project inherits it, and it can't be changed without regression-testing all of them.
+
+Then confirm the workspace: blocks build from a **nested `blocks/package.json`**, not the
+repo root. Lint and build there.
+
+## The shape of a block
+
+```
+blocks/src/<slug>/
+├── block.json      # metadata — the source of truth for registration
+├── index.js        # registerBlockType, wires edit/save/icon/transforms
+├── edit.js         # editor component
+├── save.js         # usually InnerBlocks.Content only (dynamic blocks render in PHP)
+├── render.php      # server render — copied to build/ by --webpack-copy-php
+├── view.js         # frontend behavior via @wordpress/interactivity (script module)
+├── style.scss      # front + editor styles
+├── edit.scss       # editor-only styles
+├── icon.js         # block icon
+├── controls.js     # inspector/toolbar controls (or controls/ when it grows)
+├── store.js        # editor-side data store, when the block needs one
+└── transforms.js   # block transforms, when offered
+```
+
+Only `block.json`, `index.js`, and `edit.js` are always present. Add the rest when the block
+actually needs them — see [`references/block-anatomy.md`](references/block-anatomy.md) for
+the field-by-field detail, the parent/child context pattern, and `render.php` conventions.
+
+## House rules
+
+- **`apiVersion: 3`** and the `linchpin/` namespace on every block.
+- **Dynamic by default.** Real markup lives in `render.php`; `save.js` typically returns just
+  `<InnerBlocks.Content />`. This avoids the block-validation invalidation that static markup
+  causes whenever output changes.
+- **Frontend behavior is the Interactivity API** — `viewScriptModule: file:./view.js`,
+  `store('linchpin/<block>', { state, actions, callbacks })`, and `data-wp-*` directives
+  emitted from `get_block_wrapper_attributes()`. Not jQuery, not a bespoke bundle.
+- **Parent → child data flows through block context**, namespaced
+  `linchpin/<parent>/<key>` via `providesContext` / `usesContext`. Families
+  (accordion + accordion-pane, tabs + tabs-pane, cards + card) are built this way.
+- **Ship an `example`** with representative `innerBlocks` so the inserter preview isn't blank.
+- **Lean on `supports`** (color, spacing, typography, layout, `anchor`) before inventing
+  custom attributes — you get the core UI and theme.json integration for free.
+- **PHP logic belongs in a Model/Helper class**, not inline in `render.php`. Keep render
+  files to composing wrapper attributes and echoing markup.
+
+## Build and registration
+
+From the `blocks/` workspace:
+
+```bash
+npm run build     # wp-scripts build --blocks-manifest --webpack-copy-php --experimental-modules …
+npm run start     # same, watching
+```
+
+Each flag matters: `--blocks-manifest` emits `build/blocks-manifest.php`,
+`--webpack-copy-php` copies `render.php` into `build/`, and `--experimental-modules` is what
+makes `viewScriptModule` work. Dropping one silently breaks registration or frontend behavior.
+
+Registration reads the built output, not `src/`: WordPress 6.8+ on a block theme registers
+the whole set at once with `wp_register_block_types_from_metadata_collection( build,
+build/blocks-manifest.php )`, with a per-block `register_block_type()` loop as the fallback.
+**A block that doesn't appear in the editor is usually unbuilt, not misregistered** — build
+first, then debug.
+
+## Guardrails
+
+- **Never edit anything in `build/`** — it's generated, and the next build discards it.
+- **Never put a client-specific block in the shared library** (see Preflight).
+- **Never use `core/html`** for layout or normal text; emit proper block markup.
+- **Never change a dynamic block's `save.js` output casually** — changing saved markup
+  invalidates every existing instance in the database. Prefer `render.php` changes, and when
+  saved output must change, provide a deprecation.
+- **Never hand-bump a `version` field** without checking `release-please-config.json`
+  `extra-files` — release-please may own it ([`commit-and-release`](../commit-and-release/SKILL.md)).
+- **Never add a dependency to the root `package.json`** for block code; blocks have their own
+  workspace manifest.
+- Don't skip `--webpack-copy-php` or `--experimental-modules` in a one-off build to "go
+  faster" — you'll debug a phantom registration bug instead.
+
+## Done
+
+- [ ] The block's home (shared library vs project plugin) is a deliberate choice.
+- [ ] `block.json` is apiVersion 3, `linchpin/`-namespaced, with `textdomain`, an `example`,
+      and `supports` doing the work custom attributes would otherwise duplicate.
+- [ ] Dynamic render in `render.php`; `save.js` doesn't hand-roll markup that PHP owns.
+- [ ] Frontend behavior uses the Interactivity API with a namespaced store.
+- [ ] Parent/child data passes through namespaced block context, not props or globals.
+- [ ] Built from the `blocks/` workspace with all three flags; block appears in the inserter.
+- [ ] Markup validates in the editor — no "unexpected or invalid content"
+      ([`wp-studio-cli`](../wp-studio-cli/SKILL.md) `validate_blocks`).
+- [ ] `npm run lint:js` and `npm run lint:css` pass in that workspace
+      ([`quality-gates`](../quality-gates/SKILL.md)).

package/skills/wp-block-conventions/references/block-anatomy.md

@@ -0,0 +1,175 @@
+# Block anatomy
+
+Field-level detail for a Linchpin block. The house patterns are in `SKILL.md`; this is the
+lookup you open while writing the files.
+
+## `block.json`
+
+```jsonc
+{
+  "$schema": "https://schemas.wp.org/trunk/block.json",
+  "apiVersion": 3,
+  "name": "linchpin/accordion",
+  "version": "1.5.7",
+  "title": "Accordion",
+  "category": "design",
+  "keywords": ["linchpin", "accordion", "collapse", "expand"],
+  "description": "Controls a group of accordion blocks.",
+  "textdomain": "linchpin-blocks",
+
+  "attributes": { /* only what `supports` can't express */ },
+  "supports":   { /* prefer these over custom attributes */ },
+  "providesContext": { "linchpin/accordion/autoClose": "autoClose" },
+  "styles":     [ { "name": "grouped", "label": "Grouped", "isDefault": true } ],
+  "example":    { "attributes": {}, "innerBlocks": [ /* … */ ], "viewportWidth": 640 },
+
+  "editorScript":     "file:./index.js",
+  "editorStyle":      "file:./index.css",
+  "style":            "file:./style-index.css",
+  "render":           "file:./render.php",
+  "viewScriptModule": "file:./view.js"
+}
+```
+
+Notes:
+
+- **`category`** — use an existing core category (`design`, `media`, `text`, `widgets`)
+  unless the project registers its own.
+- **`keywords`** are the inserter's search surface. Include `linchpin` plus the words an
+  editor would actually type, including synonyms the title doesn't contain.
+- **`styles`** give editors variations without new blocks. One `isDefault: true`.
+- **`viewScriptModule`** (not `viewScript`) is what pairs with `--experimental-modules` and
+  the Interactivity API. Using `viewScript` loads a classic script instead and the
+  `data-wp-*` directives will do nothing.
+- **`example`** without `innerBlocks` renders an empty inserter preview for container blocks.
+
+## `supports` before attributes
+
+Reach for these first — they wire into theme.json, give editors the standard UI, and keep
+styling in the design system:
+
+| Need | `supports` key |
+| --- | --- |
+| Text/background/link color | `color` (`{ "text": …, "background": …, "link": … }`) |
+| Padding, margin, gap | `spacing` (scope with `sides` / `blockGap`) |
+| Font size and family | `typography` |
+| Borders | `__experimentalBorder` |
+| HTML anchor | `anchor` |
+| Inner layout (flex/grid, orientation) | `layout` — set `allowEditing: false` to lock it |
+| Interactivity API directives | `interactivity: true` |
+| Suppress the "Edit as HTML" escape hatch | `html: false` |
+
+A custom attribute is the right answer only when it carries data (a term ID, an interval, a
+mode enum), not presentation.
+
+## Parent / child families
+
+Container and item blocks are separate blocks joined by **block context**, namespaced by the
+parent:
+
+```jsonc
+// parent — accordion/block.json
+"providesContext": {
+  "linchpin/accordion/autoClose":  "autoClose",
+  "linchpin/accordion/activeUUID": "activeUUID"
+}
+
+// child — accordion-pane/block.json
+"usesContext": [ "linchpin/accordion/autoClose", "linchpin/accordion/activeUUID" ]
+```
+
+Rules:
+
+- Namespace every context key `linchpin/<parent>/<key>` — bare keys collide across plugins.
+- Constrain the family with `parent` (child only insertable inside its container) or
+  `allowedBlocks` on the parent, so editors can't build invalid trees.
+- Context flows **down only**. A child that needs to change parent state does it through the
+  Interactivity store, not by mutating context.
+
+## `render.php`
+
+```php
+<?php
+/**
+ * Server-side rendering of the `linchpin/accordion` block.
+ *
+ * @package linchpin-blocks
+ *
+ * @var array     $attributes Array of Block Attributes
+ * @var string    $content    Block Content
+ * @var \WP_Block $block      WP_Block object.
+ */
+
+namespace Linchpin_Blocks\Blocks;
+
+use Linchpin_Blocks\Model\Blocks\Accordion;
+use function \Linchpin_Blocks\Helper\Block_Utils\classNames;
+
+$block_wrapper_attrs = get_block_wrapper_attributes( [
+    'data-wp-interactive' => wp_json_encode( [ 'namespace' => 'linchpin/accordion' ] ),
+    'data-wp-context'     => wp_json_encode( $model->get_initial_context( $block, $attributes ) ),
+    'data-wp-init'        => 'callbacks.onAccordionInit',
+    'class'               => classNames( [ 'has-block-gap' => /* … */ ] ),
+] );
+```
+
+- Always emit the wrapper through **`get_block_wrapper_attributes()`** — it carries the
+  `supports`-generated classes and inline styles. Hand-writing the wrapper drops them.
+- `$attributes`, `$content`, `$block` are provided; document them in the docblock.
+- **Escape on output** (`esc_html`, `esc_attr`, `wp_kses_post`) and pass structured data
+  through `wp_json_encode` for directives.
+- Non-trivial logic goes in a `Model\Blocks\<Block>` class; helpers like `classNames()` and
+  block-gap resolution live in `Helper\Block_Utils`.
+
+## `view.js` — Interactivity API
+
+```js
+import { store, getContext, getElement } from '@wordpress/interactivity';
+
+const { state } = store( 'linchpin/accordion', {
+    state: {
+        get isOpen() {
+            const { isOpen, uuid } = getContext();
+            return isOpen.includes( uuid );
+        },
+    },
+    actions: { toggle: () => { /* mutate context */ } },
+    callbacks: { onAccordionInit: () => { /* run on init */ } },
+} );
+```
+
+- The store namespace **must match** `data-wp-interactive`'s namespace in `render.php`.
+- Derived values are getters on `state`; user interactions are `actions`; lifecycle hooks are
+  `callbacks` referenced by `data-wp-init` / `data-wp-watch`.
+- Mutate `context`, not the DOM. Directives (`data-wp-bind--*`, `data-wp-class--*`,
+  `data-wp-on--*`) re-render from state.
+- Keep `view.js` plain module JavaScript — no JSX, no editor packages.
+
+## Full-width section layout
+
+When a block renders a full-bleed section, the alignment is Gutenberg's job, not CSS's:
+
+- Outer section: `core/group` with `{"align":"full","layout":{"type":"default"}}`.
+- Immediate inner shell: `core/group` with `align:"wide"` — readable text and grids live
+  here, not on the full-width outer block.
+- No intermediate constrained groups between the full-width section and the content shell
+  unless the design deliberately wants a narrow measure.
+- Keep `theme.json` `contentSize` / `wideSize` aligned with the design.
+
+**Debug order when a section still looks boxed:** wrapper alignment → serialized block
+markup → template layout → `theme.json`. Custom breakout CSS is the last resort, and usually
+a sign one of the four is wrong.
+
+## Theme-side gotcha that bites block work
+
+Block themes do **not** automatically load `style.css` on the front end. It must be enqueued
+explicitly:
+
+```php
+add_action( 'wp_enqueue_scripts', function () {
+    wp_enqueue_style( '<slug>-style', get_stylesheet_uri() );
+} );
+```
+
+Missing this makes block styles look broken in a way that resembles a build problem. Enqueue
+editor styles too, so the editor resembles the front end.

package/skills/wp-implementation-choice/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: wp-implementation-choice
+description: Decide which WordPress abstraction a request should become — theme/template work, a custom block, a functionality plugin, existing core blocks and patterns, or an off-the-shelf plugin — before any code is written. Use when a WordPress request could be built more than one way, when someone proposes a custom plugin or block, when scoping a new feature, or when reviewing an approach that feels heavier than the problem. Not for how to build the thing once chosen.
+version: 1.0.0
+---
+
+# Choosing the WordPress implementation
+
+Most expensive WordPress mistakes are made before the first line of code: a plugin written
+for something a theme template handles, a custom block that duplicates a core block, a
+bespoke build of what WooCommerce already ships. **Pick the smallest abstraction that
+cleanly solves the request** — smaller means less to maintain, less to upgrade, and less to
+hand to the next developer.
+
+## When to use
+
+- A request could reasonably be a theme change, a block, or a plugin.
+- Someone proposes building something custom and you're not sure it's warranted.
+- Scoping new work, or reviewing an approach that feels heavy for the problem.
+
+**Not this skill:** how to build each thing once chosen — see the routing table below.
+
+## Owns
+
+Canonical for: the choice itself and the reasons behind it. Every "how" belongs to the skill
+this routes to.
+
+## Preflight — what already exists?
+
+Answer these before designing anything custom; each "yes" removes work:
+
+1. **Does a core block or pattern do it?** Check the site's registered patterns and template
+   parts first — [`wordpress-blocks`](../wordpress-blocks/SKILL.md) covers reuse-before-build.
+2. **Does the shared block library already have it?** `linchpin/linchpin-blocks` ships
+   accordion, tabs, cards, slider, counter, and more.
+3. **Does a well-known plugin own this problem?** Ecommerce is WooCommerce; forms, SEO, and
+   membership all have mature answers. Building a lesser version is a liability you maintain
+   forever.
+4. **Does the project's functionality plugin already have a hook or module for it?**
+
+## The routing table
+
+| The deliverable is really… | Build it as | Then use |
+| --- | --- | --- |
+| Layout, templates, styling, a visual redesign | **Theme work** (`theme.json`, templates, parts) | Upstream `wp-block-themes` |
+| Page/post content composed from existing blocks | **Content**, not code | [`wordpress-blocks`](../wordpress-blocks/SKILL.md) |
+| An editor-insertable content component that core can't express | **Custom block** | [`wp-block-conventions`](../wp-block-conventions/SKILL.md) |
+| Reusable behavior that must survive a theme change — admin UI, settings, REST endpoints, cron, integrations, post types | **Functionality plugin** | Upstream `wp-plugin-development` |
+| Data exposed to a frontend or third party | **REST endpoint** in the plugin | Upstream `wp-rest-api` |
+| Performance, accessibility, or QA review of what's there | **An audit**, not a build | [`wp-audit`](../wp-audit/SKILL.md) |
+
+## Decision rules
+
+- **Presentation is never a plugin.** If the deliverable is how something looks, it belongs
+  in the theme or a block, not in PHP that outputs markup.
+- **Reusable backend behavior is never a theme.** Anything that must survive a redesign —
+  post types, endpoints, scheduled jobs, integrations — goes in the functionality plugin.
+  Business logic in `functions.php` dies with the next theme.
+- **A block is for content editors.** If nobody will ever insert it in the editor, it isn't a
+  block; it's a template part or plugin code.
+- **Shared vs project** matters as much as which abstraction: a block or module useful to
+  every client belongs in the shared library, a client-specific one in that project. See
+  [`wp-block-conventions`](../wp-block-conventions/SKILL.md).
+- **Configuration beats code.** A core block with the right `supports` and theme.json tokens
+  beats a custom block that hardcodes the same result.
+- **When two options both fit cleanly, take the smaller one** — and say why in the PR, so the
+  choice is reviewable rather than assumed.
+
+## Guardrails
+
+- **Never build what a well-established plugin already does** without an explicit reason the
+  user has accepted (licensing, a hard requirement it can't meet, unacceptable bloat).
+- **Never introduce a custom block that duplicates a core block** with different styling —
+  that's a block style variation or theme.json work.
+- **Never put business logic in a theme** because it's the file you happen to be editing.
+- **Never scope a plugin's boundaries around "everything this client asked for"** — a
+  functionality plugin is for behavior, not a junk drawer.
+- If the right answer is "this shouldn't be built," say so before designing it.
+
+## Done
+
+- [ ] Existing core blocks, patterns, shared library blocks, and off-the-shelf plugins were
+      checked before designing anything custom.
+- [ ] The chosen abstraction is the smallest that cleanly solves the request.
+- [ ] Presentation and behavior are on the correct sides of the theme/plugin line.
+- [ ] Shared vs project-specific placement decided deliberately.
+- [ ] The reasoning is written down where a reviewer will see it.
+- [ ] Execution handed to the skill that owns the "how".