@linchpinagency/skills 0.1.5 → 0.1.7

package/README.md

@@ -12,7 +12,7 @@ GitHub Copilot, and other compatible coding agents.
 ![Zero dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen)
 
 <!-- x-release-please-start-version -->
-### Latest release: 0.1.5
+### Latest release: 0.1.7
 <!-- x-release-please-end -->
 
 | Release | Skill standard | Install |
@@ -81,6 +81,7 @@ The fastest way to understand the library is to run one loop end to end:
 | Understand a repo you just cloned | "what am I working with here?" | `project-context` |
 | Find out why something's broken | "the hero image 404s on mobile" | `investigate` |
 | Test a site like a user, and fix what's found | "QA the checkout flow" | `web-qa` |
+| File work for later | "create an issue for the broken footer link" | `task-tracking` |
 | Check it's ready to commit | "is this ready to commit?" | `quality-gates` |
 | Commit and open the PR properly | "commit this and open a PR" | `commit-and-release` + `task-tracking` |
 | Handle a client support ticket | "the client says their contact form isn't sending" | `support-triage` |
@@ -232,7 +233,7 @@ A project that wants skills in more than one agent's directory should run
 | `support-triage` | Project mgmt | Run a client support request end to end — clarify the real need, reproduce, judge urgency and scope, fix in the right layer, verify, and close the loop with the requester. |
 | `dependency-updates` | Workflow | Handle the dependency work Renovate can't automerge — majors, breaking changes, failing or conflicted bot PRs, security advisories, `@wordpress/*` package sets. |
 | `commit-and-release` | Workflow | Write commits, branches, and PR titles that satisfy the repo's own commitlint rules, and stay out of release-please's way (it owns versions and `CHANGELOG.md`). |
-| `task-tracking` | Workflow | Tie every unit of work to a ClickUp task (or explicit `NO-TASK`) with minimal friction via the ClickUp MCP — resolve/search a task, offer to create one before committing, update it when the work lands, and carry the task key in the conventional-commit scope. |
+| `task-tracking` | Workflow | Tie every unit of work to a ClickUp task (or explicit `NO-TASK`) with minimal friction via the ClickUp MCP — resolve/search a task, create one on request ("create an issue" means ClickUp, not GitHub), update it when the work lands, and carry the task key in the conventional-commit scope. |
 | `write-a-linchpin-skill` | Meta | The house standard for authoring skills in this library — placement test, tier model, required frontmatter, the section skeleton, and the four house rules. Enforced by `scripts/validate-skills.mjs`. |
 
 _(More WordPress, React, Cloudflare Workers, marketing, and design skills to come.)_

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linchpinagency/skills",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Linchpin's library of reusable AI agent skills for WordPress projects.",
   "type": "module",
   "bin": {

package/skills/task-tracking/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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
+description: Associate every unit of work with a task in Linchpin's task platform (currently ClickUp, via the ClickUp MCP) with the least friction, update it when the work lands, and leave a handoff 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 — and whenever anyone says "create an issue", "create a task", "file a ticket", or "log a bug", all of which mean a ClickUp task unless they name GitHub. Resolve a task from an 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.3.0
 ---
 
 # Task tracking (ClickUp)
@@ -18,6 +18,8 @@ platform change.
 ## When to use
 
 - Starting any unit of work, before cutting a branch.
+- **Anyone asking for an issue, task, ticket, bug, or backlog item to be created** — in any
+  wording. See *"Create an issue" means ClickUp* below.
 - 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.
@@ -32,6 +34,21 @@ Canonical for: resolving, creating, and updating the task; the **scope key** tha
 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).
 
+## "Create an issue" means ClickUp
+
+**"Issue", "task", "ticket", "bug", "backlog item" — all of them mean a ClickUp task here.**
+Asked to create one, run the creation flow in step 3. Being in a GitHub repo, reviewing a
+PR, or reading `gh` output does not make "create an issue" mean a GitHub issue. Which space,
+folder, and (for multi-site clients) which site it lands in is
+[`engagement-types`](../engagement-types/SKILL.md)'s call.
+
+**A GitHub issue only when GitHub is named** — "open a *GitHub* issue", "file it in the
+repo's issues", "`gh issue create`". Open it with `gh issue create`; if it's work Linchpin
+will do, create the ClickUp task too and cross-link them (issue body →
+`app.clickup.com/t/<KEY>`; `clickup_create_comment` → issue URL). ClickUp stays the system
+of record. For the genuinely ambiguous — a public repo where issues *are* the tracker — ask
+once with `AskUserQuestion`, recommending ClickUp.
+
 ## Vocabulary
 
 - **Task key / issue key** — ClickUp's *custom ID*, e.g. `LINCHPIN-5113`. Space-scoped, so
