@sassywares/skills 0.5.14 → 0.5.15

package/package.json

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

package/skills/sassy-setup/SKILL.md

@@ -52,7 +52,7 @@ A check run never edits the config and never rewrites the tree: it prints what `
    - **Write `.sassywares/README.md`** from `assets/sassywares-readme.md` when absent. Never overwrite it — it may carry project notes.
    - **Tell the user to `/reload`.** The skills are invisible to the harness until it rescans.
 
-6. **Install the workspace tooling, `workspace` only.** The snapshot plus the `branches` / `pull` / `checkout-bases` git helpers. Read `references/workspace.md` and follow it.
+6. **Install the workspace tooling, `workspace` only.** The snapshot plus the `branches` / `pull` / `checkout-bases` git helpers, and one `workspace:<script>` alias per script in the project's own manifest. Read `references/workspace.md` and follow it.
 7. **Verify.** Run `scripts/detect.sh --root <path> --check`. It validates the config against the tree — topology and remotes, `base_map` shape and cycles, `repos` against each nested repo, hooks, artifacts paths, `knowledge`, `pr.*` booleans, `commit.branch`, any unknown key, and in `workspace` mode the installed snapshot's version — plus the vendored pin: every `.agents/skills/sassy-*` folder hashed against `skills-lock.json`, the lock's coverage both ways, and whether git carries the lock. Report every `drift:` line verbatim, or that the config matches the tree. Drift blocks step 8.
 8. **Commit what setup owns.** `repo` topology only, and only when step 7 is clean. The file list is exactly what setup wrote or found unwritten:
 
@@ -65,7 +65,7 @@ A check run never edits the config and never rewrites the tree: it prints what `
    - **`workspace`** — nothing to commit: the root is not a repo, and `references/workspace.md` forbids running the snapshot here. Say the root config and the pin land with the project's next snapshot.
    - **`none`** — nothing to commit, deliberately.
 
-9. **Report.** The config path, the topology, the resolved artifact and knowledge paths, the commit (hash and branch) or why there is none, and in `workspace` mode what was installed, with versions (`snapshot vN`, `workspace-git vN`). Remind: `/reload` so the harness rescans. Close with what is left over — at most dirt setup deliberately did not commit — and nothing else: a clean setup leaves the user good to go.
+9. **Report.** The config path, the topology, the resolved artifact and knowledge paths, the commit (hash and branch) or why there is none, and in `workspace` mode what was installed, with versions (`snapshot vN`, `workspace-git vN`), and the manifest the `workspace:*` aliases went into — naming it as created when there was no script surface to begin with. Remind: `/reload` so the harness rescans. Close with what is left over — at most dirt setup deliberately did not commit — and nothing else: a clean setup leaves the user good to go.
 
 ## Hard rules
 
@@ -78,8 +78,8 @@ A check run never edits the config and never rewrites the tree: it prints what `
 | No silent overwrite | An existing config or an existing `.sassywares/workspace/snapshot` is shown and asked about, never replaced blind. |
 | Version is reported | Setup names the snapshot and `workspace-git` versions it installed; `--check` flags an installed copy older than the skill's. |
 | Skills come from upstream | Install with `npx skills add`; never hand-copy skill files or maintain the links yourself. |
-| 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 — and the same list is step 8's commit. Never `package.json`, never a root `.gitignore` in a workspace. Workspace git helpers land in `.sassywares/workspace/`, never in a project's `bin/`. |
+| Never edit the manifest | No dependencies, no `postinstall`, no `skills:*` scripts. The one exception is step 6's `workspace:*` aliases in `workspace` topology: appended or corrected, never removed, and nothing else in the file touched. 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 — and the same list is step 8's commit. Never `package.json` outside step 6's `workspace:*` aliases, never a root `.gitignore` in a workspace. Workspace git helpers land in `.sassywares/workspace/`, never in a project's `bin/`. |
 | 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

@@ -43,6 +43,11 @@ across the sibling repos, next to the `snapshot` that versions the glue:
 .sassywares/workspace/snapshot          # commit + push the glue
 ```
 
+Each one also has an alias in the project manifest (`workspace:branches`,
+`workspace:pull`, `workspace:checkout-bases`, `workspace:snapshot`), so
+`npm run workspace:pull` — or the equivalent for the runner this project uses —
+works from the root.
+
 They read the repo inventory and the PR bases from `repos:` in `config.yaml`, so
 there is no second base map to keep in step. They are this project's files:
 extend them freely — just run the snapshot afterwards, since they live in the

