@sassywares/skills 0.2.0 → 0.3.1

package/package.json

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

package/skills/sassy-commit-push-pr/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Commit, push, and open a PR, then babysit it by default. Use when asked to
   ship/open a PR, or for a PR-description-only flow (writing, rewriting, or
   describing a PR body).
-argument-hint: "[PR ref] [branch:new|current] [babysit:on|off] [checkpoint] [merge:on|off] [delete-branch:on|off]"
+argument-hint: "[PR ref] [branch:new|current] [base:<branch>] [babysit:on|off] [checkpoint] [merge:on|off] [delete-branch:on|off]"
 disable-model-invocation: true
 ---
 
@@ -36,7 +36,7 @@ Only an exit-0 empty list means "no open PR". A non-zero exit means **unknown**
 
 **Branch policy.** Default: if on the base branch or detached HEAD, create a feature branch named from the work and say so. `branch:current` or a plain request keeps the checked-out branch (that run pushes and skips the PR). Never ask whether to branch. Forward the resolved choice to `sassy-commit`: `branch:new <name>` when this run creates a branch, else `branch:current`.
 
-**Base branch.** `<base>` is `repos[<repo dir>]` from a workspace config, else `git.default_branch`, else the probed remote HEAD. **Never use `defaultBranchRef` as the PR base when the config names one** — a repo whose PRs target `staging` or `dev` must not get a PR aimed at `main`. Pass it explicitly: `gh pr create --base <base>`.
+**Base branch.** `<base>` is `repos[<repo dir>]` from a workspace config, else `git.default_branch`, else the probed remote HEAD. An explicit `base:<branch>` token wins over all of them — use it when this PR targets something other than the day-to-day base, such as a release PR aimed at `main` while work lands on `staging`. **Never use `defaultBranchRef` as the PR base when the config names one.** Pass it explicitly: `gh pr create --base <base>`.
 
 **Refused topologies.** From a `workspace` root there is no single PR to open — refuse in one line and point at `sassy-ship`, which owns the per-repo fan-out. With `git.repo: none`, refuse and say why. Neither ever pushes directly to a base branch.
 

package/skills/sassy-setup/SKILL.md

@@ -1,11 +1,10 @@
 ---
 name: sassy-setup
 description: >-
-  Detect a project's topology and write .sassywares/config.yaml, so every sassy
-  skill resolves paths, base branches, and git behavior from one file. Also
-  installs the workspace snapshot tooling when the folder is a multi-repo
-  workspace rather than a repo. Use when asked to set up, configure, or verify a
-  project.
+  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.
+  Use when asked to set up, configure, or verify a project.
 argument-hint: "[path] [--check]"
 disable-model-invocation: true
 ---
@@ -23,11 +22,11 @@ disable-model-invocation: true
 1. **Resolve the start.** The argument's path, else the working directory. If a `.sassywares/config.yaml` is already found walking up, this is a **verify run**: run the checks in step 7 and report, without rewriting anything.
 2. **Detect.** Run `scripts/detect.sh --root <path>`. It prints a proposed config: topology (`repo`, `workspace`, `none`), the remote name, a probed base branch, nested repos with their bases, and which artifact paths exist.
 3. **Ask only what detection cannot answer.** Never re-ask what the tree already said.
-   - **`workspace`** — the snapshot mirror: create a **private** GitHub repo, or connect an existing one (`owner/name` or URL)? For creating it, get explicit approval and name the slug before running anything. Automatic creation is `gh repo create` inside `snapshot`, and only after that approval.
+   - **`workspace`** — the snapshot mirror: create a **private** GitHub repo, or connect an existing one? Creating it needs explicit approval and a named slug first.
    - **`none`** — confirm the intent: this folder is deliberately outside git, so commit, PR, and babysit refuse here.
    - **Artifacts** — offer the detected paths as the default; take overrides.
    - **Knowledge** — `knowledge.read` defaults to the solutions dir plus the concepts file. Ask whether there are extra folders to read (a hand-written `notes/learnings/`, a `docs/adr/`).
