@sassywares/skills 0.6.4 → 0.6.5

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sassywares/skills",
3
- "version": "0.6.4",
3
+ "version": "0.6.5",
4
4
  "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: sassy-commit
3
3
  description: >-
4
- Create a git commit with a clear, value-communicating message. Use when asked
4
+ Create a git commit with a Conventional Commits message that states the outcome. Use when asked
5
5
  to commit or save staged/unstaged changes with a repo-appropriate message.
6
6
  Local commit only — no push, no PR.
7
7
  argument-hint: "[branch:current|new <name>]"
@@ -10,7 +10,7 @@ disable-model-invocation: true
10
10
 
11
11
  # Sassy Commit
12
12
 
13
- **Outcome:** Each logical change committed with an explicit file list and a message stating the outcome, and `git status` clean of those changes.
13
+ **Outcome:** Each logical change committed with an explicit file list and a Conventional Commits message stating the outcome, and `git status` clean of those changes.
14
14
 
15
15
  **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.
16
16
 
@@ -49,11 +49,17 @@ Treat the reads as a snapshot; re-read branch and staged set right before commit
49
49
  - `reuse` — a branch that is not a base. Commit.
50
50
  - `create` — you were told `current` but nothing chose it and this is a base: the caller skipped the branch decision. **Stop and report** — do not commit. A warning inside a subagent's summary has already failed to protect a shared branch once; this is a stop, not a notice.
51
51
  - `stop-and-ask` or `refuse` — report the reason line and stop.
52
- 3. **Convention** — match the project's existing commit style; else the recent log pattern; else conventional commits (`type(scope): description`). When `fix`/`feat` both fit, default to `fix:`.
52
+ 3. **Convention** — [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), always. The project refines it, never replaces it: allowed types, scopes, and case come from its commitlint config, `CONTRIBUTING`, or agent instructions when they exist, and recent history shows which scopes are in use. Only an explicit project rule mandating a different format overrides it — follow that and say so. A non-conventional log is not such a rule.
53
53
  4. **Logical commits** — if changed files clearly split into distinct concerns, make separate commits (file level, 2–3 max, never `git add -p`). If ambiguous, one commit.