package/skills/sassy-setup/references/workspace.md

@@ -27,6 +27,8 @@ lives under one directory:
   `_lib.sh`'s `workspace-git-version` (or `branches --version`) the same way.
   **Ask before overwriting any of them when they already exist** — from the first
   install on they are the project's files, and extending them is expected.
+- **Aliases.** One `workspace:<script>` entry per installed script, in the
+  project's own manifest. See below.
 - **Excludes.** Write `.sassywares/workspace/.gitignore` for excluded paths
   (vendored trees, generated dirs, `.run/`). One pattern per line, `.gitignore`
   style. Skip it when there is nothing to exclude; the sync works without it. The
@@ -36,6 +38,57 @@ lives under one directory:
 - Do **not** run the snapshot during setup. It clones and pushes; that is the
   user's call. Offer `--dry-run` and run it only if they ask.
 
+## Script aliases
+
+The scripts should be reachable from the project's own runner, so setup wires one
+alias per installed script:
+
+```json
+"scripts": {
+  "workspace:branches": ".sassywares/workspace/branches",
+  "workspace:pull": ".sassywares/workspace/pull",
+  "workspace:checkout-bases": ".sassywares/workspace/checkout-bases",
+  "workspace:snapshot": ".sassywares/workspace/snapshot"
+}
+```
+
+Find the file that carries named commands — at the **workspace root only**, never
+inside a repo:
+
+| File at the root | Write the aliases to |
+| --- | --- |
+| `package.json` | its `scripts` |
+| `deno.json` / `deno.jsonc` | its `tasks` |
+| `composer.json` | its `scripts` |
+| `go.mod`, `pyproject.toml`, `Cargo.toml`, `Gemfile`, `Makefile`, `justfile`, … | nothing: create `package.json` as below |
+
+`go.mod` and friends name dependencies, not commands, and a make/just target
+cannot carry the `workspace:` form. Never invent a `Makefile` or `justfile` to
+avoid `package.json` — one naming convention across projects is worth more than
+one file fewer.
+
+- **Name and value are fixed**: `workspace:<script>` → `.sassywares/workspace/<script>`.
+  No `./`, no absolute paths, no `bin/`.
+- **Merge, never rewrite**: existing scripts and every other field stay as they
+  are; new keys go at the end of the scripts block; keep the file's indentation.
+  Never touch dependencies, `postinstall`, or `skills:*`.
+- **Idempotent**: a matching alias is left alone, a stale value is corrected, and
+  an alias the project added itself is never removed.
+- **No manifest at all?** Look at what the repos are — Node, Go, Python, a mix —
+  and say so. Then create a minimal `package.json`:
+
+  ```json
+  {
+    "private": true,
+    "scripts": { … }
+  }
+  ```
+
+  `private: true` keeps it unpublishable; no `name`, no `version`, no
+  dependencies. It exists so the aliases have a home. **Say that in the report** —
+  created versus already there — and skip the aliases entirely when the project
+  has removed the scripts they point at.
+
 ## What the git helpers are for
 
 `branches`, `pull`, and `checkout-bases` do across the workspace's repos what the

package/skills/sassy-setup/scripts/detect.sh

@@ -430,6 +430,28 @@ if (( CHECK )); then
     else
       note "  no workspace git helpers installed (optional)"
     fi
+
+    # Aliases live in the project's own manifest; setup only ever adds them.
+    manifest=""
+    for candidate in package.json deno.json deno.jsonc composer.json; do
+      if [[ -f "$ROOT/$candidate" ]]; then
+        manifest="$candidate"
+        break
+      fi
+    done
+    if [[ -n "$manifest" ]]; then
+      missing_aliases=()
+      for script in branches pull checkout-bases snapshot; do
+        grep -q "\"workspace:${script}\"" "$ROOT/$manifest" || missing_aliases+=("$script")
+      done
+      if [[ ${#missing_aliases[@]} -eq 0 ]]; then
+        note "  workspace:* aliases in ${manifest}"
+      elif [[ ${#missing_aliases[@]} -lt 4 ]]; then
+        bad "${manifest} is missing $(printf '`workspace:%s` ' "${missing_aliases[@]}")— half-wired aliases; re-run setup"
+      else
+        note "  no workspace:* aliases in ${manifest} (optional)"
+      fi
+    fi
     while IFS= read -r name; do
       [[ -n "$name" ]] || continue
       base="$(detect_base "$ROOT/$name")"