@linchpinagency/skills 0.1.8 → 0.1.10

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.8
+### Latest release: 0.1.10
 <!-- x-release-please-end -->
 
 | Release | Skill standard | Install |
@@ -259,8 +259,8 @@ A project that wants skills in more than one agent's directory should run
 | `engagement-types` | Project mgmt | Tell support, site maintenance, projects, product/plugin work, and pre-sales apart — each lives somewhere different in ClickUp and is planned and closed differently. |
 | `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, 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. |
+| `commit-and-release` | Workflow | Write commit messages 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`). Branch naming lives in `task-tracking`. |
+| `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), split work that spans sessions or PRs into parent + subtasks, name the branch, update the task when the work lands, and carry the task key in the 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.8",
+  "version": "0.1.10",
   "description": "Linchpin's library of reusable AI agent skills for WordPress projects.",
   "type": "module",
   "bin": {

package/skills/browser-automation/SKILL.md

@@ -13,7 +13,10 @@ parallel runs.
 
 Skills that need a browser ([`web-qa`](../web-qa/SKILL.md),
 [`wp-audit`](../wp-audit/SKILL.md), [`design-previews`](../design-previews/SKILL.md))
-reference this rather than each choosing their own way in.
+reference this rather than each choosing their own way in. **The one exception is a local
+Studio site**, whose MCP has its own `take_screenshot` and `inspect_design` against PHP-WASM
+— that isn't a browser and doesn't come through this ladder; see
+[`wp-studio-cli`](../wp-studio-cli/SKILL.md).
 
 ## When to use
 
@@ -81,6 +84,9 @@ session and are not part of this ladder.
 - **Never store credentials, cookies, or auth state in the repo.** Use the browser's existing
   session or a gitignored auth file.
 - **Never navigate anywhere the task didn't call for.** Stay on the target application.
+- **Never reach for `claude-in-chrome` tools.** They fight the Chrome DevTools MCP for the
+  same browser session; the ladder above is the whole set. This is stated here as well as in
+  the ladder because it's the one rule another skill is most likely to trip over.
 - If the browser tooling fails twice in a row, stop and report it rather than cycling through
   variations of the same call.
 

package/skills/commit-and-release/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: commit-and-release
-description: Write commits, branches, and PR titles that satisfy a Linchpin repo's own commitlint rules, and stay out of the way of release-please, which owns versions and CHANGELOG.md. Use when composing a commit message, when commitlint or a husky hook rejects one, when opening a PR, when asked how a change gets released or deployed, or before touching a version number anywhere. Not for running lint or tests — use `quality-gates`.
-version: 1.0.0
+description: Write commit messages and PR titles that satisfy a Linchpin repo's own commitlint rules, and stay out of the way of release-please, which owns versions and CHANGELOG.md. Use when composing a commit message, when commitlint or a husky hook rejects one, when opening a PR, when asked how a change gets released or deployed, or before touching a version number anywhere. Not for running lint or tests — use `quality-gates`. Not for naming the branch or resolving the task key in the scope — use `task-tracking`.
+version: 1.1.0
 ---
 
 # Commit and release
@@ -17,20 +17,21 @@ Two pieces of automation own this pipeline, and both bite when you guess:
 
 ## When to use
 
-- Composing a commit message, branch name, or PR title.
+- Composing a commit message or PR title.
 - A commit was rejected by commitlint or a husky hook.
 - The user asks how a change reaches staging or production.
 - Anything is about to touch a version number or `CHANGELOG.md`.
 - Reviewing or merging a release PR.
 
 **Not this skill:** running lint/tests before the commit — [`quality-gates`](../quality-gates/SKILL.md).
-Finding or creating the task whose key goes in the scope — [`task-tracking`](../task-tracking/SKILL.md).
+Naming the branch, and finding or creating the task whose key goes in the scope —
+[`task-tracking`](../task-tracking/SKILL.md).
 
 ## Owns
 
-Canonical for: commit message grammar, branch and PR-title rules, and the boundary between
-what you write and what release-please generates. Defers task resolution to
-[`task-tracking`](../task-tracking/SKILL.md) and verification to [`quality-gates`](../quality-gates/SKILL.md).
+Canonical for: commit message grammar, PR-title rules, and the boundary between what you
+write and what release-please generates. Defers task resolution **and branch naming** to
+[`task-tracking`](../task-tracking/SKILL.md), verification to [`quality-gates`](../quality-gates/SKILL.md).
 
 ## Preflight — the rules are per-repo
 

package/skills/design-previews/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design-previews
-description: Generate three genuinely different visual directions as self-contained HTML previews, screenshot them at desktop and mobile with the Chrome DevTools MCP (or Playwright), and get the client's pick before any theme or block work starts. Use when kicking off a design, when someone asks for design options or mockups, when a brief is vague and needs something to react to, or before building a homepage or landing page. Not for auditing an existing design — use `wp-audit`.
+description: Generate three genuinely different visual directions as self-contained HTML previews, screenshot them at desktop and mobile, and get the client's pick before any theme or block work starts. Use when kicking off a design, when someone asks for design options or mockups, when a brief is vague and needs something to react to, or before building a homepage or landing page. Not for auditing an existing design — use `wp-audit`. Not for choosing a browser tool — use `browser-automation`.
 version: 1.1.0
 ---
 
@@ -27,7 +27,8 @@ and [`wp-block-conventions`](../wp-block-conventions/SKILL.md).
 ## Owns
 
 Canonical for: the brief template, how directions are differentiated, preview output rules,
-the review loop, and the handoff. Implementation belongs to the skills above.
+the review loop, and the handoff. Implementation belongs to the skills above; getting a
+browser to screenshot with belongs to [`browser-automation`](../browser-automation/SKILL.md).
 
 ## Preflight — confirm the brief first
 
@@ -68,10 +69,10 @@ three palettes of one layout still isn't.
    gitignored; the repo is `wp-content` and previews must never ship). One file per
    direction, generated in parallel when the harness supports it.
    → `design-1.html`, `design-2.html`, `design-3.html` exist and open standalone.
-3. **Screenshot each at desktop and mobile.** Prefer the **Chrome DevTools MCP** —
-   `new_page`, `navigate_page` to the `file://` path, `resize_page` or `emulate`, then
-   `take_screenshot`. Use **Playwright** when you need scripted runs or Chrome isn't
-   available. → Six images: three directions × two widths.
+3. **Screenshot each at desktop and mobile.** Get a browser via
+   [`browser-automation`](../browser-automation/SKILL.md), which owns the tool choice and its
+   order — navigate to the `file://` path, set each viewport, capture. Don't pick a browser
+   tool here. → Six images: three directions × two widths.
 4. **Present for a decision** — each direction as name, file path, screenshot, and one line
    on what makes it different. Offer exactly three responses: pick one, pick one with
    modifications, or regenerate all three.

