@sassywares/skills 0.5.14 → 0.5.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CONCEPTS.md CHANGED
@@ -10,7 +10,7 @@ A directory containing `SKILL.md`, discovered by a harness from a project skills
10
10
 
11
11
  ## Agent
12
12
 
13
- A specialized subagent defined under `~/.pi/agent/agents/`. Skills delegate bounded work to agents such as `scout`, `worker`, `reviewer`, and `validator`.
13
+ A specialized subagent from [sassy-agents](https://github.com/sassywares/sassy-agents), installed per harness (`~/.pi/agent/agents/`, `~/.claude/agents/`, or a project `.pi/agents/` / `.claude/agents/`) by `sassy-setup`. Skills delegate bounded work to agents such as `scout`, `worker`, `reviewer`, and `validator`.
14
14
 
15
15
  ## Orchestrator
16
16
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sassywares/skills",
3
- "version": "0.5.14",
3
+ "version": "0.5.16",
4
4
  "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -3,7 +3,9 @@ name: sassy-setup
3
3
  description: >-
4
4
  Detect a project's topology and wire it for the Sassy Skills suite: write
5
5
  .sassywares/config.yaml, vendor the skills from upstream with the open
6
- `skills` CLI, and install the snapshot tooling in a multi-repo workspace.
6
+ `skills` CLI, check for the sassy-agents subagents and install them for the
7
+ running harness when missing, and install the snapshot tooling in a
8
+ multi-repo workspace.
7
9
  Use when asked to set up or configure a project, or to check an existing
8
10
  setup (`mode:check`).
9
11
  argument-hint: "[path] [mode:init|check]"
@@ -12,7 +14,7 @@ disable-model-invocation: true
12
14
 
13
15
  # Sassy Setup
14
16
 
15
- **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, the snapshot tooling installed in `workspace` mode, and every file setup wrote committed — so the project is wired and the user is good to go in one run.
17
+ **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, the sassy-agents roster installed for the running harness, the snapshot tooling installed in `workspace` mode, and every file setup wrote committed — so the project is wired and the user is good to go in one run.
16
18
 
17
19
  **Read `references/config.md` first.** It is the schema and the resolution rules; this skill only decides and writes.
18
20
 
@@ -43,20 +45,36 @@ A check run never edits the config and never rewrites the tree: it prints what `
43
45
  - **`pr.*`** — default `babysit: true`, `merge: false`, `delete_branch: false`. Say plainly that `merge: true` authorizes merging every babysat PR in this project without asking.
44
46
  - **Hooks** — offer, do not impose. Ask whether the project wants steps injected at `before_create`, `after_create`, `before_merge`, or `after_merge`, and under which head branch (`"*"` for all). Entries may carry args (`<skill> <args…>`); a hook skill's args are its own vocabulary. Leave them `[]` when there is 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.
45
47
  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.
46
- 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.
48
+ 5. **Wire the skills and the agents.** 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.
47
49
 
48
50
  - **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`.
49
51
  - **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. Note for yourself that `npx skills check` is an alias of `update` — it is not a validator, and running it here would silently move the pin.
50
52
  - **The pin is the commit.** `.agents/skills/sassy-*` and `skills-lock.json` are the pin, and step 8 commits them together so a clone needs no network.
51
53
  - **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.
52
54
  - **Write `.sassywares/README.md`** from `assets/sassywares-readme.md` when absent. Never overwrite it — it may carry project notes.
53
- - **Tell the user to `/reload`.** The skills are invisible to the harness until it rescans.
55
+ - **Wire the agents.** The skills dispatch four subagents by name — `scout`, `worker`, `reviewer`, `validator` — from [`sassy-agents`](https://github.com/sassywares/sassy-agents), which keeps one folder per harness. Use the row for the harness you are running in:
54
56
 
55
- 6. **Install the workspace tooling, `workspace` only.** The snapshot plus the `branches` / `pull` / `checkout-bases` git helpers. Read `references/workspace.md` and follow it.
57
+ | Harness | sassy-agents folder | User scope | Project scope |
58
+ |---|---|---|---|
59
+ | pi | `pi/` | `~/.pi/agent/agents/` | `.pi/agents/` |
60
+ | Claude Code | `claude/` | `~/.claude/agents/` | `.claude/agents/` |
61
+
62
+ A harness with no row has no folder in sassy-agents: say so, skip the agents, and name it in the report. Never translate another harness's folder by hand.
63
+
64
+ **Installed** means all four `<name>.md` files exist in the user scope or the project scope. If they do, report which scope and move on. If any are missing, ask once where to install, recommending user scope:
65
+
66
+ - **User scope** — every project on this machine, updated by `git pull`. Reuse the user's sassy-agents checkout if they have one; otherwise ask where to clone it (`git clone https://github.com/sassywares/sassy-agents.git <dir>`). Then run `<dir>/scripts/install.sh <folder>`, which symlinks the folder into the user scope and never overwrites a differing file.
67
+ - **Project scope** — only this project, pinned with it. Shallow-clone into a temp directory, copy `<folder>/*.md` into the project scope directory, delete the clone. Never overwrite an existing agent file that differs: show it and ask. The copies join step 8's commit list.
68
+
69
+ - **Tell the user to `/reload`** (or restart the harness). The skills and agents are invisible to the harness until it rescans.
70
+
71
+ 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.
56
72
  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.
73
+
74
+ Then check the agents exactly as step 5's **Installed** rule says, and report the scope they were found in or which are missing. A check run never installs them; a missing roster is reported with the fix (`mode:init`), and it does not block step 8.
57
75
  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:
58
76
 
59
- `.sassywares/config.yaml`, `.sassywares/README.md`, `.agents/skills/sassy-*`, `skills-lock.json`, and `.gitignore` when step 5 created it. Named files only — never `git add -A`, never `git add .`.
77
+ `.sassywares/config.yaml`, `.sassywares/README.md`, `.agents/skills/sassy-*`, `skills-lock.json`, the project-scope agent files when step 5 copied them, and `.gitignore` when step 5 created it. Named files only — never `git add -A`, never `git add .`.
60
78
 
61
79
  Dispatch `sassy-commit` with that list and `branch:current`. The token is explicit, not this skill's default: wiring is a one-time bootstrap commit, and cutting a branch would leave the project configured but uncommitted until someone ships it. Name the branch it landed on, base branch included.
62
80
 
@@ -65,7 +83,7 @@ A check run never edits the config and never rewrites the tree: it prints what `
65
83
  - **`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.
66
84
  - **`none`** — nothing to commit, deliberately.
67
85
 
68
- 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.
86
+ 9. **Report.** The config path, the topology, the resolved artifact and knowledge paths, where the agents are installed (scope and harness) or why they are not, 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.
69
87
 
70
88
  ## Hard rules
71
89
 
@@ -78,8 +96,9 @@ A check run never edits the config and never rewrites the tree: it prints what `
78
96
  | No silent overwrite | An existing config or an existing `.sassywares/workspace/snapshot` is shown and asked about, never replaced blind. |
79
97
  | Version is reported | Setup names the snapshot and `workspace-git` versions it installed; `--check` flags an installed copy older than the skill's. |
80
98
  | Skills come from upstream | Install with `npx skills add`; never hand-copy skill files or maintain the links yourself. |
81
- | Never edit the manifest | No dependencies, no scripts, no `postinstall`. Setup installs the suite; the project decides how it updates. |
82
- | 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/`. |
99
+ | Agents come from sassy-agents | Only the running harness's folder, as-is: linked by `install.sh` (user scope) or copied verbatim (project scope). Never edit, merge, or overwrite a differing agent file without asking. |
100
+ | 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. |
101
+ | Write boundary | Only `.sassywares/`, the vendored `.agents/skills/sassy-*`, `skills-lock.json`, the agent files step 5 installed, 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/`. |
83
102
  | Detect, don't guess | An unknown base branch stays unknown and gets asked about. A probed value is reported as probed. |
84
103
  | Comments are part of the file | Every key keeps its description and allowed values. A stripped config is an incomplete config. |
85
104
  | Hooks are named, not written | Setup records hook skill names. Creating those skills is the project's work. |
@@ -19,6 +19,18 @@ The vendored skills and the lock are committed; `.claude/skills` is a link and i
19
19
 
20
20
  `.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.
21
21
 
22
+ ## Agents
23
+
24
+ The skills dispatch four subagents by name — `scout`, `worker`, `reviewer`,
25
+ `validator` — from [sassy-agents](https://github.com/sassywares/sassy-agents),
26
+ one folder per harness (`pi/`, `claude/`). They live either in the harness's
27
+ user directory (`~/.pi/agent/agents/`, `~/.claude/agents/`, linked by
28
+ `sassy-agents/scripts/install.sh <harness>`) or in this project's
29
+ `.pi/agents/` / `.claude/agents/`. `sassy-setup` checks for them and offers to
30
+ install them when missing.
31
+
32
+ ## Missing skills
33
+
22
34
  If a skill tells you another skill is missing, run `npx skills add sassywares/sassy-skills` (or `npx skills experimental_install` to restore exactly what the lock pins) and restart.
23
35
 
24
36
  ## Config
@@ -43,6 +55,11 @@ across the sibling repos, next to the `snapshot` that versions the glue:
43
55
  .sassywares/workspace/snapshot # commit + push the glue
44
56
  ```
45
57
 
58
+ Each one also has an alias in the project manifest (`workspace:branches`,
59
+ `workspace:pull`, `workspace:checkout-bases`, `workspace:snapshot`), so
60
+ `npm run workspace:pull` — or the equivalent for the runner this project uses —
61
+ works from the root.
62
+
46
63
  They read the repo inventory and the PR bases from `repos:` in `config.yaml`, so
47
64
  there is no second base map to keep in step. They are this project's files:
48
65
  extend them freely — just run the snapshot afterwards, since they live in the
@@ -27,6 +27,8 @@ lives under one directory:
27
27
  `_lib.sh`'s `workspace-git-version` (or `branches --version`) the same way.
28
28
  **Ask before overwriting any of them when they already exist** — from the first
29
29
  install on they are the project's files, and extending them is expected.
30
+ - **Aliases.** One `workspace:<script>` entry per installed script, in the
31
+ project's own manifest. See below.
30
32
  - **Excludes.** Write `.sassywares/workspace/.gitignore` for excluded paths
31
33
  (vendored trees, generated dirs, `.run/`). One pattern per line, `.gitignore`
32
34
  style. Skip it when there is nothing to exclude; the sync works without it. The
@@ -36,6 +38,57 @@ lives under one directory:
36
38
  - Do **not** run the snapshot during setup. It clones and pushes; that is the
37
39
  user's call. Offer `--dry-run` and run it only if they ask.
38
40
 
41
+ ## Script aliases
42
+
43
+ The scripts should be reachable from the project's own runner, so setup wires one
44
+ alias per installed script:
45
+
46
+ ```json
47
+ "scripts": {
48
+ "workspace:branches": ".sassywares/workspace/branches",
49
+ "workspace:pull": ".sassywares/workspace/pull",
50
+ "workspace:checkout-bases": ".sassywares/workspace/checkout-bases",
51
+ "workspace:snapshot": ".sassywares/workspace/snapshot"
52
+ }
53
+ ```
54
+
55
+ Find the file that carries named commands — at the **workspace root only**, never
56
+ inside a repo:
57
+
58
+ | File at the root | Write the aliases to |
59
+ | --- | --- |
60
+ | `package.json` | its `scripts` |
61
+ | `deno.json` / `deno.jsonc` | its `tasks` |
62
+ | `composer.json` | its `scripts` |
63
+ | `go.mod`, `pyproject.toml`, `Cargo.toml`, `Gemfile`, `Makefile`, `justfile`, … | nothing: create `package.json` as below |
64
+
65
+ `go.mod` and friends name dependencies, not commands, and a make/just target
66
+ cannot carry the `workspace:` form. Never invent a `Makefile` or `justfile` to
67
+ avoid `package.json` — one naming convention across projects is worth more than
68
+ one file fewer.
69
+
70
+ - **Name and value are fixed**: `workspace:<script>` → `.sassywares/workspace/<script>`.
71
+ No `./`, no absolute paths, no `bin/`.
72
+ - **Merge, never rewrite**: existing scripts and every other field stay as they
73
+ are; new keys go at the end of the scripts block; keep the file's indentation.
74
+ Never touch dependencies, `postinstall`, or `skills:*`.
75
+ - **Idempotent**: a matching alias is left alone, a stale value is corrected, and
76
+ an alias the project added itself is never removed.
77
+ - **No manifest at all?** Look at what the repos are — Node, Go, Python, a mix —
78
+ and say so. Then create a minimal `package.json`:
79
+
80
+ ```json
81
+ {
82
+ "private": true,
83
+ "scripts": { … }
84
+ }
85
+ ```
86
+
87
+ `private: true` keeps it unpublishable; no `name`, no `version`, no
88
+ dependencies. It exists so the aliases have a home. **Say that in the report** —
89
+ created versus already there — and skip the aliases entirely when the project
90
+ has removed the scripts they point at.
91
+
39
92
  ## What the git helpers are for
40
93
 
41
94
  `branches`, `pull`, and `checkout-bases` do across the workspace's repos what the
@@ -430,6 +430,28 @@ if (( CHECK )); then
430
430
  else
431
431
  note " no workspace git helpers installed (optional)"
432
432
  fi
433
+
434
+ # Aliases live in the project's own manifest; setup only ever adds them.
435
+ manifest=""
436
+ for candidate in package.json deno.json deno.jsonc composer.json; do
437
+ if [[ -f "$ROOT/$candidate" ]]; then
438
+ manifest="$candidate"
439
+ break
440
+ fi
441
+ done
442
+ if [[ -n "$manifest" ]]; then
443
+ missing_aliases=()
444
+ for script in branches pull checkout-bases snapshot; do
445
+ grep -q "\"workspace:${script}\"" "$ROOT/$manifest" || missing_aliases+=("$script")
446
+ done
447
+ if [[ ${#missing_aliases[@]} -eq 0 ]]; then
448
+ note " workspace:* aliases in ${manifest}"
449
+ elif [[ ${#missing_aliases[@]} -lt 4 ]]; then
450
+ bad "${manifest} is missing $(printf '`workspace:%s` ' "${missing_aliases[@]}")— half-wired aliases; re-run setup"
451
+ else
452
+ note " no workspace:* aliases in ${manifest} (optional)"
453
+ fi
454
+ fi
433
455
  while IFS= read -r name; do
434
456
  [[ -n "$name" ]] || continue
435
457
  base="$(detect_base "$ROOT/$name")"