-   - **Base branch** — in `repo` mode, if detection printed no `default_branch`, ask. Never fill in `main` as a guess. In `workspace` mode, show the detected `repos` map and get a yes on every row: each probed base is only the remote's default, so a repo that targets `dev` or `staging` will read `main` until a human corrects it. Never write an unconfirmed probed base.
+   - **Base branch** — if detection printed no `default_branch`, ask; never write `main` as a guess. In `workspace` mode, show the `repos` map and get a yes on every row — a probed base is only the remote's default, so a repo that targets `dev` or `staging` reads `main` until a human corrects it.
    - **`pr.*`** — default `babysit: true`, `merge: false`, `delete_branch: false`. Say plainly that `merge: true` authorizes merging every babysat PR in this project without asking.
    - **Hooks** — offer, do not impose. Ask whether the project wants steps injected at `before_create`, `after_create`, `before_merge`, or `after_merge`, and write the skills they name. Leave them `[]` when they have nothing to add. **Never write a hook skill yourself** — hooks are project skills, and copying one of ours into that role is the fork this mechanism exists to prevent.
 4. **Write the config.** Build the file from the proposal plus the answers. It is written **fully commented**: every key keeps a description and its allowed values, exactly as the detector emits them. Never strip those comments to save lines — for a teammate opening the file, the comments are the documentation. If a config already exists, show what changes and ask before writing — never silently overwrite. Keep every key; an unset key falls back to its documented default, so a short file is legal when nothing deviates.
@@ -42,21 +41,8 @@ disable-model-invocation: true
    - **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 links are invisible to the harness until it rescans.
 
-6. **Install the snapshot, `workspace` only.** The layout is fixed, and everything the snapshot owns lives under one directory:
+6. **Install the snapshot, `workspace` only.** Read `references/workspace.md` and follow it.
 
-   ```text
-   .sassywares/
-   ├── config.yaml
-   └── workspace/
-       ├── snapshot    the script (tracked)
-       ├── .gitignore  exclude patterns for the sync (tracked)
-       └── mirror/     the side clone (untracked, self-excluded)
-   ```
-
-   - Copy `assets/snapshot` to `.sassywares/workspace/snapshot` and make it executable. **If a `snapshot` file is already there, say so and ask** — it may carry hand edits. Report the version you installed (`snapshot --version`) so a later `--check` can catch a stale copy.
-   - 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 snapshot syncs without it. The mirror itself needs no line — the script excludes it.
-   - Do **not** add a `.gitignore` at the project root, and do not modify one that exists.
-   - 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.
 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.**
 

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

@@ -0,0 +1,30 @@
+# Workspace install
+
+Read this only when the topology is `workspace`. Everything the snapshot owns
+lives under one directory:
+
+```text
+.sassywares/
+├── config.yaml
+└── workspace/
+    ├── snapshot    the script (tracked)
+    ├── .gitignore  exclude patterns for the sync (tracked)
+    └── mirror/     the side clone (untracked, self-excluded)
+```
+
+- Copy `assets/snapshot` to `.sassywares/workspace/snapshot` and make it
+  executable. **If a `snapshot` file is already there, say so and ask** — it may
+  carry hand edits. Report the version you installed (`snapshot --version`) so a
+  later `--check` can catch a stale copy.
+- 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 mirror needs no
+  line — the script excludes it itself.
+- Do **not** add a `.gitignore` at the project root, and do not modify one that
+  exists.
+- 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.
+
+The mirror remote comes from `git.remote`; the script falls back to the mirror's
+own `origin` once it exists. Never create the GitHub repository without the
+explicit approval described in the skill.

package/skills/sassy-skill/SKILL.md

@@ -1,17 +1,20 @@
 ---
 name: sassy-skill
 description: >-
