@sassywares/skills 0.6.10 → 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 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 → 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.
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
- Two mode tokens: `mode:manual` (default) and `mode:auto`. `mode:manual` asks at the skill's gate; `mode:auto` means pre-authorized, no review.
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 both. Ship reviews the whole close-out in `mode:manual` and forwards `mode:auto` to compound once its own gate is answered.
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. 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.
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
 
@@ -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 → validate → fix → verify, with at most two verified fix passes. Also reworks finished work from requested changes or failed QA rows. |
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 offers to fix findings. |
98
- | **`sassy-validate`** | Checks whether work matches a plan or stated intent, then offers to close gaps. |
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
 
@@ -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 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.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sassywares/skills",
3
- "version": "0.6.10",
3
+ "version": "0.7.0",
4
4
  "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -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, 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
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. 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`.
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 + validator always run in parallel. |
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
- | Suggestions don't block | Reviewer suggestions go to the caller's gate for the user to pick; they are never fixed automatically. |
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.
@@ -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, quality, project-rule
5
- conformance, and design-system conformance, then offer to fix the findings. Runs
6
- the reviewer, asks before changing anything, and applies approved fixes via the
7
- worker. Use when asked to review code. Leaves changes uncommitted.
8
- argument-hint: "[PR ref, branch, files, or blank for current changes]"
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; the approved fixes applied; everything left uncommitted.
15
+ **Outcome:** the scope reviewed with concrete findings, and — unless `mode:return` — the chosen ones fixed and verified; everything left uncommitted.
15
16
 
16
- **Orchestrator only.** Never edit code yourself. The `reviewer` finds; the `worker` fixes.
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 all four. Do not drop any of them.
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
- | Quality | Duplication, clarity, dead code, maintainability. |
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 across all four dimensions.
37
- 3. **Nothing actionable?** If there are no Critical or Warning findings, report the summary plus the rules/design-system check list and stop.
38
- 4. **Confirm.** Present findings grouped Critical / Warnings / Suggestions, including the rules and design-system check list, and ask which to fix: critical only / all actionable / none.
39
- 5. **Fix.** Dispatch one `worker` with the selected findings as its brief: fix exactly those, keep the change minimal, run the relevant tests.
40
- 6. **Report.** What was fixed and what was left; leave it uncommitted. Offer to re-review to confirm.
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, the `worker` fixes. |
47
- | Ask first | Never change code before the user approves. |
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 `worker` cannot fix a finding safely → report that finding as open and continue with the rest. Stop on an unsafe or ambiguous failure.
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 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:
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 four `<name>.md` files exist in the user scope or the project scope. If they do, report which scope and move on. If any are missing, ask once where to install, recommending user scope:
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 four subagents by name — `scout`, `worker`, `reviewer`,
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 offer to close the gaps. Runs the validator, asks before changing
6
- anything, and applies approved work via the worker. Use when asked to verify
7
- conformance to a plan or intent. Leaves changes uncommitted.
8
- argument-hint: "[plan path + phase, or the intent to validate against]"
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; the approved gaps closed; everything left uncommitted.
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
- **Orchestrator only.** Never edit code yourself. The `validator` finds gaps; the `worker` closes them.
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. **Conforms?** If the grade is `Conforms`, report it and stop.
27
- 4. **Confirm.** If `Partial` or `Diverges`, present the `Gaps` and ask whether to close them (all / specific / none). If `Blocked — insufficient grounding`, report what it needs and stop — do not guess.
28
- 5. **Close.** Dispatch one `worker` with the approved gaps as its brief: implement exactly those, and nothing else.
29
- 6. **Report.** What was closed and what remains; leave it uncommitted. Offer to re-validate to confirm.
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, the `worker` implements. |
37
- | Ask first | Never change code before the user approves. |
38
- | Gap-bound | Implement only the approved gaps. |
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 `worker` cannot close a gap safely → report it as open.
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.