@sassywares/skills 0.5.15 → 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
|
|
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
|
@@ -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,
|
|
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
|
-
- **
|
|
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:
|
|
56
|
+
|
|
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.
|
|
54
70
|
|
|
55
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`), 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.
|
|
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. |
|
|
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. |
|
|
81
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. |
|
|
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` 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/`. |
|
|
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
|