package/skills/task-tracking/SKILL.md

@@ -1,59 +1,77 @@
 ---
 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 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
+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, scoping something that will span multiple sessions or PRs, 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. If no task exists, confirm NO-TASK and keep working; the commit scope carries the task key (e.g. LINCHPIN-5113) or NO-TASK.
+version: 1.4.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.
+**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.
+The platform is currently **ClickUp**, driven through the **ClickUp MCP** — keep the ClickUp
+specifics in the tool calls, so the workflow below survives a 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.
+- **Scoping work that won't fit one sitting** — multiple PRs, multiple sessions, or a long
+  list of distinct action items. See step 2.
 - 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 —
+**Not this skill:** the commit message grammar and release behavior —
 [`commit-and-release`](../commit-and-release/SKILL.md). Running checks before you commit —
-[`quality-gates`](../quality-gates/SKILL.md).
+[`quality-gates`](../quality-gates/SKILL.md). Which space and folder a task belongs in —
+[`engagement-types`](../engagement-types/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).
+Canonical for: resolving, creating, and updating the task; how work is split across tasks
+and subtasks; 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).
+
+## Preflight
+
+Establish three things before the first ClickUp call. None of them blocks the work:
+
+| Check | How | When it fails |
+| --- | --- | --- |
+| **Is the ClickUp MCP connected?** | Are `clickup_*` tools present in this session? | **Say so once, out loud** — "no ClickUp MCP in this session, so this is NO-TASK" — then work as NO-TASK |
+| **Is the routing pinned?** | `.clickup.json` at the repo root, else a ClickUp section in `CLAUDE.md`/`AGENTS.md` | Fall back to the hierarchy lookup in step 4, then offer to write the file |
+| **Which Space?** | Infer from the git remote or repo name (repo `linchpin.com` → Space **Linchpin**) | Widen to a scoped Space picker — never dump the whole hierarchy |
+
+**A missing MCP is a reportable condition, not a silent skip.** A user can act on "I couldn't
+reach ClickUp"; they can't act on commits that quietly say `NO-TASK`. Same for a pinned list
+id that no longer resolves — say it and re-look-up rather than falling through to the default
+list. Orientation beyond ClickUp is [`project-context`](../project-context/SKILL.md), which
+defers back here for the Space.
 
 ## "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,
+Asked to create one, run the creation flow in step 4. 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.
+**A GitHub issue only when GitHub is named** — "open a *GitHub* issue", "`gh issue create`".
+Use `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
-  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.
+  prefixes differ per space. This is what goes in commits — **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
@@ -66,187 +84,153 @@ Try these in order; stop at the first that succeeds:
    `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.