@@ -78,6 +95,10 @@ Don't ask repeatedly and don't nag — one prompt at commit time.
 
 ### 3. Creation flow (least friction)
 
+Reached two ways: from step 2 (a NO-TASK change about to be committed), or directly, when
+someone just says *"create an issue/task for X"* — that's a standalone request and doesn't
+need a commit or a branch behind it.
+
 `clickup_create_task` requires a `list_id` and `name`. Resolve the list with the cheapest
 path that works:
 
@@ -192,6 +213,7 @@ Work happens on a dedicated branch opened as a PR against the base branch (usual
 
 ## Gotchas
 
+- **"Issue" is not a GitHub word here.** Route it to ClickUp unless GitHub was named.
 - **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`).
@@ -216,11 +238,10 @@ Work happens on a dedicated branch opened as a PR against the base branch (usual
 | 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 open a GitHub issue in place of a ClickUp task.** "Create an issue" means ClickUp;
+  `gh issue create` needs the user to have said *GitHub*.
 - **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";
@@ -233,6 +254,8 @@ is decided by [`engagement-types`](../engagement-types/SKILL.md).
 
 ## Done
 
+- [ ] Any "create an issue/task/ticket" request produced a **ClickUp** task — or a GitHub
+      issue only because the user named GitHub, in which case the two are cross-linked.
 - [ ] 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.

package/skills/wordpress-blocks/references/recipes/faq.md

@@ -2,42 +2,89 @@
 
 Use after `search_patterns("faq questions accordion")` finds no good match.
 
-## Preferred — Details block (native accordion, no plugin)
+## Preferred — core/accordion (WordPress 6.9+)
 
-Core `wp:details` renders an expand/collapse `<details>` natively. Each Q is its own block.
+Core ships a real accordion: `core/accordion` wrapping `core/accordion-item`, each holding a
+`core/accordion-heading` and a `core/accordion-panel`. Use it whenever the site is on 6.9 or
+later — confirm with `list_registered_blocks`.
 
-```html
-<!-- wp:group {"layout":{"type":"constrained"}} -->
-<div class="wp-block-group">
-<!-- wp:heading -->
-<h2 class="wp-block-heading">Frequently asked questions</h2>
-<!-- /wp:heading -->
+Why it beats the alternatives for a multi-question FAQ:
 
-<!-- wp:details -->
-<details class="wp-block-details"><summary>How does billing work?</summary>
+- **`autoclose`** — only one answer open at a time, which is what most FAQ designs show.
+- **`headingLevel` / `level`** — each question is a real heading, so the document outline and
+  screen-reader navigation are correct. `core/details` gives you a `<summary>`, which is not.
+- **One styled container** — colour, spacing, border, shadow and typography supports sit on the
+  item, so every question shares styling instead of being restyled individually.
+- Built on the Interactivity API, so no custom JS.
+
+```html
+<!-- wp:accordion {"autoclose":true,"iconPosition":"right","headingLevel":3} -->
+<div class="wp-block-accordion">
+<!-- wp:accordion-item {"openByDefault":true} -->
+<div class="wp-block-accordion-item">
+<!-- wp:accordion-heading {"level":3} -->
+<h3 class="wp-block-accordion-heading">How does billing work?</h3>
+<!-- /wp:accordion-heading -->
+<!-- wp:accordion-panel -->
+<div class="wp-block-accordion-panel">
 <!-- wp:paragraph -->
 <p>You're billed monthly and can cancel anytime.</p>
 <!-- /wp:paragraph -->
-</details>
-<!-- /wp:details -->
+</div>
+<!-- /wp:accordion-panel -->
+</div>
+<!-- /wp:accordion-item -->
 
-<!-- wp:details -->
-<details class="wp-block-details"><summary>Do you offer support?</summary>
+<!-- wp:accordion-item -->
+<div class="wp-block-accordion-item">
+<!-- wp:accordion-heading {"level":3} -->
+<h3 class="wp-block-accordion-heading">Do you offer support?</h3>
+<!-- /wp:accordion-heading -->
+<!-- wp:accordion-panel -->
+<div class="wp-block-accordion-panel">
 <!-- wp:paragraph -->
 <p>Yes — email support on every plan.</p>
 <!-- /wp:paragraph -->
+</div>
+<!-- /wp:accordion-panel -->
+</div>
+<!-- /wp:accordion-item -->
+</div>
+<!-- /wp:accordion -->
+```
+
+`openByDefault` on an item renders it expanded. `showIcon: false` hides the indicator.
+`iconPosition` takes `left` or `right`.
+
+**Generate this markup, don't hand-write it.** Nested parent/child blocks with `allowedBlocks`
+constraints are easy to get subtly wrong, and an invalid FAQ shows "Attempt block recovery" on
+every insert. Build the tree with `createBlock` and `serialize` in the editor, then use the
+serialized result — see "Verify before shipping".
+
+Designs often draw the toggle as **+ / −**; core renders a chevron. That's a block style or a
+CSS override on the heading icon, not a reason to pick a different block.
+
+## Fallback — core/details (pre-6.9, or a genuinely independent set)
+
+`wp:details` renders a native `<details>`. Reach for it when `core/accordion` isn't registered,
+or when each item is standalone and single-open behaviour would be wrong.
+
+```html
+<!-- wp:details -->
+<details class="wp-block-details"><summary>How does billing work?</summary>
+<!-- wp:paragraph -->
+<p>You're billed monthly and can cancel anytime.</p>
+<!-- /wp:paragraph -->
 </details>
 <!-- /wp:details -->
-</div>
-<!-- /wp:group -->
 ```
 
-Set `{"showContent":true}` on a `wp:details` to render it open by default.
+Set `{"showContent":true}` to render one open by default. Know the limits: no shared open/close
+coordination, and the question is a `<summary>` rather than a heading.
 
-## Simpler — heading + paragraph pairs (no interactivity)
+## Last resort — heading + paragraph pairs (no interactivity)
 
-If `wp:details` isn't registered on the site (`list_registered_blocks`), or the user wants a
-flat list, alternate headings and paragraphs:
+If neither block is registered, or the user explicitly wants a flat list:
 
 ```html
 <!-- wp:heading {"level":3} -->
@@ -49,8 +96,25 @@ flat list, alternate headings and paragraphs:
 <!-- /wp:paragraph -->
 ```
 
+Don't ship this as "an FAQ accordion" — it collapses nothing. If the design shows
+expand/collapse and you emit this, say so plainly rather than letting it pass as equivalent.
+
 ## Adapt
 
-- Generate one `wp:details` (or heading/paragraph pair) per Q&A from the user's content.
+- Generate one accordion item per Q&A from the user's content; mark only the first
+  `openByDefault`.
 - Don't reach for a third-party accordion block unless the user names one and
-  `list_registered_blocks` confirms it's installed — `wp:details` covers most needs.
+  `list_registered_blocks` confirms it's installed. Core now covers this.
+
+## Verify before shipping
+
+Validate in the site's real editor rather than trusting it by eye:
+
+```
+mcp__wordpress-studio__validate_blocks  nameOrPath=<site>  content=<the FAQ markup>
+```
+
+Expect every block valid. If a result looks wrong — for example attributes coming back as
+defaults — confirm against the editor itself with `wp.blocks.parse( markup )[0]` and check
+`isValid` plus the parsed attributes, because a validator running a stale block registration
+can report a false failure.

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

@@ -31,8 +31,15 @@ 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.
+   Check what core actually ships *on this version* rather than from memory: core has absorbed
+   a lot recently, and a block library that was the right answer two releases ago may now be
+   duplicating core. Accordions are the current example — `core/accordion` +
+   `accordion-item` / `accordion-heading` / `accordion-panel` landed in **6.9**, with
+   `autoclose`, real heading levels and the Interactivity API. On 6.9+ that beats both
+   `core/details` and any bundled accordion block. Verify with `list_registered_blocks`.
 2. **Does the shared block library already have it?** `linchpin/linchpin-blocks` ships
-   accordion, tabs, cards, slider, counter, and more.
+   accordion, tabs, cards, slider, counter, and more. Prefer core when core has caught up —
+   a plugin dependency for something core does is a maintenance cost with no upside.
 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.