@linchpinagency/skills 0.1.6 → 0.1.8

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.6
+### Latest release: 0.1.8
 <!-- 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` |
@@ -190,6 +191,33 @@ npx @linchpinagency/skills --skip-upstream
 **Updating:** re-run the same command. The installer overwrites each skill in place, so a
 fresh run always pulls the latest published version.
 
+### Keeping skills current
+
+Installed skills are a snapshot — nothing about a copy in `.claude/skills/` knows a newer
+release exists. So every install writes a stamp beside the skills, in
+`<skills-dir>/.linchpin-skills/`: `version.json` (the version, the date, the agent, the exact
+command that produced the install, and the upstream ref that was vendored) plus a
+self-contained copy of the update checker.
+
+```bash
+# Are these skills behind? One line if yes, nothing if no.
+node .claude/skills/.linchpin-skills/update-check.mjs
+
+# Print the Claude Code SessionStart hook that runs it for you
+node .claude/skills/.linchpin-skills/update-check.mjs --hook
+```
+
+With the hook installed, a stale install announces itself at the start of a session —
+`SessionStart` stdout becomes context, so the agent sees it too and can offer to run the
+update command the stamp recorded. Hooks are a Claude Code feature; under Copilot, Codex, or
+Cursor the same check still runs, just when you ask it to.
+
+The check is deliberately unobtrusive: it queries the npm registry at most once a day (a
+known-newer version keeps surfacing from cache in between), stays silent when it can't reach
+the network, and always exits 0 — a session never fails to start because of it. It reports;
+it never upgrades anything. Set `LINCHPIN_SKILLS_UPDATE_CHECK=0` to switch it off, and it
+skips itself whenever `CI` is set.
+
 ### Where skills land
 
 | Agent (`--agent`) | Project scope | Global scope (`--global`) |
@@ -232,7 +260,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/bin/install.mjs

@@ -15,6 +15,13 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(__dirname, '..');
 const SKILLS_ROOT = path.join(PKG_ROOT, 'skills');
 const UPSTREAM_MANIFEST = path.join(PKG_ROOT, 'upstream.json');
+const PKG_MANIFEST = path.join(PKG_ROOT, 'package.json');
+
+// Version stamp + a self-contained copy of the update checker, written into each install
+// directory. Dot-prefixed and without a SKILL.md, so no agent mistakes it for a skill.
+const STAMP_DIR = '.linchpin-skills';
+const STAMP_FILE = 'version.json';
+const CHECKER = 'update-check.mjs';
 
 // Per-agent install locations. `project` paths are relative to cwd, `global` to home.
 // These follow the Agent Skills conventions each tool reads from. An agent may read more
@@ -80,6 +87,50 @@ function readUpstreamManifest() {
   }
 }
 
+function packageVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(PKG_MANIFEST, 'utf8')).version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+// The exact command that reproduces this install, recorded in the stamp so the update
+// checker can tell someone how to re-run it with the flags they actually used.
+function updateCommand(opts) {
+  const parts = ['npx @linchpinagency/skills'];
+  if (opts.skills.length) parts.push(...opts.skills);
+  if (opts.agent !== 'claude-code') parts.push('--agent', opts.agent);
+  if (opts.global) parts.push('--global');
+  if (opts.skipUpstream) parts.push('--skip-upstream');
+  return parts.join(' ');
+}
+
+// Record what landed here and leave the checker beside it. Best-effort: a stamp we can't
+// write costs an upgrade nudge, not the install.
+function writeStamp(target, { version, opts, skills, upstream }) {
+  const dir = path.join(target.dir, STAMP_DIR);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    const stamp = {
+      package: '@linchpinagency/skills',
+      version,
+      installedAt: new Date().toISOString(),
+      agent: target.agent,
+      scope: opts.global ? 'global' : 'project',
+      updateCommand: updateCommand(opts),
+      skills,
+      upstream,
+    };
+    fs.writeFileSync(path.join(dir, STAMP_FILE), JSON.stringify(stamp, null, 2) + '\n');
+    fs.copyFileSync(path.join(__dirname, CHECKER), path.join(dir, CHECKER));
+    return true;
+  } catch (err) {
+    console.warn(`  ! Could not write the version stamp in ${dir}: ${err.message}`);
+    return false;
+  }
+}
+
 // Fetch a repo tarball at a pinned ref, extract it once, and copy the requested skill
 // dirs into every directory in `bases`. Best-effort: any failure (offline, no `tar`,
 // missing skill) warns and returns false rather than aborting the Linchpin install.
@@ -193,12 +244,15 @@ async function main() {
     process.exit(1);
   }
 
-  // One flat list of destination dirs across every selected agent.
-  const bases = agentIds.flatMap((id) =>
-    (opts.global ? AGENTS[id].global : AGENTS[id].project).map((rel) =>
-      opts.global ? path.join(os.homedir(), rel) : path.join(process.cwd(), rel)
-    )
+  // Every destination across every selected agent, each tagged with the agent it belongs to
+  // (the stamp records it; the copy loops only need the directory).
+  const targets = agentIds.flatMap((id) =>
+    (opts.global ? AGENTS[id].global : AGENTS[id].project).map((rel) => ({
+      agent: id,
+      dir: opts.global ? path.join(os.homedir(), rel) : path.join(process.cwd(), rel),
+    }))
   );
+  const bases = targets.map((t) => t.dir);
 
   const wanted = opts.skills.length ? opts.skills : all;
   const unknown = wanted.filter((s) => !all.includes(s));
@@ -221,11 +275,26 @@ async function main() {
   const labels = agentIds.map((id) => AGENTS[id].label).join(', ');
   console.log(`\nInstalled ${wanted.length} Linchpin skill(s) for ${labels}.`);
 
+  const upstream = [];
   if (!opts.skipUpstream && sources.length) {
     console.log('\nVendoring pinned base layer (upstream WordPress/agent-skills):');
-    for (const s of sources) await installUpstreamSource(s, bases);
+    for (const s of sources) {
+      const installed = await installUpstreamSource(s, bases);
+      upstream.push({ repo: s.repo, ref: s.ref, installed });
+    }
     console.log('\nTip: --skip-upstream installs Linchpin skills only.');
   }
+
+  // Stamp last, so `upstream` reflects what actually landed rather than what was intended.
+  const version = packageVersion();
+  const stamped = targets.filter((t) => writeStamp(t, { version, opts, skills: wanted, upstream }));
+  if (stamped.length && agentIds.includes('claude-code')) {
+    const rel = path.join(STAMP_DIR, CHECKER);
+    console.log(
+      `\nStamped v${version}. To be told when these skills go stale, add a SessionStart hook:` +
+        `\n  node ${path.join(opts.global ? '~/.claude/skills' : '.claude/skills', rel)} --hook`
+    );
+  }
 }
 
 main();

package/bin/update-check.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// @linchpinagency/skills — installed-version check.
+//
+// Prints ONE line when a newer release is published, and nothing at all otherwise. Exits 0
+// on every path — offline, unwritable cache, missing stamp, malformed JSON — because this is
+// meant to be wired into a Claude Code `SessionStart` hook, where stdout becomes session
+// context. A failure here must never be the first thing an agent reads.
+//
+//   node .claude/skills/.linchpin-skills/update-check.mjs
+//   node .claude/skills/.linchpin-skills/update-check.mjs --force   # ignore the throttle
+//   node .claude/skills/.linchpin-skills/update-check.mjs --json    # always emit a status
+//   node .claude/skills/.linchpin-skills/update-check.mjs --hook    # print the hook snippet
+//
+// Off switch: LINCHPIN_SKILLS_UPDATE_CHECK=0. Also silent when CI is set.
+//
+// `bin/install.mjs` copies this file next to the `version.json` stamp it writes, so the
+// installed copy is self-contained — it reads the stamp as a sibling, not from the package.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PKG = '@linchpinagency/skills';
+// Overridable so this is testable offline, and usable behind a private registry mirror.
+const REGISTRY = process.env.LINCHPIN_SKILLS_REGISTRY || `https://registry.npmjs.org/${PKG}/latest`;
+const THROTTLE_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 3000;
+const OFF = new Set(['0', 'false', 'off', 'no']);
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The installed version, from the stamp `install.mjs` wrote alongside this file. Falls back
+ * to the package's own version so the script is still exercisable from a checkout, where no
+ * install stamp exists.
+ */
+function readStamp() {
+  const stamp = readJson(path.join(HERE, 'version.json'));
+  if (stamp?.version) return stamp;
+  const pkg = readJson(path.join(HERE, '..', 'package.json'));
+  if (pkg?.version) return { version: pkg.version, updateCommand: `npx ${PKG}`, source: 'package' };
+  return null;
+}
+
+function cacheFile() {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(base, 'linchpin-skills', 'update-check.json');
+}
+
+function readCache() {
+  const c = readJson(cacheFile());
+  return typeof c?.checkedAt === 'number' && c.latest ? c : null;
+}
+
+function writeCache(entry) {
+  try {
+    const file = cacheFile();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(entry) + '\n');
+  } catch {
+    // A read-only or missing HOME just means we check again next time.
+  }
+}
+
+async function fetchLatest() {
+  try {
+    const res = await fetch(REGISTRY, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      headers: { accept: 'application/json' },
+    });
+    if (!res.ok) return null;
+    const { version } = await res.json();
+    return typeof version === 'string' ? version : null;
+  } catch {
+    return null; // offline, DNS, timeout, private registry — all the same answer here.
+  }
+}
+
+/** -1 / 0 / 1. Release beats prerelease at the same core version; build metadata ignored. */
+function compareVersions(a, b) {
+  const parse = (v) => {
+    const [core, pre = ''] = String(v).trim().replace(/^v/, '').split('+')[0].split('-');
+    const parts = core.split('.').map((n) => Number.parseInt(n, 10));
+    return { nums: [0, 1, 2].map((i) => (Number.isFinite(parts[i]) ? parts[i] : 0)), pre };
+  };
+  const A = parse(a);
+  const B = parse(b);
+  for (let i = 0; i < 3; i++) {
+    if (A.nums[i] !== B.nums[i]) return A.nums[i] < B.nums[i] ? -1 : 1;
+  }
+  if (A.pre === B.pre) return 0;
+  if (!A.pre) return 1;
+  if (!B.pre) return -1;
+  return A.pre < B.pre ? -1 : 1;
+}
+
+async function evaluate({ force }) {
+  if (OFF.has(String(process.env.LINCHPIN_SKILLS_UPDATE_CHECK ?? '').toLowerCase())) {
+    return { status: 'disabled', reason: 'LINCHPIN_SKILLS_UPDATE_CHECK' };
+  }
+  // No human reads a CI log for upgrade nudges, and headless runs shouldn't reach the network.
+  if (process.env.CI && !force) return { status: 'disabled', reason: 'CI' };
+
+  const stamp = readStamp();
+  if (!stamp) return { status: 'unknown', reason: 'no-version-stamp' };
+
+  // Throttle the network call, not the message: a known-newer version keeps surfacing on
+  // later sessions from cache, so the nudge survives without re-hitting the registry.
+  const cache = force ? null : readCache();
+  const cached = cache && Date.now() - cache.checkedAt < THROTTLE_MS;
+  const latest = cached ? cache.latest : await fetchLatest();
+  if (!latest) return { status: 'unknown', reason: 'registry-unreachable', installed: stamp.version };
+  if (!cached) writeCache({ checkedAt: Date.now(), latest });
+
+  const command = stamp.updateCommand || `npx ${PKG}`;
+  const result = { installed: stamp.version, latest, command, installedAt: stamp.installedAt ?? null };
+  return compareVersions(latest, stamp.version) > 0
+    ? { status: 'update-available', ...result }
+    : { status: 'up-to-date', ...result };
+}
+
+function hookSnippet() {
+  const run =
+    'f=.claude/skills/.linchpin-skills/update-check.mjs; ' +
+    '[ -f "$f" ] || f=$HOME/.claude/skills/.linchpin-skills/update-check.mjs; ' +
+    '[ -f "$f" ] && node "$f" || true';
+  return `{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [{
+          "type": "command",
+          "command": ${JSON.stringify(`bash -c '${run}'`)},
+          "timeout": 10
+        }]
+      }
+    ]
+  }
+}`;
+}
+
+function printHook() {
+  console.log(`Add to .claude/settings.json (project) or ~/.claude/settings.json (global):\n`);
+  console.log(hookSnippet());
+  console.log(`
+The command prefers the project install and falls back to the global one, and swallows its
+own failures — a session never fails to start because of this check.`);
+}
+
+function help() {
+  console.log(
+    `
+${PKG} — report when the installed skills are behind the published release.
+
+Usage:
+  node update-check.mjs [options]
+
+Options:
+  --force    Ignore the 24h throttle (and the CI opt-out) and query the registry now
+  --json     Always print a status object, even when up to date
+  --hook     Print the Claude Code SessionStart hook snippet that runs this check
+  -h, --help Show this help
+
+Environment:
+  LINCHPIN_SKILLS_UPDATE_CHECK=0   Disable the check entirely
+  LINCHPIN_SKILLS_REGISTRY=<url>   Query a different registry endpoint
+
+Prints one line when an update is available, nothing otherwise. Always exits 0.
+`.trimStart()
+  );
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) return help();
+  if (args.includes('--hook')) return printHook();
+
+  const asJson = args.includes('--json');
+  const result = await evaluate({ force: args.includes('--force') });
+
+  if (asJson) return console.log(JSON.stringify(result));
+  if (result.status !== 'update-available') return;
+
+  const when = result.installedAt ? ` (installed ${String(result.installedAt).slice(0, 10)})` : '';
+  console.log(
+    `Linchpin skills ${result.installed} → ${result.latest} available${when}. Update with: ${result.command}`
+  );
+}
+
+main().catch(() => {}); // Never let this be the reason a session start fails.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linchpinagency/skills",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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.