@linchpinagency/skills 0.1.8 → 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.8
+### Latest release: 0.1.9
 <!-- x-release-please-end -->
 
 | Release | Skill standard | Install |

package/package.json

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