@sassywares/skills 0.8.0 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONCEPTS.md +15 -5
- package/README.md +40 -8
- package/package.json +1 -1
- package/skills/sassy-cycle/SKILL.md +1 -1
- package/skills/sassy-dogfood/SKILL.md +79 -0
- package/skills/sassy-lfg/SKILL.md +11 -8
- package/skills/sassy-plan/SKILL.md +6 -2
- package/skills/sassy-plan/references/plan-format.md +28 -8
- package/skills/sassy-setup/SKILL.md +17 -8
- package/skills/sassy-setup/assets/dogfood-recipe.md +29 -0
- package/skills/sassy-setup/assets/roster +20 -0
- package/skills/sassy-setup/assets/sassywares-readme.md +1 -1
- package/skills/sassy-setup/references/branching.md +1 -1
- package/skills/sassy-setup/references/config.md +75 -11
- package/skills/sassy-setup/references/dogfood.md +209 -0
- package/skills/sassy-setup/scripts/detect.sh +229 -39
- package/skills/sassy-setup/scripts/lockcheck.mjs +18 -11
- package/skills/sassy-ship/SKILL.md +11 -6
- package/skills/sassy-work/SKILL.md +15 -11
package/CONCEPTS.md
CHANGED
|
@@ -20,6 +20,16 @@ A skill that mostly coordinates. It reads compact results, writes briefs, and av
|
|
|
20
20
|
|
|
21
21
|
`sassy-cycle` runs one unit of work through implement → review + simplify + validate (in parallel) → fix → verify. Simplifications are applied and verified but never block. Verify is a reviewer scoped to the fix, confirming each finding resolved and checking the fix for new ones; at most two fix passes, then anything open is `blocked`. Reviewer suggestions never block; they go to the gate. Given findings instead of a brief — requested changes, failed QA rows — it reworks existing work through the same fix → verify loop. It never commits. Work and LFG run it; debug fixes through work.
|
|
22
22
|
|
|
23
|
+
## Dogfood
|
|
24
|
+
|
|
25
|
+
Agent QA: the project's own stored procedure for proving a change works in the running product, not merely in the diff. `sassy-dogfood` executes it, and the report's verdict is the only thing that settles an `Auto` QA row.
|
|
26
|
+
|
|
27
|
+
- **Recipe** — `.sassywares/dogfood/recipe.md`, committed and reviewed like code. Append-only sections of ordered steps, each with a `Do` and an `Expect`, ending in one `Prove it:` step whose exit code is the verdict. It names no tool: whatever the harness has connected at run time is what satisfies a step. The config points at it and never restates it — commands in the config would duplicate the manifest and could not express order.
|
|
28
|
+
- **Report** — `.sassywares/dogfood/reports/<run-id>/`, never committed and pruned to ten: `summary.md` (status, class, the per-step table, artifact paths), one log per executed step, and the artifacts. The durable record is the QA row's note — verdict and run id — never a path that will vanish.
|
|
29
|
+
- **Verdict classes** — `code` is a finding for the cycle, `env` means the toolchain is broken (report and park, never loop), `recipe` means the procedure itself is stale (propose a diff, never improvise around it).
|
|
30
|
+
- **Two gates** — an `Auto` row needs `dogfood.enabled: true` **and** a section with a `Prove it:` step. One without the other keeps the row `Manual`, which is how an unfinished recipe degrades safely instead of making a gate lie.
|
|
31
|
+
- **Frozen against the run** — a red run never edits the recipe or its expectations to pass. The cheapest way past a check must not be to weaken it.
|
|
32
|
+
|
|
23
33
|
## Gates
|
|
24
34
|
|
|
25
35
|
A gate is a deliberate stop or pass/fail condition.
|
|
@@ -27,7 +37,7 @@ A gate is a deliberate stop or pass/fail condition.
|
|
|
27
37
|
- **Fix gate** — `sassy-debug` presents the causal chain, fix, and risks before changing code.
|
|
28
38
|
- **Code approval gate** — the user approves the code before committing or shipping. Always on for `sassy-work` and `sassy-lfg`.
|
|
29
39
|
- **Ship review gate** — `sassy-ship` summarizes the close-out and waits in `mode:manual` (default); skipped only when the caller passed `mode:auto`.
|
|
30
|
-
- **QA gate** —
|
|
40
|
+
- **QA gate** — QA tables, part of phase completion rather than a separate track: a phase turns `Done` only when the code is approved and every QA row passed. A `Manual` row belongs to the user, and no agent ticks its own. An `Auto` row is settled by a passing dogfood report, never by an opinion, and ship will not persist behind one that is unproven. It exists only when the plan document has QA tables; an in-context brief has none.
|
|
31
41
|
|
|
32
42
|
## Branch and base
|
|
33
43
|
|
|
@@ -47,12 +57,12 @@ Three shared mode tokens: `mode:manual` (default) asks at the skill's gate; `mod
|
|
|
47
57
|
|
|
48
58
|
Everything else is decided by the artifact, not a mode:
|
|
49
59
|
|
|
50
|
-
- A plan document under `docs/plans/` drives phased execution and carries
|
|
60
|
+
- A plan document under `docs/plans/` drives phased execution and carries QA tables whose rows are `Auto` or `Manual`.
|
|
51
61
|
- An in-context brief drives one cycle and has no plan file and no QA tables.
|
|
52
62
|
|
|
53
63
|
## Plan
|
|
54
64
|
|
|
55
|
-
A durable document under `docs/plans/` with intent, decisions, constraints, phase tracking, and per-phase
|
|
65
|
+
A durable document under `docs/plans/` with intent, decisions, constraints, phase tracking, and per-phase QA tables.
|
|
56
66
|
|
|
57
67
|
## Goal
|
|
58
68
|
|
|
@@ -74,6 +84,6 @@ A settled in-context brief produced by `sassy-plan` when the user picks "start w
|
|
|
74
84
|
|
|
75
85
|
`sassy-handoff` in `mode:write` writes a self-contained handoff file under `/tmp/sassywares/<harness>/handoffs/` and gives the user a `sassy-handoff mode:read <path>` command; `mode:read` in the fresh session summarizes what was done, why, and the current state against the tree, then asks what to do next. A skill cannot start a session, so the user opens the fresh one; the file is the only bridge, in any harness.
|
|
76
86
|
|
|
77
|
-
##
|
|
87
|
+
## Release
|
|
78
88
|
|
|
79
|
-
There is no background watcher.
|
|
89
|
+
There is no background watcher. Releases go through `sassy-ship` under `commit.branch: current`: after the approved push, the `hooks.push` `after_push` hook runs the `sassy-skills-release` project skill, which runs the vendored `bin/release` script. It bumps the patch version and tags when consumer-facing files changed, and the tag publishes to npm. It installs nothing: `npx skills add` reads this repo directly. AGENTS.md has the details.
|
package/README.md
CHANGED
|
@@ -12,6 +12,8 @@ It covers the whole path from a rough idea to a shipped PR, and from a bug repor
|
|
|
12
12
|
- [Quick start](#quick-start)
|
|
13
13
|
- [Skills](#skills)
|
|
14
14
|
- [Project config](#project-config)
|
|
15
|
+
- [Dogfooding a project](#dogfooding-a-project)
|
|
16
|
+
- [Extending the pipeline](#extending-the-pipeline)
|
|
15
17
|
- [Workflows](#workflows)
|
|
16
18
|
- [From idea to ship](#from-idea-to-ship)
|
|
17
19
|
- [From goal to done](#from-goal-to-done)
|
|
@@ -28,7 +30,7 @@ It covers the whole path from a rough idea to a shipped PR, and from a bug repor
|
|
|
28
30
|
|
|
29
31
|
- **Lean.** Skills are indexes and workflows, not documentation dumps. Detail moves into `references/` only when it is conditionally needed.
|
|
30
32
|
- **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.
|
|
31
|
-
- **Controlled.** Code approval, manual
|
|
33
|
+
- **Controlled.** Code approval, QA — manual and proved — and ship review are visible gates that all run in sequence. Mode tokens are opt-in per skill: `mode:manual` (default) and `mode:auto` on `sassy-ship` and `sassy-compound`, plus `mode:return` on `sassy-review`, `sassy-simplify`, and `sassy-validate`; work, lfg, and debug take no mode; `sassy-goal` takes one mode per step of a goal (`write`, `next`, `check`, `close`).
|
|
32
34
|
- **Reliable.** Work runs through `sassy-cycle` with isolated subagents for implementation, review, simplification, validation, and verified fixes.
|
|
33
35
|
- **Context-efficient.** Orchestrators coordinate; subagents do the heavy reading and return compact results.
|
|
34
36
|
- **Never surprising.** Nothing is committed just because a step finished. Shipping is its own phase.
|
|
@@ -99,9 +101,12 @@ Debugging:
|
|
|
99
101
|
| **`sassy-review`** | Reviews a diff, branch, PR, or files for bugs, security, project-rule conformance, and design-system conformance, then fixes the findings you pick. |
|
|
100
102
|
| **`sassy-simplify`** | Finds behavior-preserving simplifications — reuse, quality, efficiency — then applies the ones you pick. |
|
|
101
103
|
| **`sassy-validate`** | Checks whether work matches a plan or stated intent, then closes the gaps you pick. |
|
|
104
|
+
| **`sassy-dogfood`** | Uses the product the way a user does to prove a change actually works at runtime — runs the project's stored procedure, writes a report with a verdict, and in `mode:discover` builds or repairs that procedure from what really worked. Tooling-agnostic: it uses whatever your harness has connected and never installs a runner. |
|
|
102
105
|
|
|
103
106
|
Each does one job and takes `mode:manual` (default: ask which to fix), `mode:auto` (fix without asking), or `mode:return` (report only). Fixes run through `sassy-cycle`, so they are verified. Inside work, lfg, and debug, the cycle runs all three agents in parallel itself.
|
|
104
107
|
|
|
108
|
+
`sassy-dogfood` takes its own modes instead: `run` (default), `discover`, and `check`.
|
|
109
|
+
|
|
105
110
|
### Shipping
|
|
106
111
|
|
|
107
112
|
| Skill | What it does |
|
|
@@ -162,11 +167,19 @@ hooks:
|
|
|
162
167
|
after_merge: [] # this run observed the merge
|
|
163
168
|
staging: # a per-point override for one head
|
|
164
169
|
before_create: []
|
|
170
|
+
push: # only under commit.branch: current
|
|
171
|
+
"*":
|
|
172
|
+
after_push: [] # right after the push succeeds
|
|
173
|
+
dogfood: # agent QA: a stored procedure that proves a change runs
|
|
174
|
+
enabled: false # true lets a plan write Mode: Auto QA rows
|
|
175
|
+
recipe: .sassywares/dogfood/recipe.md # the procedure; never commands here
|
|
176
|
+
reports: .sassywares/dogfood/reports # run output; gitignored
|
|
177
|
+
timeout: 900 # whole procedure, seconds
|
|
165
178
|
```
|
|
166
179
|
|
|
167
180
|
### Extending the pipeline
|
|
168
181
|
|
|
169
|
-
A project adds its own steps by naming a skill that lives in its own `.agents/skills/`. Nothing declared means nothing runs. Keys are the **head** branch — the one a PR comes from — and every point can be overridden per head; entries may carry args (`<skill> <args…>`).
|
|
182
|
+
A project adds its own steps by naming a skill that lives in its own `.agents/skills/`. Nothing declared means nothing runs. Keys are the **head** branch — the one a PR comes from (for `hooks.push`, the pushed branch) — and every point can be overridden per head; entries may carry args (`<skill> <args…>`).
|
|
170
183
|
|
|
171
184
|
| Hook | Runs | Typical use |
|
|
172
185
|
|---|---|---|
|
|
@@ -174,11 +187,29 @@ A project adds its own steps by naming a skill that lives in its own `.agents/sk
|
|
|
174
187
|
| `after_create` | the PR was just created | labels, deploy-target comment |
|
|
175
188
|
| `before_merge` | this run is about to merge | a final approval gate |
|
|
176
189
|
| `after_merge` | this run observed the merge | sync a back-merge branch, tag, notify |
|
|
190
|
+
| `hooks.push` `after_push` | `commit.branch: current` only: after ship's push | notify, trigger a follow-up step |
|
|
177
191
|
|
|
178
|
-
Hooks run in declared order, one subagent each, and fail closed: a declared skill that is missing or returns `blocked` stops the run.
|
|
192
|
+
Hooks run in declared order, one subagent each, and fail closed: a declared skill that is missing or returns `blocked` stops the run. Which points may write, and how, is stated once in `sassy-setup`'s `references/config.md` (the hook contract). `before_merge` and `after_merge` never fire unless this run merges.
|
|
179
193
|
|
|
180
194
|
This is deliberately not a fork mechanism. A project skill that *adds* a step is a hook; one that *restates* our steps is a copy, and copies rot. Rules are not hooks either — those belong in `AGENTS.md`.
|
|
181
195
|
|
|
196
|
+
### Dogfooding a project
|
|
197
|
+
|
|
198
|
+
Agent QA is opt-in and stores a **procedure**, not a command. One command can never say "seed first, boot the simulator, wait for the health endpoint, then re-auth if the token is stale" — and that ordering is the only genuinely project-specific part. So the config holds four keys and the work lives in a file:
|
|
199
|
+
|
|
200
|
+
```text
|
|
201
|
+
.sassywares/
|
|
202
|
+
├── config.yaml
|
|
203
|
+
└── dogfood/
|
|
204
|
+
├── recipe.md committed — ordered steps, one `Prove it:` step per section
|
|
205
|
+
├── .gitignore one line: /reports/
|
|
206
|
+
└── reports/ run logs and artifacts — never committed
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
`recipe.md` is the project's, written by `sassy-dogfood mode:discover` from what actually worked, and reviewed like code: numbered steps you append to, each with a `Do` and an `Expect`, ending in a `Prove it:` step whose exit code is the verdict. It names no tool, so it outlives whichever browser driver or emulator your harness happens to have this quarter.
|
|
210
|
+
|
|
211
|
+
A QA row is `Auto` only when `dogfood.enabled` is `true` **and** the row names a recipe section with a `Prove it:` step. One without the other keeps the row `Manual`, which is how an unfinished recipe degrades safely instead of turning into a gate that proves nothing. Anything subjective, physical, irreversible, or unobservable stays a human's check — a false `Auto` pass is unrecoverable. The directory also makes a good fence: a run that trips on a step may not edit the recipe to pass, only propose the diff.
|
|
212
|
+
|
|
182
213
|
Precedence is always explicit token > session instruction > config > skill default. `sassy-setup` writes the file from the tree it detects and keeps `pr.merge` off unless you say otherwise. The full schema, resolution chains, and the three topologies are in [`skills/sassy-setup/references/config.md`](skills/sassy-setup/references/config.md).
|
|
183
214
|
|
|
184
215
|
In a `workspace` there is exactly one ignore file, and it is not at the root:
|
|
@@ -218,9 +249,9 @@ flowchart LR
|
|
|
218
249
|
L -->|approve or mode:auto| M[Commit, PR, babysit]
|
|
219
250
|
```
|
|
220
251
|
|
|
221
|
-
Option 1 produces a durable plan with phased slices and
|
|
252
|
+
Option 1 produces a durable plan with phased slices and QA tables. Options 2 and 3 keep the whole job as one settled in-context brief and write no plan file.
|
|
222
253
|
|
|
223
|
-
`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
|
|
254
|
+
`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 QA checklist; nothing is `Done`, committed, or shipped until both pass. `Manual` rows are yours to run. `Auto` rows are proved before the gate by `sassy-dogfood`, and a failed one goes back through the cycle as a finding. With an in-context brief there are no QA rows, so the gate is code approval alone.
|
|
224
255
|
|
|
225
256
|
Inside the cycle, every finding is fixed and then **verified**: a reviewer scoped to the fix confirms each finding resolved, and checks the fix itself for anything new. Whatever is still open gets a second fix pass; anything open after that comes back `blocked` rather than looping. Critical findings, warnings, and validator gaps are fixed automatically; the simplifier's findings are applied in the same pass but never block; the reviewer's suggestions are listed at the gate for you to pick. Changes you request at the gate and QA rows that fail go through the same loop as findings, then the gate comes back.
|
|
226
257
|
|
|
@@ -284,10 +315,11 @@ The fix gate offers four options:
|
|
|
284
315
|
| Control | When it applies |
|
|
285
316
|
|---|---|
|
|
286
317
|
| Code approval | Always on for `sassy-work` and `sassy-lfg`. |
|
|
287
|
-
|
|
|
318
|
+
| QA | Part of the same gate, and only when the plan document has QA tables. `Manual` rows are yours; `Auto` rows are settled by a `sassy-dogfood` report. A phase is `Done` only when both pass. |
|
|
319
|
+
| Dogfood | `Auto` rows only exist when `dogfood.enabled` is on and the row's recipe section has a `Prove it:` step. `sassy-ship` persists nothing behind an unproven row. |
|
|
288
320
|
| Ship review | On in `mode:manual` (default), skipped by `mode:auto`. |
|
|
289
321
|
|
|
290
|
-
The artifact decides QA: a plan document carries
|
|
322
|
+
The artifact decides QA: a plan document carries QA tables that gate phase completion, an in-context brief does not. Gates are deliberate stops; the only way past one is the user's approval. `mode:auto` is accepted only by `sassy-ship` and `sassy-compound`.
|
|
291
323
|
|
|
292
324
|
## Branching
|
|
293
325
|
|
|
@@ -366,4 +398,4 @@ pi install npm:@sassywares/skills
|
|
|
366
398
|
|
|
367
399
|
## Repository maintenance
|
|
368
400
|
|
|
369
|
-
|
|
401
|
+
Work here lands on `main` through `sassy-ship` (`commit.branch: current`). After the approved push, the project's `hooks.push` `after_push` step runs the release: on `main`, when files consumers receive changed, it bumps the patch version and tags it, and the tag publishes `@sassywares/skills` to npm. [`AGENTS.md`](AGENTS.md) is the full guide: layout, adding a skill, testing, and releasing.
|
package/package.json
CHANGED
|
@@ -79,7 +79,7 @@ A finding is `resolved`, and a simplification `applied`, only when step 6's revi
|
|
|
79
79
|
| Only fixes block | Simplifications are applied and verified but never make a run `blocked`; reviewer suggestions go to the caller's gate for the user to pick and are never applied automatically. |
|
|
80
80
|
| Simplifier runs once | Only at step 3 (or never, on rework). Verify re-checks what was applied; it does not hunt for more. |
|
|
81
81
|
| Never commit | This skill leaves everything uncommitted. Shipping is `sassy-ship`. |
|
|
82
|
-
|
|
|
82
|
+
| QA stays the caller's | Never mark a QA row `Done`, `Manual` or `Auto`. A `Manual` row is confirmed by the user at the caller's gate and an `Auto` row by a passing dogfood report; failing rows come back as findings. |
|
|
83
83
|
|
|
84
84
|
## Context and token discipline
|
|
85
85
|
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sassy-dogfood
|
|
3
|
+
description: >-
|
|
4
|
+
Use the product the way a user does, to prove a change actually works at
|
|
5
|
+
runtime rather than only in the diff. Runs the project's stored dogfood
|
|
6
|
+
procedure, writes a report with a verdict, and — in `mode:discover` — builds
|
|
7
|
+
or repairs that procedure from what really worked. Tooling-agnostic: it uses
|
|
8
|
+
whatever the harness has connected at run time and never installs a runner.
|
|
9
|
+
Use before a phase gate, when a plan row is `Mode: Auto`, or to set up
|
|
10
|
+
agent QA for a project.
|
|
11
|
+
argument-hint: "[section:<name>] [mode:run|discover|check]"
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# Sassy Dogfood
|
|
15
|
+
|
|
16
|
+
**Outcome:** a report with a verdict — `pass`, `failed` with the failing step and its output tail, or `env`/`recipe` explaining why the run could not judge the work — in `.sassywares/dogfood/reports/<run-id>/`, plus, in `mode:discover`, a `recipe.md` that a fresh agent can follow with no other context.
|
|
17
|
+
|
|
18
|
+
**A procedure is the artifact.** The project stores how to dogfood itself in `.sassywares/dogfood/recipe.md`: ordered steps, each with an observable expectation, ending in one `Prove it:` step whose exit code is the verdict. The config points at it; it never restates it. Read the `sassy-setup` skill's `references/dogfood.md` first — it owns the recipe format, the report layout, and the verdict classes, and this skill only executes them.
|
|
19
|
+
|
|
20
|
+
**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. `dogfood.enabled`, `dogfood.recipe`, `dogfood.reports`, and `dogfood.timeout` are the only inputs. Precedence: explicit token > session instruction > config > skill default.
|
|
21
|
+
|
|
22
|
+
**No tooling.** This skill names no browser, driver, emulator, or MCP server, and it never installs one. A step says *what to do and what to see*; how the agent satisfies that is discovered at run time from what the harness already offers, and a plain command is often the better answer.
|
|
23
|
+
|
|
24
|
+
**Harness.** Loading another skill, dispatching an agent, and any command you hand the user follow the `sassy-setup` skill's `references/harness.md`. Read it once per run, before the first of those.
|
|
25
|
+
|
|
26
|
+
## Modes
|
|
27
|
+
|
|
28
|
+
| Mode | What it does |
|
|
29
|
+
|------|--------------|
|
|
30
|
+
| `run` (default) | Preflight, execute the procedure from the recipe, write the report, classify, report back |
|
|
31
|
+
| `discover` | Build or repair the recipe: probe the repo, try the cheapest proof that could work, write down what actually worked |
|
|
32
|
+
| `check` | Lint the config and the recipe and print the last report's verdict; runs nothing, changes nothing |
|
|
33
|
+
|
|
34
|
+
`run` never edits the recipe. `discover` never gates anything: it produces a
|
|
35
|
+
recipe, and the next `run` is what proves it.
|
|
36
|
+
|
|
37
|
+
## Steps — `mode:run`
|
|
38
|
+
|
|
39
|
+
1. **Resolve the target.** Read the `dogfood:` block. If `enabled` is not `true`, stop with one line: reporting is not enabled, and enabling it is `sassy-setup mode:init`. Load the recipe; a section the caller names (`section:<name>`) is the target, otherwise every section. A missing recipe, or one whose section has no `Prove it:` step, stops the run and names `mode:discover` — never guess a verdict from a procedure that has none.
|
|
40
|
+
2. **Preflight, and do not run blind.** The recipe's *Set up once* lists what must exist. Check that each env var it **names** is present — presence only, never print a value — and that the commands' entry points exist. A missing dependency, a tool not on `PATH`, or an absent env var is `class: env`: write the report, report it, and stop. Never install, never `docker pull`, never mutate the environment to get past preflight.
|
|
41
|
+
3. **Open the report.** Create `<reports>/<YYYYMMDD-HHMMSS>/` with `steps/` and `artifacts/`, and write `summary.md` with `status: running`, the class blank, the recipe path with the current commit, and the start time. Prune older run directories down to ten.
|
|
42
|
+
4. **Execute in order, stopping at the first broken expectation.** Per step: write `steps/<section>-<NN>.log`, capped head-and-tail, with the command and its output, values of every env var the recipe names masked, and the exit code. `Do` is a command *or* an instruction — satisfy it with whatever is available, and judge it only against its `Expect`. A step whose expectation fails ends that section: record it, keep everything already written, and skip to the report. Resume at the failed step on the next run, never from the top: the summary's `Next:` line says which.
|
|
43
|
+
5. **Take the verdict from the prove step.** The section's `Prove it:` step decides: exit 0 is `pass`, non-zero is `failed`. A failure earlier in the section is `failed` regardless. This skill holds no opinion about the work — a check it judged by reading instead of running is not a verdict.
|
|
44
|
+
6. **Classify.** `env` when the toolchain is broken (exit 75 or 127, a missing dependency, an unreachable service that is not part of the change); `recipe` when a step cannot be followed at all (a script renamed, a URL that no longer exists, a UI that no longer matches) — that is the procedure being stale, not the code being wrong; `code` otherwise. When in doubt between `recipe` and `code`, ask: could a person follow this step as written and still be testing the app? If not, it is `recipe`.
|
|
45
|
+
7. **Finalize and report.** Write the final `summary.md` (`status`, `class`, the per-step table, artifacts, `Next:`), then return compactly: verdict, class, section, failing step id, the last ~600 characters of that step's log, the report path, and — for `recipe` — the one-line diff you propose. Never paste a whole log to the caller.
|
|
46
|
+
8. **On `recipe`, propose and stop.** Show the diff that would make the procedure followable and ask before writing it. Never edit the recipe to turn a red run green: the cheapest way to pass a check must not be to weaken it.
|
|
47
|
+
|
|
48
|
+
## Steps — `mode:discover`
|
|
49
|
+
|
|
50
|
+
1. **Read what the project already says.** The existing recipe, the config, and the manifest's scripts (`package.json`, `Makefile`, `pyproject.toml`, `deno.json`, a CI workflow) — what is already wired is the answer more often than a new harness is. Discover, do not impose.
|
|
51
|
+
2. **Find the surfaces.** What is this product? A web app, an API, a CLI, a library, a desktop app, a mobile app in a simulator, several of them. Each surface that a change can break gets a section.
|
|
52
|
+
3. **Find the cheapest proof per surface.** Prefer, in order: an existing test suite or e2e target, a single narrow command that exercises the change, an instruction the agent can carry out against the running product. Whatever the harness has connected right now is fair game; nothing is installed to make this work.
|
|
53
|
+
4. **Try it, then write down what worked.** Bring the product up, run the proof, watch it fail at least once if you can arrange it — a check nobody has seen fail is not a check — then write the steps exactly as they succeeded, with the `Expect` each one actually produced. Write instructions, not recipes for one tool.
|
|
54
|
+
5. **Report.** The sections written, which proof each uses, what is still unknown, and whether a `Mode: Auto` row is now justified. Say plainly that `sassy-setup mode:init` flips `dogfood.enabled` and that the switch alone changes nothing.
|
|
55
|
+
|
|
56
|
+
## Steps — `mode:check`
|
|
57
|
+
|
|
58
|
+
Run the `sassy-setup` skill's `scripts/detect.sh --root <path> --check` and report the `dogfood` and recipe lines verbatim; print the newest report's `status`, `class`, and timestamp, or that there is none. Write nothing.
|
|
59
|
+
|
|
60
|
+
## Hard rules
|
|
61
|
+
|
|
62
|
+
| Rule | Requirement |
|
|
63
|
+
|------|-------------|
|
|
64
|
+
| The verdict is an exit code | A section's `Prove it:` step decides. Never a judgement, a screenshot someone liked, or "looks right". |
|
|
65
|
+
| No tooling, no installs | Never name or require a browser, driver, emulator, or MCP server; never install one to make a run possible. Missing tooling is `class: env`. |
|
|
66
|
+
| Never production | Local or staging only. A recipe step pointing at production is refused and reported, not run. |
|
|
67
|
+
| The run may not edit the check | A red run never fixes itself by editing the recipe or its expectations. Propose the diff, ask, stop. |
|
|
68
|
+
| Reports stay local | Never commit `reports/`. Never paste a full log to a caller, a plan, or a PR. |
|
|
69
|
+
| No secrets, ever | Env var **names** only. Mask values before a log is written, and never echo one in a report. |
|
|
70
|
+
| Env is not code | Exit 75/127, a missing dependency, or an unreachable service is `env`: report and park. Looping on a broken toolchain burns a run for nothing. |
|
|
71
|
+
| Resume, don't restart | Re-run from the failed step; the summary says where. Starting over hides the state that made the failure happen. |
|
|
72
|
+
| Reports are disposable | Pruned to ten. The durable record is the QA row's note, which names the verdict and the run id, never a path that will vanish. |
|
|
73
|
+
| Not a test framework | If the project has a suite, the recipe wraps it. This skill never grows assertions of its own beyond a step's `Expect`. |
|
|
74
|
+
|
|
75
|
+
## What dogfood is not
|
|
76
|
+
|
|
77
|
+
Not a test-authoring skill, and not a CI replacement: CI runs your suite on every push, dogfood runs *this* change against the running product once, and its job is to hand back a verdict the plan can trust. Not a harness either — it does not drive the agent, retry until green, or decide when work is done; `sassy-work` owns the gate and `sassy-cycle` owns the fix.
|
|
78
|
+
|
|
79
|
+
Not a reason to skip a human. Anything subjective, physical, irreversible, or unobservable stays a `Manual` QA row: a false `Auto` pass is unrecoverable, a manual row is merely slower.
|
|
@@ -9,7 +9,7 @@ argument-hint: "<plan path | brief> [branch:infer|current|new]"
|
|
|
9
9
|
|
|
10
10
|
# Sassy LFG
|
|
11
11
|
|
|
12
|
-
**Outcome:** every phase in the plan run through `sassy-cycle`, then one gate that carries the code approval and every phase's
|
|
12
|
+
**Outcome:** every phase in the plan run through `sassy-cycle`, then one gate that carries the code approval and every phase's QA checklist (`Manual` rows from the user, `Auto` rows from a `sassy-dogfood` report), 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.
|
|
13
13
|
|
|
14
14
|
**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.
|
|
15
15
|
|
|
@@ -28,13 +28,16 @@ If nothing is passed and no plan exists, run `sassy-plan` first and use what the
|
|
|
28
28
|
|
|
29
29
|
## QA gate
|
|
30
30
|
|
|
31
|
-
Read the plan's `**QA:**` line and its per-phase QA tables. QA is
|
|
31
|
+
Read the plan's `**QA:**` line and its per-phase QA tables. QA is 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.
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
Rows split by `Mode`:
|
|
34
|
+
|
|
35
|
+
- **`Manual` rows are the user's.** The agent never ticks one it did not hear confirmed: it becomes `Done` only on the user's explicit confirmation, with their note recorded.
|
|
36
|
+
- **`Auto` rows are proved, not opined.** Before the gate, run `sassy-dogfood` in `mode:run` for each row's section and take the verdict from its report; a row becomes `Done` only on a `pass`, with the run id in `Notes`.
|
|
34
37
|
- 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.
|
|
35
38
|
- Rows nobody has reported on stay `Pending` and hold their phase `In progress`.
|
|
36
39
|
|
|
37
|
-
A brief has no QA table, so its gate is code approval alone. Never invent, enable, or disable QA.
|
|
40
|
+
A brief has no QA table, so its gate is code approval alone. Never invent, enable, or disable QA. Never edit the dogfood recipe to make a red run green — propose the diff and ask.
|
|
38
41
|
|
|
39
42
|
## Steps
|
|
40
43
|
|
|
@@ -44,10 +47,10 @@ A brief has no QA table, so its gate is code approval alone. Never invent, enabl
|
|
|
44
47
|
- 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.
|
|
45
48
|
- On `Status: done`, leave the phase `In progress` — its QA rows are still owed, and only the gate closes them.
|
|
46
49
|
- On `Status: blocked`, mark it `Blocked` and stop the run.
|
|
47
|
-
4. **The gate.** After the last phase, report: the plan path, each phase's status, what changed per phase, findings raised and resolved (with the fix passes each took), the simplifications applied, the validator/reviewer summaries, and the reviewers' suggestions as options the user may pick. Then give every phase's QA checklist verbatim — row ID, check, how to run it
|
|
50
|
+
4. **The gate.** After the last phase, prove the `Auto` rows — run `sassy-dogfood` in `mode:run` for each row's section; a `failed` verdict is a finding for that phase's rework, and a `class: env` verdict stops the run with the toolchain named. Then report: the plan path, each phase's status, what changed per phase, findings raised and resolved (with the fix passes each took), the simplifications applied, the validator/reviewer summaries, and the reviewers' suggestions as options the user may pick. Then give every phase's QA checklist verbatim — row ID, check, `Mode`, and for `Manual` how to run it and what passing looks like, for `Auto` the dogfood verdict and run id — with unreported rows `Pending`. Ask for both decisions: code approval (or the changes wanted, including any suggestions picked) and the result per `Manual` row. Wait. Do not commit.
|
|
48
51
|
5. **Resolve the gate.** Three outcomes:
|
|
49
|
-
- **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.
|
|
50
|
-
- **Code approved,
|
|
52
|
+
- **Code approved and every QA row passes** → mark the rows `Done` (`Manual` with the user's notes, `Auto` with the verdict and run id), mark the phases `Done`, then run the close-out below.
|
|
53
|
+
- **Code approved, `Manual` rows 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.
|
|
51
54
|
- **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.
|
|
52
55
|
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.
|
|
53
56
|
|
|
@@ -76,7 +79,7 @@ When the argument is not a plan path, the brief is the one phase:
|
|
|
76
79
|
| 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. |
|
|
77
80
|
| Phases in plan order | Phases run one after another, in plan order. |
|
|
78
81
|
| Done needs both gates | Mark a phase `Done` only when the user approves the code and every QA row for it is `Done`. |
|
|
79
|
-
| 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. |
|
|
82
|
+
| QA rows follow the user | Tick a `Manual` QA row `Done` only from the user's explicit confirmation, and an `Auto` row only from a passing dogfood report; keep unreported rows `Pending`; a failed row is a finding for a rework cycle. |
|
|
80
83
|
| 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
84
|
| Gates before shipping | Nothing is committed or shipped until the code is approved and every QA row passes. Shipping is `sassy-ship`. |
|
|
82
85
|
| No plan on the brief path | Use the in-context brief; never create or update a plan file. |
|
|
@@ -59,7 +59,7 @@ The user must pick explicitly. There is no default and no auto-selection. If no
|
|
|
59
59
|
|
|
60
60
|
### Option 1 — Write the plan
|
|
61
61
|
|
|
62
|
-
Read `references/plan-format.md` and write the plan, including the per-phase
|
|
62
|
+
Read `references/plan-format.md` and write the plan, including the per-phase QA tables that format defines, with each row's `Mode` decided the way that format says. Then report the absolute path and offer the remaining two options, now run on the plan file:
|
|
63
63
|
|
|
64
64
|
```text
|
|
65
65
|
Plan written to <absolute path>. Pick one, or stop here:
|
|
@@ -79,7 +79,11 @@ Load the `sassy-lfg` skill the same way: the settled brief as the work brief, it
|
|
|
79
79
|
|
|
80
80
|
## QA
|
|
81
81
|
|
|
82
|
-
The plan document carries
|
|
82
|
+
The plan document carries QA tables per `references/plan-format.md`. Those rows gate phase completion: a phase is `Done` only when the code is approved and every row passed. `Manual` rows are the user's to run; `Auto` rows are proved by `sassy-dogfood` and its report.
|
|
83
|
+
|
|
84
|
+
A row is `Auto` only when the project's `dogfood.enabled` is `true` **and** the row names a recipe section with a `Prove it:` step; otherwise it is `Manual`. That reference owns the list of checks that stay human — subjective, physical, irreversible, unobservable, unprovable — and on doubt the row is `Manual`. Never invent a section, a command, or a check to make a row look automatable: a false `Auto` pass is unrecoverable.
|
|
85
|
+
|
|
86
|
+
The in-context brief has no QA table, so its gate is code approval alone. Omit QA tables only when the user explicitly asks to skip QA in plain language.
|
|
83
87
|
|
|
84
88
|
## Resume
|
|
85
89
|
|
|
@@ -14,11 +14,29 @@ The plan has no open-questions section. Every branch the interview found is a de
|
|
|
14
14
|
4. **Readable.** 3–8 phases for a typical feature. Merge only when a split leaves a phase with no meaningful thing to verify.
|
|
15
15
|
5. **No dump sections.** Anything executable lives under a phase. No giant task list outside the phases.
|
|
16
16
|
|
|
17
|
-
## QA —
|
|
17
|
+
## QA — part of the gate
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
Every phase gets a QA table. Each row's `Mode` is `Auto` or `Manual`, and the choice is not a preference:
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
- **`Manual` is the default.** Write each row so a person can run it without reading code — what to set up, what to do, and what passing looks like.
|
|
22
|
+
- **`Auto` needs two things**: the project's `dogfood.enabled` is `true` (per the `sassy-setup` skill's `references/dogfood.md`) **and** the row names a recipe section that carries a `Prove it:` step. One without the other stays `Manual`. An `Auto` row with no check behind it is a gate that proves nothing.
|
|
23
|
+
- An `Auto` row names the recipe **section**, never a command. Commands belong in the recipe; copied into a row they rot one row at a time.
|
|
24
|
+
|
|
25
|
+
A row stays `Manual` when the answer is genuinely a human's:
|
|
26
|
+
|
|
27
|
+
| The check is… | Because |
|
|
28
|
+
|---|---|
|
|
29
|
+
| subjective | "does this look right", "does this feel intuitive", "is this the right product decision" |
|
|
30
|
+
| physical or sensory | audio, haptics, camera, mic, a real device, a push to a real phone |
|
|
31
|
+
| irreversible or third-party | payments, mail actually sent, shared or staging data touched |
|
|
32
|
+
| unobservable | no artifact an agent can inspect |
|
|
33
|
+
| unprovable | no check exists yet |
|
|
34
|
+
|
|
35
|
+
On doubt, `Manual`. A false `Auto` pass is unrecoverable; a `Manual` row is merely slower.
|
|
36
|
+
|
|
37
|
+
**An `Auto` check must have been seen failing once** — break the thing, watch the check fail, restore it — before the row is recorded. A check nobody has watched fail is not a check.
|
|
38
|
+
|
|
39
|
+
QA is a completion gate, not a separate track: a phase turns `Done` only when the code is approved and every QA row for that phase passes. `Manual` rows belong to the user, and the agent records what it hears. `Auto` rows are settled by a `sassy-dogfood` run and its report, never by an opinion.
|
|
22
40
|
|
|
23
41
|
The user may ask in plain language to omit QA tables for this plan, in which case omit the tables and the `**QA:**` line entirely.
|
|
24
42
|
|
|
@@ -27,7 +45,9 @@ The user may ask in plain language to omit QA tables for this plan, in which cas
|
|
|
27
45
|
```markdown
|
|
28
46
|
# <Plan title>
|
|
29
47
|
|
|
30
|
-
**QA:**
|
|
48
|
+
**QA:** auto
|
|
49
|
+
|
|
50
|
+
(`auto` when at least one row in the plan is `Auto`, `manual` when none is. It is the source of truth for executors, so it never disagrees with the tables.)
|
|
31
51
|
|
|
32
52
|
## Intent
|
|
33
53
|
One short paragraph: what we are building and why.
|
|
@@ -81,15 +101,15 @@ Omit empty layers. Do not put the next goal's work here.
|
|
|
81
101
|
|
|
82
102
|
**Done when:** Plain-language acceptance for this phase only.
|
|
83
103
|
|
|
84
|
-
#### QA — P1 (
|
|
104
|
+
#### QA — P1 (Auto)
|
|
85
105
|
|
|
86
106
|
| ID | Check | Mode | Status | Notes |
|
|
87
107
|
|----|-------|------|--------|-------|
|
|
88
|
-
| P1-Q1 |
|
|
89
|
-
| P1-Q2 |
|
|
108
|
+
| P1-Q1 | Searching "wool socks" returns matching products | Auto (catalog) | Pending | |
|
|
109
|
+
| P1-Q2 | The empty state reads well | Manual | Pending | |
|
|
90
110
|
|
|
91
111
|
### P2 — <short goal name>
|
|
92
112
|
…
|
|
93
113
|
```
|
|
94
114
|
|
|
95
|
-
Every phase has at least one QA row. Status values there are `Pending` | `Done` | `Blocked`: `Done`
|
|
115
|
+
Every phase has at least one QA row. Status values there are `Pending` | `Done` | `Blocked`: a `Manual` row is `Done` once the user ran that check and confirmed it passed, an `Auto` row is `Done` once a dogfood run passed and its run id is in `Notes`, `Blocked` carries a note saying what failed, and anything unreported stays `Pending`. The `**QA:**` line near the title is the source of truth for executors.
|
|
@@ -12,7 +12,7 @@ argument-hint: "[path] [mode:init|check]"
|
|
|
12
12
|
|
|
13
13
|
# Sassy Setup
|
|
14
14
|
|
|
15
|
-
**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.
|
|
15
|
+
**Outcome:** `.sassywares/config.yaml` at the project root matching the tree it describes, the dogfood scaffold when agent QA was asked for, 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.
|
|
16
16
|
|
|
17
17
|
**Read `references/config.md` first.** It is the schema and the resolution rules; this skill only decides and writes.
|
|
18
18
|
|
|
@@ -41,10 +41,13 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
41
41
|
- **Artifacts** — offer the detected paths as the default; take overrides.
|
|
42
42
|
- **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/`).
|
|
43
43
|
- **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.
|
|
44
|
-
- **`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.
|
|
44
|
+
- **`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; `hooks.push` runs). Under `mode:auto` with `current` on a base branch, ship pushes to that base with no gate.
|
|
45
45
|
- **`pr.*`** — default `babysit: true`, `merge: false`, `delete_branch: false`. Say plainly that `merge: true` authorizes merging every babysat PR in this project without asking.
|
|
46
|
-
- **Hooks** — offer, do not impose. Ask whether the project wants steps injected at `before_create`, `after_create`, `before_merge`, or `after_merge`, and under which head branch (`"*"` for all). Entries may carry args (`<skill> <args…>`); a hook skill's args are its own vocabulary. Leave them `[]` when there is nothing to add. **Never write a hook skill yourself** — hooks are project skills, and copying one of ours into that role is the fork this mechanism exists to prevent.
|
|
46
|
+
- **Hooks** — offer, do not impose. Ask whether the project wants steps injected at `before_create`, `after_create`, `before_merge`, or `after_merge` (or `hooks.push` `after_push`, for `commit.branch: current` only), 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.
|
|
47
|
+
- **Dogfood** — ask whether the project wants agent QA: a stored procedure that proves a change works in the running product, which then lets `sassy-plan` write `Mode: Auto` QA rows instead of manual ones. Say plainly what each answer means. `false` — every QA row stays a human's, which is today's behavior. `true` — a plan may write Auto rows, but only for a recipe section that carries a `Prove it:` step, so the switch alone never makes a gate prove something. Write the answer explicitly either way; never leave it to inference. On yes, scaffold per step 4. Read `references/dogfood.md` and **never** write a command into the block or author the procedure: the recipe is the project's, and its first real content comes from a `sassy-dogfood mode:discover` run.
|
|
47
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.
|
|
49
|
+
|
|
50
|
+
**The dogfood scaffold, only when the answer was yes.** Create `.sassywares/dogfood/` holding `recipe.md` copied verbatim from `assets/dogfood-recipe.md`, and a `.gitignore` whose one line is `/reports/`. Never overwrite an existing recipe or ignore file — show it and ask. The skeleton is deliberately incomplete: it carries the shape and the rules and fills in nothing, because `sassy-dogfood mode:discover` writes the procedure from what actually worked. Say so in the report — `enabled: true` is a permission, not a promise that a check exists.
|
|
48
51
|
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.
|
|
49
52
|
|
|
50
53
|
- **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.
|
|
@@ -76,21 +79,23 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
76
79
|
- **Tell the user to `/reload`** (or restart the harness). The skills and agents are invisible to the harness until it rescans.
|
|
77
80
|
|
|
78
81
|
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.
|
|
79
|
-
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
|
|
82
|
+
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`, the `dogfood` block, any unknown key, and in `workspace` mode the installed snapshot's version — plus, for a project-scope install, the pin: every suite-skill folder in `.agents/skills` (a name in the suite's roster, `assets/roster` in sassy-setup, not any `sassy-` prefix) 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.
|
|
83
|
+
|
|
84
|
+
The `dogfood` half is structural and never runs the product: `enabled` and `timeout` are in range, the two paths are relative and stay inside the project, `reports` is gitignored in a `repo` topology, and the recipe has a `**Prove it:**` line per section with an `**Expect**` per step and no secret-shaped string. A recipe that does not exist yet is a note, not drift — unless `enabled` is `true`, which is the one combination that would let a planner write Auto rows against a check nobody has.
|
|
80
85
|
|
|
81
86
|
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.
|
|
82
87
|
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:
|
|
83
88
|
|
|
84
|
-
`.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 .`.
|
|
89
|
+
`.sassywares/config.yaml`, `.sassywares/README.md`, `.sassywares/dogfood/recipe.md` and `.sassywares/dogfood/.gitignore` when step 4 scaffolded them, `.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 .`. The reports directory is never in this list: it is gitignored, and nothing setup writes lives there.
|
|
85
90
|
|
|
86
91
|
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.
|
|
87
92
|
|
|
88
|
-
**Nothing else** unless the user asks: a plan, a doc, a source file, or anything already dirty in the tree stays uncommitted, because setup's commit is not a place to launder work in progress. A user who says "commit my plan too" widens the list with the file they named — never with a sweep for it. On a `check` run this fires only when something setup owns is dirty: an uncommitted pin, a config edited since the last commit. Nothing dirty, nothing to commit.
|
|
93
|
+
**Nothing else** unless the user asks: a plan, a doc, a source file, or anything already dirty in the tree stays uncommitted, because setup's commit is not a place to launder work in progress. A user who says "commit my plan too" widens the list with the file they named — never with a sweep for it. On a `check` run this fires only when something setup owns is dirty: an uncommitted pin, a config edited since the last commit, a scaffold nobody committed. Nothing dirty, nothing to commit.
|
|
89
94
|
|
|
90
95
|
- **`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.
|
|
91
96
|
- **`none`** — nothing to commit, deliberately.
|
|
92
97
|
|
|
93
|
-
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.
|
|
98
|
+
9. **Report.** The config path, the topology, the resolved artifact and knowledge paths, whether agent QA is on and — when it is — that the recipe is a skeleton until a `sassy-dogfood mode:discover` run writes it, 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.
|
|
94
99
|
|
|
95
100
|
## Hard rules
|
|
96
101
|
|
|
@@ -105,10 +110,14 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
105
110
|
| Skills come from upstream | Install with `npx skills add`, `-g` for user scope; never hand-copy skill files or maintain the links yourself. |
|
|
106
111
|
| 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. |
|
|
107
112
|
| 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. |
|
|
108
|
-
| Write boundary | Only `.sassywares
|
|
113
|
+
| Write boundary | Only `.sassywares/` (the config, the setup README, and the dogfood scaffold), 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/`. |
|
|
109
114
|
| Detect, don't guess | An unknown base branch stays unknown and gets asked about. A probed value is reported as probed. |
|
|
110
115
|
| Comments are part of the file | Every key keeps its description and allowed values. A stripped config is an incomplete config. |
|
|
111
116
|
| Hooks are named, not written | Setup records hook skill names. Creating those skills is the project's work. |
|
|
117
|
+
| Dogfood is a pointer | The block names a recipe, a reports path, a timeout, and whether Auto rows are allowed — four keys. Never a command and never a tool: a copied command duplicates the manifest and cannot express step order. |
|
|
118
|
+
| The recipe is the project's | Setup scaffolds the skeleton and stops. Authoring or "fixing" a procedure is `sassy-dogfood mode:discover`'s job, and a run may never edit the recipe to make its own failure pass. |
|
|
119
|
+
| Reports never ship | `.sassywares/dogfood/reports/` is gitignored by one setup-owned line, `/reports/`. Never remove it, never add anything from it to the commit. |
|
|
120
|
+
| No secrets in setup's writes | Env var names only, in the config and in the skeleton. A credential never lands in a file setup commits. |
|
|
112
121
|
| Repair is `check` | Run against an existing config, setup reports drift — it does not rewrite the file without approval. |
|
|
113
122
|
|
|
114
123
|
## What setup is not
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Dogfood — <project>
|
|
2
|
+
|
|
3
|
+
**Never** production. Local or staging only.
|
|
4
|
+
|
|
5
|
+
**Set up once:** <install, services to start, env files to copy; name variables,
|
|
6
|
+
never values>
|
|
7
|
+
|
|
8
|
+
**Reset:** <back to a known state>
|
|
9
|
+
|
|
10
|
+
<!--
|
|
11
|
+
Incomplete on purpose. sassy-setup writes this skeleton so the shape is visible;
|
|
12
|
+
`sassy-dogfood mode:discover` fills it by trying the product once and writing down
|
|
13
|
+
what actually worked. Until a section has a **Prove it:** step, every QA row stays
|
|
14
|
+
Manual.
|
|
15
|
+
|
|
16
|
+
Rules: steps are ordered and append-only; every step has **Do** and **Expect**;
|
|
17
|
+
one **Prove it:** per section and its exit code is the verdict; env var names
|
|
18
|
+
only; no tool names. Schema: sassy-setup/references/dogfood.md
|
|
19
|
+
-->
|
|
20
|
+
|
|
21
|
+
## <section> — <one line: what this proves>
|
|
22
|
+
|
|
23
|
+
1. **Do** <command or instruction>
|
|
24
|
+
**Expect** <observable, checkable result>
|
|
25
|
+
|
|
26
|
+
2. **Do** <the proving command>
|
|
27
|
+
**Expect** exit 0
|
|
28
|
+
|
|
29
|
+
**Prove it:** step 2 — its exit code is the verdict.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
sassy-babysit
|
|
2
|
+
sassy-commit
|
|
3
|
+
sassy-commit-push-pr
|
|
4
|
+
sassy-compound
|
|
5
|
+
sassy-cycle
|
|
6
|
+
sassy-debug
|
|
7
|
+
sassy-dogfood
|
|
8
|
+
sassy-goal
|
|
9
|
+
sassy-handbook
|
|
10
|
+
sassy-handoff
|
|
11
|
+
sassy-lfg
|
|
12
|
+
sassy-plan
|
|
13
|
+
sassy-review
|
|
14
|
+
sassy-scout
|
|
15
|
+
sassy-setup
|
|
16
|
+
sassy-ship
|
|
17
|
+
sassy-simplify
|
|
18
|
+
sassy-skill
|
|
19
|
+
sassy-validate
|
|
20
|
+
sassy-work
|
|
@@ -71,4 +71,4 @@ mirrored tree. The `sassy-*` skills do their own git and never call them.
|
|
|
71
71
|
|
|
72
72
|
## Hooks
|
|
73
73
|
|
|
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.
|
|
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; `hooks.push` (one point, `after_push`, keyed by the pushed branch) runs there instead, right after a successful push.
|
|
@@ -94,7 +94,7 @@ Only reachable with `policy: current`, which is an explicit statement that
|
|
|
94
94
|
committing on the base branch is intended. Proceed, and say in the run's gate
|
|
95
95
|
summary that the commits are landing on `<head>`. When the config says
|
|
96
96
|
`commit.branch: current`, the close-out commits and pushes `<head>` to its upstream with **no PR** — no
|
|
97
|
-
`sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge. `pr-base` is
|
|
97
|
+
`sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge; only `hooks.push.after_push` runs. `pr-base` is
|
|
98
98
|
irrelevant here. Never infer this from a skill default.
|
|
99
99
|
|
|
100
100
|
### `stop-and-ask`
|