-  Create, retune, or improve an Agent Skill for pi. Use when asked to create a
-  skill, turn a workflow into a skill, fix a skill's description or triggering,
-  restructure a bloated skill, or retune an existing one. Writes to the user or
-  project skill directory and follows pi's Agent Skills rules.
+  Create, retune, or improve an Agent Skill. Asks where the skill should live —
+  inside this suite, in a project, or for one user — then writes it there with
+  the rules and release steps that location requires. Use when asked to create a
+  skill, turn a workflow into a skill, fix a description or triggering,
+  restructure a bloated skill, or retune an existing one.
 argument-hint: "[create|retune] [name, idea, or skill path]"
 disable-model-invocation: true
 ---
 
 # Sassy Skill
 
-**Outcome:** a well-formed Agent Skill directory installed at the user or project location, or an existing skill improved and re-verified. Pi's loader accepts it with no diagnostics.
+**Outcome:** a well-formed Agent Skill at a location the user chose, or an existing skill improved and re-verified. The harness loads it with no diagnostics.
+
+**Locations are not interchangeable** — they decide who gets the skill, how it ships, and what it may be called. Ask before writing.
 
 **Scope:** skills only — not extensions, packages, or prompt templates.
 
@@ -22,11 +25,26 @@ disable-model-invocation: true
 - **Description:** required, ≤1024 chars. Pi advertises name + description at startup; the body loads only when the skill is used. The description decides whether the skill ever fires — write **what it does and when to use it**.
 - **Frontmatter fields:** `name`, `description` (required); optional `license`, `compatibility`, `metadata`, `allowed-tools`, `disable-model-invocation`.
 - Use `disable-model-invocation: true` for skills that should run only via explicit `/skill:name`.
-- **Locations:** user `~/.agents/skills/<name>/`; project `<repo>/.agents/skills/<name>/` (discovered from cwd up to the repo root). Also the `skills` array in settings and pi packages.
 - **Reference other skills by name, never by absolute path.** The suite can live in `~/.agents/skills/`, a project `.agents/skills/`, or inside `node_modules/`, so "load the sassy-commit skill" is portable where a `~/…` path is not. Name a bundled file as "the sassy-setup skill's `references/config.md`".
 - Pi **validates at startup**; malformed or descriptionless skills warn. `/reload` applies changes.
 - Pi implements the **Agent Skills specification** (agentskills.io). For the full spec, pi's own `docs/skills.md` is authoritative — read it when the rules here are not enough.
 
+## Where the skill lives
+
+Ask which one, unless the request already made it obvious. The answer changes the name, the sharing, and whether a release is needed.
+
+| 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 |
+| **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.
+
+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.
+
 ## Shape rule — the lean rule
 
 - **Default to one `SKILL.md`.**
@@ -36,7 +54,7 @@ disable-model-invocation: true
 
 ## Workflow
 
-1. **Intake.** What the skill does, when it should trigger, and whether it is **user-level** or **project-level**. For a retune, read the existing skill and name the specific failure (won't trigger, too long, wrong steps, stale).
+1. **Intake.** What the skill does, when it should trigger, and **where it lives** — internal, project, or user (see above). Ask; do not infer from the cwd. For a retune, read the existing skill and name the specific failure (won't trigger, too long, wrong steps, stale, wrong scope).
 2. **Choose the shape.** Single file, or `SKILL.md` + `references/` per the rule above.
 3. **Write the frontmatter.** A description that states both what and when.
 4. **Write the body.** Outcome, a hard-rules table, the workflow, and reference pointers. Plain English. Structured output where the skill returns a result. Match this setup's house style.
@@ -59,7 +77,7 @@ When asked to retune or improve a skill, change the **smallest** thing that fixe
 - **Won't trigger** → rewrite the description (what + when, concrete verbs).
 - **Too long / bloated** → extract conditional content to `references/`, or delete what never gets used.
 - **Wrong or stale steps** → correct the workflow against the current tree.
-- **Wrong scope** → move it between user and project locations.
+- **Wrong scope** → move it between internal, project, and user. Moving into the suite is a release; moving out of it means the next release drops the skill for everyone.
 
 Re-verify after any retune.