@camunda8/spm 0.1.1 → 0.2.0

package/README.md

@@ -15,13 +15,13 @@ ai.json ──resolve──▶ ai.lock ──fetch──▶ ~/.spm/store/<repo>@
 
 - **`ai.json`** — you author it, commit it. Declares target vendors + skill deps.
 - **`ai.lock`** — generated, commit it. Pins every version selector to an immutable commit SHA → reproducible installs.
-- **Global store** (`~/.spm/store`) — each repo@commit fetched once, shared across all projects.
-- **Vendor projection** — spm copies the store's skills into wherever each vendor loads them from. Nothing spm generates is committed to your repo.
+- **Global store** (`~/.spm/store`) — a **fetch cache only**: each repo@commit is cloned once and shared across all projects. Nothing is *registered* or *materialized* here — it exists purely so repeated installs don't re-clone.
+- **Vendor projection** — spm copies the store's skills into a **project-local** directory wherever each vendor loads them from. Nothing spm generates is committed to your repo, and nothing is written into a user-global vendor location.
 - **Registration** differs per vendor:
   - **Claude** — spm assembles a self-contained plugin marketplace in the **project-local**, gitignored `.spm/claude/` dir and writes a pointer to it into `.claude/settings.local.json` (gitignored by convention). The dir sits outside `.agents/skills/` so Copilot's scanner never picks it up. Declarative, per-project, zero VCS footprint.
   - **Copilot CLI** — spm copies the resolved skills into a **project-local** directory, `.agents/skills/spm-managed-skills/<name>/`, where Copilot CLI auto-discovers them (`.agents/skills/**/SKILL.md`). That directory is added to the project's `.gitignore` (with an explanatory comment) so the materialized skills stay truly local and are never committed. No user-global state, no `copilot` CLI required.
 
-On a fresh clone, teammates run `spm install` — it rebuilds their own store and re-registers from `ai.lock`. Same model as `node_modules`.
+On a fresh clone, teammates run `spm install` — it repopulates their own fetch cache and re-materializes the project-local skills from `ai.lock`. Same model as `node_modules`.
 
 ## ai.json
 
@@ -144,13 +144,63 @@ spm remove <name>                                  # drop a skill
 spm update [name]                                  # re-resolve branches/tags to latest
 spm install                                        # rebuild from ai.lock (after clone)
 spm list                                           # show skills + pinned commits
+spm status                                         # check skills are materialized in this checkout
 spm clean                                          # remove generated vendor config
 ```
 
+## Worktrees & fresh clones
+
+spm materializes skills into **gitignored** project-local dirs (`.spm/claude/`,
+`.agents/skills/spm-managed-skills/`). Git **worktrees** have their own working
+tree and don't share those untracked files, so — exactly like `node_modules` —
+**each checkout needs its own `spm install`**:
+
+```bash
+git worktree add ../feature -b feature
+cd ../feature && spm install         # materialize this worktree's skills
+```
+
+Skipping this is the usual reason an agent doesn't see a declared skill in a new
+worktree or a fresh clone. `spm status` tells you at a glance and **exits
+non-zero** when anything is missing, so it works in scripts too:
+
+```bash
+spm status
+# [claude]  0/1 installed  .../.spm/claude/plugin/skills
+#   reviewer  MISSING
+# error: some declared skills are not materialized in this checkout — run `spm install` here
+```
+
+To install automatically on every branch checkout and new worktree, add a
+`post-checkout` git hook (worktrees share the repo's `.git/hooks`):
+
+```sh
+# .git/hooks/post-checkout   — then: chmod +x .git/hooks/post-checkout
+#!/bin/sh
+# Re-materialize spm skills so Claude/Copilot always see the declared set.
+[ -f ai.lock ] && command -v spm >/dev/null 2>&1 && spm install >/dev/null 2>&1
+exit 0
+```
+
+> **Claude note:** `spm install` writes the *absolute* path of the current
+> checkout's `.spm/claude/` into that checkout's `.claude/settings.local.json`.
+> Since that file is gitignored, a new worktree either has no registration at all
+> or — if it was copied over — one still pointing at the checkout it came from.
+> Either way, run `spm install` inside the worktree and start (or
+> `/reload-plugins` in) the Claude session from that same worktree; discovery is
+> snapshotted at session start. `spm status` reports a stale pointer explicitly:
+>
+> ```
+>   ! .claude/settings.local.json marketplace points at /repo/.spm/claude, not this checkout (/repo-feature/.spm/claude)
+> ```
+
+To see what each harness actually loaded: `claude plugin list` /
+`claude plugin marketplace list` for Claude; `copilot skill list` for Copilot.
+
 ## Design notes
 
 - **Cross-OS**: shells out to the system `git` (no libgit2 build deps); no symlinks; all paths via `std::path`. Runs on Linux, macOS, Windows.
-- **`SPM_HOME`** overrides the store/vendor root (default `~/.spm`) — used by tests.
+- **`SPM_HOME`** overrides the store root (default `~/.spm`, holding only the fetch cache) — used by tests. Vendor output is always project-local and is not affected by `SPM_HOME`.
 - **Vendor adapters**: adding a target means implementing one `Vendor` trait (`src/vendor/`). `claude` assembles a plugin-marketplace layout (`marketplace.json` → `plugin.json` → `skills/<name>/SKILL.md`) into the gitignored project-local `.spm/claude/` and points to it; `copilot` copies skills into the gitignored project-local `.agents/skills/spm-managed-skills/`. Both keep their materialized files out of VCS via the shared `src/gitignore.rs` helper.
 
 ## Development

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camunda8/spm",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Skill package manager (spm): declare AI skills in ai.json and materialize them for Claude/Copilot.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/camunda/spm-cli#readme",
@@ -33,10 +33,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@camunda8/spm-linux-x64": "0.1.1",
-    "@camunda8/spm-linux-arm64": "0.1.1",
-    "@camunda8/spm-darwin-x64": "0.1.1",
-    "@camunda8/spm-darwin-arm64": "0.1.1",
-    "@camunda8/spm-win32-x64": "0.1.1"
+    "@camunda8/spm-linux-x64": "0.2.0",
+    "@camunda8/spm-linux-arm64": "0.2.0",
+    "@camunda8/spm-darwin-x64": "0.2.0",
+    "@camunda8/spm-darwin-arm64": "0.2.0",
+    "@camunda8/spm-win32-x64": "0.2.0"
   }
 }