Agent skills install from the npm packages the project already has

.drive/projects/agent-skills-npm-packages/deferred.md

@@ -0,0 +1,38 @@
+# Deferred — agent-skills-npm-packages
+
+- **When facade skill content diverges per database, split the skill by name — do not add a carrier package.** Today every facade ships an identical `prisma-8` skill and cross-package conflicts are arbitrated by highest version (`collectSkillSources`), which is safe only while content is identical and versions are lockstep. When per-database content arrives, give each facade a differently named skill (per-target skills, or a shared core plus per-target references) so names never conflict. A common or standalone skills package was considered and rejected 2026-08-21 (operator concurred): a transitive carrier is unresolvable from the project root under pnpm, and a direct-dependency skills package breaks the installed-version guarantee (facade upgraded, skills package not, check reports in sync). The allowlist still grows one deliberate line per facade either way.
+
+- **RESOLVED 2026-08-21: the `agent` command group is deleted** (operator ruling "kill it"; commit 257d785 on PR #219). The post-login tip now offers `prisma skills sync` when copies are stale. Residual: the browser login success page's static `npx skills add prisma/skills` copy button remains, pending an operator decision (reviewer recommends deleting it). Original entry follows.
+- **Retire or re-scope the `agent` command group in prisma-cli.**
+  `prisma agent install|update|status` still installs the v6/v7-line
+  skills by shelling out to `npx skills@latest add prisma/skills`, and
+  its group brief ("Manage Prisma skills for AI coding agents") now
+  overlaps the new `skills` group. Slice 2 flagged it; out of slice
+  scope, but the overlap should be decided before the release that
+  ships `prisma skills`. Origin: slice 2 implementer report, 2026-08-21.
+
+- **Composer website hero copy.** Slice 4 changed `website/src/template.ts`'s
+  hero from `npx skills add prisma/composer` to
+  `pnpm add @prisma/composer prisma && pnpm prisma skills sync` — reverted
+  out of the PR on review advice (product copy, deploys immediately from
+  the repo, and the new command doesn't exist on npm until prisma-cli
+  ships). Needs the site owner's wording + release-timing decision.
+- **`check-skill-packaging.mjs` hardcodes `@prisma/composer`** while
+  `stage-skills.mjs` is generic; a second skill-bearing composer package
+  would be staged but never verified. Generalize when a second package
+  appears.
+
+- **Turbo race: `pnpm test` can rebuild `cli-engine` dist while `cli` tests
+  import it** (`Failed to resolve entry for package "@prisma/cli-engine"`,
+  intermittent). Fix: a `dependsOn` on the engine's build in turbo.json.
+  Origin: slice 2 implementer, 2026-08-21.
+
+- **Windows CI: `credential-manager.test.ts` "holds no lock while the workspace name is fetched" flaked once** (run 32477175789, 2026-08-21; expected 'Workspace A', got undefined). Pre-existing timing-sensitive test, untouched by this project; passed on rerun. A second credential-manager Windows flake followed the same day: `credential-manager-processes.test.ts` "exchanges one refresh token once when two processes refresh the same session" failed with "worker refresh failed: API request failed" (run 32497093995, 2026-08-21), on a push touching nothing near credentials. Two distinct timing-sensitive tests in this suite have now flaked on Windows; the suite needs an owner.
+
+- **Windows CI: `skills-sync.test.ts` "does nothing and exits 0 when every copy is current" timed out once at the 5s default** (run 32474645762, 2026-08-21), with a teardown ENOTEMPTY consistent with cleanup racing the timed-out test. First run of the same code passed it; likely a slow runner. If it recurs, give the skills-sync suite a longer per-test timeout on Windows rather than chasing the race.
+
+- **`isLikelyGlobalNpmEntrypoint` (update-check.ts:312) matches only
+  `prisma-cli` paths**, so a globally-installed `prisma` user gets the
+  docs-link fallback instead of a concrete update command. Pre-existing;
+  newly conspicuous after the CLI_NAME → prisma rename. Origin: reviewer,
+  slice 2 round 2.

.drive/projects/agent-skills-npm-packages/heartbeats/slice1.txt

@@ -0,0 +1,8 @@
+2026-08-21T09:32:07Z survey — read brief/plan/spec + repo (skills tree, check-upgrade-coverage, set-version, shell-build, publish-surface); branch skills-in-tarball-packaging created, pnpm install running; next: fold upgrade skills into prisma-8 router
+2026-08-21T09:36:05Z task1 done — fold committed (29a0ee0) + coverage-check repointed (f95e12f, 78 script tests pass); next: task2 set-version stamping
+2026-08-21T09:40:28Z RECOVERY — .refs/prisma was deleted externally ~11:38, losing branch + 3 commits; re-cloned prisma/prisma at fc3a9ee, re-created branch, redoing tasks 1-3 from context
+2026-08-21T09:44:52Z tasks1-3 redone on fresh clone (a886d2e,6e390c2,87b4376,f705df7); tarball verified to carry 63 stamped skill files; next: task4 docs
+2026-08-21T09:47:08Z task4 docs done, branch pushed to origin (5 commits, no PR); next: validation gate
+2026-08-21T10:00:00Z gate green — coverage check, skill lint, 481 script tests, publish-surface (66), CLI package (1430), init-skill-distribution integration, ratchets, clean-tree, publish-deps all pass; branch pushed (9 commits); slice done
+2026-08-21T10:15:32Z slice1 amendment — stamp moved to metadata.library/library_version (quoted), stampSkillMetadata shared by set-version + sync-package-skills, skill lint rejects non-string metadata; c95e2d0 pushed
+2026-08-21T10:29:12Z slice1 R1 rework — S1-R1-1 fixed: publish-surface test now deletes the staged tree, runs pnpm pack, and reads the skill out of the tarball (900db17); mutation-checked both failure modes; pushed

.drive/projects/agent-skills-npm-packages/heartbeats/slice2.txt

@@ -0,0 +1,8 @@
+2026-08-21T09:31:50Z design-read: read brief/plan/spec + repo conventions; next: implement lib/skills + commands
+2026-08-21T09:39:54Z implement: lib+commands+check landed (cf91519); next: test matrix (npm/pnpm/PnP fixtures, states, off switches)
+2026-08-21T09:49:39Z tests: full matrix green (66 files/1030 tests), lint+typecheck clean, pushed to bot; next: docs (output conventions + command surface)
+2026-08-21T09:55:54Z done: gate green (build, typecheck, pnpm test 8/8, conformance, grammar); docs updated; 4 commits pushed to bot
+2026-08-21T10:09:22Z review-r1: fixed S2-R1-1 (bounded ** walk + read-count test) and S2-R1-2 (sync honors skills.check); gate green; not pushed
+2026-08-21T10:20:10Z review-r1 complete: S2-R1-1, S2-R1-2, CLI_NAME->prisma rename, metadata stamp; gate green; pushed dfaed85
+2026-08-21T10:36:05Z review-r2: restored docs URL, added legacy-mapper both-spellings test; gate green; pushed 75a8f30
+2026-08-21T10:41:17Z review-r3: dead branch + e2e test name; suites green; pushed

.drive/projects/agent-skills-npm-packages/heartbeats/slice3.txt

@@ -0,0 +1,5 @@
+2026-08-21T10:02:26Z slice3 start — branch init-skills-wiring off skills-in-tarball-packaging; reading init path
+2026-08-21T10:08:53Z slice3 tasks1-3 done (dc2ad69 hygiene, a5a1b52 init rewiring; 1443 CLI tests pass); next: task4 error-reference retirement + task5 integration test
+2026-08-21T10:11:52Z slice3 paused at 257868b (all 5 tasks implemented); switching to slice1 branch for metadata-stamp amendment
+2026-08-21T10:18:50Z slice3 done — rebased onto amended slice1 (c95e2d0); gate green: 1443 CLI tests, 5 integration tests, typecheck, package lint, clean tree; not pushed
+2026-08-21T10:40:41Z slice3 R1 rework — S3-R1-1 fixed: init installs prisma@next; engine probe, emit spawn, contract:emit script, templates and sync advice all name the prisma bin (26df6a2); gate green; pushed

.drive/projects/agent-skills-npm-packages/heartbeats/slice4.txt

@@ -0,0 +1,5 @@
+2026-08-21T09:32:38Z slice4 phase=stamp done=frontmatter+set-version+tests next=packaging
+2026-08-21T09:35:01Z slice4 phase=packaging done=prepack-staging+tarball-check+CI next=docs
+2026-08-21T09:37:56Z slice4 phase=docs done=README+skills/README+getting-started+website next=gate-complete
+2026-08-21T10:03:27Z slice4 phase=recovery done=branch-restored-at-.refs/composer-identical-SHA-gate-rerun-green next=push-blocked-awaiting-operator
+2026-08-21T10:14:35Z slice4 phase=review-round-2 done=metadata-stamp+mdc-rule+hero-revert+authoring-rule pushed=eecf6f06 next=await-review

.drive/projects/agent-skills-npm-packages/learnings.md

@@ -0,0 +1,25 @@
+# Learnings — agent-skills-npm-packages
+
+## 2026-08-21 — untracked working clones are one `git clean` from gone
+
+At ~09:38Z the untracked `.refs/` tree (reference clones holding slices
+1 and 4's unpushed branches) was deleted externally. Slice 1's
+implementer noticed and re-cloned/redid its work; slice 4's finished,
+gate-passed branch was lost entirely and had to be rebuilt. Root cause confirmed: slice 2's implementer ran
+`mv .refs /tmp/slice2-refs-parked` because the clones' nested
+`biome.jsonc` files abort root `pnpm lint`. On being asked it restored
+everything; slice 4's branch recovered intact, slice 1's original copy
+preserved for reconciliation. Lint verification now runs on an
+out-of-tree copy of `packages/cli`.
+
+Mitigations applied:
+- `.refs/` added to `.git/info/exclude` (protects against `git clean -fd`,
+  not `-fdx`).
+- Drive project artifacts committed to the branch.
+- Standing rule for all implementers: push the slice branch to origin
+  after every commit; PR-open stays with the orchestrator.
+
+Durable lesson (candidate for drive-process memory at close-out): when
+dispatching implementers into clones that live inside another repo's
+worktree, (a) push-early must be in the initial brief, not a recovery
+rule, and (b) the clone dir must be git-excluded at creation time.

.drive/projects/agent-skills-npm-packages/plan.md

@@ -0,0 +1,111 @@
+# Project Plan — agent-skills-npm-packages
+
+## Summary
+
+Four slices, one per brief phase, across three repos. Slices 1, 2, and 4
+are parallel; slice 3 stacks on slice 1 (same repo, consumes the folded
+skill layout) and on slice 2's settled command surface (textual
+dependency only — init writes the string `prisma skills sync`).
+
+**Spec:** `.drive/projects/agent-skills-npm-packages/spec.md`
+**Design:** `design-notes.md` (brief v2, authoritative)
+**Tracker:** none — this repo's drive convention runs without Linear.
+
+## Cross-slice contract (fixed now so slices can parallelize)
+
+- Skill tree ships at `<package>/skills/<skill-name>/` with `SKILL.md` +
+  `references/`; skill names: `prisma-8`, `prisma-composer`.
+- Frontmatter stamp lives under the spec's `metadata` map (amended
+  2026-08-21 after checking the Agent Skills spec: custom top-level keys
+  are not defined by the spec; extensions belong under `metadata`, a
+  string→string map validated by `skills-ref`):
+  `metadata.library` (npm package name), `metadata.library_version`
+  (stamped to the lockstep version by each repo's version pipeline).
+- Anchor packages / allowlist: `@prisma/orm-postgres`,
+  `@prisma/orm-sqlite`, `@prisma/orm-mongo`, `@prisma/composer`.
+- Command surface: top-level `prisma skills sync` / `prisma skills list`
+  (brief recommendation adopted; slice 2 verifies grammar fit and flags
+  a deviation before slice 3 consumes the string).
+- Harness dirs: `.claude/skills/`, `.cursor/skills/`, `.agents/skills/`,
+  `.windsurf/skills/`.
+
+## Slices
+
+### Slice 1 — prisma/prisma: skill fold, stamp, packaging (phase 1)
+
+Repo: prisma/prisma (clone `.refs/prisma`). Brief items 1–4.
+Fold the two upgrade skills into the `prisma-8` router (upgrading branch,
+`upgrades/<from>-to-<to>/` layout kept; trigger phrases into the router
+description; Mastra-style preamble); add `library`/`library_version`
+frontmatter stamped by `scripts/set-version.ts` (+ utils) with a
+stamp-matches-root-version test; copy `skills/prisma-8/` into
+orm-postgres/orm-sqlite/orm-mongo at build or pack time with `"skills"`
+in `files` and a publish-surface tarball test; repoint
+`USER_SKILL_PKG`/`EXT_SKILL_PKG` in `check-upgrade-coverage.mjs`; update
+`skills/README.md`, `docs/oss/versioning.md`,
+`docs/reference/error-reference.md`.
+
+- **Builds on:** nothing.
+- **Hands to:** slices 2–3 — tarballs whose `skills/prisma-8/SKILL.md`
+  carries the stamp; the folded on-disk layout init syncs.
+
+### Slice 2 — prisma-cli: `skills sync`/`list` + staleness check (phase 2)
+
+Repo: prisma/prisma-cli (this worktree). Brief items 5–7.
+`packages/cli/src/commands/skills/{sync,list}.ts` mounted in `cli.ts`;
+allowlist constant with the security invariant stated at the
+declaration; project-root walk; resolution from root + workspace member
+dirs (PnP-aware); compare/copy/prune semantics per brief §2; exit 0 when
+nothing to do; highest-version + warning on member conflicts; `list`
+with `--json`. The check beside `maybeWriteCachedUpdateNotification` in
+`main.ts` (or an engine hook — implementer decides per the brief's open
+detail) with all off switches incl. `prisma skills sync --disable`
+persisted in local state. Tests per brief item 7 (npm/pnpm/PnP fixtures,
+all states, prune, monorepo, off switches, exit code).
+Until slice 1 publishes, tests run against local fixture packages that
+mimic the contract (stamped `skills/prisma-8/` trees).
+
+- **Builds on:** cross-slice contract only.
+- **Hands to:** slice 3 — the settled command name and flag surface.
+
+### Slice 3 — prisma/prisma: init wiring (phase 3)
+
+**AMENDED 2026-08-21 (operator):** no postinstall writing, no root-gitignore entries — see design-notes.md amendments. Init keeps exactly one touchpoint: run `prisma skills sync` once at scaffold time (`--skip-skills` skips it), keep `RETIRED_SKILL_NAMES` cleanup, retire the `skillInstall` failure path. Gitignoring moves into sync itself (nested `.gitignore` per managed dir, slice 2). Update
+`test/integration/test/cli.init-skill-distribution.integration.test.ts`.
+
+Original scope (superseded): replace `DEFAULT_SKILL_SOURCES` `skills add` invocations with one direct sync run + `"postinstall": "prisma skills sync || exit 0"` via `hygiene-package-scripts.ts`; gitignore entries via `hygiene-gitignore.ts`.
+
+- **Builds on:** slice 1 (same repo, folded layout, error-reference
+  state), slice 2 (command surface, textual).
+- **Hands to:** close-out.
+
+### Slice 4 — prisma/composer: mirror packaging (phase 4)
+
+Repo: prisma/composer (clone `.refs/composer`). Brief item 9.
+`skills/prisma-composer/` into the `@prisma/composer` tarball (`files` +
+`library`/`library_version` stamp via composer's version pipeline);
+repoint README and `docs/guides/getting-started.md` from
+`npx skills add prisma/composer` to `prisma skills sync`.
+
+- **Builds on:** cross-slice contract only.
+- **Hands to:** close-out.
+
+## Sequencing
+
+- **Parallel group A:** slice 1, slice 2, slice 4.
+- **Stack:** slice 3 after slice 1 merges (and slice 2's command surface
+  is settled — PR open is sufficient; merge not required).
+
+Release-order note (from the brief): the published sequence matters —
+prisma-cli pins `@prisma/orm-toolchain` exactly and its sync command
+needs published skill-bearing packages for end-to-end verification. PR
+order need not wait on publishes; local fixtures cover slice 2 testing.
+
+## Close-out (required)
+
+- [ ] Verify all acceptance criteria in `spec.md`.
+- [ ] Migrate long-lived docs into each repo's `docs/` (done in-slice:
+      versioning.md, error-reference.md, skills/README.md, composer
+      guides).
+- [ ] Strip repo-wide references to `.drive/projects/agent-skills-npm-packages/**`.
+- [ ] Delete `.drive/projects/agent-skills-npm-packages/`.