@sassywares/skills 0.6.9 → 0.7.0
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 +5 -4
- package/README.md +13 -10
- package/package.json +1 -1
- package/skills/sassy-cycle/SKILL.md +25 -16
- package/skills/sassy-lfg/SKILL.md +1 -1
- package/skills/sassy-plan/SKILL.md +9 -1
- package/skills/sassy-review/SKILL.md +33 -19
- package/skills/sassy-setup/SKILL.md +2 -2
- package/skills/sassy-setup/assets/sassywares-readme.md +2 -2
- package/skills/sassy-setup/references/harness.md +1 -1
- package/skills/sassy-simplify/SKILL.md +64 -0
- package/skills/sassy-validate/SKILL.md +28 -14
- package/skills/sassy-work/SKILL.md +1 -1
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 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`.
|
|
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`, `simplifier`, and `validator`.
|
|
14
14
|
|
|
15
15
|
## Orchestrator
|
|
16
16
|
|
|
@@ -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
|
|
21
|
+
`sassy-cycle` runs one unit of work through implement → review + simplify + validate (in parallel) → fix → verify. Simplifications are applied and verified but never block. 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
|
|
|
@@ -37,9 +37,10 @@ A gate is a deliberate stop or pass/fail condition.
|
|
|
37
37
|
|
|
38
38
|
## Modes
|
|
39
39
|
|
|
40
|
-
|
|
40
|
+
Three mode tokens: `mode:manual` (default) asks at the skill's gate; `mode:auto` means pre-authorized, no review; `mode:return` reports and changes nothing.
|
|
41
41
|
|
|
42
|
-
- `sassy-ship` and `sassy-compound` accept
|
|
42
|
+
- `sassy-ship` and `sassy-compound` accept `manual` and `auto`. Ship reviews the whole close-out in `mode:manual` and forwards `mode:auto` to compound once its own gate is answered.
|
|
43
|
+
- `sassy-review`, `sassy-simplify`, and `sassy-validate` accept all three: `manual` asks which findings to fix, `auto` fixes them without asking, `return` hands the findings back to the caller.
|
|
43
44
|
- `sassy-debug` accepts no mode. It always leaves ship's review gate in place.
|
|
44
45
|
- `sassy-work` and `sassy-lfg` accept no mode.
|
|
45
46
|
|
package/README.md
CHANGED
|
@@ -27,8 +27,8 @@ It covers the whole path from a rough idea to a shipped PR, and from a bug repor
|
|
|
27
27
|
|
|
28
28
|
- **Lean.** Skills are indexes and workflows, not documentation dumps. Detail moves into `references/` only when it is conditionally needed.
|
|
29
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.
|
|
30
|
-
- **Controlled.** Code approval, manual QA, and ship review are visible gates that all run in sequence.
|
|
31
|
-
- **Reliable.** Work runs through `sassy-cycle` with isolated subagents for implementation, review, validation, and fixes.
|
|
30
|
+
- **Controlled.** Code approval, manual QA, and ship review are visible gates that all run in sequence. Mode tokens are opt-in per skill: `mode:manual` (default) and `mode:auto` on `sassy-ship` and `sassy-compound`, plus `mode:return` on `sassy-review`, `sassy-simplify`, and `sassy-validate`; work, lfg, and debug take no mode.
|
|
31
|
+
- **Reliable.** Work runs through `sassy-cycle` with isolated subagents for implementation, review, simplification, validation, and verified fixes.
|
|
32
32
|
- **Context-efficient.** Orchestrators coordinate; subagents do the heavy reading and return compact results.
|
|
33
33
|
- **Never surprising.** Nothing is committed just because a step finished. Shipping is its own phase.
|
|
34
34
|
|
|
@@ -51,13 +51,13 @@ Settled. Pick one:
|
|
|
51
51
|
3. Implement and ship it via /sassy-lfg
|
|
52
52
|
```
|
|
53
53
|
|
|
54
|
-
Pick 1 to get a plan file
|
|
54
|
+
Pick 1 to get a plan file. Plan then asks again with just the other two — start working on it, or implement and ship it — or you stop there and run it later, one phase at a time:
|
|
55
55
|
|
|
56
56
|
```text
|
|
57
57
|
/sassy-work docs/plans/add-workspace-invitations.md
|
|
58
58
|
```
|
|
59
59
|
|
|
60
|
-
Or
|
|
60
|
+
Or the whole plan through one session:
|
|
61
61
|
|
|
62
62
|
```text
|
|
63
63
|
/sassy-lfg docs/plans/add-workspace-invitations.md
|
|
@@ -86,7 +86,7 @@ Debugging:
|
|
|
86
86
|
| **`sassy-scout`** | Grounds an area on demand and writes the shared grounding brief other agents read instead of re-exploring. |
|
|
87
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. |
|
|
88
88
|
| **`sassy-lfg`** | Executes every phase of a plan, or one in-context brief, then closes out via `sassy-ship` after code approval. |
|
|
89
|
-
| **`sassy-cycle`** | Runs one unit of work through implement → review
|
|
89
|
+
| **`sassy-cycle`** | Runs one unit of work through implement → review + simplify + validate → fix → verify, with at most two verified fix passes. Also reworks finished work from requested changes or failed QA rows. |
|
|
90
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`. |
|
|
91
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. |
|
|
92
92
|
|
|
@@ -94,8 +94,11 @@ Debugging:
|
|
|
94
94
|
|
|
95
95
|
| Skill | What it does |
|
|
96
96
|
|---|---|
|
|
97
|
-
| **`sassy-review`** | Reviews a diff, branch, PR, or files for bugs, project-rule conformance, and design-system conformance, then
|
|
98
|
-
| **`sassy-
|
|
97
|
+
| **`sassy-review`** | Reviews a diff, branch, PR, or files for bugs, security, project-rule conformance, and design-system conformance, then fixes the findings you pick. |
|
|
98
|
+
| **`sassy-simplify`** | Finds behavior-preserving simplifications — reuse, quality, efficiency — then applies the ones you pick. |
|
|
99
|
+
| **`sassy-validate`** | Checks whether work matches a plan or stated intent, then closes the gaps you pick. |
|
|
100
|
+
|
|
101
|
+
Each does one job and takes `mode:manual` (default: ask which to fix), `mode:auto` (fix without asking), or `mode:return` (report only). Fixes run through `sassy-cycle`, so they are verified. Inside work, lfg, and debug, the cycle runs all three agents in parallel itself.
|
|
99
102
|
|
|
100
103
|
### Shipping
|
|
101
104
|
|
|
@@ -199,8 +202,8 @@ flowchart LR
|
|
|
199
202
|
D -->|1. plan document| E[docs/plans/slug.md]
|
|
200
203
|
D -->|2. start working| F[sassy-work]
|
|
201
204
|
D -->|3. implement and ship| G[sassy-lfg]
|
|
202
|
-
E
|
|
203
|
-
E
|
|
205
|
+
E -->|then: start working| F
|
|
206
|
+
E -->|then: implement and ship| G
|
|
204
207
|
F --> H[sassy-cycle]
|
|
205
208
|
G --> H
|
|
206
209
|
H --> I{Code approval}
|
|
@@ -217,7 +220,7 @@ Option 1 produces a durable plan with phased slices and manual QA tables. Option
|
|
|
217
220
|
|
|
218
221
|
`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.
|
|
219
222
|
|
|
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
|
|
223
|
+
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, warnings, and validator gaps are fixed automatically; the simplifier's findings are applied in the same pass but never block; 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
224
|
|
|
222
225
|
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).
|
|
223
226
|
|
package/package.json
CHANGED
|
@@ -2,9 +2,11 @@
|
|
|
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
|
|
6
|
-
Also reworks
|
|
7
|
-
failed QA rows
|
|
5
|
+
review + simplify + validate in parallel, then fix and verify findings — at
|
|
6
|
+
most two fix passes. Also reworks existing work from a list of findings
|
|
7
|
+
(requested changes, failed QA rows, a standalone review's picks). Used by
|
|
8
|
+
sassy-work, sassy-lfg, sassy-review, sassy-simplify, and sassy-validate.
|
|
9
|
+
Never commits. Built for context and token
|
|
8
10
|
efficiency — the orchestrator only writes briefs and reads compact results.
|
|
9
11
|
argument-hint: "<work brief | findings> [intent reference]"
|
|
10
12
|
disable-model-invocation: true
|
|
@@ -21,9 +23,9 @@ disable-model-invocation: true
|
|
|
21
23
|
## Inputs
|
|
22
24
|
|
|
23
25
|
- **Work brief** — what to build or fix, concretely.
|
|
24
|
-
- **Intent reference** — how conformance is judged: a plan path + phase, or root-cause findings.
|
|
26
|
+
- **Intent reference** — how conformance is judged: a plan path + phase, or root-cause findings. Optional on rework only; without one, verify runs the reviewer alone.
|
|
25
27
|
- **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.
|
|
28
|
+
- **Findings** — rework only: a list of changes to make to work that already exists — the user's requested changes, failing QA rows, a standalone skill's picked findings. Each is a **fix** unless the caller marks it a **simplification**. 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.
|
|
27
29
|
|
|
28
30
|
## Steps
|
|
29
31
|
|
|
@@ -33,16 +35,21 @@ disable-model-invocation: true
|
|
|
33
35
|
- 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.
|
|
34
36
|
- 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
37
|
- Report the files it changed.
|
|
38
|
+
- For a **simplification**: behavior stays identical — same output for every input, same errors, same side effects and ordering. Never remove validation, error handling that prevents data loss, authorization, escaping, or accessibility code to make something simpler, and never weaken a test to make it pass. A simplification that cannot meet that is skipped and reported with the reason.
|
|
36
39
|
|
|
37
40
|
For independent chunks, batch them as **parallel** `worker` tasks in one call (max 8). The worker reads whatever it needs itself.
|
|
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
|
|
39
|
-
4. **Triage.**
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
41
|
+
3. **Review + simplify + validate (parallel).** Dispatch the `reviewer`, the `simplifier`, and the `validator` together in one **parallel** call. Give the validator the intent reference so it can judge conformance; give the simplifier the plan path, if there is one, so settled structure stays.
|
|
42
|
+
4. **Triage.** Two lists, both numbered:
|
|
43
|
+
- **Fixes** — every reviewer **critical** and **warning**, every validator gap, every blocker a worker reported, and on rework every finding not marked a simplification.
|
|
44
|
+
- **Simplifications** — every simplifier finding, and on rework every finding marked one.
|
|
45
|
+
|
|
46
|
+
Reviewer **Suggestions** are neither: carry them to the result untouched for the caller's gate. Both lists empty → step 7.
|
|
47
|
+
5. **Fix.** Dispatch one `worker` with both lists, labeled, to do exactly those and nothing else. This is fix pass 1 or 2.
|
|
48
|
+
6. **Verify (parallel).** Dispatch the `reviewer` and, when there is an intent reference, the `validator` together, both scoped to this fix. The simplifier does not run again — a fresh pass would always find more.
|
|
49
|
+
- **Reviewer** — both lists and the files the fix changed. It returns, per item, `resolved` or `not resolved` with a reason — for a simplification, `resolved` also means behavior is unchanged — plus any **new** critical or warning the fix's changes introduced. A simplification that changed behavior is a new finding.
|
|
50
|
+
- **Validator** — the intent reference plus the fixes list. It re-grades conformance and names any gap left.
|
|
51
|
+
|
|
52
|
+
The new fixes list is every unresolved fix, every new finding, and every validator gap; unresolved simplifications carry forward on their own list. Both empty → step 7 as `done`. Otherwise, after fix pass 1 → back to step 5; after fix pass 2 → step 7: `blocked` when fixes remain open, `done` when only simplifications do — they are reported, never blocking.
|
|
46
53
|
7. **Return** the structured result below.
|
|
47
54
|
|
|
48
55
|
## Structured result
|
|
@@ -54,22 +61,24 @@ Status: done | blocked
|
|
|
54
61
|
Files changed: <paths>
|
|
55
62
|
Fix passes: 0 | 1 | 2
|
|
56
63
|
Findings: <finding -> resolved (pass n) | open: reason>
|
|
64
|
+
Simplifications: <finding -> applied (pass n) | skipped: reason | open: reason>
|
|
57
65
|
Suggestions: <reviewer suggestions, not acted on>
|
|
58
66
|
Validator: Conforms | Partial | Diverges | Blocked
|
|
59
67
|
Reviewer: <n> critical, <n> warnings open
|
|
60
68
|
Notes: <anything the caller needs>
|
|
61
69
|
```
|
|
62
70
|
|
|
63
|
-
A finding is `resolved` only when step 6's reviewer said so. The fixing worker's own report is never evidence.
|
|
71
|
+
A finding is `resolved`, and a simplification `applied`, only when step 6's reviewer said so. The fixing worker's own report is never evidence.
|
|
64
72
|
|
|
65
73
|
## Rules
|
|
66
74
|
|
|
67
75
|
| Rule | Requirement |
|
|
68
76
|
|------|-------------|
|
|
69
77
|
| Orchestrator only | Never edit code or read source in the main context. Delegate. |
|
|
70
|
-
| Parallel where independent | Independent work chunks → parallel workers. Reviewer
|
|
78
|
+
| Parallel where independent | Independent work chunks → parallel workers. Reviewer, simplifier, and validator run in one parallel call; verify's reviewer and validator likewise. |
|
|
71
79
|
| 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
|
-
|
|
|
80
|
+
| Only fixes block | Simplifications are applied and verified but never make a run `blocked`; reviewer suggestions go to the caller's gate for the user to pick and are never applied automatically. |
|
|
81
|
+
| Simplifier runs once | Only at step 3 (or never, on rework). Verify re-checks what was applied; it does not hunt for more. |
|
|
73
82
|
| Never commit | This skill leaves everything uncommitted. Shipping is `sassy-ship`. |
|
|
74
83
|
| Manual QA | Never mark QA rows `Done`. QA is confirmed by the user at the caller's gate; failing rows come back as findings. |
|
|
75
84
|
|
|
@@ -45,7 +45,7 @@ A brief has no QA table, so its gate is code approval alone. Never invent, enabl
|
|
|
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
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, 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.
|
|
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 simplifications applied, 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.
|
|
@@ -56,7 +56,15 @@ The user must pick explicitly. There is no default and no auto-selection. If no
|
|
|
56
56
|
|
|
57
57
|
### Option 1 — Write the plan
|
|
58
58
|
|
|
59
|
-
Read `references/plan-format.md` and write the plan, including the per-phase manual QA tables that format defines. Then report the absolute path and
|
|
59
|
+
Read `references/plan-format.md` and write the plan, including the per-phase manual QA tables that format defines. Then report the absolute path and offer the remaining two options, now run on the plan file:
|
|
60
|
+
|
|
61
|
+
```text
|
|
62
|
+
Plan written to <absolute path>. Pick one, or stop here:
|
|
63
|
+
1. Start working via /sassy-work
|
|
64
|
+
2. Implement and ship it via /sassy-lfg
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Wait for the user. A pick loads that skill with the plan path as its argument — `sassy-work` runs the next phase, `sassy-lfg` runs every phase and ships. Anything else, or no human present, ends here with the plan written. Do not recommend one, and do not implement or commit before a pick.
|
|
60
68
|
|
|
61
69
|
### Option 2 — Start working via `sassy-work`
|
|
62
70
|
|
|
@@ -1,54 +1,68 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sassy-review
|
|
3
3
|
description: >-
|
|
4
|
-
Review a diff, branch, PR, or files for bugs, regressions,
|
|
5
|
-
conformance, and design-system conformance, then
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
4
|
+
Review a diff, branch, PR, or files for bugs, regressions, security,
|
|
5
|
+
project-rule conformance, and design-system conformance, then fix the findings
|
|
6
|
+
you pick. Runs the reviewer and fixes through sassy-cycle. mode:manual
|
|
7
|
+
(default) asks which to fix, mode:auto fixes all actionable, mode:return only
|
|
8
|
+
reports. Use when asked to review code. Leaves changes uncommitted.
|
|
9
|
+
argument-hint: "[PR ref, branch, files, or blank for current changes] [mode:manual|auto|return]"
|
|
9
10
|
disable-model-invocation: true
|
|
10
11
|
---
|
|
11
12
|
|
|
12
13
|
# Sassy Review
|
|
13
14
|
|
|
14
|
-
**Outcome:** the scope reviewed with concrete findings
|
|
15
|
+
**Outcome:** the scope reviewed with concrete findings, and — unless `mode:return` — the chosen ones fixed and verified; everything left uncommitted.
|
|
15
16
|
|
|
16
|
-
**
|
|
17
|
+
**Review only.** Simplification is `sassy-simplify`; plan conformance is `sassy-validate`.
|
|
18
|
+
|
|
19
|
+
**Orchestrator only.** Never edit code yourself. The `reviewer` finds; `sassy-cycle` fixes and verifies.
|
|
17
20
|
|
|
18
21
|
**Harness.** Loading another skill, dispatching an agent, and any command you hand the user follow the `sassy-setup` skill's `references/harness.md`. Read it once per run, before the first of those.
|
|
19
22
|
|
|
23
|
+
## Modes
|
|
24
|
+
|
|
25
|
+
| Mode | Behavior |
|
|
26
|
+
|------|----------|
|
|
27
|
+
| `mode:manual` (default) | Present the findings, ask which to fix, fix those. |
|
|
28
|
+
| `mode:auto` | Fix every Critical and Warning without asking; Suggestions are reported, not fixed. |
|
|
29
|
+
| `mode:return` | Return the findings and change nothing — for a caller that owns the fix. |
|
|
30
|
+
|
|
31
|
+
Use the mode the caller passed; never pick one yourself.
|
|
32
|
+
|
|
20
33
|
## Review dimensions
|
|
21
34
|
|
|
22
|
-
The `reviewer` covers
|
|
35
|
+
The `reviewer` covers the first three always, and each risk lens when the diff touches its surface.
|
|
23
36
|
|
|
24
37
|
| Dimension | What it checks |
|
|
25
38
|
|-----------|----------------|
|
|
26
|
-
| Correctness & security | Bugs, regressions, injection, auth gaps, data loss. |
|
|
39
|
+
| Correctness & security | Bugs, regressions, injection, auth gaps, data loss; behavior changed with no test changed. |
|
|
27
40
|
| Project rules | Nearest `AGENTS.md`/`CLAUDE.md` at repo root and in each touched package, plus conventions they reference: required validators/auth, forbidden or gated commands, typing, naming, file placement, generated files. |
|
|
28
41
|
| Design system | Shared components and tokens instead of hardcoded colors/spacing/typography, required variants and states, accessibility, responsive/RTL, i18n, approved icons and assets. |
|
|
29
|
-
|
|
|
42
|
+
| Risk lenses | Security, data migrations, API contracts, concurrency and reliability — only where the diff touches them. |
|
|
30
43
|
|
|
31
|
-
Findings must be grounded: every rule finding quotes the rule file and section; every design finding names the shared component, token, or system pattern the code bypasses. A dimension with no applicable surface is reported as not applicable, not padded. If the change knowingly departs from a rule, ask for the reason or a docs update instead of assuming it is fine.
|
|
44
|
+
Findings must be grounded: every rule finding quotes the rule file and section; every design finding names the shared component, token, or system pattern the code bypasses. A dimension with no applicable surface is reported as not applicable, not padded. Issues already handled elsewhere, or not introduced by the diff, are dropped. If the change knowingly departs from a rule, ask for the reason or a docs update instead of assuming it is fine.
|
|
32
45
|
|
|
33
46
|
## Workflow
|
|
34
47
|
|
|
35
48
|
1. **Scope.** Use the target the user named (PR, branch, or files), else the current diff against the base branch.
|
|
36
|
-
2. **Review.** Dispatch the `reviewer` on that scope
|
|
37
|
-
3. **
|
|
38
|
-
4. **
|
|
39
|
-
5. **
|
|
40
|
-
6. **
|
|
49
|
+
2. **Review.** Dispatch the `reviewer` on that scope.
|
|
50
|
+
3. **Return.** In `mode:return`, return the reviewer's output as-is and stop.
|
|
51
|
+
4. **Nothing actionable?** If there are no Critical or Warning findings, report the summary plus the rules/design-system check list and stop.
|
|
52
|
+
5. **Choose.** In `mode:manual`, present findings grouped Critical / Warnings / Suggestions, including the rules and design-system check list, and ask which to fix: critical only / all actionable / specific / none. In `mode:auto`, take every Critical and Warning.
|
|
53
|
+
6. **Fix.** Load the `sassy-cycle` skill on rework with the chosen findings and the reviewed files as the scope hint. Its verify step confirms each one resolved, with at most two fix passes.
|
|
54
|
+
7. **Report.** What was fixed, what is still open and why; leave it uncommitted.
|
|
41
55
|
|
|
42
56
|
## Hard rules
|
|
43
57
|
|
|
44
58
|
| Rule | Requirement |
|
|
45
59
|
|------|-------------|
|
|
46
|
-
| Orchestrator only | Never edit code. The `reviewer` finds,
|
|
47
|
-
| Ask first |
|
|
60
|
+
| Orchestrator only | Never edit code. The `reviewer` finds, `sassy-cycle` fixes. |
|
|
61
|
+
| Ask first | In `mode:manual`, never change code before the user picks. |
|
|
48
62
|
| Specific findings | Fix the reviewed findings, not unrelated code. |
|
|
49
63
|
| Grounded findings | Rule and design-system findings cite the rule file, shared component, or token they rest on. |
|
|
50
64
|
| Uncommitted | Never commit, push, or open a PR. |
|
|
51
65
|
|
|
52
66
|
## Failure handling
|
|
53
67
|
|
|
54
|
-
The
|
|
68
|
+
The cycle returns a finding open after two passes → report it with its reason and continue with the rest. Stop on an unsafe or ambiguous failure.
|
|
@@ -60,7 +60,7 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
60
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.
|
|
61
61
|
|
|
62
62
|
- **Write `.sassywares/README.md`** from `assets/sassywares-readme.md` when absent. Never overwrite it — it may carry project notes.
|
|
63
|
-
- **Agents.** The skills dispatch
|
|
63
|
+
- **Agents.** The skills dispatch five subagents by name — `scout`, `worker`, `reviewer`, `simplifier`, `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:
|
|
64
64
|
|
|
65
65
|
| Harness | sassy-agents folder | User scope | Project scope |
|
|
66
66
|
|---|---|---|---|
|
|
@@ -69,7 +69,7 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
69
69
|
|
|
70
70
|
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.
|
|
71
71
|
|
|
72
|
-
**Installed** means all
|
|
72
|
+
**Installed** means all five `<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:
|
|
73
73
|
|
|
74
74
|
- **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.
|
|
75
75
|
- **Project scope** — only this project, pinned with it. Shallow-clone into `/tmp/sassywares/<harness>/scratch/` (per `references/harness.md`), 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.
|
|
@@ -25,8 +25,8 @@ scopes installed, Claude Code runs the user-scope copy.
|
|
|
25
25
|
|
|
26
26
|
## Agents
|
|
27
27
|
|
|
28
|
-
The skills dispatch
|
|
29
|
-
`validator` — from [sassy-agents](https://github.com/sassywares/sassy-agents),
|
|
28
|
+
The skills dispatch five subagents by name — `scout`, `worker`, `reviewer`,
|
|
29
|
+
`simplifier`, `validator` — from [sassy-agents](https://github.com/sassywares/sassy-agents),
|
|
30
30
|
one folder per harness (`pi/`, `claude/`). They live either in the harness's
|
|
31
31
|
user directory (`~/.pi/agent/agents/`, `~/.claude/agents/`, linked by
|
|
32
32
|
`sassy-agents/scripts/install.sh <harness>`) or in this project's
|
|
@@ -12,7 +12,7 @@ A missing sibling means the suite is incomplete: stop and point at `sassy-setup`
|
|
|
12
12
|
|
|
13
13
|
## Dispatching an agent
|
|
14
14
|
|
|
15
|
-
"Dispatch a `worker`" (or `scout`, `reviewer`, `validator`) means: start that [sassy-agents](https://github.com/sassywares/sassy-agents) subagent by name through the harness's own mechanism — the `subagent` tool in pi, the Agent tool with that agent type in Claude Code. "In parallel" means several dispatches in one turn.
|
|
15
|
+
"Dispatch a `worker`" (or `scout`, `reviewer`, `simplifier`, `validator`) means: start that [sassy-agents](https://github.com/sassywares/sassy-agents) subagent by name through the harness's own mechanism — the `subagent` tool in pi, the Agent tool with that agent type in Claude Code. "In parallel" means several dispatches in one turn.
|
|
16
16
|
|
|
17
17
|
- **Agent not installed** — stop and point at `sassy-setup`, which installs the roster for the running harness. Never substitute a generic agent silently.
|
|
18
18
|
- **Cannot dispatch** — you are yourself a subagent and the harness does not let subagents dispatch (Claude Code), or the harness has no subagents at all. Do that step inline with the same brief and constraints, and say in your result that it ran inline. Never skip it.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sassy-simplify
|
|
3
|
+
description: >-
|
|
4
|
+
Find behavior-preserving simplifications in changed code — reuse, quality,
|
|
5
|
+
efficiency — then apply the ones you pick. Runs the simplifier and applies
|
|
6
|
+
through sassy-cycle. mode:manual (default) asks which to apply, mode:auto
|
|
7
|
+
applies all, mode:return only reports. Use when asked to simplify, tidy, or
|
|
8
|
+
refactor recent changes. Leaves changes uncommitted.
|
|
9
|
+
argument-hint: "[files, branch, or blank for current changes] [mode:manual|auto|return]"
|
|
10
|
+
disable-model-invocation: true
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# Sassy Simplify
|
|
14
|
+
|
|
15
|
+
**Outcome:** the scope's simplification findings, and — unless `mode:return` — the chosen ones applied with behavior unchanged and verified; everything left uncommitted.
|
|
16
|
+
|
|
17
|
+
**Simplify only.** Not a bug hunt — that is `sassy-review`. Not a plan check — that is `sassy-validate`.
|
|
18
|
+
|
|
19
|
+
**Orchestrator only.** Never edit code or read source yourself. The `simplifier` finds; `sassy-cycle` applies and verifies.
|
|
20
|
+
|
|
21
|
+
**Harness.** Loading another skill, dispatching an agent, and any command you hand the user follow the `sassy-setup` skill's `references/harness.md`. Read it once per run, before the first of those.
|
|
22
|
+
|
|
23
|
+
## Modes
|
|
24
|
+
|
|
25
|
+
| Mode | Behavior |
|
|
26
|
+
|------|----------|
|
|
27
|
+
| `mode:manual` (default) | Present the findings, ask which to apply, apply those. |
|
|
28
|
+
| `mode:auto` | Apply every finding without asking. |
|
|
29
|
+
| `mode:return` | Return the findings and change nothing — for a caller that owns the fix. |
|
|
30
|
+
|
|
31
|
+
Use the mode the caller passed; never pick one yourself.
|
|
32
|
+
|
|
33
|
+
## What it looks for
|
|
34
|
+
|
|
35
|
+
The `simplifier` covers three dimensions, all behavior-preserving:
|
|
36
|
+
|
|
37
|
+
| Dimension | What it checks |
|
|
38
|
+
|-----------|----------------|
|
|
39
|
+
| Reuse | New code that duplicates an existing helper, reimplements a standard-library primitive, or hand-maintains a guarantee a framework already provides. |
|
|
40
|
+
| Quality | Redundant state, parameter sprawl, near-duplicate code, leaky abstractions, raw strings where a constant exists, deep nesting, narrating comments, dead code. |
|
|
41
|
+
| Efficiency | Repeated or N+1 work, sequential calls that could run concurrently, hot-path bloat, unconditional updates, leaks, overly broad reads. |
|
|
42
|
+
|
|
43
|
+
Fewer lines is not the goal. A finding that would make code longer or harder to follow, change behavior, or remove a safety check is not a finding.
|
|
44
|
+
|
|
45
|
+
## Workflow
|
|
46
|
+
|
|
47
|
+
1. **Scope.** Use the target the user named (files, branch, or PR), else the current diff against the base branch. Nothing in scope → ask what to simplify and stop.
|
|
48
|
+
2. **Simplify.** Dispatch the `simplifier` on that scope, with the plan path if the caller gave one, so settled structure stays.
|
|
49
|
+
3. **Nothing to apply?** On `Nothing to simplify` or no findings, report that and stop.
|
|
50
|
+
4. **Return.** In `mode:return`, return the simplifier's findings as-is — files reviewed, findings by dimension, summary — and stop.
|
|
51
|
+
5. **Choose.** In `mode:manual`, present the findings grouped by dimension and ask which to apply: all / specific / none. In `mode:auto`, take all.
|
|
52
|
+
6. **Apply.** Load the `sassy-cycle` skill on rework with the chosen findings, each marked a **simplification**, and the scope's files as the scope hint. The cycle's worker keeps behavior identical and its verify step confirms each one.
|
|
53
|
+
7. **Report.** What was applied per dimension, what was skipped and why, and the checks the worker ran. Leave it uncommitted.
|
|
54
|
+
|
|
55
|
+
## Hard rules
|
|
56
|
+
|
|
57
|
+
| Rule | Requirement |
|
|
58
|
+
|------|-------------|
|
|
59
|
+
| Behavior is fixed | Same output for every input, same errors, same side effects and ordering. |
|
|
60
|
+
| Safety stays | Never remove validation, data-loss error handling, authorization, escaping, or accessibility code. |
|
|
61
|
+
| Tests stay | Never weaken an assertion or skip a test to make a simplification pass. |
|
|
62
|
+
| Ask first | In `mode:manual`, never change code before the user picks. |
|
|
63
|
+
| Orchestrator only | The `simplifier` finds; `sassy-cycle` applies. |
|
|
64
|
+
| Uncommitted | Never commit, push, or open a PR. |
|
|
@@ -2,42 +2,56 @@
|
|
|
2
2
|
name: sassy-validate
|
|
3
3
|
description: >-
|
|
4
4
|
Check whether implemented work matches what a plan or stated intent expected,
|
|
5
|
-
then
|
|
6
|
-
|
|
7
|
-
conformance to a plan or
|
|
8
|
-
|
|
5
|
+
then close the gaps you pick. Runs the validator and closes gaps through
|
|
6
|
+
sassy-cycle. mode:manual (default) asks which to close, mode:auto closes all,
|
|
7
|
+
mode:return only reports. Use when asked to verify conformance to a plan or
|
|
8
|
+
intent. Leaves changes uncommitted.
|
|
9
|
+
argument-hint: "[plan path + phase, or the intent to validate against] [mode:manual|auto|return]"
|
|
9
10
|
disable-model-invocation: true
|
|
10
11
|
---
|
|
11
12
|
|
|
12
13
|
# Sassy Validate
|
|
13
14
|
|
|
14
|
-
**Outcome:** a grounded conformance judgment against an intent
|
|
15
|
+
**Outcome:** a grounded conformance judgment against an intent, and — unless `mode:return` — the chosen gaps closed and verified; everything left uncommitted.
|
|
15
16
|
|
|
16
|
-
**
|
|
17
|
+
**Validate only.** Code quality and bugs are `sassy-review`; simplification is `sassy-simplify`.
|
|
18
|
+
|
|
19
|
+
**Orchestrator only.** Never edit code yourself. The `validator` finds gaps; `sassy-cycle` closes and verifies them.
|
|
17
20
|
|
|
18
21
|
**This skill needs an intent.** Validation without something to validate against is meaningless. If the user gave no plan path or intent, ask for one before doing anything.
|
|
19
22
|
|
|
20
23
|
**Harness.** Loading another skill, dispatching an agent, and any command you hand the user follow the `sassy-setup` skill's `references/harness.md`. Read it once per run, before the first of those.
|
|
21
24
|
|
|
25
|
+
## Modes
|
|
26
|
+
|
|
27
|
+
| Mode | Behavior |
|
|
28
|
+
|------|----------|
|
|
29
|
+
| `mode:manual` (default) | Present the gaps, ask which to close, close those. |
|
|
30
|
+
| `mode:auto` | Close every gap without asking. |
|
|
31
|
+
| `mode:return` | Return the grade and gaps and change nothing — for a caller that owns the fix. |
|
|
32
|
+
|
|
33
|
+
Use the mode the caller passed; never pick one yourself.
|
|
34
|
+
|
|
22
35
|
## Workflow
|
|
23
36
|
|
|
24
37
|
1. **Intent.** Resolve the reference: a plan path plus phase (preferred), or an explicit intent the user states. If neither exists, ask and stop.
|
|
25
38
|
2. **Validate.** Dispatch the `validator` with that intent reference.
|
|
26
|
-
3. **
|
|
27
|
-
4. **
|
|
28
|
-
5. **
|
|
29
|
-
6. **
|
|
39
|
+
3. **Return.** In `mode:return`, return the validator's grade, evidence, and gaps as-is and stop.
|
|
40
|
+
4. **Conforms?** If the grade is `Conforms`, report it and stop. If `Blocked — insufficient grounding`, report what it needs and stop — do not guess.
|
|
41
|
+
5. **Choose.** On `Partial` or `Diverges`, in `mode:manual` present the `Gaps` and ask which to close: all / specific / none. In `mode:auto`, take all.
|
|
42
|
+
6. **Close.** Load the `sassy-cycle` skill on rework with the chosen gaps as findings and the same intent reference. Its verify step re-runs the validator against that intent, with at most two fix passes.
|
|
43
|
+
7. **Report.** What was closed, what remains and why; leave it uncommitted.
|
|
30
44
|
|
|
31
45
|
## Hard rules
|
|
32
46
|
|
|
33
47
|
| Rule | Requirement |
|
|
34
48
|
|------|-------------|
|
|
35
49
|
| Intent required | Never validate without a plan phase or explicit intent. |
|
|
36
|
-
| Orchestrator only | Never edit code. The `validator` judges,
|
|
37
|
-
| Ask first |
|
|
38
|
-
| Gap-bound |
|
|
50
|
+
| Orchestrator only | Never edit code. The `validator` judges, `sassy-cycle` closes. |
|
|
51
|
+
| Ask first | In `mode:manual`, never change code before the user picks. |
|
|
52
|
+
| Gap-bound | Close only the chosen gaps. |
|
|
39
53
|
| Uncommitted | Never commit, push, or open a PR. |
|
|
40
54
|
|
|
41
55
|
## Failure handling
|
|
42
56
|
|
|
43
|
-
The grade is `Blocked — insufficient grounding` → treat it as a real blocker; report exactly what it asked to inspect and stop. The
|
|
57
|
+
The grade is `Blocked — insufficient grounding` → treat it as a real blocker; report exactly what it asked to inspect and stop. The cycle returns a gap open after two passes → report it with its reason.
|
|
@@ -54,7 +54,7 @@ Always gate before committing. The cycle has already fixed and verified its find
|
|
|
54
54
|
- work brief = the phase's goal, work items, and "Done when" criteria
|
|
55
55
|
- intent reference = the plan path and phase
|
|
56
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.
|
|
57
|
+
5. **Present the phase gate.** Report the phase, what changed, findings raised and resolved (with the fix passes it took), the simplifications applied, 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.
|