@sassywares/skills 0.6.5 → 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 +48 -43
- package/package.json +1 -1
- package/skills/sassy-commit-push-pr/SKILL.md +1 -1
- package/skills/sassy-cycle/SKILL.md +25 -12
- package/skills/sassy-debug/SKILL.md +13 -21
- package/skills/sassy-lfg/SKILL.md +10 -9
- package/skills/sassy-setup/SKILL.md +27 -21
- package/skills/sassy-setup/assets/sassywares-readme.md +17 -13
- package/skills/sassy-setup/references/branching.md +11 -5
- package/skills/sassy-setup/references/config.md +16 -7
- package/skills/sassy-setup/scripts/detect.sh +4 -2
- package/skills/sassy-setup/scripts/lockcheck.mjs +30 -2
- package/skills/sassy-ship/SKILL.md +17 -11
- package/skills/sassy-work/SKILL.md +10 -9
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
|
|
@@ -98,7 +101,7 @@ Debugging:
|
|
|
98
101
|
|
|
99
102
|
| Skill | What it does |
|
|
100
103
|
|---|---|
|
|
101
|
-
| **`sassy-ship`** | Compound learnings, optional handbook, commit, PR, and babysit. Review gate in `mode:manual` (default), skipped by `mode:auto`. |
|
|
104
|
+
| **`sassy-ship`** | Compound learnings, optional handbook, commit, PR, and babysit (under `commit.branch: current`: commit and push, no PR). Review gate in `mode:manual` (default), skipped by `mode:auto`. |
|
|
102
105
|
| **`sassy-commit`** | Creates a local commit with a clear message. No push, no PR. |
|
|
103
106
|
| **`sassy-commit-push-pr`** | Commits, pushes, opens or updates a PR, and babysits by default. |
|
|
104
107
|
| **`sassy-babysit`** | Watches a PR until it looks merge-ready or blocked. |
|
|
@@ -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
|
|
@@ -264,27 +270,15 @@ The artifact decides QA: a plan document carries manual QA tables that gate phas
|
|
|
264
270
|
|
|
265
271
|
A base is **any `base_map` value**, not just the remote default: in a repo whose `"*"` targets `staging`, standing on `staging` counts as standing on a base. That distinction is the whole point of the key — see [`skills/sassy-setup/references/branching.md`](skills/sassy-setup/references/branching.md).
|
|
266
272
|
|
|
267
|
-
The three skills take `branch:infer|current|new` to override the config for one run: `infer` (default) means the config decides, `new` forces a branch, `current` commits where you stand. `sassy-ship` never creates a branch; finding the head on a base branch with unpublished commits is a stop-and-ask.
|
|
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
|
@@ -41,7 +41,7 @@ gh pr list --head <branch> --state open --json url,number
|
|
|
41
41
|
|
|
42
42
|
Only an exit-0 empty list means "no open PR". A non-zero exit means **unknown** — resolve auth/connectivity first, never treat it as "none". Probe output is a snapshot; re-check branch/remote/PR state right before the push and the PR create.
|
|
43
43
|
|
|
44
|
-
**Branch policy.** The run's branch is normally already decided: `sassy-work` and `sassy-lfg` cut it at the start via the `sassy-setup` skill's `references/branching.md`, and `sassy-ship` forwards `branch:current`. So the default here is to commit on the checked-out branch when `state` is not `on-base`. Only when it *is* `on-base` or `detached` — a bare invocation with no orchestrator above it — create a feature branch named from the work and say so. `branch:current` or a plain request keeps the checked-out branch (that run pushes and
|
|
44
|
+
**Branch policy.** The run's branch is normally already decided: `sassy-work` and `sassy-lfg` cut it at the start via the `sassy-setup` skill's `references/branching.md`, and `sassy-ship` forwards `branch:current`. So the default here is to commit on the checked-out branch when `state` is not `on-base`. Only when it *is* `on-base` or `detached` — a bare invocation with no orchestrator above it — create a feature branch named from the work and say so. `branch:current` or a plain request keeps the checked-out branch (that run still pushes and opens the PR; only `commit.branch: current` in the config skips it, in `sassy-ship`). Never ask whether to branch. Forward the resolved choice to `sassy-commit`: `branch:new <name>` only when this run creates a branch, else `branch:current`.
|
|
45
45
|
|
|
46
46
|
**Base branch.** `<base>` is `base_map[<current head>]` from the nearest config — a nested repo's own config wins over the workspace's `repos[<dir>]` — falling back to `base_map["*"]`, else the probed remote HEAD **confirmed with the user before use**. The map is the reason a release PR targets `main` while the work sits on `staging`, with no token passed. An explicit `base:<branch>` token wins over all of them — use it when this PR targets something other than the day-to-day base, such as a release PR aimed at `main` while work lands on `staging`. **Never use `defaultBranchRef` as the PR base when the config names one.** Pass it explicitly: `gh pr create --base <base>`.
|
|
47
47
|
|
|
@@ -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
|
|
|
@@ -10,7 +10,7 @@ disable-model-invocation: true
|
|
|
10
10
|
|
|
11
11
|
# Sassy LFG
|
|
12
12
|
|
|
13
|
-
**Outcome:** every phase in the plan run through `sassy-cycle`, then one gate that carries the code approval and every phase's manual QA checklist, phases marked `Done` only when both pass, then `sassy-ship` closes it out (compound, handbook, commit, PR, babysit). A brief runs one cycle through the same gate, then ships.
|
|
13
|
+
**Outcome:** every phase in the plan run through `sassy-cycle`, then one gate that carries the code approval and every phase's manual QA checklist, phases marked `Done` only when both pass, then `sassy-ship` closes it out (compound, handbook, commit, PR, babysit; under `commit.branch: current`, commit and push with no PR). A brief runs one cycle through the same gate, then ships.
|
|
14
14
|
|
|
15
15
|
**The orchestrator does not do work.** Read the plan, dispatch `sassy-cycle` per phase, then `sassy-ship`. Never edit application code. Keep the main context small — all heavy work happens in subagents.
|
|
16
16
|
|
|
@@ -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,14 +43,14 @@ 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
|
-
- **
|
|
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.
|
|
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
|
+
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
|
|
56
56
|
|
|
@@ -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
|
|
|
@@ -43,18 +42,25 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
43
42
|
- **Artifacts** — offer the detected paths as the default; take overrides.
|
|
44
43
|
- **Knowledge** — `knowledge.read` defaults to the solutions dir plus the concepts file. Ask whether there are extra folders to read (a hand-written `notes/learnings/`, a `docs/adr/`).
|
|
45
44
|
- **Base map** — detection proposes `"*"` from the probed remote default. Ask where ordinary work branches from, and whether the default branch itself releases to another branch (a `staging: main` rung). Never write `main` as a guess. In `workspace` mode, show the `repos` map and get a yes on every row — a probed base is only the remote's default.
|
|
46
|
-
- **`commit.branch`** — default `new`: the run cuts a branch before the first change and never commits on a base branch. Offer `current` for a repo that genuinely wants work committed where it stands, and say plainly that `current` lets a run commit onto its base branch.
|
|
45
|
+
- **`commit.branch`** — default `new`: the run cuts a branch before the first change and never commits on a base branch. Offer `current` for a repo that genuinely wants work committed where it stands, and say plainly that `current` lets a run commit onto its base branch and push it, with no PR (`pr.*` and `hooks.pr` are ignored). Under `mode:auto` with `current` on a base branch, ship pushes to that base with no gate.
|
|
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`.
|
|
@@ -67,4 +71,4 @@ mirrored tree. The `sassy-*` skills do their own git and never call them.
|
|
|
67
71
|
|
|
68
72
|
## Hooks
|
|
69
73
|
|
|
70
|
-
`hooks.pr` names project skills that run inside the PR pipeline, keyed by the PR's **head** branch: `"*"` for every PR, an exact branch, or a family such as `release/*`, overriding per point (`before_create`, `after_create`, `before_merge`, `after_merge`). An entry is `<skill> <args…>`; the args mean whatever that skill says they mean — `mode:auto` pre-authorizes the step. Hooks are ordinary skills in `.agents/skills/`, which makes them **code**: review them like code, and never point a hook at a copy of a suite skill.
|
|
74
|
+
`hooks.pr` names project skills that run inside the PR pipeline, keyed by the PR's **head** branch: `"*"` for every PR, an exact branch, or a family such as `release/*`, overriding per point (`before_create`, `after_create`, `before_merge`, `after_merge`). An entry is `<skill> <args…>`; the args mean whatever that skill says they mean — `mode:auto` pre-authorizes the step. Hooks are ordinary skills in `.agents/skills/`, which makes them **code**: review them like code, and never point a hook at a copy of a suite skill. Under `commit.branch: current` there is no PR, so these hooks do not run.
|
|
@@ -88,8 +88,10 @@ than forced.
|
|
|
88
88
|
|
|
89
89
|
Only reachable with `policy: current`, which is an explicit statement that
|
|
90
90
|
committing on the base branch is intended. Proceed, and say in the run's gate
|
|
91
|
-
summary that the commits are landing on `<head
|
|
92
|
-
|
|
91
|
+
summary that the commits are landing on `<head>`. When the config says
|
|
92
|
+
`commit.branch: current`, the close-out commits and pushes `<head>` to its upstream with **no PR** — no
|
|
93
|
+
`sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge. `pr-base` is
|
|
94
|
+
irrelevant here. Never infer this from a skill default.
|
|
93
95
|
|
|
94
96
|
### `stop-and-ask`
|
|
95
97
|
|
|
@@ -122,11 +124,15 @@ policies.
|
|
|
122
124
|
|
|
123
125
|
## After the branch exists
|
|
124
126
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
+
With the token alone, this is a commit only; the push-and-no-PR close-out comes
|
|
128
|
+
from the config. Downstream steps forward `branch:current` to `sassy-commit`,
|
|
129
|
+
because the decision has already been made and the commits belong on that branch. `sassy-ship` never
|
|
127
130
|
creates the branch — by the time it runs, the branch carries the work. If it ever
|
|
128
131
|
finds the run's head on a base branch with unpublished commits, that is a
|
|
129
|
-
mis-run: stop and ask, never relocate commits silently.
|
|
132
|
+
mis-run: stop and ask, never relocate commits silently. The exception is a
|
|
133
|
+
config with `commit.branch: current`, where unpublished commits on the head are
|
|
134
|
+
simply pushed along. Only that config skips the PR. A typed `branch:current`
|
|
135
|
+
token, and the `branch:current` forwarded to `sassy-commit`, do not.
|
|
130
136
|
|
|
131
137
|
Report the branch and its start point in every gate summary. A decision the user
|
|
132
138
|
cannot see is a decision they cannot correct.
|
|
@@ -91,7 +91,7 @@ hooks:
|
|
|
91
91
|
| `git.remote` | mirror of `git.repo` | Workspace only: mirror remote (URL or `owner/name`) |
|
|
92
92
|
| `git.mirror_branch` | `main` | Workspace only: the branch the mirror pushes to |
|
|
93
93
|
| `repos` | `{}` | Workspace only: repo dir name → the base its PRs target |
|
|
94
|
-
| `commit.branch` | `new` | Resolved once per run, before the first change. `new` never commits on a base branch: `sassy-work`, `sassy-lfg`, and `sassy-debug` cut a branch first. `current` commits where you stand, base branch included |
|
|
94
|
+
| `commit.branch` | `new` | Resolved once per run, before the first change. `new` never commits on a base branch: `sassy-work`, `sassy-lfg`, and `sassy-debug` cut a branch first. `current` commits where you stand, base branch included, and the close-out pushes it to its upstream with no PR |
|
|
95
95
|
| `pr.babysit` | `true` | Whether close-out babysits the PR it opened |
|
|
96
96
|
| `pr.merge` | `false` | `true` authorizes merging a single babysat PR |
|
|
97
97
|
| `pr.delete_branch` | `false` | Delete the head branch once merged |
|
|
@@ -168,7 +168,7 @@ branch from `origin/<base>` then leaves them behind entirely.
|
|
|
168
168
|
|
|
169
169
|
| Value | Meaning |
|
|
170
170
|
|-------|---------|
|
|
171
|
-
| `current` | Commit where you stand, even on a base branch. An explicit statement that this repo's work in progress is acceptable |
|
|
171
|
+
| `current` | Commit where you stand, even on a base branch, then push the branch to its upstream (never forced) with no PR. An explicit statement that this repo's work in progress is acceptable |
|
|
172
172
|
| `new` (default) | Never commit on a base branch. Cut one first, then stay on it for the rest of the run |
|
|
173
173
|
|
|
174
174
|
A branch that is already checked out and is **not** a base is reused, whatever
|
|
@@ -181,8 +181,15 @@ default alone. In the config above `staging` is a base because `"*"` targets it,
|
|
|
181
181
|
even though `origin/HEAD` is `main`. Comparing only against `origin/HEAD` is how
|
|
182
182
|
phase work once got committed straight onto `staging`.
|
|
183
183
|
|
|
184
|
+
Under `current` the close-out skips the PR pipeline: `pr.*` and `hooks.pr.*`
|
|
185
|
+
are ignored (`before_create`, `after_create`, `before_merge`, `after_merge` never
|
|
186
|
+
run), and there is no babysit or merge. A non-fast-forward push stops the run.
|
|
187
|
+
Only this config value triggers it. A typed `branch:current` token, or the one
|
|
188
|
+
skills forward to `sassy-commit`, does not suppress the PR.
|
|
189
|
+
|
|
184
190
|
The `branch:infer|current|new` token on those skills overrides this key for one
|
|
185
|
-
run
|
|
191
|
+
run, for branching only; the no-PR close-out follows the config
|
|
192
|
+
`commit.branch: current` regardless of the token; `infer` means this key decides. In a workspace the key is resolved from the
|
|
186
193
|
workspace config for the whole run, one branch name in every repo; a nested
|
|
187
194
|
repo whose own `commit.branch` disagrees is drift, because one run cannot follow
|
|
188
195
|
two policies.
|
|
@@ -329,7 +336,7 @@ hooks — the run says so in one line rather than skipping silently.
|
|
|
329
336
|
|
|
330
337
|
## Multi-repo runs
|
|
331
338
|
|
|
332
|
-
A run that touches N repos produces N commits, N PRs, and one snapshot:
|
|
339
|
+
A run that touches N repos produces N commits, N PRs (no PRs under `current`), and one snapshot:
|
|
333
340
|
|
|
334
341
|
| Artifact | Where |
|
|
335
342
|
|----------|-------|
|
|
@@ -369,9 +376,11 @@ per-PR say-so, because one switch would merge N PRs nobody re-read.
|
|
|
369
376
|
run uses a default this project never chose.
|
|
370
377
|
|
|
371
378
|
`scripts/detect.sh --check` enforces all of the above and reports each breach as
|
|
372
|
-
a `drift:` line, exiting non-zero.
|
|
373
|
-
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
|
|
374
381
|
definition and compared to `computedHash` in `skills-lock.json`, the lock is
|
|
375
382
|
checked against the installed set in both directions, and git-tracked state of
|
|
376
383
|
the lock is reported. A stale, hand-edited, or half-installed suite is drift
|
|
377
|
-
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
|
|
@@ -947,7 +948,8 @@ esac
|
|
|
947
948
|
cat <<'EOF'
|
|
948
949
|
|
|
949
950
|
# --- Commit ---------------------------------------------------------------
|
|
950
|
-
# current: commit on the checked-out branch, even on a base branch
|
|
951
|
+
# current: commit on the checked-out branch, even on a base branch, then push
|
|
952
|
+
# it to its upstream. No PR: pr.* and hooks.pr are ignored.
|
|
951
953
|
# new: never commit on a base branch — sassy-work, sassy-lfg, and sassy-debug
|
|
952
954
|
# cut a branch at the start of the run and stay on it.
|
|
953
955
|
commit:
|
|
@@ -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
|
|
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
name: sassy-ship
|
|
3
3
|
description: >-
|
|
4
4
|
Close out approved work: capture learnings, write a handover handbook when
|
|
5
|
-
warranted, then commit, open a PR, and babysit it
|
|
5
|
+
warranted, then commit, open a PR, and babysit it (under
|
|
6
|
+
`commit.branch: current`, commit and push only). Every heavy step is
|
|
6
7
|
delegated to subagents. Default `mode:manual` presents a shipping summary and
|
|
7
8
|
waits before anything is written, committed, pushed, or opened. `mode:auto`
|
|
8
9
|
runs the close-out with no review.
|
|
@@ -11,11 +12,15 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
|
|
|
11
12
|
|
|
12
13
|
# Sassy Ship
|
|
13
14
|
|
|
14
|
-
**Outcome:** qualifying learnings captured, a handbook written when warranted, the change committed — or snapshotted, in a workspace — a PR opened or updated, and the PR babysat to looks-merge-ready or blocked.
|
|
15
|
+
**Outcome:** qualifying learnings captured, a handbook written when warranted, the change committed — or snapshotted, in a workspace — a PR opened or updated, and the PR babysat to looks-merge-ready or blocked. Under `commit.branch: current` there is no PR: the commit is pushed to the checked-out branch's upstream and the close-out ends there.
|
|
15
16
|
|
|
16
17
|
**Modes.** `mode:manual` (default) reviews the whole close-out before any side effect; `mode:auto` is pre-authorized and skips that review. Never toggle it on your own.
|
|
17
18
|
|
|
18
|
-
**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Precedence: explicit token > session instruction > config > skill default. `pr.babysit`, `pr.merge`, and `pr.delete_branch` seed the close-out; `git.repo` decides whether this run commits, snapshots, or refuses; `hooks.pr.*` adds project steps to the PR pipeline.
|
|
19
|
+
**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Precedence: explicit token > session instruction > config > skill default. `pr.babysit`, `pr.merge`, and `pr.delete_branch` seed the close-out; `git.repo` decides whether this run commits, snapshots, or refuses; `hooks.pr.*` adds project steps to the PR pipeline. `commit.branch: current` replaces the PR pipeline with a push; see Current policy below.
|
|
20
|
+
|
|
21
|
+
**Current policy.** `commit.branch: current` in the config is an explicit opt-in to work landing where it stands. Under it the close-out commits on the checked-out branch and pushes it to its upstream, base branch included, and skips the PR entirely: no `sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge. A user-typed `branch:current` token keeps its usual meaning (commit on the checked-out branch) and does not suppress the PR; neither does the `branch:current` ship forwards to `sassy-commit`.
|
|
22
|
+
|
|
23
|
+
**How to obtain it.** Before the gate, in both `mode:manual` and `mode:auto`, dispatch one dedicated probe `worker`: run the `sassy-setup` skill's `scripts/detect.sh --branch` with **no `--policy`** and return `configured`, `head`, and the upstream (or that none is set). `configured: current` means the current policy applies. Never take the policy from the commit worker: it runs with the forwarded `branch:current` and always reports `policy: current`.
|
|
19
24
|
|
|
20
25
|
**Subagent-maximal by design.** The orchestrator delegates every heavy step (docs, tree reads, git, gh) to subagents and only receives compact summaries. It never reads diffs, file contents, or the tree itself.
|
|
21
26
|
|
|
@@ -23,19 +28,19 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
|
|
|
23
28
|
|
|
24
29
|
## Steps (in order)
|
|
25
30
|
|
|
26
|
-
1. **Review gate.** In `mode:manual` only: present a compact shipping summary — the plan or topic, the changes from the cycle results, the docs the close-out expects to write, the branch/PR target, the babysit options, and **the hooks resolved for this run's head — point, skill, and args — or that none are declared** — and wait. In `mode:auto`, skip this gate.
|
|
31
|
+
1. **Review gate.** In `mode:manual` only: present a compact shipping summary — the plan or topic, the changes from the cycle results, the docs the close-out expects to write, the branch/PR target, the babysit options, and **the hooks resolved for this run's head — point, skill, and args — or that none are declared** — and wait. Under `commit.branch: current`, state instead "commit + push to `<head>`, no PR" and that no PR, babysit, merge, or `hooks.pr.*` (`before_create`, `after_create`, `before_merge`, `after_merge`) will run. In `mode:auto`, skip this gate.
|
|
27
32
|
2. **Compound (conditional).** If the work produced a qualifying learning, dispatch a `worker` whose task is: *load the `sassy-compound` skill and follow it with `mode:auto`* — with a compact learnings brief (the solved problems, root causes, and solutions taken from the cycle results, not from re-reading the tree). It always gets `mode:auto` because ship's own gate already covered the approval. Skip cleanly when nothing qualifies, and skip entirely when `knowledge.write` is `false`.
|
|
28
33
|
3. **Handbook (conditional).** If the feature is self-contained and independent enough that a teammate would benefit from a handover, dispatch a `worker` whose task is: *load the `sassy-handbook` skill and follow it* — with the plan path and topic. The worker reads the tree itself. Skip for small or tightly-coupled changes.
|
|
29
34
|
4. **Commit or snapshot.** After the review gate — never before it — the docs and any remaining code become durable.
|
|
30
35
|
- **`git.repo` is a remote.** Dispatch a `worker`: *load the `sassy-commit` skill and follow it with `branch:current`*, naming that the commit must include the plan, any new solutions docs, the concepts file, `AGENTS.md`, and any handbook just written — resolved from `artifacts.*`, never hardcoded. The branch already exists: `sassy-work` or `sassy-lfg` cut it before the first change, so the docs belong on it with the phase commits. It returns the hash and subject.
|
|
31
36
|
|
|
32
|
-
**Ship never creates the branch.**
|
|
37
|
+
**Ship never creates the branch.** Outside `commit.branch: current`, a head on a base branch with unpublished commits is a mis-run — `sassy-work` was supposed to cut before touching code. Ask the commit worker to return `state` and `unpublished` from the `sassy-setup` skill's `scripts/detect.sh --branch`, and stop and ask if they show a base with a non-zero count. Never relocate commits silently, never push to the base. Under `commit.branch: current` this check does not fire: unpublished commits on the head are simply pushed along with the close-out commit.
|
|
33
38
|
- **`git.repo: workspace`.** Commit code inside each affected repo on the run's shared branch — cut once at the start of the run, `branch:current` from then on — then run `.sassywares/workspace/snapshot`. The snapshot is the workspace's commit and it runs every time, right after approval. A missing or outdated `.sassywares/workspace/snapshot` is a blocker: report it and say to run `sassy-setup`.
|
|
34
39
|
- **`git.repo: none`.** No commit exists here. Report that the work is not persisted and stop.
|
|
35
|
-
5. **PR.** In a `remote` repo, dispatch a `worker`: *load the `sassy-commit-push-pr` skill and follow it with `branch:current` and `babysit:off`, forwarding `base:<branch>` when the caller supplied one* (step 6 owns the babysit). It returns the PR URL. In a `workspace`, open one PR per affected repo — the same branch name in each, `--base` from that repo's own `base_map` when it carries a `.sassywares/config.yaml`, else its `repos` entry — and return a table. A touched repo missing from `repos`, or a base that cannot be resolved, is a stop-and-ask, never a guess. `none` opens nothing.
|
|
40
|
+
5. **PR, or push.** Under `commit.branch: current` in a `remote` repo, skip the PR: dispatch a `worker` to push the head to its upstream with `git push` (upstream set), or `git push -u <remote> <head>` when the head has no upstream — never force. On a non-fast-forward rejection, stop and report; fetching or rebasing is a stop-and-ask. Return the pushed hash and `<head>`, then end the close-out (step 6 is skipped too). In a workspace, push each affected repo in `repos` order, stop at the first rejection, and return a per-repo table (pushed / rejected / not attempted). The final report says "no PR — hooks.pr.* skipped", in `mode:auto` too. Otherwise, in a `remote` repo, dispatch a `worker`: *load the `sassy-commit-push-pr` skill and follow it with `branch:current` and `babysit:off`, forwarding `base:<branch>` when the caller supplied one* (step 6 owns the babysit). It returns the PR URL. In a `workspace`, open one PR per affected repo — the same branch name in each, `--base` from that repo's own `base_map` when it carries a `.sassywares/config.yaml`, else its `repos` entry — and return a table. A touched repo missing from `repos`, or a base that cannot be resolved, is a stop-and-ask, never a guess. `none` opens nothing.
|
|
36
41
|
|
|
37
42
|
**The PR step owns the PR hooks.** `before_create` and `after_create` run inside `sassy-commit-push-pr`, once per PR; ship neither runs nor repeats them.
|
|
38
|
-
6. **Babysit.** With `pr.babysit` (default `true`), dispatch a `worker`: *load the `sassy-babysit` skill and follow it for the PR just created, one checkpoint*, forwarding any `merge:on|off` and `delete-branch:on|off` the caller supplied, else `pr.merge` and `pr.delete_branch`. It reports looks-ready or blocked. For a continuous watch, tell the user to run `sassy-babysit` in-session.
|
|
43
|
+
6. **Babysit.** Skipped under `commit.branch: current`. With `pr.babysit` (default `true`), dispatch a `worker`: *load the `sassy-babysit` skill and follow it for the PR just created, one checkpoint*, forwarding any `merge:on|off` and `delete-branch:on|off` the caller supplied, else `pr.merge` and `pr.delete_branch`. It reports looks-ready or blocked. For a continuous watch, tell the user to run `sassy-babysit` in-session.
|
|
39
44
|
|
|
40
45
|
**One PR per run.** Babysitting a workspace fan-out means one `sassy-babysit` run per PR, and a fan-out is never auto-merged: `pr.merge` and `pr.merge:on` apply to a single-PR run only. A multi-repo merge needs an explicit per-PR say-so.
|
|
41
46
|
|
|
@@ -49,9 +54,10 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
|
|
|
49
54
|
| Delegate everything | The orchestrator runs no git, gh, or file work itself. |
|
|
50
55
|
| Conditional docs | Compound and handbook are skipped when they do not qualify. |
|
|
51
56
|
| Docs in the commit | New docs and pointer lines ship in the same change. |
|
|
52
|
-
| One branch | The branch is cut once, before the first change, by `sassy-work` or `sassy-lfg
|
|
53
|
-
| Never create the branch | Ship never cuts a branch.
|
|
54
|
-
| Never default | Never push directly to the repo base branch. |
|
|
57
|
+
| One branch | The branch is cut once, before the first change, by `sassy-work` or `sassy-lfg` (unless `commit.branch: current`). Ship and its docs commit land on it. |
|
|
58
|
+
| Never create the branch | Ship never cuts a branch. Outside `commit.branch: current`, a head on a base branch with unpublished commits is a stop-and-ask, decided from the commit worker's `state` and `unpublished`. |
|
|
59
|
+
| Never default | Never push directly to the repo base branch — except under `commit.branch: current`, an explicit opt-in, where ship pushes the checked-out branch (base or not) to its upstream, never forced. |
|
|
60
|
+
| Current policy | `commit.branch: current` means commit + push, no PR: no `sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge. A non-fast-forward push is a stop-and-report; in a workspace the push stops at the first rejected repo. |
|
|
55
61
|
| Snapshot after approval | In a workspace, the snapshot runs every time, immediately after the commit approval — never before it, never skipped. |
|
|
56
62
|
| One PR per run | `pr.babysit` and `pr.merge` are single-PR. A fan-out gets one babysit run per PR and no automatic merge. |
|
|
57
63
|
| Hooks are visible | The gate names every hook this run will trigger. A hook that runs unseen is a side effect nobody approved. |
|
|
@@ -61,4 +67,4 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
|
|
|
61
67
|
## Context and token discipline
|
|
62
68
|
|
|
63
69
|
- Hand each subagent a short brief plus the path of the skill to follow; the subagent reads the skill and the tree in its own context.
|
|
64
|
-
- Return only the PR URL, commit hash, doc paths, and a one-line babysit status to the caller.
|
|
70
|
+
- Return only the PR URL (or the pushed hash and "no PR — hooks.pr.* skipped"), commit hash, doc paths, and a one-line babysit status to the caller.
|
|
@@ -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.
|
|
@@ -69,7 +69,7 @@ Always gate before committing. One worker fixes findings, one re-check, then pre
|
|
|
69
69
|
8. **On commit success:**
|
|
70
70
|
- **A next phase exists** → load the `sassy-handoff` skill in `mode:write` with the goal *Execute phase <next> of <plan> by invoking `sassy-work <plan> phase:<next>`*. It writes the handoff file and gives the user a `sassy-handoff mode:read <path>` command; the next phase starts when they run it in a fresh session and pick it.
|
|
71
71
|
|
|
72
|
-
- **This was the last phase** → run the close-out: load the `sassy-ship` skill and follow it.
|
|
72
|
+
- **This was the last phase** → run the close-out: load the `sassy-ship` skill and follow it (under `commit.branch: current` ship commits and pushes, with no PR).
|
|
73
73
|
|
|
74
74
|
**Why a fresh session:** one phase per context keeps every phase's context small. A skill cannot start a session itself, so the handoff file is the bridge and the user opens the session.
|
|
75
75
|
|
|
@@ -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.
|