54
- 5. **Message** — imperative subject naming the outcome, not the file list. Body only when the motivation is not obvious.
55
- - Bad: `Update checkout.rb`
56
- - Good: `Fix double-submit on checkout`
54
+ 5. **Message** — `<type>[(scope)][!]: <description>`, then an optional body and footers, each after a blank line.
55
+ - **Type** — `feat` (new behavior), `fix` (bug fix), `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`. When `fix`/`feat` both fit, default to `fix`. Split the commit rather than pick a type that hides half of it.
56
+ - **Scope** — optional; the area touched, lowercase, as the project already names it (`checkout`, `api`). Omit rather than invent one.
57
+ - **Description** — imperative, names the outcome rather than the file list, lowercase start, no trailing period, header at most 72 characters.
58
+ - **Body** — only when the motivation is not obvious: why, not what. Wrap at 72.
59
+ - **Breaking change** — `!` before the colon and a `BREAKING CHANGE: <what breaks and how to migrate>` footer.
60
+ - **Footers** — `Refs: #123`, `Closes #123`, `Co-authored-by:` lines go last.
61
+ - Bad: `Update checkout.rb`, `Fix double-submit on checkout`
62
+ - Good: `fix(checkout): prevent double-submit on slow networks`
57
63
  6. **Stage and commit** — stage **named files only** (never `git add -A` or `git add .`). Write the full message to `/tmp/sassywares/<harness>/commits/<UTC timestamp>-<slug>.txt` (directory per the `sassy-setup` skill's `references/harness.md`), then:
58
64
  ```
59
65
  git add file1 file2 file3
@@ -54,9 +54,9 @@ Only an exit-0 empty list means "no open PR". A non-zero exit means **unknown**
54
54
  3. **Pre-push gate** — resolve any pre-push or review-ready requirement from the project's active instructions. Only evidence valid for the exact commit being sent satisfies it; otherwise stop and report what is missing. If none, proceed.
55
55
  4. **Push** — `git push -u origin <branch>` for a new branch, else `git push`. Re-verify branch and remote first, and re-check that the branch is ahead of origin after any hook commits.
56
56
  5. **Compose the PR title and body**
57
- - Title: outcome-stating, concise.
58
- - Body: what changed, why, and how it was verified. Preserve any existing `Related:` / `Fixes` line on an update.
59
- - If no PR exists, compose fresh; if one does, edit its body.
60
- 6. **Apply** — re-check PR presence. With a matching PR: `gh pr edit <url> --body-file <path>`. With none: `gh pr create --base <base> --title <title> --body-file <path>`. Always pass the body via `--body-file`, never stdin, and always name the base. The body file lives in `/tmp/sassywares/<harness>/prs/` (per `references/harness.md`), named `<UTC timestamp>-<branch>.md`.
57
+ - **Title** — a Conventional Commits header, the same rules as `sassy-commit`'s message step, because a squash merge turns it into the commit on the base: `<type>[(scope)][!]: <description>`, at most 72 characters. A single-commit PR reuses that commit's header. A multi-commit PR takes the type of its most significant change (`feat` over `fix` over the rest), and `!` when any commit breaks something.
58
+ - **Body** — use the repo's PR template when one exists: `.github/pull_request_template.md`, `.github/PULL_REQUEST_TEMPLATE.md`, a `.github/PULL_REQUEST_TEMPLATE/` folder (pick the template that fits the change), or the same names at the repo root or under `docs/`. Fill every section; write "N/A" rather than deleting one, and keep its checklists. With no template, use `## Summary` (what changed and why), `## Changes` (the notable ones, as bullets), `## Verification` (how it was tested, the commands and their results), and `## Related` (issues or plan) when there is anything to link. Carry a `BREAKING CHANGE` from the commits into the body. Preserve any existing `Related:` / `Fixes` line on an update.
59
+ - If no PR exists, compose fresh; if one does, edit its body, and its title too when the title is not conventional.
60
+ 6. **Apply** — re-check PR presence. With a matching PR: `gh pr edit <url> --body-file <path>`, adding `--title <title>` when step 5 rewrote the title. With none: `gh pr create --base <base> --title <title> --body-file <path>`. Always pass the body via `--body-file`, never stdin, and always name the base. The body file lives in `/tmp/sassywares/<harness>/prs/` (per `references/harness.md`), named `<UTC timestamp>-<branch>.md`.
61
61
  7. **`after_create` hooks.** Only when this run **created** the PR — an update does not fire them, say so in one line. Same resolution and ordering as step 2, with the PR URL added to the brief. These must leave the tree clean: anything they write is reported, not committed.
62
62
  8. **Babysit** — with `babysit:on` (default), load `sassy-babysit` and follow it for the PR just opened or updated, forwarding `checkpoint`, `merge:`, and `delete-branch:` unchanged. Report the PR URL and the babysit status; for a continuous watch beyond this run, point the user at `sassy-babysit`. With `babysit:off`, report the PR URL only.
@@ -22,26 +22,23 @@ disable-model-invocation: true
22
22
 
23
23
  ## Hard rules
24
24
 
25
- - **Assume nothing.** Your inference is not a decision until the user confirms it. No silent defaults, no "I'll go with X unless you object". A branch is closed only when the user decided it, told you to use your recommendation, or chose to defer it — and each closure is recorded.
26
- - **One question per turn.** Pick the single question whose answer unblocks the most of the tree. Stacked questions get diluted answers.
27
- - **Always recommend.** Every question carries your recommended answer and why, so the user can confirm in one word. Recommending is not deciding.
28
- - **Explore before asking.** If the codebase, config, docs, or a prior learning can answer it, look it up and show the answer with its `file:line` instead of asking. Ask only what the user alone can settle.
29
- - **Push back.** Challenge thin reasoning, contradictions, and unexamined solution shapes with evidence. Disagree when you disagree. Concede only to an argument or to the user's explicit call — never to fatigue.
30
- - **No exit with open branches.** "Settled enough" is not settled. The only exits are a ledger with zero open items or the user explicitly ending the interview, in which case every open item becomes a named, user-acknowledged assumption.
25
+ - **Assume nothing.** Your inference is not a decision until the user confirms it. No silent defaults.
26
+ - **One question per turn, always with your recommended answer.** Recommending is not deciding.
27
+ - **Explore before asking.** What the repo can answer, look up and cite.
28
+ - **Push back** with evidence. Concede to an argument or the user's explicit call, never to fatigue.
29
+ - **No exit with open branches.** Only a ledger with zero open items, or the user explicitly ending the interview, reaches the picker.
31
30
 
32
31
  ## Phase A — Grill
33
32
 
34
- **Read `references/interview.md` first.** It is the decision-tree protocol, the pushback lenses, the coverage sweep, and the ledger format; this section is only the order.
33
+ **Read `references/interview.md` first.** It owns the ledger, how to ask, the pushback lenses, the coverage sweep, and the read-back; this is only the order.
35
34
 
36
- 1. **Frame.** Restate the goal in one or two sentences and ask the user to confirm or correct it. Ask what they are already thinking before offering your own ideas.
37
- 2. **Ground.** Use `sassy-scout` to ground the area: relevant files, existing patterns, prior art, and prior learnings. It writes a grounding brief and returns a gist plus the brief path; do not read the whole repo yourself. A relevant learning is a constraint — record it as a decision (`D3: …`) so the plan cites it; one that contradicts the user's direction is a pushback, raised now.
38
- 3. **Map the tree.** Lay out the decision tree — every branch you can see, in dependency order — as the open ledger, and show it. The user can add, cut, or reorder branches.
39
- 4. **Walk it.** Resolve branches one question per turn, parents before children. Each answer can open new branches; add them to the ledger as they appear. Apply the pushback lenses as gaps show up, not as a gauntlet.
40
- 5. **Approaches.** When a branch has more than one plausible direction, present 2–3 concrete approaches — at least one non-obvious — with trade-offs, all before your recommendation.
41
- 6. **Sweep.** Before declaring anything settled, run the coverage sweep: flows, states, edge and failure paths, permissions, data, integration seams, rollout, verification. Every item ends decided or marked not applicable with a reason. Then run the integration check for consequences of decisions combined.
42
- 7. **Read back.** Show the full ledger — decisions with provenance, constraints, non-goals, deferred items, assumptions — and ask the user to confirm it is complete and correct. A correction reopens that branch.
35
+ 1. **Frame.** Restate the goal in one or two sentences; ask the user to confirm or correct it, and what they are already thinking.
36
+ 2. **Ground.** Use `sassy-scout` on the area; it returns a gist and a brief path. A relevant prior learning becomes a decision the plan cites, or a pushback if it contradicts the user's direction.
37
+ 3. **Map.** Show the decision tree as the open ledger, in dependency order. The user can add, cut, or reorder.
38
+ 4. **Walk.** Resolve branches parents first, adding new ones as answers open them. Where a branch has several plausible directions, present 2–3 approaches — one non-obvious — before recommending.
39
+ 5. **Sweep and read back.** Run the coverage sweep and integration check, then the read-back.
43
40
 
44
- **UI work.** When a decision is about layout, navigation, states, flow, or interaction shape and the user asks to see it, read `references/sketches.md` and draw it. Say once, at the first such decision, that a sketch is available.
41
+ **UI work.** At the first layout, state, flow, or interaction-shape decision, say once that you can sketch it; when the user asks, read `references/sketches.md`.
45
42
 
46
43
  ## The picker
47
44
 
@@ -76,4 +73,4 @@ The plan document carries manual QA tables per `references/plan-format.md`. Thos
76
73
 
77
74
  If the user points at an existing sassy plan, update phases and tables in place. If they point at a raw plan from elsewhere, reshape it into this format without discarding its settled decisions — but grill whatever it leaves open or merely asserts. An existing plan is already the document.
78
75
 
79
- Decisions the user already made earlier in the conversation, with the trade-off in view, are settled: carry them forward and never re-ask. A bare assertion nobody examined gets exactly one challenge per `references/interview.md`.
76
+ Decisions already settled earlier in the conversation carry forward per `references/interview.md`; never re-ask them.
@@ -33,7 +33,7 @@ Every item closes into exactly one bucket, with provenance:
33
33
  | `user-deferred` | The user chose to decide later. Lands in Deferred, with when or by whom. |
34
34
  | `from code` | The repo answered it. Cite `file:line`. Shown to the user, never closed off-screen. |
35
35
 
36
- Nothing you inferred alone gets a label. "Sounds good" to a passing mention is at most `user-approved`, never `user-directed`. If you cannot name what an item was chosen over, it was not examined — it is still open.
36
+ Decisions the user made earlier in the conversation with the trade-off in view enter the ledger as settled, with their provenance — never re-ask them. Nothing you inferred alone gets a label. "Sounds good" to a passing mention is at most `user-approved`, never `user-directed`. If you cannot name what an item was chosen over, it was not examined — it is still open.
37
37
 
38
38
  ## Asking
39
39