@linchpinagency/skills 0.1.0

package/skills/task-tracking/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: task-tracking
+description: Associate every unit of work with a task in Linchpin's task platform (currently ClickUp, via the ClickUp MCP) with the least possible friction, update that task when the work lands, and leave a handoff on it when stopping mid-flight. Use whenever starting work, creating a TODO, preparing to commit, finishing a change, or pausing work someone else may pick up. Resolve a ClickUp task from what the user gave you (ID/custom-ID/URL) or by searching; if none exists, confirm NO-TASK and keep working. The conventional-commit scope carries the task key (e.g. LINCHPIN-5113) or NO-TASK.
+version: 1.2.0
+---
+
+# Task tracking (ClickUp)
+
+**Goal: get work into the task system with the least friction, while never blocking the
+user from working.** Every unit of work is either tied to a ClickUp task (its commits carry
+the task key) or explicitly marked **NO-TASK**. The user always chooses; you make the
+right thing the easy thing.
+
+The platform is currently **ClickUp**, driven through the **ClickUp MCP**. Keep ClickUp
+specifics in the tool calls; the workflow below is what matters and would survive a
+platform change.
+
+## When to use
+
+- Starting any unit of work, before cutting a branch.
+- Opening a local TODO that should exist in the task system too.
+- Preparing to commit and needing the scope key.
+- Finishing work — the task needs its status and a pointer to the PR.
+
+**Not this skill:** the commit message grammar and release rules —
+[`commit-and-release`](../commit-and-release/SKILL.md). Running checks before you commit —
+[`quality-gates`](../quality-gates/SKILL.md).
+
+## Owns
+
+Canonical for: resolving, creating, and updating the task; the **scope key** that goes in
+commits; branch naming; and the PR ↔ task link. Everything about the commit message *other
+than the scope* belongs to [`commit-and-release`](../commit-and-release/SKILL.md).
+
+## Vocabulary
+
+- **Task key / issue key** — ClickUp's *custom ID*, e.g. `LINCHPIN-5113`. Space-scoped, so
+  prefixes differ per space (`LINCHPIN-…`, etc.). This is what goes in commits. It is **not**
+  the internal id (`86badg2te`) — though `clickup_get_task` accepts either.
+- **NO-TASK** — the sentinel used in the commit scope when work has no associated task.
+
+## Workflow
+
+### 1. Resolve the task (at the start of a unit of work)
+
+Try these in order; stop at the first that succeeds:
+
+1. **User gave a reference** (a custom ID like `LINCHPIN-5113`, an internal id, or an
+   `app.clickup.com/t/...` URL) → `clickup_get_task` to confirm it exists. Capture its
+   `custom_id`, `name`, and `status`. Done.
+2. **No reference given → search before asking.** Derive keywords from the work and
+   `clickup_search` (or `clickup_filter_tasks`), narrowed to the relevant Space/List so you
+   don't trawl all 36 spaces — infer the Space from the repo (e.g. repo `linchpin.com` →
+   Space **Linchpin**). Prefer open/active statuses. If there are plausible matches, present
+   the top few and let the user pick or reject.
+3. **Still nothing → ask, don't assume.** Use `AskUserQuestion`:
+   - **Work as NO-TASK** (recommended for quick/throwaway work) — proceed now, commits use
+     `NO-TASK`.
+   - **Create a task now** — run the creation flow below, then use the new key.
+   - The user can also paste a key they had in mind.
+
+**Never block work.** NO-TASK is a first-class, always-available choice.
+
+Record the resolved key (or `NO-TASK`) for this unit of work and reuse it for every commit
+in it. When you open a local TODO with `TaskCreate`, put the ClickUp key (or `NO-TASK`) in
+the task text so the local list and ClickUp stay aligned. Then cut the working branch for
+this change — see **Branch & PR**.
+
+### 2. Before committing, if NO-TASK — offer to create one
+
+When the work is complete and you're about to commit a NO-TASK change, ask once (via
+`AskUserQuestion`): **"Create a ClickUp task for this before committing?"**
+
+- **No** → commit with `NO-TASK`.
+- **Yes** → run the creation flow, then commit with the new key.
+
+Don't ask repeatedly and don't nag — one prompt at commit time.
+
+### 3. Creation flow (least friction)
+
+`clickup_create_task` requires a `list_id` and `name`. Resolve the list with the cheapest
+path that works:
+
+1. **Use a known default if the project has one.** If the project pins a default list
+   (see *Reducing friction*), confirm it in one line ("Create in *Linchpin › linchpin.com ›
+   Development*?") rather than making the user navigate.
+2. **Otherwise present a picker** built from `clickup_get_workspace_hierarchy`:
+   - Call it with `max_depth: 2` **scoped to the likely Space** (pass `space_ids`) so you
+     return Folders + Lists for one space, not the whole workspace.
+   - Offer the candidate Lists via `AskUserQuestion`. Example (Linchpin space):
+     `linchpin.com › Development`, `linchpin.com › Deploy`, `Internal Projects › …`.
+   - Only widen to a Space picker first if you can't infer the Space.
+3. **Name + details:** default the task `name` to the commit subject / work summary; confirm
+   or let the user tweak. Optionally set `assignees: ["me"]` (resolve via
+   `clickup_resolve_assignees`), a `priority`, and a short `markdown_description`.
+4. `clickup_create_task` → read back the new task's **`custom_id`** and use it as the commit
+   scope.
+
+### 4. Update the task when the work lands
+
+A task that never moves is worse than no task — it makes the board lie. Once the change is
+committed and the PR is open, close the loop in ClickUp:
+
+1. **Comment with the pointer.** `clickup_create_comment` on the task with the PR URL and a
+   one-line summary of what changed. This is the step that makes the task useful to whoever
+   picks it up next — do it even if you can't move the status.
+2. **Move the status** with `clickup_update_task` — but **read the valid statuses first**.
+   They're per-Space/List (`in progress`, `review`, `qa`, `complete`, … all vary); take them
+   from the task's own status metadata or `clickup_get_list`. If none obviously matches the
+   state ("PR open, awaiting review"), ask rather than guess.
+3. **Don't close what you can't verify.** Work in an open PR is *in review*, not done. Only
+   move a task to a terminal status when the user says it's shipped, or when a deploy you
+   can observe has completed.
+4. **Time tracking is opt-in.** Only use `clickup_add_time_entry` (or the start/stop tools)
+   when the user asked for it.
+
+For `NO-TASK` work there's nothing to update — skip this step silently.
+
+### 5. Session handoff (when you stop mid-flight)
+
+When work pauses unfinished — end of day, a context switch, or handing off — the task is
+where the state belongs. Not a local file, not the chat: the task is what a teammate opens.
+
+Post one `clickup_create_comment` with these five things, and nothing else:
+
+```markdown
+**Handoff — <date>**
+- **Done:** <what actually works now, and where it's committed or pushed>
+- **In progress:** <what's half-built, and which files>
+- **Open decisions:** <what needs an answer before continuing, and the options>
+- **Where:** branch `<branch>`, PR <link or "none yet">, environment <local|staging|prod>
+- **Next step:** <the single next action, concrete enough to start from cold>
+```
+
+Rules that keep this useful:
+
+- **Write it for someone who wasn't here.** No "as discussed", no pronouns pointing at chat
+  history.
+- **Be honest about what's unfinished.** A handoff that overstates progress costs more than
+  no handoff.
+- **One handoff comment per pause**, not a running log — supersede the previous one by
+  posting a fresh comment rather than editing history.
+- Uncommitted work is not a handoff. Commit or stash it first and say which
+  ([`commit-and-release`](../commit-and-release/SKILL.md)).
+
+## Conventional commits
+
+**Scope = the task key or `NO-TASK`.** That is this skill's half of the message:
+
+```
+feat(LINCHPIN-5113): Add cloudflare email sending on launch
+chore(NO-TASK): Tidy editorconfig and ignore rules
+```
+
+Everything else about the message — allowed types (they differ per repo), sentence case,
+punctuation limits, breaking changes — lives in
+[`commit-and-release`](../commit-and-release/SKILL.md). Two notes that are about the *key*
+rather than the grammar:
+
+- A trailing PR number — `… (#758)` — is appended by the PR/release flow; you don't add it
+  by hand.
+- Reserve `chore(main): …` for release-please release commits — don't reuse `main` as a
+  scope for normal work.
+
+## Branch & PR
+
+Work happens on a dedicated branch opened as a PR against the base branch (usually `main`)
+— never commit straight to `main`.
+
+- **Branch naming** (cut from an up-to-date `main`):
+  - With a task: **`issue/<ISSUE-KEY>`** — the ClickUp custom ID, e.g. `issue/LINCHPIN-5113`.
+  - NO-TASK: **`no-task/<short-kebab-slug>`** describing the change (a bare `issue/no-task`
+    would collide across changes).
+  - Started NO-TASK, then created a task before pushing? Rename the branch to match:
+    `git branch -m issue/<ISSUE-KEY>`.
+- **Pull request** (head = your branch, base = `main`):
+  - Title follows the commit convention: `type(<ISSUE-KEY | NO-TASK>): subject`.
+  - Body **links the ClickUp task** — paste `https://app.clickup.com/t/<ISSUE-KEY>` and the
+    key so GitHub ↔ ClickUp stay connected. For NO-TASK, note there's no task.
+  - Keep every commit on the branch using the same scope.
+
+## Reducing friction
+
+- **Pin a default list per project.** Record the project's usual Space/List (id + path) in
+  the project's `CLAUDE.md` or a small `.clickup.json`, so creation becomes a one-line
+  confirm instead of navigation — e.g. `<Space> › <Project> › Development` with its
+  `list_id`. The id belongs in that project's repo, not in this shared library.
+- **Remember the last-used list** within a session and reuse it.
+- **Infer the Space from the repo** to scope every search and hierarchy call.
+- **Batch the questions**: when you must ask, resolve task-vs-NO-TASK and (if creating) the
+  list in as few `AskUserQuestion` prompts as possible.
+
+## Gotchas
+
+- **Search before creating** — avoid duplicate tasks; an open task often already exists.
+- **Don't dump the hierarchy.** 36 spaces is overwhelming; always scope `space_ids` and go
+  only as deep as you need (`max_depth`).
+- **Use `custom_id` in commits**, never the internal id (`86badg2te`).
+- **Custom-ID prefixes are space-specific** — read the prefix off the task; don't assume
+  `LINCHPIN-` for non-Linchpin work.
+- **NO-TASK is not failure.** Offer task creation, accept "no", and move on.
+
+## Quick reference
+
+| Step | Tool |
+| --- | --- |
+| Confirm a given key/URL | `clickup_get_task` (accepts `LINCHPIN-5113` or `86badg2te`) |
+| Find an existing task | `clickup_search` / `clickup_filter_tasks` (scope to the Space) |
+| Build a Space/List picker | `clickup_get_workspace_hierarchy` (`space_ids`, `max_depth: 2`) |
+| Resolve "me"/assignees | `clickup_resolve_assignees` |
+| Create the task | `clickup_create_task` (`list_id` + `name` required) |
+| Branch the work | `git switch -c issue/LINCHPIN-#### main` (or `no-task/<slug>`) |
+| Commit | `type(LINCHPIN-#### | NO-TASK): subject` |
+| Open the PR | `gh pr create` — title `type(KEY): …`, body links `app.clickup.com/t/<KEY>` |
+| Comment on the task | `clickup_create_comment` (PR URL + one-line summary) |
+| Move the status | `clickup_update_task` (valid statuses come from the List) |
+| Hand off mid-flight | `clickup_create_comment` with the five-line handoff block |
+
+Where a *new* task belongs — which space, folder, and (on multi-site clients) which site —
+is decided by [`engagement-types`](../engagement-types/SKILL.md).
+
+## Guardrails
+
+- **Never invent a task key.** If you can't resolve one, `NO-TASK` is the correct answer.
+- **Never block the user** waiting for a task decision — NO-TASK is always available.
+- **Never mark a task complete** on your own judgment. An open PR is at most "in review";
+  terminal statuses need the user's word or an observed deploy.
+- **Never guess a status name** — they're Space-specific. Read them, then set them.
+- **Never create a duplicate task** — search first; an open one usually exists.
+- **Never dump the full workspace hierarchy** into a prompt; scope `space_ids` and
+  `max_depth`.
+- Don't log time unless asked.
+
+## Done
+
+- [ ] The unit of work has a resolved task key or an explicit, user-accepted `NO-TASK`.
+- [ ] The branch name matches the key (`issue/<KEY>` or `no-task/<slug>`).
+- [ ] Every commit on the branch carries the same scope.
+- [ ] The PR body links `app.clickup.com/t/<KEY>` (or notes there is no task).
+- [ ] For task-backed work: a comment with the PR link exists, and the status reflects
+      reality without over-claiming completion.
+- [ ] If work is pausing unfinished, a handoff comment exists that a teammate could act on
+      cold, and nothing is left uncommitted.

package/skills/web-qa/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: web-qa
+description: QA a site or app like a real user and fix what you find — explore the front end, wp-admin, and the block editor in a browser, record findings with severity and evidence, then fix each bug in its own atomic commit and re-verify. Use when asked to QA, test, or "make sure this works", after shipping a feature to a branch, before handing work to a client, or when you want a bug report without fixes (report-only mode). Not for lint or unit tests — use `quality-gates`.
+version: 1.0.0
+---
+
+# Web QA
+
+You are the QA engineer *and* the fix engineer. Click everything, fill every form, check
+every state — then fix what's broken, one atomic commit at a time, and prove it with
+before/after evidence.
+
+The discipline that makes this useful rather than noise: **scope it, evidence it, fix it in
+isolation, re-verify it.** A QA pass that ends in one giant commit is not reviewable, and a
+finding without evidence is an opinion.
+
+## When to use
+
+- "QA this", "test this", "make sure this works", "does this actually run?"
+- After shipping a feature to a branch, before opening or merging the PR.
+- Before handing work back to a client.
+- When you want findings only, no code changes — say so, and it runs report-only.
+
+**Not this skill:** lint, PHPCS, static analysis, unit tests —
+[`quality-gates`](../quality-gates/SKILL.md). Performance and accessibility measurement —
+[`wp-audit`](../wp-audit/SKILL.md). Root-causing one specific bug —
+[`investigate`](../investigate/SKILL.md).
+
+## Owns
+
+Canonical for: QA scope and tiers, the explore → triage → fix → verify loop, severity, and
+the report format. Browser mechanics belong to
+[`browser-automation`](../browser-automation/SKILL.md); commits to
+[`commit-and-release`](../commit-and-release/SKILL.md).
+
+## Preflight
+
+1. **Orient** via [`project-context`](../project-context/SKILL.md) — repo shape, environment,
+   URL, host.
+2. **Require a clean working tree.** `git status --porcelain` must be empty, so each fix
+   lands as its own reviewable commit. If it isn't, stop and offer: commit the current work,
+   stash it, or abort. Never QA on top of uncommitted changes.
+3. **Resolve scope**, in this order:
+   - The user named a URL or area → use it.
+   - On a feature branch with no URL → **diff-aware mode**: `git diff --name-only` against
+     the merge base, and test what those files affect. This is the common case.
+   - Otherwise → the whole app, front end and admin.
+4. **Set the tier** — it decides what gets fixed, not what gets reported:
+
+| Tier | Fixes | Use for |
+| --- | --- | --- |
+| Quick | Critical + high | A fast pre-PR check |
+| **Standard** (default) | + medium | Normal QA |
+| Exhaustive | + low/cosmetic | Pre-client-handoff polish |
+| Report-only | nothing | You want the findings, not the changes |
+
+## Procedure
+
+1. **Explore like a user, not like a developer.** Front end *and* `/wp-admin` *and* the block
+   editor where content is involved; primary flows first, then forms, empty states, error
+   states, and mobile width. See
+   [`references/qa-checklist.md`](references/qa-checklist.md).
+   → Every area in scope has been visited, not assumed.
+2. **Record each finding with evidence** — what you did, what happened, what should have
+   happened, plus a screenshot and any console or network error. No evidence, no finding.
+   → A reader could reproduce it without you.
+3. **Assign severity** from the table in
+   [`references/qa-checklist.md`](references/qa-checklist.md), and say plainly when something
+   is a judgment call rather than a defect. → Each finding is critical/high/medium/low.
+4. **Triage against the tier.** List what you're fixing and what you're leaving, before
+   touching code. → The user can redirect before any commits exist.
+5. **Fix loop — one bug at a time.** Fix in the source (never in the database or on the
+   server), run [`quality-gates`](../quality-gates/SKILL.md), re-test that specific flow, then
+   commit that single fix per
+   [`commit-and-release`](../commit-and-release/SKILL.md). → One bug, one commit, one
+   verification.
+6. **Final pass.** Re-run the primary flows end to end to catch anything the fixes broke.
+   → Green, or a new finding that goes back through triage.
+7. **Report** — what was tested, findings by severity with before/after evidence, what was
+   fixed, what was deliberately left, and what couldn't be tested. Then update the ClickUp
+   task ([`task-tracking`](../task-tracking/SKILL.md)).
+
+## Guardrails
+
+- **Never start on a dirty tree.** Mixing QA fixes with in-flight work makes both unreviewable.
+- **Never batch unrelated fixes into one commit** — a single bad fix then can't be reverted
+  without taking the good ones with it.
+- **Never fix a bug by changing the database or editing files on the server.** Code fixes go
+  through the repo and the deploy pipeline ([`wp-pressable`](../wp-pressable/SKILL.md)).
+- **Never QA destructively against production.** Deletes, bulk actions, payments, and "send"
+  buttons are real there. Test locally or on staging; if production is the only option, it's
+  read-only and confirmed first.
+- **Never claim a fix works without re-testing the exact flow that failed.** "Should work now"
+  is not verification.
+- **Never expand scope silently.** A refactor discovered mid-QA is a finding, not a fix.
+- **Never report a clean pass for an area you couldn't reach** — auth walls, missing test
+  data, and unreachable states get listed as untested, not as passing.
+
+## Done
+
+- [ ] Started from a clean tree; scope and tier stated up front.
+- [ ] Every in-scope area actually exercised in a browser, including admin where relevant.
+- [ ] Findings carry reproduction steps, severity, and evidence.
+- [ ] Triage shown to the user before fixes began.
+- [ ] Each fix is its own commit, gates green, and the specific flow re-tested.
+- [ ] Final end-to-end pass run after the last fix.
+- [ ] Report lists fixed, deliberately-not-fixed, and untested areas.
+- [ ] ClickUp task updated with the outcome.

package/skills/web-qa/references/qa-checklist.md

@@ -0,0 +1,98 @@
+# QA checklist, severity, and report format
+
+## Severity
+
+Severity is about **user impact**, not how hard it is to fix.
+
+| Severity | Means | Examples |
+| --- | --- | --- |
+| **Critical** | Blocks a core task, loses data, or exposes something it shouldn't | Checkout fails, form submits nothing, 500 on a key page, private content public, fatal PHP error |
+| **High** | A primary flow is broken or badly degraded, no reasonable workaround | Nav broken on mobile, search returns nothing, images 404, admin screen unusable |
+| **Medium** | Works but wrong or awkward; a workaround exists | Validation message never clears, wrong date format, layout breaks at one width, confusing empty state |
+| **Low** | Cosmetic or minor polish | Spacing inconsistency, a typo, a hover state that doesn't match its neighbors |
+
+Two rules that keep reports honest:
+
+- **A judgment call is not a defect.** "I'd have used more spacing here" is design feedback —
+  label it as such, don't file it as a bug.
+- **Uncertain severity rounds down**, and say why. Inflating severity to force a fix wastes
+  the tier system.
+
+## What to exercise
+
+### Every project
+
+- **Primary flows first** — whatever the site exists to do: contact, apply, donate, buy,
+  search, read.
+- **Forms**: submit valid, submit empty, submit invalid. Check the error messages, the
+  success state, and that the submission actually arrived somewhere.
+- **States**: empty, loading, error, and "lots of content". Empty and error states are where
+  most bugs hide because nobody looks at them.
+- **Mobile width** — not just a narrow desktop window; check tap targets and any nav drawer.
+- **Console and network**: JS errors, 404s, failed requests, mixed content.
+- **Back/forward and refresh** mid-flow — state that only works forwards is a real bug.
+
+### WordPress
+
+- **Logged out vs logged in.** The admin bar shifts layout, and capability-gated UI only
+  appears for some roles. Test both.
+- **`/wp-admin`**: the screens this work touches — post lists, editors, settings pages,
+  custom post types, taxonomies.
+- **Block editor**: insert the block, edit its attributes, save, reload, and confirm no
+  "unexpected or invalid content" ([`wordpress-blocks`](../../wordpress-blocks/SKILL.md);
+  `validate_blocks` via [`wp-studio-cli`](../../wp-studio-cli/SKILL.md)).
+- **Content edge cases**: a very long title, a missing featured image, an unset optional
+  field, a post with no terms.
+- **Permalinks and 404s** — a template change can quietly break the 404 or archive views.
+- **Caching** — on a hosted environment, flush object and page cache before concluding a fix
+  didn't work.
+
+### Cloudflare Workers / API projects
+
+- Route behavior and status codes, error payload shape, auth boundaries, and what happens on
+  a cold start. The browser matters less; the responses matter more.
+
+## Diff-aware mode
+
+On a feature branch with no URL given, scope from the change itself:
+
+```bash
+git diff --name-only $(git merge-base HEAD origin/main)...HEAD
+```
+
+Map files to surfaces before exploring:
+
+| Changed | Test |
+| --- | --- |
+| `themes/*/templates/*`, `parts/*` | The pages using that template or part, logged out and in |
+| `blocks/src/<block>/*` | Insert and edit the block, save, reload, then view it on the front end |
+| `plugins/*/includes/*` | The admin screens and endpoints that code backs |
+| `theme.json`, `style.scss` | Visual regression across a few representative pages |
+| REST or API code | The endpoints directly, plus whatever consumes them |
+
+## Report format
+
+```markdown
+## QA report — <scope> (<environment>)
+
+**Tested:** <areas, URLs, viewports> · **Tier:** <quick|standard|exhaustive|report-only>
+
+### Findings
+
+| # | Severity | Finding | Status |
+|---|----------|---------|--------|
+| 1 | Critical | Contact form submits but sends no email | Fixed — <commit> |
+| 2 | Medium   | Validation error persists after correcting the field | Fixed — <commit> |
+| 3 | Low      | Footer spacing differs from header | Not fixed (below tier) |
+
+### 1. Contact form submits but sends no email
+**Steps:** … **Expected:** … **Actual:** …
+**Evidence:** <screenshot>, console error, failed request
+**Cause:** … **Fix:** <commit> **Verified:** re-submitted, message received
+
+### Not tested
+- Member dashboard — no test account available
+```
+
+Always include the **Not tested** section, even when empty. An unreachable area silently
+omitted reads as an area that passed.

package/skills/wordpress-blocks/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: wordpress-blocks
+description: Author and edit WordPress content as valid Gutenberg block markup from a chat interface (Mantle). Use whenever a request means adding or changing page/post/content — a section, hero, pricing table, FAQ, CTA, columns, etc. Encodes the pattern-first procedure (reuse the site's synced patterns / template parts / registered patterns BEFORE composing from core blocks), the block-markup grammar models get wrong, and the live tool contract the host plugin must expose. Always validate generated block markup before inserting — invalid comment delimiters silently break the editor.
+version: 0.1.0
+---
+
+# WordPress Blocks (content authoring)
+
+Use this skill when you are **editing WordPress content** (a page, post, or other
+block-based content) through a chat interface — i.e. the Mantle plugin asks you to
+"add a pricing table," "build a hero," "insert an FAQ," "make this two columns," etc.
+
+Your output for a content region is **WordPress block markup** (Gutenberg "block grammar"),
+not Markdown and not plain HTML. Block markup is HTML wrapped in `<!-- wp:… -->` comment
+delimiters; if those delimiters are malformed, the editor flags the content as an
+**"unexpected or invalid"** block and the user loses the layout. Getting the grammar right,
+and reusing the site's own design assets, is the whole job.
+
+## When to use
+
+- A request means adding or changing content on a page or post — a hero, pricing table,
+  FAQ, CTA, columns, or any section.
+- Existing content needs restructuring into different blocks.
+- You need to know whether a layout should reuse a site pattern or be composed fresh.
+
+**Not this skill:** building blocks, plugins, or themes (PHP `block.json`, `render.php`,
+registering patterns in a theme) — use the upstream WordPress skills
+[`wp-block-development`](https://github.com/WordPress/agent-skills) and
+[`wp-block-themes`](https://github.com/WordPress/agent-skills). One site's specific block
+and pattern conventions belong in that project's own `CLAUDE.md`/`AGENTS.md`.
+
+## The core principle: reuse before you build
+
+A site is not a blank canvas. It already ships design assets the user (or their designer)
+made, and reusing them is almost always better than hand-composing core blocks:
+
+| Asset | What it is | How you emit it |
+| --- | --- | --- |
+| **Synced pattern** (`wp_block` CPT) | A saved, *linked* block — edits propagate everywhere it's used | `<!-- wp:block {"ref":ID} /-->` |
+| **Registered pattern** (theme/plugin) | A reusable layout *template*, inserted as a one-time copy | Its expanded block markup (fetch via `get_pattern`) |
+| **Template part** (FSE) | Header/footer/section parts of a block theme | `<!-- wp:template-part {"slug":"…","theme":"…"} /-->` (templates, not post body) |
+| **Core / registered blocks** | The block library primitives | Composed markup — the **fallback** |
+
+See `references/patterns-and-parts.md` for the distinctions and when each is appropriate.
+
+## Procedure (pattern-first)
+
+When a request means "add/build/change a layout or section":
+
+1. **Classify the intent** and extract search keywords (e.g. "pricing table" → `pricing`,
+   `plans`, `tiers`).
+2. **Search the live site first.** Call `search_patterns(query)` (it covers synced +
+   registered patterns and template parts). Do this *before* writing any markup.
+3. **If there's a strong match**, reuse it:
+   - **Synced pattern** → emit `<!-- wp:block {"ref":ID} /-->`. Don't inline its markup — keep it synced. If the user wants edits to *this instance only*, detach (see `references/patterns-and-parts.md`).
+   - **Registered pattern** → `get_pattern(slug)` and insert its `block_markup`, adapting the copy/text to the request.
+   - **Template part** → only when editing a template (not post body).
+4. **If no good match**, compose from core blocks:
+   - Pull the recipe from `references/recipes/` when one exists (`pricing-table.md`, `hero.md`, `faq.md`); otherwise apply `references/core-blocks.md`.
+   - Use the site's **design tokens** (color slugs, font-size slugs, `contentSize`/`wideSize`) from `get_theme_tokens()` instead of hardcoded hex/px, so content matches the design system.
+   - If you reference a **non-core** block, confirm it's actually registered on this install via `list_registered_blocks()` first.
+5. **Validate before returning.** Run the markup through `validate_blocks` (or the host's
+   block validator) and repair/simplify on failure. See `references/validation.md`. Never
+   hand back content you haven't validated.
+
+## Output rules
+
+- Emit **only** block markup for the content region — no Markdown fences, no commentary
+  mixed in. The plugin inserts your output verbatim.
+- **Preserve** existing blocks unless the user asked to replace them. When editing, return
+  the changed block(s) in context, not the whole document, unless asked.
+- **Prefer the fewest blocks** that achieve the layout. Don't wrap everything in nested
+  groups "just in case."
+- Prefer **token references** (`{"textColor":"primary"}`, `{"fontSize":"large"}`) over raw
+  values when `get_theme_tokens()` exposes a matching slug.
+- Core blocks drop the namespace: `wp:paragraph`, **not** `wp:core/paragraph`.
+
+## Reference files (load as needed)
+
+- `references/block-grammar.md` — the delimiter grammar and the top causes of "invalid block."
+- `references/core-blocks.md` — copy-paste-correct markup for the common core blocks.
+- `references/patterns-and-parts.md` — synced vs registered patterns vs template parts.
+- `references/tool-contract.md` — JSON Schemas for the live tools the host plugin must expose.
+- `references/validation.md` — the validate-before-insert contract and repair loop.
+- `references/recipes/` — fallback compositions (`pricing-table.md`, `hero.md`, `faq.md`).
+
+## Guardrails
+
+- **Never return unvalidated block markup.** Malformed `<!-- wp:… -->` delimiters produce an
+  "unexpected or invalid content" block and the user loses their layout — validate, repair,
+  and only then hand it back.
+- **Never inline a synced pattern's markup** to make an edit. That silently detaches it from
+  every other place it's used; detach deliberately or edit the pattern itself.
+- **Never replace content the user didn't ask you to change.** Return the changed blocks in
+  context; preserve everything else exactly.
+- **Never reference a block that isn't registered on the install** — confirm with
+  `list_registered_blocks()` before using anything outside core.
+- **Never hardcode colors, sizes, or widths** when `get_theme_tokens()` exposes a matching
+  slug; raw values break the site's design system on theme changes.
+- Don't wrap output in Markdown fences or mix commentary into it — the host inserts your
+  output verbatim.
+
+## Done
+
+- [ ] The site was searched for an existing pattern/part before composing anything new.
+- [ ] Output is block markup only — no fences, no commentary.
+- [ ] Design tokens used wherever the theme exposes a matching slug.
+- [ ] Every non-core block referenced is confirmed registered.
+- [ ] `validate_blocks` (or the host validator) passes on the final markup.
+- [ ] Untouched blocks are byte-for-byte preserved.

package/skills/wordpress-blocks/references/block-grammar.md

@@ -0,0 +1,94 @@
+# Block grammar — the part models get wrong
+
+WordPress stores block content as HTML annotated with **HTML-comment delimiters**. The
+parser ("block grammar") reads those comments to know where each block starts/ends and what
+its attributes are. Malformed delimiters → the editor shows *"This block contains unexpected
+or invalid content"* and the user loses the layout. This file is the contract for emitting
+correct markup.
+
+Upstream: <https://developer.wordpress.org/block-editor/reference-guides/block-api/block-grammar/>
+and block attributes: <https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/>
+
+## Anatomy of a block
+
+```
+<!-- wp:NAMESPACE/NAME {"attr":"value"} -->
+  ...the block's saved HTML...
+<!-- /wp:NAMESPACE/NAME -->
+```
+
+- **Core blocks omit the namespace**: `wp:paragraph`, `wp:heading`, `wp:columns` — NOT
+  `wp:core/paragraph`. Third-party blocks keep theirs: `wp:linchpin/testimonial`.
+- The **opening** delimiter may carry a JSON attributes object. The **closing** delimiter
+  never does: `<!-- /wp:paragraph -->`.
+- The name in the closing delimiter must match the opening one exactly.
+
+## Two block forms
+
+**1. Block with content** (open + close, inner HTML between):
+
+```
+<!-- wp:paragraph -->
+<p>Hello.</p>
+<!-- /wp:paragraph -->
+```
+
+**2. Void / self-closing block** (no inner HTML — note the `/-->`):
+
+```
+<!-- wp:block {"ref":42} /-->
+<!-- wp:spacer {"height":"40px"} /-->          ← (spacer actually has HTML — see note)
+<!-- wp:template-part {"slug":"header"} /-->
+```
+
+The `/` before `-->` marks a void block. Use it **only** for blocks that save no inner HTML
+(synced-pattern reference `wp:block`, `wp:pattern`, `wp:template-part`, `wp:post-content`,
+etc.). A `wp:paragraph` is never self-closing. (Spacer *does* render a `<div>`, so it uses
+the open/close form — see `core-blocks.md`.)
+
+## Attribute JSON rules
+
+- Attributes are a **single valid JSON object**: double-quoted keys/strings, no trailing
+  commas, no comments, no single quotes.
+- **Omit attributes that equal the default.** WordPress only serializes non-default
+  attributes. Adding `{"level":2}` to a heading (2 is the default) or inventing attributes
+  the block doesn't define is a common cause of invalid blocks.
+- Numbers/booleans are unquoted: `{"dimRatio":50,"isStackedOnMobile":true}`.
+- Many visual attributes map to generated classes/inline styles in the HTML **and** must be
+  declared in the JSON — they have to agree. Example: a heading's level lives in `{"level":3}`
+  *and* the tag must be `<h3>`. Don't set one without the other.
+
+## The #1 rule: saved HTML must match the block's save output
+
+Each block has a fixed shape it serializes to. If your inner HTML doesn't match what that
+block would save (wrong wrapper class, wrong tag, missing element), the editor marks it
+invalid even when the delimiters are perfect. Practical consequences:
+
+- A heading saves with `class="wp-block-heading"`: `<h2 class="wp-block-heading">…</h2>`.
+- A button saves nested: `wp:buttons` → `.wp-block-buttons` → `wp:button` → `.wp-block-button`
+  → `<a class="wp-block-button__link wp-element-button">`.
+- A list wraps each item in its own `wp:list-item` block (modern WP), not bare `<li>`.
+
+Because these shapes **drift between WordPress/Gutenberg versions**, do not trust hand-written
+markup blindly — always run it through `validate_blocks` (see `validation.md`) and let the
+validator/normalizer repair class names and wrappers. Treat the examples in `core-blocks.md`
+and `recipes/` as *starting structure*, not byte-perfect truth for every site.
+
+## Top causes of "invalid block"
+
+1. **Void/open mismatch** — `<!-- wp:block {"ref":42} -->` without `/`, or a `/-->` on a
+   block that has inner HTML.
+2. **Malformed attribute JSON** — trailing comma, single quotes, unescaped quote inside a
+   string. Escape inner quotes as `"` if needed.
+3. **Inner HTML doesn't match save output** — missing `wp-block-*` class, wrong tag, wrong
+   nesting.
+4. **Namespaced a core block** — `wp:core/paragraph` instead of `wp:paragraph`.
+5. **Mismatched open/close names** — `<!-- wp:group -->` … `<!-- /wp:columns -->`.
+6. **Markdown leaking in** — emitting `**bold**` or `- item` instead of `<strong>`/list
+   blocks. Block markup is HTML, never Markdown.
+
+## Whitespace
+
+Keep block delimiters on their own lines and put a blank line between sibling blocks for
+readability; the parser tolerates this. Inside a parent's wrapper `<div>`, child block
+delimiters sit directly inside the div (see the columns example in `core-blocks.md`).