@sassywares/skills 0.4.0 → 0.4.3

package/CONCEPTS.md

@@ -2,7 +2,7 @@
 
 ## Source of truth
 
-The repo's `skills/` directory is the only copy of the skills. It ships as the npm package `@sassywares/skills`, so consumers pin a version rather than linking a directory; the sync service handles git commit and push.
+The repo's `skills/` directory is the only copy of the skills. Consumers install from it with `npx skills add sassywares/sassy-skills`, which vendors the files into their project and pins content hashes in `skills-lock.json`; the sync service handles git commit and push.
 
 ## Skill
 

package/README.md

@@ -302,12 +302,12 @@ npx skills remove                 # take the suite out again
 `@sassywares/skills` is on npm for harnesses that install packages rather than skill directories:
 
 ```bash
-pi install npm:@sassywares/skills@0.4.0
+pi install npm:@sassywares/skills
 ```
 
 ## Repository maintenance
 
-`scripts/sync.sh` commits skill changes, rebases on `origin/main`, and pushes. Any agent that changes a skill must run it immediately, without asking for confirmation. It installs nothing anywhere — a change reaches consumers when a version is released and they bump their pin. `AGENTS.md` documents the workflow for agents working on this repo.
+`scripts/sync.sh` commits skill changes, rebases on `origin/main`, and pushes. Any agent that changes a skill must run it immediately, without asking for confirmation. It installs nothing anywhere — consumers get a change when they run `npx skills update` after a push. `AGENTS.md` documents the workflow for agents working on this repo.
 
 ### Releases
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sassywares/skills",
-  "version": "0.4.0",
+  "version": "0.4.3",
   "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
   "type": "module",
   "license": "MIT",

package/skills/sassy-setup/SKILL.md

@@ -2,8 +2,8 @@
 name: sassy-setup
 description: >-
   Detect a project's topology and wire it for the Sassy Skills suite: write
-  .sassywares/config.yaml, pin the skills as an npm dependency, link them where
-  harnesses look, and install the snapshot tooling in a multi-repo workspace.
+  .sassywares/config.yaml, vendor the skills from upstream with the open
+  `skills` CLI, and install the snapshot tooling in a multi-repo workspace.
   Use when asked to set up, configure, or verify a project.
 argument-hint: "[path] [--check]"
 disable-model-invocation: true
@@ -11,7 +11,7 @@ disable-model-invocation: true
 
 # Sassy Setup
 
-**Outcome:** `.sassywares/config.yaml` at the project root matching the tree it describes, the skills wired as a pinned dependency and visible to the harness, and — in `workspace` mode — the snapshot tooling installed.
+**Outcome:** `.sassywares/config.yaml` at the project root matching the tree it describes, the skills vendored and pinned in `skills-lock.json` and visible to the harness, and — in `workspace` mode — the snapshot tooling installed.
 
 **Read `references/config.md` first.** It is the schema and the resolution rules; this skill only decides and writes.
 
@@ -33,7 +33,7 @@ disable-model-invocation: true
 5. **Wire the skills.** The suite is installed from upstream with the open `skills` CLI, which vendors the skill files into the project and pins them. Never copy skill files in by hand, never add the suite as a dependency.
 
    - **Install it**: `npx -y skills add sassywares/sassy-skills -y`. That writes `.agents/skills/sassy-*` (real files), per-agent links such as `.claude/skills/sassy-*`, and `skills-lock.json`.
-   - **Scripts**, adding only what is missing: `"skills:sync": "npx -y skills experimental_install"` (restores exactly what the lock pins) and `"skills:update": "npx -y skills update -y"` (pulls the latest from upstream). **Never rewrite an existing `postinstall`** — leave it alone and tell the user to chain what they need.
+   - **Do not wire updates.** How and when the project refreshes the suite is the project's decision, not setup's: no `skills:*` scripts, no `postinstall` edit. Mention the commands (`npx skills update`, `npx skills experimental_install`) and stop there.
    - **Commit the vendored skills and the lock.** `.agents/skills/sassy-*` and `skills-lock.json` are the pin; a clone then needs no network.
    - **Ignore `.claude/skills` only.** It is a link created at install time. Create `.gitignore` only when there is none — and in `workspace` topology never touch the project's root `.gitignore` at all.
    - **Write `.sassywares/README.md`** from `assets/sassywares-readme.md` when absent. Never overwrite it — it may carry project notes.
@@ -41,8 +41,8 @@ disable-model-invocation: true
 
 6. **Install the snapshot, `workspace` only.** Read `references/workspace.md` and follow it.
 