+   `clickup_search` (or `clickup_filter_tasks`), narrowed to the Space you established in
+   Preflight so you don't trawl the whole workspace. 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.** `AskUserQuestion` with three ways out: **work as
+   NO-TASK** (recommended for quick/throwaway work), **create a task now** (the flow in step
+   4), or 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**.
+Record the resolved key (or `NO-TASK`) and reuse it for every commit in this unit of work.
+When you open a local TODO with `TaskCreate`, put the key in the task text so the local list
+and ClickUp stay aligned.
 
-### 2. Before committing, if NO-TASK — offer to create one
+### 2. Right-size the tracking (before cutting the branch)
 
-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?"**
+One task is the default and usually right. But when scoping reveals work that will
 
-- **No** → commit with `NO-TASK`.
-- **Yes** → run the creation flow, then commit with the new key.
+- **span more than one session**, or plausibly **exhaust this context window**, or
+- need **more than one PR**, or
+- carry **a large number of distinct action items**,
 
-Don't ask repeatedly and don't nag — one prompt at commit time.
+then one task can't hold the state, and a plan that lives only in the chat dies with the
+session. Confirm the shape with the user — once, with `AskUserQuestion`:
 
-### 3. Creation flow (least friction)
+| Shape | Use when | How |
+| --- | --- | --- |
+| **One task** | Multi-step, but one sitting and one PR | The default; nothing extra to do |
+| **Parent + a subtask per step** | Steps land in separate commits or PRs, or someone else may pick one up | Create the parent, then each subtask via `clickup_create_task`'s `parent` |
+| **Keep the plan local** | Exploratory work whose shape will change | `TaskCreate` only — revisit if it grows |
+
+- **Every item carries its own "done when"** in its description. A subtask named "Fix the
+  thing" with no acceptance line is a reminder, not a handoff.
+- **The scope key is the parent's**, unless a subtask genuinely owns its own PR — then that
+  subtask's key scopes those commits and the parent tracks the whole.
+- **Splitting late is fine.** If one task turns out bigger than it looked, come back here.
+
+### 3. 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. One prompt at commit
+time; don't nag.
 
-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.
+### 4. Creation flow (least friction)
+
+Reached three ways: from step 2 (splitting a larger endeavor), from step 3 (a NO-TASK change
+about to be committed), or directly, when someone just says *"create an issue/task for X"* —
+a standalone request needing no commit or branch behind it.
 
 `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
+1. **Use the routing you found in Preflight.** `.clickup.json` pins the Space, a default
+   list, and often a source-directory → list map — confirm the destination in one line
+   ("Create in *Mantle › Modules › Security*?") rather than making the user navigate.
+2. **Otherwise build a scoped picker** from `clickup_get_workspace_hierarchy` — see
+   [`references/clickup-json.md`](references/clickup-json.md) for both paths.
+3. **Name + details:** default `name` to the commit subject / work summary and confirm.
+   Optionally `assignees: ["me"]` (via `clickup_resolve_assignees`), a `priority`, and a
+   `markdown_description` — which is where the "done when" line goes.
+4. `clickup_create_task`, then **read the key back with `clickup_get_task`.** The create
+   response carries `custom_id` inconsistently — often `null`, because the key is assigned
+   after the task exists. `null` means "not yet", never "this space has no keys", so don't
+   fall back to the internal id as your commit scope.
+
+### 5. 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.
+1. **Comment with the pointer.** `clickup_create_comment` with the PR URL and a one-line
+   summary. This is what makes the task useful to whoever picks it up next — do it even if
+   you can't move the status.
+2. **Move the status, but read the valid ones first** (`expand_statuses: true`, or
+   `clickup_get_list`). They're per-Space/List and there can be dozens. If none obviously
+   matches the state ("PR open, awaiting review"), ask rather than guess.
+3. **Don't close what you can't verify.** An open PR is *in review*, not done — terminal
+   statuses need the user's word or a deploy you observed.
+4. **Subtasks close as they land; the parent closes last.** Moving a parent while its
+   subtasks are open is the same lie as never moving anything.
+5. **Time tracking is opt-in** — `clickup_add_time_entry` only when asked.
 
 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>
-```
+### 6. Session handoff (when you stop mid-flight)
 
-Rules that keep this useful:
+When work pauses unfinished, the state belongs on the task — not in a local file and not in
+the chat. Post one `clickup_create_comment` covering **done / in progress / open decisions /
+where (branch, PR, environment) / next step**, written for someone who wasn't here, and
+commit or stash first so it points at something real.
 
-- **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)).
+Template and the rules that make it actionable: [`references/handoff.md`](references/handoff.md).
 
