@linchpinagency/skills 0.1.7 → 0.1.9

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.7
+### Latest release: 0.1.9
 <!-- x-release-please-end -->
 
 | Release | Skill standard | Install |
@@ -191,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`) |

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.7",
+  "version": "0.1.9",
   "description": "Linchpin's library of reusable AI agent skills for WordPress projects.",
   "type": "module",
   "bin": {

package/skills/task-tracking/SKILL.md

@@ -102,9 +102,11 @@ 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:
 
-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.
+1. **Read `.clickup.json` first.** If the repo root has one, it pins the Space, a default
+   list, and often a routing map from source directory → list — confirm the destination in
+   one line ("Create in *Mantle › Modules › Security*?") rather than making the user
+   navigate. A ClickUp section in the project's `CLAUDE.md`/`AGENTS.md` counts too. Schema
+   and lookup order: [`references/clickup-json.md`](references/clickup-json.md).
 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.
@@ -202,10 +204,13 @@ Work happens on a dedicated branch opened as a PR against the base branch (usual
 
 ## 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`.** A small file at the repo root holding
+  the Space, a default list, and (where the board mirrors the code) a directory → list map,
+  so creation becomes a one-line confirm instead of navigation. Schema, worked example, and
+  packaging notes: [`references/clickup-json.md`](references/clickup-json.md). The ids belong
+  in that project's repo, not 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

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

@@ -0,0 +1,125 @@
+# `.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
+
+## 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.