-7. **Verify.** Run `scripts/detect.sh --root <path> --check`, then `sassy-skills check` for the links. Report every `drift:` line it prints — including an outdated `snapshot` version — or that the config matches the tree.
-8. **Report.** The config path, the topology, the resolved artifact and knowledge paths, the skills version pinned and that `/reload` is needed, and in `workspace` mode what was installed. **Commit nothing.**
+7. **Verify.** Run `scripts/detect.sh --root <path> --check`. Report every `drift:` line it prints — including an outdated `snapshot` version — or that the config matches the tree, plus that `skills-lock.json` is tracked and matches the vendored skills.
+8. **Report.** The config path, the topology, the resolved artifact and knowledge paths, that the vendored skills and lock are committed and `/reload` is needed, and in `workspace` mode what was installed. **Commit nothing.**
 
 ## Hard rules
 
@@ -54,8 +54,8 @@ disable-model-invocation: true
 | Version is reported | Setup names the snapshot version it installed; `--check` flags an installed copy older than the skill's. |
 | Never commit | Setup writes files and stops. Committing is `sassy-commit`. |
 | Skills come from upstream | Install with `npx skills add`; never hand-copy skill files or maintain the links yourself. |
-| Scripts are shared | Adding a missing script is fine; rewriting an existing `postinstall` or `skills:*` entry is not. |
-| Write boundary | Only `.sassywares/`, the vendored `.agents/skills/sassy-*`, `skills-lock.json`, two `package.json` scripts, and one `.gitignore` line. Never a root `.gitignore` in a workspace. |
+| Never edit the manifest | No dependencies, no scripts, no `postinstall`. Setup installs the suite; the project decides how it updates. |
+| Write boundary | Only `.sassywares/`, the vendored `.agents/skills/sassy-*`, `skills-lock.json`, and one `.gitignore` line. Never `package.json`, never a root `.gitignore` in a workspace. |
 | Detect, don't guess | An unknown base branch stays unknown and gets asked about. A probed value is reported as probed. |
 | Comments are part of the file | Every key keeps its description and allowed values. A stripped config is an incomplete config. |
 | Hooks are named, not written | Setup records hook skill names. Creating those skills is the project's work. |

package/skills/sassy-setup/assets/sassywares-readme.md

@@ -9,10 +9,12 @@ Installed from upstream with the open `skills` CLI, which vendors the skills int
 
 ```bash
 npx skills add sassywares/sassy-skills   # first install
-bun run skills:sync                       # restore exactly what the lock pins
-bun run skills:update                     # pull the latest from upstream
+npx skills update -y                      # pull the latest from upstream
+npx skills experimental_install           # restore exactly what the lock pins
 ```
 
+Refreshing the suite is this project's decision — nothing here updates itself.
+
 The vendored skills and the lock are committed; `.claude/skills` is a link and is not.
 
 `.agents/skills/` is read by pi and Cursor; Claude Code reads `.claude/skills/` only, which is why that symlink exists. After any change, `/reload` your harness.

package/skills/sassy-skill/SKILL.md

@@ -35,13 +35,13 @@ Ask which one, unless the request already made it obvious. The answer changes th
 
 | Location | Path | Who gets it | Extra work |
 |---|---|---|---|
-| **Internal** — part of this suite | `skills/<name>/` in the sassy-skills repo | Everyone, after a release | Name it `sassy-<name>`, bump `package.json`, run `scripts/sync.sh`, then tag to publish |
+| **Internal** — part of this suite | `skills/<name>/` in the sassy-skills repo | Everyone, once pushed to `main` | Name it `sassy-<name>`, run `scripts/sync.sh`; the npm package follows the next tag |
 | **Project** — team workflow | `<repo>/.agents/skills/<name>/` | Everyone who clones that repo | Commit it; prefix the project (`tap2-…`) so it can't collide with a suite skill or a harness built-in |
 | **User** — personal workflow | `~/.agents/skills/<name>/` | Only this person, every repo on this machine | None — but nothing gates it either; never put something a teammate needs here |
 
 Recommend by audience: the team needs it → **project**; only the requester → **user**; it belongs to every project using this suite → **internal**.
 
-Internal is the only one that implies a release. Never choose it silently: from the moment it lands, consumers see it only when they bump their pin. Say that out loud when you do.
+Internal is the only one that ships to everyone. Never choose it silently: once it lands on `main`, every consumer gets it on their next `npx skills update`. Say that out loud when you do.
 
 Paths in the table are the defaults. Harnesses also read `skills` arrays in settings and installed packages, so a skill may live elsewhere — write down where it actually went.