-## Conventional commits
+## Scope, branch & PR
 
-**Scope = the task key or `NO-TASK`.** That is this skill's half of the message:
+**Scope = the task key or `NO-TASK`.** That is this skill's half of the commit 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.
+Everything else — allowed types, sentence case, punctuation limits, breaking changes, release
+commits — is [`commit-and-release`](../commit-and-release/SKILL.md). One note about the *key*
+rather than the grammar: a trailing PR number (`… (#758)`) is appended by the PR/release flow,
+not by hand.
+
+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`: **`issue/<custom_id>`** — the ClickUp
+  custom ID verbatim (`issue/LINCHPIN-5113`), never the internal id and never a slug. Without
+  a task, **`no-task/<short-kebab-slug>`**, since a bare `issue/no-task` would collide. Created
+  a task after starting NO-TASK? `git branch -m issue/<custom_id>`.
+- **The PR body links the ClickUp task** — paste `https://app.clickup.com/t/<custom_id>` and
+  the key so GitHub ↔ ClickUp stay connected; for NO-TASK, note there's no task. The title
+  follows the commit convention, whose grammar is `commit-and-release`'s.
+- 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.
+- **Pin the routing per project in `.clickup.json`** — the Space, a default list, and (where
+  the board mirrors the code) a directory → list map, so creation is a one-line confirm
+  instead of navigation. Schema, worked example, and packaging notes:
+  [`references/clickup-json.md`](references/clickup-json.md). The ids live in that project's
+  repo, never in this shared library.
+- **Write the file when you had to look it up.** Resolving a list the slow way is the moment
+  to offer to pin it — otherwise the next agent pays the same cost.
 - **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
