@sassywares/skills 0.6.6 → 0.6.7
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 +3 -3
- package/README.md +46 -41
- package/package.json +1 -1
- package/skills/sassy-cycle/SKILL.md +25 -12
- package/skills/sassy-debug/SKILL.md +13 -21
- package/skills/sassy-lfg/SKILL.md +8 -7
- package/skills/sassy-setup/SKILL.md +26 -20
- package/skills/sassy-setup/assets/sassywares-readme.md +16 -12
- package/skills/sassy-setup/references/config.md +5 -3
- package/skills/sassy-setup/scripts/detect.sh +2 -1
- package/skills/sassy-setup/scripts/lockcheck.mjs +30 -2
- package/skills/sassy-work/SKILL.md +9 -8
package/CONCEPTS.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
## Source of truth
|
|
4
4
|
|
|
5
|
-
The repo's `skills/` directory is the only copy of the skills. Consumers install from it with `npx skills add sassywares/sassy-skills
|
|
5
|
+
The repo's `skills/` directory is the only copy of the skills. Consumers install from it with `npx skills add sassywares/sassy-skills` — per project, which vendors the files and pins content hashes in `skills-lock.json`, or globally with `-g`, into `~/.agents/skills/`. See README.md's Installation section.
|
|
6
6
|
|
|
7
7
|
## Skill
|
|
8
8
|
|
|
@@ -18,7 +18,7 @@ A skill that mostly coordinates. It reads compact results, writes briefs, and av
|
|
|
18
18
|
|
|
19
19
|
## Cycle
|
|
20
20
|
|
|
21
|
-
`sassy-cycle` runs one unit of work through implement → review → validate → fix →
|
|
21
|
+
`sassy-cycle` runs one unit of work through implement → review → validate → fix → verify. Verify is a reviewer scoped to the fix, confirming each finding resolved and checking the fix for new ones; at most two fix passes, then anything open is `blocked`. Reviewer suggestions never block; they go to the gate. Given findings instead of a brief — requested changes, failed QA rows — it reworks existing work through the same fix → verify loop. It never commits. Work and LFG run it; debug fixes through work.
|
|
22
22
|
|
|
23
23
|
## Gates
|
|
24
24
|
|
|
@@ -62,4 +62,4 @@ A settled in-context brief produced by `sassy-plan` when the user picks "start w
|
|
|
62
62
|
|
|
63
63
|
## Sync
|
|
64
64
|
|
|
65
|
-
There is no background watcher. Any agent that changes a skill must run `scripts/sync.sh` immediately, without asking for confirmation.
|
|
65
|
+
There is no background watcher. Any agent that changes a skill must run `scripts/sync.sh` immediately, without asking for confirmation. It commits and pushes; on `main`, when shipped files changed, it also bumps the patch version and tags, which publishes to npm. It installs nothing: `npx skills add` reads this repo directly. AGENTS.md has the details.
|
package/README.md
CHANGED
|
@@ -16,14 +16,17 @@ It covers the whole path from a rough idea to a shipped PR, and from a bug repor
|
|
|
16
16
|
- [From idea to ship](#from-idea-to-ship)
|
|
17
17
|
- [From bug to ship](#from-bug-to-ship)
|
|
18
18
|
- [Gates and controls](#gates-and-controls)
|
|
19
|
-
- [
|
|
19
|
+
- [Branching](#branching)
|
|
20
20
|
- [Installation](#installation)
|
|
21
|
+
- [Per project](#per-project)
|
|
22
|
+
- [Globally](#globally)
|
|
23
|
+
- [Both at once](#both-at-once)
|
|
21
24
|
- [Repository maintenance](#repository-maintenance)
|
|
22
25
|
|
|
23
26
|
## Why this suite
|
|
24
27
|
|
|
25
28
|
- **Lean.** Skills are indexes and workflows, not documentation dumps. Detail moves into `references/` only when it is conditionally needed.
|
|
26
|
-
- **Explicit.** Every skill
|
|
29
|
+
- **Explicit.** Every skill but `sassy-ship` runs only when you invoke it; ship may be started by the agent once you approve the work, and its review gate still waits. No silent background behavior.
|
|
27
30
|
- **Controlled.** Code approval, manual QA, and ship review are visible gates that all run in sequence. There are two mode tokens, `mode:manual` (default) and `mode:auto`, accepted by `sassy-ship` and `sassy-compound` only; every other skill takes no mode.
|
|
28
31
|
- **Reliable.** Work runs through `sassy-cycle` with isolated subagents for implementation, review, validation, and fixes.
|
|
29
32
|
- **Context-efficient.** Orchestrators coordinate; subagents do the heavy reading and return compact results.
|
|
@@ -83,8 +86,8 @@ Debugging:
|
|
|
83
86
|
| **`sassy-scout`** | Grounds an area on demand and writes the shared grounding brief other agents read instead of re-exploring. |
|
|
84
87
|
| **`sassy-work`** | Executes exactly one plan phase, or one in-context brief, commits after code approval, then hands off the next phase — a brief stops before ship. |
|
|
85
88
|
| **`sassy-lfg`** | Executes every phase of a plan, or one in-context brief, then closes out via `sassy-ship` after code approval. |
|
|
86
|
-
| **`sassy-cycle`** | Runs one unit of work through implement → review → validate → fix →
|
|
87
|
-
| **`sassy-debug`** | Diagnoses a bug, gates the fix, fixes via `sassy-cycle
|
|
89
|
+
| **`sassy-cycle`** | Runs one unit of work through implement → review → validate → fix → verify, with at most two verified fix passes. Also reworks finished work from requested changes or failed QA rows. |
|
|
90
|
+
| **`sassy-debug`** | Diagnoses a bug, gates the fix, fixes via `sassy-work` (cycle, code approval, commit), then ships. Debug takes no mode and always leaves ship's review gate in place unless you invoke ship yourself with `mode:auto`. |
|
|
88
91
|
| **`sassy-handoff`** | `mode:write` (default) writes a self-contained handoff file to `/tmp/sassywares/<harness>/handoffs/` and gives you a `sassy-handoff mode:read <path>` command for a fresh session; `mode:read` explains what the handoff did, why, and where things stand now, then asks what to do next. Works in any harness. |
|
|
89
92
|
|
|
90
93
|
### Code quality
|
|
@@ -115,7 +118,7 @@ Debugging:
|
|
|
115
118
|
| Skill | What it does |
|
|
116
119
|
|---|---|
|
|
117
120
|
| **`sassy-skill`** | Creates, retunes, or restructures Agent Skills. |
|
|
118
|
-
| **`sassy-setup`** | Detects the project topology and writes `.sassywares/config.yaml`; installs the sassy-agents subagents
|
|
121
|
+
| **`sassy-setup`** | Detects the project topology and writes `.sassywares/config.yaml`; installs the suite and the sassy-agents subagents, globally or per project, when missing; installs the snapshot tooling for a multi-repo workspace; commits the files it wrote. `mode:check` verifies an existing setup, including a project install's pin. |
|
|
119
122
|
|
|
120
123
|
## Project config
|
|
121
124
|
|
|
@@ -214,6 +217,8 @@ Option 1 produces a durable plan with phased slices and manual QA tables. Option
|
|
|
214
217
|
|
|
215
218
|
`sassy-work` handles one phase and hands off the next. `sassy-lfg` drains the whole plan in one session. Both delegate to `sassy-cycle` and stop at one gate carrying code approval plus the manual QA checklist; nothing is `Done`, committed, or shipped until both pass. With an in-context brief there are no QA rows, so the gate is code approval alone.
|
|
216
219
|
|
|
220
|
+
Inside the cycle, every finding is fixed and then **verified**: a reviewer scoped to the fix confirms each finding resolved, and checks the fix itself for anything new. Whatever is still open gets a second fix pass; anything open after that comes back `blocked` rather than looping. Critical findings and warnings are fixed automatically; the reviewer's suggestions are listed at the gate for you to pick. Changes you request at the gate and QA rows that fail go through the same loop as findings, then the gate comes back.
|
|
221
|
+
|
|
217
222
|
The branch is cut once, before the first change, by `sassy-work` or `sassy-lfg` — never at commit time — and `sassy-ship` never creates it. `commit.branch` (default `new`) decides whether the run cuts one at all; see [Branching](#branching).
|
|
218
223
|
|
|
219
224
|
`sassy-ship` is the close-out. It summarizes what is about to ship and waits, unless the caller passed `mode:auto`.
|
|
@@ -232,7 +237,8 @@ flowchart LR
|
|
|
232
237
|
E -->|4. stop| I[Diagnosis only]
|
|
233
238
|
F --> J{Code approval}
|
|
234
239
|
J -->|changes| F
|
|
235
|
-
J -->|approved|
|
|
240
|
+
J -->|approved| N[Commit]
|
|
241
|
+
N --> K[sassy-ship]
|
|
236
242
|
K --> L{Ship review}
|
|
237
243
|
L -->|approve| M[Commit, PR, babysit]
|
|
238
244
|
```
|
|
@@ -241,7 +247,7 @@ flowchart LR
|
|
|
241
247
|
|
|
242
248
|
The fix gate offers four options:
|
|
243
249
|
|
|
244
|
-
- **Fix it now** — hand the fix brief to `sassy-work`: one cycle,
|
|
250
|
+
- **Fix it now** — hand the fix brief to `sassy-work`: one cycle, the code approval gate, a commit; then debug ships it via `sassy-ship`
|
|
245
251
|
- **Write a plan** — carry the diagnosis into `sassy-plan`, which ends in its own 3-option picker
|
|
246
252
|
- **Hand off** — continue in a fresh session via `sassy-handoff`
|
|
247
253
|
- **Stop here** — keep the diagnosis and change nothing
|
|
@@ -266,25 +272,13 @@ A base is **any `base_map` value**, not just the remote default: in a repo whose
|
|
|
266
272
|
|
|
267
273
|
The three skills take `branch:infer|current|new` to override the config's branching for one run (the no-PR close-out follows the config `commit.branch: current` regardless of the token): `infer` (default) means the config decides, `new` forces a branch, `current` commits where you stand; it does not skip the PR. Only `commit.branch: current` in the config makes the close-out push to the upstream with no PR, hooks, or babysit. `sassy-ship` never creates a branch; finding the head on a base branch with unpublished commits is a stop-and-ask, except under `commit.branch: current`, where they are pushed along.
|
|
268
274
|
|
|
269
|
-
##
|
|
275
|
+
## Installation
|
|
270
276
|
|
|
271
|
-
|
|
272
|
-
sassy-skills/
|
|
273
|
-
├── skills/
|
|
274
|
-
│ ├── sassy-plan/
|
|
275
|
-
│ ├── sassy-work/
|
|
276
|
-
│ ├── sassy-lfg/
|
|
277
|
-
│ └── ...
|
|
278
|
-
├── scripts/
|
|
279
|
-
│ └── sync.sh
|
|
280
|
-
├── AGENTS.md
|
|
281
|
-
├── CONCEPTS.md
|
|
282
|
-
└── README.md
|
|
283
|
-
```
|
|
277
|
+
The suite installs from this repository with the open `skills` CLI. Install it per project, globally, or both.
|
|
284
278
|
|
|
285
|
-
|
|
279
|
+
### Per project
|
|
286
280
|
|
|
287
|
-
The
|
|
281
|
+
The team's setup. The CLI vendors the skill files into the project and pins them, so a clone needs no network and every checkout runs the same skills.
|
|
288
282
|
|
|
289
283
|
```bash
|
|
290
284
|
npx skills add sassywares/sassy-skills
|
|
@@ -299,41 +293,52 @@ That writes three things:
|
|
|
299
293
|
Commit the vendored skills and the lock; ignore `.claude/skills`, which is a link created at install time.
|
|
300
294
|
|
|
301
295
|
```bash
|
|
302
|
-
npx skills update -y
|
|
296
|
+
npx skills update -p -y # pull the latest from this repo
|
|
303
297
|
npx skills experimental_install # restore exactly what the lock pins
|
|
304
|
-
npx skills remove
|
|
298
|
+
npx skills remove --all # take the suite out again
|
|
305
299
|
```
|
|
306
300
|
|
|
307
301
|
`npx skills check` is an alias for `update`: it moves the pin, it does not validate it. To check a project's setup without touching the pin, run `sassy-setup` with `mode:check`.
|
|
308
302
|
|
|
309
|
-
|
|
303
|
+
### Globally
|
|
310
304
|
|
|
311
|
-
|
|
305
|
+
Your own setup, in every project on this machine, with nothing committed anywhere.
|
|
312
306
|
|
|
313
|
-
|
|
307
|
+
```bash
|
|
308
|
+
npx skills add sassywares/sassy-skills -g
|
|
309
|
+
```
|
|
314
310
|
|
|
315
|
-
|
|
311
|
+
That writes:
|
|
316
312
|
|
|
317
|
-
|
|
313
|
+
- `~/.agents/skills/sassy-*` — the skill files, read by pi and other harnesses that use `~/.agents/skills`
|
|
314
|
+
- `~/.claude/skills/sassy-*` — links for Claude Code
|
|
315
|
+
- `~/.agents/.skill-lock.json` — the global lock
|
|
318
316
|
|
|
319
317
|
```bash
|
|
320
|
-
|
|
318
|
+
npx skills update -g -y # pull the latest from this repo
|
|
319
|
+
npx skills remove -g --all # take the suite out again
|
|
321
320
|
```
|
|
322
321
|
|
|
323
|
-
|
|
322
|
+
A global install is yours alone: teammates do not get it, and it moves whenever you update rather than with the project.
|
|
323
|
+
|
|
324
|
+
### Both at once
|
|
325
|
+
|
|
326
|
+
A skill installed in both places is listed once, not twice; the harness picks one copy. Claude Code prefers the global copy over the project's, so on a machine with a global install the project's pin does not decide which version Claude Code runs. Other harnesses apply their own precedence. When a project's pinned version must be the one that runs, skip the global install on that machine.
|
|
324
327
|
|
|
325
|
-
`
|
|
328
|
+
`sassy-setup` handles either scope, the same way it handles the agents: if the suite is already installed it reports where, and if not it asks where to install it, recommending global. A project install also gets the ignore line, the verified pin, and the commit. `mode:check` verifies the pin only for a project install; a global one has nothing to pin.
|
|
326
329
|
|
|
327
|
-
###
|
|
330
|
+
### While editing the suite
|
|
331
|
+
|
|
332
|
+
`.pi/settings.json` in this repo declares `./skills`, so pi loads your working copy directly. Consumers see a change once it is pushed to `main` and they run `npx skills update` — no release step in between.
|
|
328
333
|
|
|
329
|
-
|
|
334
|
+
### Also published as a package
|
|
330
335
|
|
|
331
|
-
|
|
336
|
+
`@sassywares/skills` is on npm for harnesses that install packages rather than skill directories:
|
|
332
337
|
|
|
333
338
|
```bash
|
|
334
|
-
|
|
335
|
-
git add -A && git commit -m "chore: release v$(node -p "require('./package.json').version")"
|
|
336
|
-
git push origin main
|
|
337
|
-
git tag "v$(node -p "require('./package.json').version")"
|
|
338
|
-
git push origin --tags
|
|
339
|
+
pi install npm:@sassywares/skills
|
|
339
340
|
```
|
|
341
|
+
|
|
342
|
+
## Repository maintenance
|
|
343
|
+
|
|
344
|
+
Any agent that changes a skill runs `scripts/sync.sh` immediately, which commits, pushes, and — on `main`, when shipped files changed — bumps the patch version and tags the release that publishes `@sassywares/skills` to npm. [`AGENTS.md`](AGENTS.md) is the full guide: layout, adding a skill, sync, and the manual release fallback.
|
package/package.json
CHANGED
|
@@ -2,16 +2,17 @@
|
|
|
2
2
|
name: sassy-cycle
|
|
3
3
|
description: >-
|
|
4
4
|
Run one unit of work through the full quality loop using subagents: implement,
|
|
5
|
-
review, validate, fix findings
|
|
6
|
-
|
|
5
|
+
review, validate, then fix and verify findings — at most two fix passes.
|
|
6
|
+
Also reworks finished work from a list of findings (requested changes,
|
|
7
|
+
failed QA rows). Used by sassy-work and sassy-lfg. Never commits. Built for context and token
|
|
7
8
|
efficiency — the orchestrator only writes briefs and reads compact results.
|
|
8
|
-
argument-hint: "<work brief> [intent reference]"
|
|
9
|
+
argument-hint: "<work brief | findings> [intent reference]"
|
|
9
10
|
disable-model-invocation: true
|
|
10
11
|
---
|
|
11
12
|
|
|
12
13
|
# Sassy Cycle
|
|
13
14
|
|
|
14
|
-
**Outcome:** one unit of work taken through the full quality loop,
|
|
15
|
+
**Outcome:** one unit of work taken through the full quality loop, every finding fixed and verified fixed by a reviewer — or reported open after two fix passes — returning a compact structured result to the caller. This skill never commits, pushes, or ships.
|
|
15
16
|
|
|
16
17
|
**Subagent-maximal by design.** The orchestrator (the main context) must never read source files, diffs, or the tree. Every heavy read happens inside a subagent with its own isolated context window. The orchestrator only writes briefs and reads compact structured results. This is what keeps the caller's context small across many phases.
|
|
17
18
|
|
|
@@ -22,20 +23,27 @@ disable-model-invocation: true
|
|
|
22
23
|
- **Work brief** — what to build or fix, concretely.
|
|
23
24
|
- **Intent reference** — how conformance is judged: a plan path + phase, or root-cause findings.
|
|
24
25
|
- **Scope hint** — files or areas, optional.
|
|
26
|
+
- **Findings** — rework only: a list of changes to make to work that already exists — the user's requested changes, failing QA rows. Given findings, skip steps 1–3 and start at step 4. The intent reference stays the original one, so the validator still judges the whole unit.
|
|
25
27
|
|
|
26
28
|
## Steps
|
|
27
29
|
|
|
28
30
|
1. **Recon (optional).** If the work is large or its location is unclear, run `sassy-scout` first and pass the grounding brief path into the work brief. Skip when the brief is already precise.
|
|
29
|
-
2. **Implement.** Dispatch a `worker` with the work brief, the intent reference, and the plan path if there is one. Every worker brief must also carry these constraints:
|
|
31
|
+
2. **Implement.** Dispatch a `worker` with the work brief, the intent reference, and the plan path if there is one. Every worker brief — here and in step 5 — must also carry these constraints:
|
|
30
32
|
- Tests only for the files the worker changed and the existing tests that directly regress them. The full suite runs once at the final gate.
|
|
31
33
|
- A hard timeout around long-running commands, for example `timeout 300 bunx vitest run path/to/file.test.ts`; a hung command is killed and reported.
|
|
32
34
|
- Stop and report a blocker to the orchestrator after one failed retry, with the exact command and error, instead of looping on the same failure.
|
|
35
|
+
- Report the files it changed.
|
|
33
36
|
|
|
34
37
|
For independent chunks, batch them as **parallel** `worker` tasks in one call (max 8). The worker reads whatever it needs itself.
|
|
35
|
-
3. **Review + validate (parallel).** Dispatch the `reviewer` and the `validator` together in one **parallel** call. Give the validator the intent reference so it can judge conformance. Simplification opportunities belong in the reviewer's Suggestions
|
|
36
|
-
4. **
|
|
37
|
-
5. **
|
|
38
|
-
6. **
|
|
38
|
+
3. **Review + validate (parallel).** Dispatch the `reviewer` and the `validator` together in one **parallel** call. Give the validator the intent reference so it can judge conformance. Simplification opportunities belong in the reviewer's Suggestions.
|
|
39
|
+
4. **Triage.** The open list is every reviewer **critical** and **warning**, every validator gap, and every blocker a worker reported — or, on rework, the findings given. Reviewer **Suggestions** are not findings: carry them to the result untouched for the caller's gate. An empty open list → step 7.
|
|
40
|
+
5. **Fix.** Dispatch one `worker` with the open list, numbered, to fix exactly those and nothing else. This is fix pass 1 or 2.
|
|
41
|
+
6. **Verify (parallel).** Dispatch the `reviewer` and the `validator` together, both scoped to this fix:
|
|
42
|
+
- **Reviewer** — the numbered open list and the files the fix changed. It returns, per finding, `resolved` or `not resolved` with a reason, plus any **new** critical or warning the fix's changes introduced.
|
|
43
|
+
- **Validator** — the intent reference plus the open list. It re-grades conformance and names any gap left.
|
|
44
|
+
|
|
45
|
+
The new open list is every `not resolved` finding, every new finding, and every validator gap. Empty → step 7 as `done`. Otherwise, after fix pass 1 → back to step 5; after fix pass 2 → step 7 as `blocked`.
|
|
46
|
+
7. **Return** the structured result below.
|
|
39
47
|
|
|
40
48
|
## Structured result
|
|
41
49
|
|
|
@@ -44,19 +52,24 @@ Return this to the caller, compactly:
|
|
|
44
52
|
```text
|
|
45
53
|
Status: done | blocked
|
|
46
54
|
Files changed: <paths>
|
|
47
|
-
|
|
55
|
+
Fix passes: 0 | 1 | 2
|
|
56
|
+
Findings: <finding -> resolved (pass n) | open: reason>
|
|
57
|
+
Suggestions: <reviewer suggestions, not acted on>
|
|
48
58
|
Validator: Conforms | Partial | Diverges | Blocked
|
|
49
|
-
Reviewer: <n> critical, <n> warnings
|
|
59
|
+
Reviewer: <n> critical, <n> warnings open
|
|
50
60
|
Notes: <anything the caller needs>
|
|
51
61
|
```
|
|
52
62
|
|
|
63
|
+
A finding is `resolved` only when step 6's reviewer said so. The fixing worker's own report is never evidence.
|
|
64
|
+
|
|
53
65
|
## Rules
|
|
54
66
|
|
|
55
67
|
| Rule | Requirement |
|
|
56
68
|
|------|-------------|
|
|
57
69
|
| Orchestrator only | Never edit code or read source in the main context. Delegate. |
|
|
58
70
|
| Parallel where independent | Independent work chunks → parallel workers. Reviewer + validator always run in parallel. |
|
|
59
|
-
|
|
|
71
|
+
| Two fix passes, verified | At most two fix → verify rounds per run. Every fix is verified by a reviewer scoped to that fix; anything still open after the second → `blocked`. Never loop further. |
|
|
72
|
+
| Suggestions don't block | Reviewer suggestions go to the caller's gate for the user to pick; they are never fixed automatically. |
|
|
60
73
|
| Never commit | This skill leaves everything uncommitted. Shipping is `sassy-ship`. |
|
|
61
74
|
| Manual QA | Never mark QA rows `Done`. QA is confirmed by the user at the caller's gate; failing rows come back as findings. |
|
|
62
75
|
|
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
name: sassy-debug
|
|
3
3
|
description: >-
|
|
4
4
|
Diagnose a bug to root cause, get approval for the proposed fix, then fix it
|
|
5
|
-
through sassy-
|
|
6
|
-
through sassy-ship
|
|
5
|
+
through sassy-work (quality cycle, code approval, commit), and finally ship
|
|
6
|
+
it through sassy-ship. Never auto-commits. Use when asked to
|
|
7
7
|
debug or fix a failure.
|
|
8
8
|
argument-hint: "[issue reference, error message, test path, or description] [branch:infer|current|new]"
|
|
9
9
|
disable-model-invocation: true
|
|
@@ -25,7 +25,7 @@ Find the root cause of a failure, get approval for the fix, fix it through the s
|
|
|
25
25
|
|
|
26
26
|
Establish the exact input, the observed symptom, the expected behavior, and how to reproduce it. If an issue/ticket is given, carry its identifier and URL through to the end. If only a stack trace or description is given, there is no issue of record — that is fine; never manufacture one.
|
|
27
27
|
|
|
28
|
-
Trivial bugs whose cause is readable from the input may skip the scout, but still state the causal chain and pass the fix gate before changing code, then run the fix through `sassy-
|
|
28
|
+
Trivial bugs whose cause is readable from the input may skip the scout, but still state the causal chain and pass the fix gate before changing code, then run the fix through `sassy-work`.
|
|
29
29
|
|
|
30
30
|
**Search prior learnings first.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. For every existing path in `knowledge.read`, search the docs for the symptom's keywords, the module, and the failure type. A matching doc **seeds or confirms** a hypothesis — it never replaces the causal chain or the reproduction. Name the docs you consulted, and say plainly when none matched: no match is not evidence that nothing similar has happened.
|
|
31
31
|
|
|
@@ -61,11 +61,17 @@ This gate is mandatory even when the original request said "fix the bug". Do not
|
|
|
61
61
|
|
|
62
62
|
### Option 1 — Fix it now
|
|
63
63
|
|
|
64
|
-
Load the `sassy-work` skill
|
|
64
|
+
Load the `sassy-work` skill on its brief path, forwarding this run's `branch:` token if it was given, with:
|
|
65
|
+
|
|
66
|
+
- work brief = "Fix the root cause: <causal chain>. Apply the smallest change; add or strengthen the regression test first."
|
|
67
|
+
- intent reference = the diagnosis from Phase 1
|
|
68
|
+
- scope hint = the files the fix touches
|
|
69
|
+
|
|
70
|
+
Work owns the fix from here: one `sassy-cycle` (fix, review, validate, verified fix passes), its code approval gate — where the result shows the causal chain next to the fix — the rework loop for any changes the user asks for, and the commit. It stops before ship. Do not dispatch `sassy-cycle` or present a second code approval gate yourself.
|
|
65
71
|
|
|
66
72
|
The branch decision belongs to work, not to this phase: diagnosis writes nothing, so cutting a branch before the fix gate would leave an empty branch every time the gate ends in *Write a plan*, *Hand off*, or *Stop here*. Work resolves it per `sassy-setup`'s `references/branching.md` before it touches code, so the fix is on its own branch from the first edit and still never lands on a base branch.
|
|
67
73
|
|
|
68
|
-
|
|
74
|
+
When work committed the fix, continue to Phase 3. When it ended `Blocked`, stop and report the open findings — nothing ships.
|
|
69
75
|
|
|
70
76
|
### Option 2 — Write a plan
|
|
71
77
|
|
|
@@ -79,23 +85,9 @@ Load the `sassy-handoff` skill in `mode:write` with the root-cause chain and pro
|
|
|
79
85
|
|
|
80
86
|
Report the diagnosis and stop. Nothing is committed.
|
|
81
87
|
|
|
82
|
-
## Phase 3 —
|
|
83
|
-
|
|
84
|
-
Runs only after the user picked **Fix it now** at the fix gate. Load the `sassy-cycle` skill and follow it, with:
|
|
85
|
-
|
|
86
|
-
- work brief = "Fix the root cause: <causal chain>. Apply the smallest change; add or strengthen the regression test first."
|
|
87
|
-
- intent reference = the diagnosis from Phase 1
|
|
88
|
-
- scope hint = the files the fix touches
|
|
89
|
-
|
|
90
|
-
This runs fix → review → validate → fix findings, all in subagents. Do **not** commit.
|
|
91
|
-
|
|
92
|
-
## Phase 4 — Code approval gate
|
|
93
|
-
|
|
94
|
-
Leave everything uncommitted. Present the result: the causal chain, the fix, the quality result (validator grade, reviewer findings), and the files changed. Wait for the user's approval. Do **not** commit before approval.
|
|
95
|
-
|
|
96
|
-
## Phase 5 — Ship via `sassy-ship`
|
|
88
|
+
## Phase 3 — Ship via `sassy-ship`
|
|
97
89
|
|
|
98
|
-
|
|
90
|
+
After work's code approval and commit, load the `sassy-ship` skill and follow it, leaving ship's default `mode:manual` review gate in place. Do not pass a mode yourself. Ship presents its shipping summary and waits. It compounds any learnings, commits, opens or updates the PR, and babysits it via `sassy-babysit` (under `commit.branch: current` it commits and pushes the checked-out branch instead, with no PR, hooks, or babysit). Babysit options (`merge:on|off`, `delete-branch:on|off`) are forwarded through `sassy-ship`. Run only the steps the user approves.
|
|
99
91
|
|
|
100
92
|
If the fix gate ended in **Write a plan**, **Hand off**, or **Stop here**, this skill stops there — never commit.
|
|
101
93
|
|
|
@@ -32,7 +32,7 @@ If nothing is passed and no plan exists, run `sassy-plan` first and use what the
|
|
|
32
32
|
Read the plan's `**QA:**` line and its per-phase QA tables. QA is manual and part of the completion gate: LFG builds every phase first, then presents one gate carrying code approval plus every phase's QA checklist. No phase turns `Done`, and nothing is committed or shipped, until both pass.
|
|
33
33
|
|
|
34
34
|
- The user runs the checks. The agent never ticks a row it did not hear confirmed: a row becomes `Done` only on the user's explicit confirmation, with their note recorded.
|
|
35
|
-
- A failed row is a finding.
|
|
35
|
+
- A failed row is a finding. It goes through a rework cycle on its phase (step 5) and the gate is presented again; a row that fails again after its rework is `Blocked` with the reason and stops the run.
|
|
36
36
|
- Rows nobody has reported on stay `Pending` and hold their phase `In progress`.
|
|
37
37
|
|
|
38
38
|
A brief has no QA table, so its gate is code approval alone. Never invent, enable, or disable QA.
|
|
@@ -43,13 +43,13 @@ A brief has no QA table, so its gate is code approval alone. Never invent, enabl
|
|
|
43
43
|
2. **Resolve the branch, before touching code.** Follow the `sassy-setup` skill's `references/branching.md` with this run's `branch:` token, if any. LFG runs every phase in one session, so the branch is cut once here and every phase commits onto it. Report the branch and its start point in the gate. A `stop-and-ask` here stops the run before any phase starts.
|
|
44
44
|
3. **Run every phase, in order.** For each phase not `Done`:
|
|
45
45
|
- Set the phase `In progress`, then load the `sassy-cycle` skill and follow it, with work brief = the phase's goal/work/"Done when", and intent reference = the plan path and phase.
|
|
46
|
-
- On `Status: done
|
|
46
|
+
- On `Status: done`, leave the phase `In progress` — its QA rows are still owed, and only the gate closes them.
|
|
47
47
|
- On `Status: blocked`, mark it `Blocked` and stop the run.
|
|
48
|
-
4. **The gate.** After the last phase, report: the plan path, each phase's status, what changed per phase, and the validator/reviewer summaries. Then give every phase's QA checklist verbatim — row ID, check, how to run it, what passing looks like — with unreported rows `Pending`. Ask for both decisions: code approval and the QA result per row. Wait. Do not commit.
|
|
48
|
+
4. **The gate.** After the last phase, report: the plan path, each phase's status, what changed per phase, findings raised and resolved (with the fix passes each took), the validator/reviewer summaries, and the reviewers' suggestions as options the user may pick. Then give every phase's QA checklist verbatim — row ID, check, how to run it, what passing looks like — with unreported rows `Pending`. Ask for both decisions: code approval (or the changes wanted, including any suggestions picked) and the QA result per row. Wait. Do not commit.
|
|
49
49
|
5. **Resolve the gate.** Three outcomes:
|
|
50
50
|
- **Code approved and every QA row passes** → mark the rows `Done` with the user's notes, mark the phases `Done`, then run the close-out below.
|
|
51
51
|
- **Code approved, QA still pending** → tick nothing, mark nothing `Done`, commit nothing, ship nothing. Report which rows are outstanding and how to resume (invoke `sassy-lfg <plan>` in the harness's syntax), and stop.
|
|
52
|
-
- **
|
|
52
|
+
- **Changes requested, or any QA row fails** → a rework cycle per affected phase: load `sassy-cycle` with that phase's requested changes and failing rows as its findings, and the plan path and phase as the intent reference. When every rework is `done`, present the gate again; a `blocked` rework marks its phase `Blocked` and stops the run. A QA row that fails again after its rework is `Blocked` with the reason and stops the run. Change requests have no cap — each one is the user's call.
|
|
53
53
|
6. **Close-out.** On both gates passing, load the `sassy-ship` skill and follow it. Do only the close-out steps the user approves. Babysit options (`merge:on|off`, `delete-branch:on|off`) are forwarded through `sassy-ship` to `sassy-babysit`. The branch from step 2 already carries the work, so ship commits and opens the PR on it; ship never creates the branch. Under `commit.branch: current` ship commits and pushes the checked-out branch to its upstream and skips the PR, `hooks.pr.*`, babysit, and merge.
|
|
54
54
|
|
|
55
55
|
## Brief constraints
|
|
@@ -66,7 +66,7 @@ When the argument is not a plan path, the brief is the one phase:
|
|
|
66
66
|
|
|
67
67
|
1. Resolve the branch exactly as the plan path does — the `sassy-setup` skill's `references/branching.md`, this run's `branch:` token — before the cycle runs.
|
|
68
68
|
2. Run one `sassy-cycle` with the brief as the work brief and its decisions / done-when as the intent reference. Do not split it into multiple phases.
|
|
69
|
-
3. Present the code approval gate with no QA checklist, and wait.
|
|
69
|
+
3. Present the code approval gate with no QA checklist, and wait. Changes requested → a rework cycle with the changes as findings and the brief's decisions / done-when as the intent reference, then this gate again; `blocked` stops.
|
|
70
70
|
4. On code approval, run `sassy-ship`. Do not run `sassy-plan` or write a plan file.
|
|
71
71
|
|
|
72
72
|
## Hard rules
|
|
@@ -77,7 +77,8 @@ When the argument is not a plan path, the brief is the one phase:
|
|
|
77
77
|
| Branch before code | Resolve the branch per the `sassy-setup` skill's `references/branching.md` before any phase runs, so no change lands on a base branch. |
|
|
78
78
|
| Phases in plan order | Phases run one after another, in plan order. |
|
|
79
79
|
| Done needs both gates | Mark a phase `Done` only when the user approves the code and every QA row for it is `Done`. |
|
|
80
|
-
| QA rows follow the user | Tick a QA row `Done` only from the user's explicit confirmation; keep unreported rows `Pending`;
|
|
80
|
+
| QA rows follow the user | Tick a QA row `Done` only from the user's explicit confirmation; keep unreported rows `Pending`; a failed row is a finding for a rework cycle. |
|
|
81
|
+
| Send-backs are rework | Requested changes and failed QA rows go through `sassy-cycle` as findings — verified, two fix passes at most — never a direct edit. |
|
|
81
82
|
| Gates before shipping | Nothing is committed or shipped until the code is approved and every QA row passes. Shipping is `sassy-ship`. |
|
|
82
83
|
| No plan on the brief path | Use the in-context brief; never create or update a plan file. |
|
|
83
84
|
| Compact context | Only pass briefs to subagents and keep only their summaries. |
|
|
@@ -85,6 +86,6 @@ When the argument is not a plan path, the brief is the one phase:
|
|
|
85
86
|
## Failure handling
|
|
86
87
|
|
|
87
88
|
- A phase returns `blocked` → stop the run, report the open findings and diagnostic.
|
|
88
|
-
- QA rows stay pending or
|
|
89
|
+
- QA rows stay pending, or a row fails again after its rework → stop, commit nothing, ship nothing, report the outstanding rows.
|
|
89
90
|
- The validator returns **Blocked — insufficient grounding** → stop; do not advance.
|
|
90
91
|
- Ambiguous or unsafe failure → stop and ask rather than guessing.
|
|
@@ -2,10 +2,9 @@
|
|
|
2
2
|
name: sassy-setup
|
|
3
3
|
description: >-
|
|
4
4
|
Detect a project's topology and wire it for the Sassy Skills suite: write
|
|
5
|
-
.sassywares/config.yaml,
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
multi-repo workspace.
|
|
5
|
+
.sassywares/config.yaml, check for the suite's skills and the sassy-agents
|
|
6
|
+
subagents and install whichever is missing in user or project scope, and
|
|
7
|
+
install the snapshot tooling in a multi-repo workspace.
|
|
9
8
|
Use when asked to set up or configure a project, or to check an existing
|
|
10
9
|
setup (`mode:check`).
|
|
11
10
|
argument-hint: "[path] [mode:init|check]"
|
|
@@ -14,7 +13,7 @@ disable-model-invocation: true
|
|
|
14
13
|
|
|
15
14
|
# Sassy Setup
|
|
16
15
|
|
|
17
|
-
**Outcome:** `.sassywares/config.yaml` at the project root matching the tree it describes, the skills
|
|
16
|
+
**Outcome:** `.sassywares/config.yaml` at the project root matching the tree it describes, the skills installed in user or project scope 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.
|
|
18
17
|
|
|
19
18
|
**Read `references/config.md` first.** It is the schema and the resolution rules; this skill only decides and writes.
|
|
20
19
|
|
|
@@ -47,14 +46,21 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
47
46
|
- **`pr.*`** — default `babysit: true`, `merge: false`, `delete_branch: false`. Say plainly that `merge: true` authorizes merging every babysat PR in this project without asking.
|
|
48
47
|
- **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.
|
|
49
48
|
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.
|
|
50
|
-
5. **Wire the skills and the agents.**
|
|
49
|
+
5. **Wire the skills and the agents.** Both install the same way: if they are already there in either scope, report which and move on; if not, ask once where to install, recommending user scope.
|
|
50
|
+
|
|
51
|
+
- **Skills.** The suite comes from upstream with the open `skills` CLI. Never copy skill files in by hand, never add the suite as a dependency.
|
|
52
|
+
|
|
53
|
+
**Installed** means the `sassy-*` skills exist in the project scope (`.agents/skills/sassy-*`, pinned in `skills-lock.json`) or the user scope (`~/.agents/skills/`, plus `~/.claude/skills/` for Claude Code). If they do, report which scope and move on. If not, ask once where to install, recommending user scope:
|
|
54
|
+
|
|
55
|
+
- **User scope** — every project on this machine, nothing committed, updated with `npx skills update -g`. Run `npx -y skills add sassywares/sassy-skills -g -y`, which writes `~/.agents/skills/sassy-*`, the `~/.claude/skills/sassy-*` links, and `~/.agents/.skill-lock.json`.
|
|
56
|
+
- **Project scope** — only this project, pinned with it. Run `npx -y skills add sassywares/sassy-skills -y`, which writes `.agents/skills/sassy-*` (real files), per-agent links such as `.claude/skills/sassy-*`, and `skills-lock.json`. The vendored folders and the lock are the pin and join step 8's commit list, so a clone 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.
|
|
57
|
+
|
|
58
|
+
A project that wants its own pin on a machine that already has the user-scope suite can install in project scope too — say that Claude Code prefers the user-scope copy, so the project's pin does not decide what Claude Code runs there.
|
|
59
|
+
|
|
60
|
+
**Do not wire updates.** How and when the suite is refreshed is the user's or the project's decision, not setup's: no `skills:*` scripts, no `postinstall` edit. Mention the update command for the chosen scope 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.
|
|
51
61
|
|
|
52
|
-
- **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`.
|
|
53
|
-
- **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.
|
|
54
|
-
- **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.
|
|
55
|
-
- **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.
|
|
56
62
|
- **Write `.sassywares/README.md`** from `assets/sassywares-readme.md` when absent. Never overwrite it — it may carry project notes.
|
|
57
|
-
- **
|
|
63
|
+
- **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:
|
|
58
64
|
|
|
59
65
|
| Harness | sassy-agents folder | User scope | Project scope |
|
|
60
66
|
|---|---|---|---|
|
|
@@ -71,12 +77,12 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
71
77
|
- **Tell the user to `/reload`** (or restart the harness). The skills and agents are invisible to the harness until it rescans.
|
|
72
78
|
|
|
73
79
|
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.
|
|
74
|
-
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
|
|
80
|
+
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, for a project-scope install, the pin: every `.agents/skills/sassy-*` folder hashed against `skills-lock.json`, the lock's coverage both ways, and whether git carries the lock. A user-scope install has no pin here; the check notes the scope it found. Report every `drift:` line verbatim, or that the config matches the tree. Drift blocks step 8.
|
|
75
81
|
|
|
76
|
-
Then check the agents exactly as step 5's **Installed**
|
|
82
|
+
Then check the skills and the agents exactly as step 5's **Installed** rules say, and report the scope each was found in or what is missing. A check run never installs them; a missing suite or roster is reported with the fix (`mode:init`), and it does not block step 8.
|
|
77
83
|
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:
|
|
78
84
|
|
|
79
|
-
`.sassywares/config.yaml`, `.sassywares/README.md`, `.agents/skills/sassy
|
|
85
|
+
`.sassywares/config.yaml`, `.sassywares/README.md`, `.agents/skills/sassy-*` and `skills-lock.json` when the suite is in project scope, 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 .`.
|
|
80
86
|
|
|
81
87
|
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.
|
|
82
88
|
|
|
@@ -85,22 +91,22 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
85
91
|
- **`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.
|
|
86
92
|
- **`none`** — nothing to commit, deliberately.
|
|
87
93
|
|
|
88
|
-
9. **Report.** The config path, the topology, the resolved artifact and knowledge paths, where the
|
|
94
|
+
9. **Report.** The config path, the topology, the resolved artifact and knowledge paths, where the skills are installed (scope) and where the agents are (scope and harness), or why either is 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.
|
|
89
95
|
|
|
90
96
|
## Hard rules
|
|
91
97
|
|
|
92
98
|
| Rule | Requirement |
|
|
93
99
|
|------|-------------|
|
|
94
100
|
| No `git init` | Setup never turns a folder into a repo, and never does remote or ref surgery. The step 8 commit is its only git write. |
|
|
95
|
-
| Commit only what setup owns | The config, the setup README, the vendored `sassy-*` folders
|
|
101
|
+
| Commit only what setup owns | The config, the setup README, the vendored `sassy-*` folders and `skills-lock.json` (project scope), the project-scope agent files, and a `.gitignore` setup created. Never a file the user wrote or the repo already had, unless they name it. |
|
|
96
102
|
| Verify before commit | A config that fails `--check` is reported, never committed. |
|
|
97
103
|
| Approval to create a remote | Creating the mirror repo needs an explicit yes and a named slug first. |
|
|
98
104
|
| No silent overwrite | An existing config or an existing `.sassywares/workspace/snapshot` is shown and asked about, never replaced blind. |
|
|
99
105
|
| Version is reported | Setup names the snapshot and `workspace-git` versions it installed; `--check` flags an installed copy older than the skill's. |
|
|
100
|
-
| Skills come from upstream | Install with `npx skills add
|
|
106
|
+
| Skills come from upstream | Install with `npx skills add`, `-g` for user scope; never hand-copy skill files or maintain the links yourself. |
|
|
101
107
|
| 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. |
|
|
102
|
-
| 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. |
|
|
103
|
-
| Write boundary | Only `.sassywares/`, the
|
|
108
|
+
| 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 user or project decides how it updates. |
|
|
109
|
+
| Write boundary | Only `.sassywares/`, the skills and agent files step 5 installed in the scope the user chose, `skills-lock.json` (project scope), and one `.gitignore` line — and the project-scope part of that 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/`. |
|
|
104
110
|
| Detect, don't guess | An unknown base branch stays unknown and gets asked about. A probed value is reported as probed. |
|
|
105
111
|
| Comments are part of the file | Every key keeps its description and allowed values. A stripped config is an incomplete config. |
|
|
106
112
|
| Hooks are named, not written | Setup records hook skill names. Creating those skills is the project's work. |
|
|
@@ -110,4 +116,4 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
110
116
|
|
|
111
117
|
Not a migration tool. A project already using another convention keeps its files; setup records where they already are. There is no rename step, and no fallback to `docs/` behind a configured path.
|
|
112
118
|
|
|
113
|
-
Not an updater. `check` reports a pin that is stale or edited; it never moves it. Updating the suite is `npx skills update
|
|
119
|
+
Not an updater. `check` reports a project pin that is stale or edited; it never moves it. Updating the suite is `npx skills update` (`-g` for user scope), which is the user's or project's decision and not setup's.
|
|
@@ -4,20 +4,24 @@ Project config and tooling for the Sassy Skills suite. Written by `sassy-setup`.
|
|
|
4
4
|
|
|
5
5
|
## Skills
|
|
6
6
|
|
|
7
|
-
Installed from upstream with the open `skills` CLI,
|
|
8
|
-
|
|
7
|
+
Installed from upstream with the open `skills` CLI, in one of two scopes:
|
|
8
|
+
|
|
9
|
+
- **Project** — vendored into `.agents/skills/` and pinned in `skills-lock.json`,
|
|
10
|
+
both committed, so every clone runs the same skills. `.claude/skills` is a link
|
|
11
|
+
created at install time and is not committed.
|
|
12
|
+
- **User** — `~/.agents/skills/` (plus `~/.claude/skills/` links), for one person
|
|
13
|
+
across every project on their machine. Nothing is committed here.
|
|
9
14
|
|
|
10
15
|
```bash
|
|
11
|
-
npx skills add sassywares/sassy-skills
|
|
12
|
-
npx skills update -y # pull the latest
|
|
13
|
-
npx skills experimental_install
|
|
16
|
+
npx skills add sassywares/sassy-skills # project install (-g for user scope)
|
|
17
|
+
npx skills update -p -y # pull the latest (-g -y for user scope)
|
|
18
|
+
npx skills experimental_install # restore exactly what the project lock pins
|
|
14
19
|
```
|
|
15
20
|
|
|
16
|
-
Refreshing the suite is
|
|
17
|
-
|
|
18
|
-
The vendored skills and the lock are committed; `.claude/skills` is a link and is not.
|
|
21
|
+
Refreshing the suite is your decision — nothing here updates itself. With both
|
|
22
|
+
scopes installed, Claude Code runs the user-scope copy.
|
|
19
23
|
|
|
20
|
-
`.agents/skills/` is read by pi and Cursor; Claude Code reads `.claude/skills/` only, which is why
|
|
24
|
+
`.agents/skills/` is read by pi and Cursor; Claude Code reads `.claude/skills/` only, which is why those links exist. After any change, reload your harness (`/reload` in pi, a new session in Claude Code).
|
|
21
25
|
|
|
22
26
|
## Agents
|
|
23
27
|
|
|
@@ -31,14 +35,14 @@ install them when missing.
|
|
|
31
35
|
|
|
32
36
|
## Missing skills
|
|
33
37
|
|
|
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.
|
|
38
|
+
If a skill tells you another skill is missing, run `npx skills add sassywares/sassy-skills` (add `-g` for user scope, or run `npx skills experimental_install` to restore exactly what the project lock pins) and restart.
|
|
35
39
|
|
|
36
40
|
## Config
|
|
37
41
|
|
|
38
|
-
`config.yaml` holds the project's paths, git topology, and PR defaults. Every key is documented inline, including its allowed values, and the full schema is in the `sassy-setup` skill's `references/config.md`. Verify the setup still matches the tree — the config, the hooks it names, and the vendored pin:
|
|
42
|
+
`config.yaml` holds the project's paths, git topology, and PR defaults. Every key is documented inline, including its allowed values, and the full schema is in the `sassy-setup` skill's `references/config.md`. Verify the setup still matches the tree — the config, the hooks it names, and the vendored pin when the suite is installed in project scope:
|
|
39
43
|
|
|
40
44
|
```bash
|
|
41
|
-
.agents/skills/sassy-setup/scripts/detect.sh --root . --check
|
|
45
|
+
.agents/skills/sassy-setup/scripts/detect.sh --root . --check # ~/.agents/skills/... for user scope
|
|
42
46
|
```
|
|
43
47
|
|
|
44
48
|
Or ask for `mode:check` on the setup skill, which runs the same check and reports it. Neither moves the pin: `npx skills check` is an alias of `update`.
|
|
@@ -376,9 +376,11 @@ per-PR say-so, because one switch would merge N PRs nobody re-read.
|
|
|
376
376
|
run uses a default this project never chose.
|
|
377
377
|
|
|
378
378
|
`scripts/detect.sh --check` enforces all of the above and reports each breach as
|
|
379
|
-
a `drift:` line, exiting non-zero.
|
|
380
|
-
every `.agents/skills/sassy-*` folder is hashed with the `skills` CLI's own
|
|
379
|
+
a `drift:` line, exiting non-zero. When the suite is installed in project
|
|
380
|
+
scope it also verifies the vendored pin offline: every `.agents/skills/sassy-*` folder is hashed with the `skills` CLI's own
|
|
381
381
|
definition and compared to `computedHash` in `skills-lock.json`, the lock is
|
|
382
382
|
checked against the installed set in both directions, and git-tracked state of
|
|
383
383
|
the lock is reported. A stale, hand-edited, or half-installed suite is drift
|
|
384
|
-
even when the config itself matches the tree.
|
|
384
|
+
even when the config itself matches the tree. A user-scope install
|
|
385
|
+
(`~/.agents/skills/`) has no pin to verify; the check notes it, and a suite
|
|
386
|
+
found in neither scope is noted, not drift.
|
|
@@ -618,9 +618,10 @@ if (( CHECK )); then
|
|
|
618
618
|
if [[ "$TOPOLOGY" == "repo" ]]; then
|
|
619
619
|
# Tracked, not merely present: a clone has to get the pin without a network
|
|
620
620
|
# call, so an untracked lock is a setup that does not travel.
|
|
621
|
+
# Only a project-scope install has a lock; a user-scope one has nothing here.
|
|
621
622
|
if [[ -n "$(git -C "$ROOT" ls-files -- skills-lock.json 2>/dev/null)" ]]; then
|
|
622
623
|
note " skills-lock.json is tracked"
|
|
623
|
-
|
|
624
|
+
elif [[ -f "$ROOT/skills-lock.json" ]]; then
|
|
624
625
|
note " skills-lock.json is not tracked yet — the setup commit carries it"
|
|
625
626
|
fi
|
|
626
627
|
if [[ -e "$ROOT/.claude/skills" ]] && ! git -C "$ROOT" check-ignore -q -- .claude/skills 2>/dev/null; then
|
|
@@ -1,6 +1,12 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
// Verify the vendored sassy-* folders against skills-lock.json.
|
|
3
3
|
//
|
|
4
|
+
// The suite installs in one of two scopes, like the agents: the project
|
|
5
|
+
// (vendored into .agents/skills and pinned in skills-lock.json) or the user
|
|
6
|
+
// (~/.agents/skills, plus ~/.claude/skills for Claude Code). Only a project
|
|
7
|
+
// install has a pin to verify; a user install is reported, and a missing suite
|
|
8
|
+
// is reported without counting as drift.
|
|
9
|
+
//
|
|
4
10
|
// Read-only, offline. The folder hash is the `skills` CLI's own definition —
|
|
5
11
|
// sha256 over each file's relative path then its bytes, files sorted by relative
|
|
6
12
|
// path — so "identical to the pin" is a fact this script asserts, not a claim
|
|
@@ -12,7 +18,8 @@
|
|
|
12
18
|
|
|
13
19
|
import { createHash } from "node:crypto";
|
|
14
20
|
import { readdir, readFile } from "node:fs/promises";
|
|
15
|
-
import { existsSync } from "node:fs";
|
|
21
|
+
import { existsSync, readdirSync } from "node:fs";
|
|
22
|
+
import { homedir } from "node:os";
|
|
16
23
|
import { join, relative } from "node:path";
|
|
17
24
|
|
|
18
25
|
const SUITE = "sassywares/sassy-skills";
|
|
@@ -58,10 +65,31 @@ async function folderHash(dir) {
|
|
|
58
65
|
return hash.digest("hex");
|
|
59
66
|
}
|
|
60
67
|
|
|
68
|
+
// sassy-* skills in a skills directory. Follows symlinks: a user scope may link
|
|
69
|
+
// each skill to a working copy rather than holding the files.
|
|
70
|
+
function suiteIn(dir) {
|
|
71
|
+
if (!existsSync(dir)) return [];
|
|
72
|
+
return readdirSync(dir).filter(
|
|
73
|
+
(name) => SASSY.test(name) && existsSync(join(dir, name, "SKILL.md")),
|
|
74
|
+
);
|
|
75
|
+
}
|
|
76
|
+
|
|
61
77
|
async function main() {
|
|
62
78
|
const lockPath = join(root, "skills-lock.json");
|
|
79
|
+
if (!existsSync(lockPath) && suiteIn(join(root, ".agents", "skills")).length === 0) {
|
|
80
|
+
const userScope = [join(homedir(), ".agents", "skills"), join(homedir(), ".claude", "skills")]
|
|
81
|
+
.map((dir) => [dir, suiteIn(dir).length])
|
|
82
|
+
.filter(([, count]) => count > 0);
|
|
83
|
+
if (userScope.length > 0) {
|
|
84
|
+
const where = userScope.map(([dir, count]) => `${dir} (${count})`).join(", ");
|
|
85
|
+
note(`suite installed in user scope: ${where} — this project does not pin it`);
|
|
86
|
+
} else {
|
|
87
|
+
note(`suite not found in the project or user scope — sassy-setup mode:init installs it`);
|
|
88
|
+
}
|
|
89
|
+
return;
|
|
90
|
+
}
|
|
63
91
|
if (!existsSync(lockPath)) {
|
|
64
|
-
drift(`no skills-lock.json —
|
|
92
|
+
drift(`sassy-* folders in .agents/skills but no skills-lock.json — re-pin with npx skills add ${SUITE}`);
|
|
65
93
|
return;
|
|
66
94
|
}
|
|
67
95
|
|
|
@@ -35,14 +35,14 @@ If a plan path is given but the file does not exist, run `sassy-plan` first and
|
|
|
35
35
|
Read the plan's `**QA:**` line and its per-phase QA table. QA is manual and it is part of the phase gate, not a separate track: a phase turns `Done` only when the code is approved **and** every QA row for that phase has passed.
|
|
36
36
|
|
|
37
37
|
- The user runs the checks. The agent never ticks a row it did not hear confirmed: a row becomes `Done` only on the user's explicit confirmation in this conversation, with their note recorded.
|
|
38
|
-
- A row the user reports failing is a finding.
|
|
38
|
+
- A row the user reports failing is a finding. It goes through a rework cycle (step 6) and the gate is presented again; a row that fails again after its rework is `Blocked` with the reason.
|
|
39
39
|
- Rows nobody has reported on stay `Pending`, and they keep the phase `In progress`. Never infer, batch-assume, or self-certify a pass.
|
|
40
40
|
|
|
41
41
|
A brief has no QA table, so its gate is code approval alone. Never invent, enable, or disable QA.
|
|
42
42
|
|
|
43
43
|
## Phase gate
|
|
44
44
|
|
|
45
|
-
Always gate before committing.
|
|
45
|
+
Always gate before committing. The cycle has already fixed and verified its findings; present the combined gate — code approval plus the QA checklist — and wait for the user. Anything the user sends back goes through a rework cycle and the gate again.
|
|
46
46
|
|
|
47
47
|
## Steps
|
|
48
48
|
|
|
@@ -53,12 +53,12 @@ Always gate before committing. One worker fixes findings, one re-check, then pre
|
|
|
53
53
|
3. **Run the cycle.** Set the phase `In progress` in the Phase tracking table, then load the `sassy-cycle` skill and follow it, with:
|
|
54
54
|
- work brief = the phase's goal, work items, and "Done when" criteria
|
|
55
55
|
- intent reference = the plan path and phase
|
|
56
|
-
4. **Evaluate the phase.** On `Status: done
|
|
57
|
-
5. **Present the phase gate.** Report the phase, what changed, findings raised
|
|
56
|
+
4. **Evaluate the phase.** On `Status: done`, the code is ready for the gate, but leave the phase `In progress` — both gates must pass before it closes. On `Status: blocked`, set it `Blocked` in the Phase tracking table and stop; a blocked phase is a real outcome and needs no approval.
|
|
57
|
+
5. **Present the phase gate.** Report the phase, what changed, findings raised and resolved (with the fix passes it took), the validator grade, the reviewer summary, and the reviewer's suggestions as options the user may pick. Then give the QA checklist verbatim: each row's ID, check, how to run it, and what passing looks like, with unreported rows `Pending`. Ask for both decisions — code approval (or the changes wanted, including any suggestions picked) and the QA result per row. Wait.
|
|
58
58
|
6. **Resolve the gate.** Three outcomes, nothing in between:
|
|
59
59
|
- **Code approved and every QA row passes** → go to step 7.
|
|
60
60
|
- **Code approved, QA still pending** → record that code is approved but leave the phase `In progress`, tick nothing, commit nothing, hand off nothing, and report that the phase is waiting on manual QA plus the command that resumes it.
|
|
61
|
-
- **
|
|
61
|
+
- **Changes requested, or any QA row fails** → a rework cycle: load `sassy-cycle` with the requested changes and the failing rows as its findings, and the plan path and phase as the intent reference. On `done`, present the gate again from step 5; on `blocked`, mark the phase `Blocked` and stop. A QA row that fails again after its rework is `Blocked` with the reason and stops the phase. Change requests have no cap — each one is the user's call.
|
|
62
62
|
7. **Commit the phase.** On both gates passing, first mark the phase's QA rows `Done` with the user's notes and the phase `Done` in the Phase tracking table, then persist according to `git.repo`:
|
|
63
63
|
|
|
64
64
|
- **A remote** — dispatch a `worker` whose task is: *load the `sassy-commit` skill and follow it with `branch:current`*, naming that the commit must include the phase's code changes, the QA table results, and the now-updated Phase tracking table. It returns the hash and subject. The branch already exists: step 2 cut it, so committing on it is the point of `branch:current` here.
|
|
@@ -79,7 +79,7 @@ When the argument is not a plan path, it is one settled brief:
|
|
|
79
79
|
|
|
80
80
|
1. Resolve the branch exactly as the plan path does — `references/branching.md`, this run's `branch:` token — before the cycle runs.
|
|
81
81
|
2. Run one `sassy-cycle` with the brief as the work brief and its decisions / done-when as the intent reference. Do not split it into multiple cycles.
|
|
82
|
-
3. Present the code approval gate with no QA checklist, and wait.
|
|
82
|
+
3. Present the code approval gate with no QA checklist, and wait. Changes requested → a rework cycle with the changes as findings and the brief's decisions / done-when as the intent reference, then this gate again; `blocked` stops.
|
|
83
83
|
4. On code approval, persist the brief's changes the same way the plan path does: a `sassy-commit` delegation with `branch:current` in a remote repo, or the workspace snapshot in a workspace.
|
|
84
84
|
5. Stop and report. Shipping is a separate step (`sassy-ship`), or `sassy-lfg` would have taken it all the way. Never create or update a plan file.
|
|
85
85
|
|
|
@@ -93,13 +93,14 @@ When the argument is not a plan path, it is one settled brief:
|
|
|
93
93
|
| Gate before commit and handoff | Do not commit, hand off, or close out until the user approves the code and the phase QA rows pass. |
|
|
94
94
|
| Commit per phase | Commit the phase, its QA results, and the plan update via `sassy-commit` before handoff or close-out. |
|
|
95
95
|
| Done needs both gates | Mark a phase `Done` only when the user approves the code and every QA row for that phase is `Done`, never before. |
|
|
96
|
-
| QA rows follow the user | Tick a QA row `Done` only from the user's explicit confirmation; keep unreported rows `Pending`;
|
|
96
|
+
| QA rows follow the user | Tick a QA row `Done` only from the user's explicit confirmation; keep unreported rows `Pending`; a failed row is a finding for a rework cycle. |
|
|
97
|
+
| Send-backs are rework | Requested changes and failed QA rows go through `sassy-cycle` as findings — verified, two fix passes at most — never a direct edit. |
|
|
97
98
|
| No shipping on the brief path | The brief path commits and stops. Shipping is `sassy-ship` or `sassy-lfg`. |
|
|
98
99
|
|
|
99
100
|
## Failure handling
|
|
100
101
|
|
|
101
102
|
- `sassy-cycle` returns `blocked` → mark the phase `Blocked`, stop, report the open findings and the diagnostic.
|
|
102
|
-
- QA stays pending or
|
|
103
|
+
- QA stays pending, or a row fails again after its rework → keep the phase `In progress` (or `Blocked` with the reason), commit nothing, hand off nothing, and report.
|
|
103
104
|
- `sassy-commit` fails or leaves the phase changes uncommitted → stop and report; never hand off on top of uncommitted phase work.
|
|
104
105
|
- The validator returns **Blocked — insufficient grounding** → treat it as a real blocker; do not advance or hand off.
|
|
105
106
|
- Ambiguous or unsafe failure → stop and ask.
|