-
-- **"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`).
-- **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 |
+- **Batch the questions** — task-vs-NO-TASK, the split shape, and the list in as few
+  `AskUserQuestion` prompts as possible.
+
+Call signatures for every step: [`references/clickup-mcp-tools.md`](references/clickup-mcp-tools.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";
-  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 invent a task key**, and never fall back to the internal id (`86badg2te`) because
+  the create call returned `custom_id: null` — read it back. Unresolvable means `NO-TASK`.
+- **Never assume the custom-ID prefix** — it's Space-specific; read it off the task rather
+  than reaching for `LINCHPIN-` on non-Linchpin work.
+- **Never claim a task exists that you didn't create.** A missing MCP or a failed call gets
+  said out loud, not treated as though the board was updated.
+- **Never block the user** waiting for a task decision. NO-TASK is always available and is
+  not a failure state; offer creation, accept "no", move on.
+- **Never mark a task complete** on your own judgment, and **never guess a status name** —
+  they're Space-specific. An open PR is at most "in review".
 - **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`.
@@ -254,12 +238,16 @@ Work happens on a dedicated branch opened as a PR against the base branch (usual
 
 ## Done
 
+- [ ] Preflight ran: MCP availability, routing, and Space established — and any failure was
+      **said out loud** rather than silently downgraded.
 - [ ] 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.
-- [ ] The PR body links `app.clickup.com/t/<KEY>` (or notes there is no task).
+- [ ] The unit of work has a resolved task key or an explicit, user-accepted `NO-TASK`, read
+      back from `custom_id` rather than taken from an internal id.
+- [ ] Work spanning sessions, contexts, or PRs was split deliberately with the user, and
+      every task or subtask carries a "done when".
+- [ ] The branch matches the key (`issue/<custom_id>` or `no-task/<slug>`), every commit on it
+      carries the same scope, and the PR body links `app.clickup.com/t/<custom_id>`.
 - [ ] 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

package/skills/task-tracking/references/clickup-json.md

@@ -0,0 +1,139 @@
+# `.clickup.json` — per-project ClickUp routing
+
+A small file at a project's repo root that pins **where this project's tasks live**, so
+creating one is a single confirmation instead of a workspace-hierarchy crawl across dozens of
+spaces.
+
+The **convention** is portable and lives here. The **IDs** are project-specific and live in
+that project's repo — never in this library.
+
+## Why it exists
+
+Without it, every "create a task for X" starts the same way: call
+`clickup_get_workspace_hierarchy`, guess the Space from the repo name, page through folders,
+and rediscover the same handful of list IDs that were found last week. That's slow, it burns
+context, and it produces inconsistent placement when the guess is wrong.
+
+With it, the flow is: read the file, confirm the list in one line, create.
+
+## Where to look
+
+Check in this order, and stop at the first hit:
+
+1. `.clickup.json` at the repo root
+2. A ClickUp section in the project's `CLAUDE.md` / `AGENTS.md`
+3. Nothing pinned → fall back to the hierarchy lookup in the main skill, and **offer to write
+   `.clickup.json`** once the list has been resolved, so the next agent doesn't repeat the work
+
+## When nothing is pinned — the picker
+
+Falling back to a lookup is fine; doing it unscoped is not. `clickup_get_workspace_hierarchy`
+will happily return dozens of spaces and bury the prompt.
+
+1. Call it with `max_depth: 2` and **`space_ids` set to the likely Space**, so you get Folders
+   + Lists for one space rather than the whole workspace.
+2. Offer the candidate Lists via `AskUserQuestion` — e.g. `linchpin.com › Development`,
+   `linchpin.com › Deploy`, `Internal Projects › …`.
+3. Only widen to a Space picker first when the Space genuinely can't be inferred from the git
+   remote or repo name.
+
+Then write the file, so the next agent skips all of this.
+
+## Schema
+
+Every field is optional except `space` and `defaultList` — a two-key file is already useful.
+
+| Key | Type | Purpose |
+| --- | --- | --- |
+| `space` | object | `id`, `name`, and `customIdPrefix` (e.g. `MANTLE` — the prefix on custom IDs, used to sanity-check a key before putting it in a commit scope) |
+| `defaultList` | object | `id`, `name`, `path`, and a `use` string saying what belongs there. The fallback for anything that doesn't route elsewhere |
+| `lists` | object | Human list name → list id. Flat map; use `›` in the name for nesting when two lists share a name |
+| `folders` | object | Human folder name → folder id. Only needed when a tool call wants a folder rather than a list |
+| `moduleRouting` | object | Source directory → list **name** (a key in `lists`). For repos whose board mirrors their code structure |
+| `unmapped` | object | Deliberate code↔board mismatches, recorded so they read as intentional rather than as failed lookups |
+
+Two rules that matter more than the shape:
+
+- **IDs are the contract; names are for humans.** ClickUp list names get renamed freely and
+  the id survives it. Route on the id, show the name.
+- **`moduleRouting` points at names, not ids** — so a renamed list is a one-line fix in
+  `lists` rather than a find-and-replace through the routing map.
+
+## Example
+
+Trimmed from a real plugin repo whose ClickUp board has one list per code module:
+
+```json
+{
+  "$comment": "ClickUp routing for this repo. IDs are workspace-stable; names are for humans.",
+  "space": {
+    "id": "90140515528",
+    "name": "Mantle",
+    "customIdPrefix": "MANTLE"
+  },
+  "defaultList": {
+    "id": "901401607739",
+    "name": "Product Roadmap",
+    "path": "Mantle › Product Roadmap",
+    "use": "Cross-cutting work, new modules, and anything that doesn't map to a single existing module."
+  },
+  "lists": {
+    "Product Roadmap": "901401607739",
+    "Housekeeping": "901414301271",
+    "Optimizations": "901413938412",
+    "Security": "901413938417",
+    "Declutter": "901413954051"
+  },
+  "folders": {
+    "Modules": "90147467026"
+  },
+  "moduleRouting": {
+    "$comment": "includes/Modules/<Dir> → list name. Fall back to defaultList.",
+    "Optimizations": "Optimizations",
+    "Security": "Security"
+  },
+  "unmapped": {
+    "modulesWithoutList": [
+      "Maintenance — no dedicated list; use Product Roadmap"
+    ],
+    "listsWithoutModule": [
+      "Declutter — intended home for admin-menu tidying; no module exists yet"
+    ]
+  }
+}
+```
+
+`$comment` keys are ignored by every JSON parser and are the only way to annotate JSON —
+use them, since this file is read by people as often as by agents.
+
+## `unmapped` is the part people skip
+
+A board and a codebase drift apart. A list gets created for work that was never built; a
+module ships without anyone adding a list for it. An agent that finds no route for
+`includes/Modules/Maintenance` can't tell "nobody added it" from "I looked in the wrong
+place", so it either asks a pointless question or files the task somewhere wrong.
+
+Recording the mismatch converts a lookup failure into a documented decision. Keep it honest
+and prune it when the gap closes.
+
+## Packaging
+
+Projects that build a distributable — WordPress plugins and themes especially — should
+exclude the file from the build:
+
+- `.distignore` for `wp dist-archive` / plugin zips
+- `.npmignore` or a `files` allowlist for npm packages
+
+It's dev-time metadata with no runtime meaning. It contains no secrets — workspace, folder,
+and list IDs are not credentials, and the ClickUp API still requires a token — so it can be
+committed to a private repo without concern. Treat it the same as any other project config
+in a public repo: harmless, but pointless to publish.
+
+## Keeping it current
+
+- A renamed list keeps its id — nothing to do.
+- A **new** list, or one that gets retired, needs the map updated. Cheapest moment is when
+  you notice the drift while creating a task; fix it in the same PR.
+- If a lookup by the pinned id fails, the list was deleted or moved out of the space. Re-run
+  the hierarchy lookup, correct the file, and say so — don't silently fall back to the
+  default list, or tasks quietly pile up in the wrong place.

package/skills/task-tracking/references/clickup-mcp-tools.md

@@ -0,0 +1,37 @@
+# ClickUp MCP — call signatures
+
+The tool for each step of the workflow in [`../SKILL.md`](../SKILL.md). Names are the ClickUp
+MCP's; if these tools aren't in the session, the workflow's Preflight says what to do instead.
+
+| 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) |
+| Create a subtask | `clickup_create_task` with `parent: <parent task id>` |
+| Read the key back | `clickup_get_task` → `custom_id` |
+| List valid statuses | `clickup_get_task` with `expand_statuses: true`, or `clickup_get_list` |
+| 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 |
+
+## Two that bite
+
+**`custom_id` is assigned after creation.** `clickup_create_task` returns `custom_id: null`
+much of the time — the key exists moments later. Always `clickup_get_task` before using a key
+as a commit scope, and never read `null` as "this space doesn't use custom IDs".
+
+**Statuses are per-Space/List and there are often dozens** — a single Linchpin list carries
+open, unstarted, custom, done, and closed variants (`needs estimate`, `needs peer/code
+review`, `in qa/testing`, `blocked by client`, `resolved`, `complete`, …). Read them; never
+guess a name, and never assume `complete` is the only terminal one.
+
+## Escaping note for editors of this file
+
+The pipe in the commit row is escaped (`\|`). GFM splits table cells on pipes **even inside
+code spans**, so an unescaped one silently truncates the cell.

package/skills/task-tracking/references/handoff.md

@@ -0,0 +1,40 @@
+# Session handoff
+
+What to post on a task when work pauses unfinished — end of day, a context switch, running
+low on context, or handing to someone else. Step 6 of [`../SKILL.md`](../SKILL.md).
+
+The task is where the state belongs. Not a local file, not the chat: the task is what a
+teammate opens.
+
+## The comment
+
+One `clickup_create_comment`, these five things, 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 it useful
+
+- **Write it for someone who wasn't here.** No "as discussed", no pronouns pointing at chat
+  history, no "the file we changed".
+- **Be honest about what's unfinished.** A handoff that overstates progress costs more than
+  no handoff — the next person trusts it and builds on sand.
+- **One handoff per pause, not a running log.** Supersede the previous one by posting a fresh
+  comment rather than editing history, so the newest comment is always current.
+- **Uncommitted work is not a handoff.** Commit or stash first and say which, per
+  [`commit-and-release`](../../commit-and-release/SKILL.md). A handoff pointing at a dirty
+  working tree on someone else's machine is not actionable.
+- **On a parent + subtasks split, the handoff goes on the parent** and names the subtask in
+  flight — so one comment still answers "where is this?" without opening every child.
+
+## Why the "Next step" line carries the most weight
+
+Everything above it is context; that line is the only part that gets someone moving. "Finish
+the migration" fails the test. "Run `npm run validate` — it fails on `wp-audit`'s missing
+README row; add the row and re-run" passes: the next person starts without rereading anything.

package/skills/wp-audit/SKILL.md

@@ -35,8 +35,8 @@ the code being changed.
 | 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 |
+| Production / staging | A real browser via [`browser-automation`](../browser-automation/SKILL.md) 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-automation`](../browser-automation/SKILL.md) 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.

package/skills/wp-local-setup/SKILL.md

@@ -51,68 +51,14 @@ Target shape (the repo root doubles as `wp-content`):
   .gitignore                   # allowlist pattern — see below
 ```
 
-### composer.json baseline
-
-```json
-{
-  "name": "linchpin/<project>",
-  "repositories": [
-    { "type": "composer", "url": "https://wpackagist.org" },
-    { "type": "composer", "url": "https://packagist.linchpin.com" }
-  ],
-  "require": {
-    "php": ">=8.2"
-  },
-  "require-dev": {
-    "composer/installers": "^2"
-  },
-  "extra": {
-    "installer-paths": {
-      "plugins/{$name}/": ["type:wordpress-plugin"],
-      "themes/{$name}/": ["type:wordpress-theme"]
-    }
-  }
-}
-```
+### composer.json and .gitignore baselines
 
-- wordpress.org plugins/themes → `wpackagist-plugin/<slug>` / `wpackagist-theme/<slug>`.
-- Premium or shared-private packages → `linchpin/<slug>` from packagist.linchpin.com.
-- A plugin built **only for this client** is committed to `plugins/` instead (and
-  allowlisted in `.gitignore`).
-- Which plugins a project needs is project-specific — don't copy another site's list.
-- Mature projects add the PHP QA stack to `require-dev` (`wp-coding-standards/wpcs`,
-  `phpstan/phpstan` + `szepeviktor/phpstan-wordpress`, `php-parallel-lint/php-parallel-lint`,
-  `friendsofphp/php-cs-fixer`) — mirror `linchpin/linchpin.com` when setting that up.
-
-### .gitignore baseline (allowlist pattern)
-
-Ignore everything Composer or the runtime writes; explicitly re-include what's ours:
-
-```gitignore
-# Plugins/themes are Composer-installed — commit only project code
-/plugins/*
-!plugins/<project>-functionality/
-!plugins/<project>-functionality/**
-/themes/*
-!themes/<project>/
-!themes/<project>/**
-/vendor
-node_modules
-
-# WordPress runtime
-debug.log
-/uploads/
-/upgrade/
-
-# WordPress Studio runtime (SQLite) — never commit these
-db.php
-/database
-/mu-plugins/sqlite-database-integration
-mu-plugins/99-studio-loader.php
-```
+Both templates, the package-name conventions for each dependency source, and the allowlist
+trap: [`references/scaffold-baselines.md`](references/scaffold-baselines.md).
 
-Adding a new **committed** plugin later requires a new `!plugins/<name>/` pair —
-otherwise the `/plugins/*` rule silently keeps it out of git.
+Two things worth knowing before you open it: **which plugins a project needs is
+project-specific** — don't copy another site's list — and the `.gitignore` is an *allowlist*,
+so every committed plugin needs its own re-include pair or git silently ignores it.
 
 ### The project theme
 
@@ -203,19 +149,6 @@ correct. From here, day-to-day operation is `wp-studio-cli`.
 - **Media isn't in git** (`/uploads/` is ignored). Getting real content/uploads locally
   is per-project — check that project's docs.
 
-## Quick reference
-
-| Task | Command |
-| --- | --- |
-| Start the project theme | see [`wp-theme-baseline`](../wp-theme-baseline/SKILL.md) — child / fresh / fork |
-| Install plugins | `composer install` (repo root) |
-| Add a wordpress.org plugin | `composer require wpackagist-plugin/<slug>` |
-| Add a premium/shared plugin | `composer require linchpin/<slug>` (packagist.linchpin.com) |
-| Build the theme (if it has a build) | `npm run build` in `themes/<project>` (`npm start` to watch) |
-| Symlink repo into Studio | `mv <site>/wp-content <site>/wp-content-studio-default && ln -s <repo> <site>/wp-content` |
-| Start the site | `studio start --skip-browser --path ~/Studio/<project>` |
-| Activate the theme | `studio wp theme activate <project> --path ~/Studio/<project>` |
-| Site URL + credentials | `studio site status --path ~/Studio/<project> --format json` |
 
 ## Guardrails
 
@@ -231,7 +164,8 @@ correct. From here, day-to-day operation is `wp-studio-cli`.
 - **Never commit Composer-installed plugins/themes** — `installer-paths` writes into
   gitignored directories by design.
 - Don't hand-edit versions or `CHANGELOG.md` in a scaffolded repo — release-please owns
-  them ([`commit-and-release`](../commit-and-release/SKILL.md)).
+  them ([`commit-and-release`](../commit-and-release/SKILL.md)), and tie the setup work to a
+  task before committing ([`task-tracking`](../task-tracking/SKILL.md)).
 
 ## Done
 
@@ -241,14 +175,3 @@ correct. From here, day-to-day operation is `wp-studio-cli`.
       and the SQLite runtime pieces intact.
 - [ ] The site loads, the project theme is active, and the admin URL/credentials are known.
 - [ ] `.gitignore` allowlists only project code; `git status` is clean of vendored plugins.
-
-## Related skills
-
-- [`wp-theme-baseline`](../wp-theme-baseline/SKILL.md) — choosing and standing up the project
-  theme that lands in `themes/<project>/`.
-- [`wp-studio-cli`](../wp-studio-cli/SKILL.md) — operating the running Studio site (WP-CLI
-  passthrough, `eval`, the PHP-WASM `ABSPATH` rule).
-- [`wp-pressable`](../wp-pressable/SKILL.md) — the hosted environments this baseline deploys
-  to, and the release-please → `linchpin/actions` pipeline.
-- [`task-tracking`](../task-tracking/SKILL.md) — tie the setup work to a ClickUp task before
-  committing.

package/skills/wp-local-setup/references/scaffold-baselines.md

@@ -0,0 +1,83 @@
+# Scaffold baselines — `composer.json` and `.gitignore`
+
+The two file templates a new Linchpin WordPress project repo starts from. Copy, substitute
+`<project>`, then follow Part 1 of [`../SKILL.md`](../SKILL.md).
+
+Both encode the same premise: **the repo is `wp-content`**, plugins and themes arrive via
+Composer, and only project-specific code is committed.
+
+## `composer.json`
+
+```json
+{
+  "name": "linchpin/<project>",
+  "repositories": [
+    { "type": "composer", "url": "https://wpackagist.org" },
+    { "type": "composer", "url": "https://packagist.linchpin.com" }
+  ],
+  "require": {
+    "php": ">=8.2"
+  },
+  "require-dev": {
+    "composer/installers": "^2"
+  },
+  "extra": {
+    "installer-paths": {
+      "plugins/{$name}/": ["type:wordpress-plugin"],
+      "themes/{$name}/": ["type:wordpress-theme"]
+    }
+  }
+}
+```
+
+Where dependencies come from:
+
+| Source | Package name | Command |
+| --- | --- | --- |
+| wordpress.org plugin | `wpackagist-plugin/<slug>` | `composer require wpackagist-plugin/<slug>` |
+| wordpress.org theme | `wpackagist-theme/<slug>` | `composer require wpackagist-theme/<slug>` |
+| Premium / shared-private | `linchpin/<slug>` | `composer require linchpin/<slug>` |
+| Built only for this client | *not a dependency* | Commit it to `plugins/` and allowlist it below |
+
+- **Which plugins a project needs is project-specific** — don't copy another site's list.
+- `installer-paths` writes into `plugins/` and `themes/`, which are gitignored. That's by
+  design; CI runs `composer install` at deploy time.
+- Mature projects add the PHP QA stack to `require-dev`: `wp-coding-standards/wpcs`,
+  `phpstan/phpstan` + `szepeviktor/phpstan-wordpress`, `php-parallel-lint/php-parallel-lint`,
+  `friendsofphp/php-cs-fixer`. Mirror an existing repo that already has it configured rather
+  than assembling the versions from scratch.
+
+## `.gitignore` (allowlist pattern)
+
+Ignore everything Composer or the runtime writes; explicitly re-include what's ours:
+
+```gitignore
+# Plugins/themes are Composer-installed — commit only project code
+/plugins/*
+!plugins/<project>-functionality/
+!plugins/<project>-functionality/**
+/themes/*
+!themes/<project>/
+!themes/<project>/**
+/vendor
+node_modules
+
+# WordPress runtime
+debug.log
+/uploads/
+/upgrade/
+
+# WordPress Studio runtime (SQLite) — never commit these
+db.php
+/database
+/mu-plugins/sqlite-database-integration
+mu-plugins/99-studio-loader.php
+```
+
+**The allowlist is the part that bites.** Adding a new *committed* plugin later requires its
+own `!plugins/<name>/` **and** `!plugins/<name>/**` pair — without both, the `/plugins/*` rule
+silently keeps it out of git and the omission usually surfaces at deploy.
+
+The Studio block matters just as much in the other direction: those four paths are the local
+SQLite database layer. Committing them ships a `db.php` drop-in that shadows a real host's
+MySQL configuration.

package/skills/wp-studio-cli/SKILL.md

@@ -27,6 +27,11 @@ the fallback and the scripting route.
 [`wp-audit`](../wp-audit/SKILL.md). A legacy project on wp-env or LocalWP — use that
 project's tooling ([`quality-gates`](../quality-gates/SKILL.md) detects which).
 
+`take_screenshot` and `inspect_design` below are **Studio's own**, rendering PHP-WASM rather
+than driving a browser — enough for markup and layout checks. When you need a *real* browser
+against the Studio URL (actual session state, extensions, console and network behaviour), get
+one via [`browser-automation`](../browser-automation/SKILL.md).
+
 ## Preflight — pick the interface
 
 1. **Try MCP first.** A cheap call like `site_list` confirms it's connected.

package/skills/write-a-linchpin-skill/SKILL.md

@@ -61,6 +61,13 @@ hand-roll this parse and drift"). If you can't name one, drop to B.
 Most skills here are **A or B**. `wordpress-blocks` is the reference B (recipes and grammar
 live in `references/`); this library's own `scripts/validate-skills.mjs` is the C pattern.
 
+**What the validator checks:** a body over **200 lines with no `references/` at all** warns —
+that combination is Tier B content held in Tier A. Length alone is never the fault;
+`wordpress-blocks` runs 877 lines across its package and passes, because the
+reference-shaped parts were promoted. **Don't compress prose to clear this warning** —
+promote the templates, command matrices, and schemas. That's the only fix that improves the
+skill rather than just the number.
+
 ## Step 3 — Write `SKILL.md`
 
 ### Frontmatter (all required)