@sassywares/skills 0.7.0 → 0.7.2

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.7.0",
3
+ "version": "0.7.2",
4
4
  "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -41,11 +41,13 @@ Snapshot the PR state first, then act in this order:
41
41
 
42
42
  1. **Terminal** — `MERGED`/`CLOSED` → if it is `MERGED` and `after_merge` resolves for this PR's head, run those hooks once (see Step 3) before stopping.
43
43
  2. **Capture the head SHA** — a later push invalidates this snapshot's CI.
44
- 3. **Feedback before CI** — fetch open review threads (`gh pr view --json reviewThreads,comments`). Address each actionable thread: reply, then fix. Use `sassy-debug` for a real defect. Never wait for a reviewer who is "still reviewing" before acting on feedback already posted.
44
+ 3. **Feedback before CI** — fetch open review threads (`gh pr view --json reviewThreads,comments`). Fix every actionable thread (see **Fixing** below), then reply on each with what changed and the commit. A thread that is not actionable gets a reply saying why. Never wait for a reviewer who is "still reviewing" before acting on feedback already posted.
45
45
  4. **Stale-SHA cancellation** — if the head moved since step 2, skip the CI work for this snapshot.
46
- 5. **CI** — `gh pr checks`. One pass for all failures. Flaky/infra → `gh run rerun <run-id> --failed`. Real failure → fix it (via `sassy-debug`). Mark each check handled; unfixed checks stay red.
46
+ 5. **CI** — `gh pr checks`. One pass for all failures. Flaky/infra → `gh run rerun <run-id> --failed`. Real failure → fix it (see **Fixing**). Mark each check handled; unfixed checks stay red.
47
47
  6. **Branch currency** — if the branch is `BEHIND` or `DIRTY`, update it (`gh pr update-branch <ref>`, or ask for a local rebase). Do not update just because the base moved; only when the status actually requires it.
48
48
 
49
+ **Fixing.** Load the `sassy-cycle` skill on rework with the threads and failing checks as findings and the PR's changed files as the scope hint; it fixes and verifies, at most two passes. Then load `sassy-commit` with `branch:current` and `git push`. A finding the cycle leaves open, or a failure you cannot diagnose from the log and the diff, is `needs-human`. Never load `sassy-debug` or `sassy-ship` from here — they commit, open PRs, and babysit on their own, which nests a second watch over this PR.
50
+
49
51
  After a tick with no true stop, wait and run the next tick. Checkpoint mode: run one tick and report paused with the resume command.
50
52
 
51
53
  ## Step 3 — Stop conditions
@@ -2,7 +2,7 @@
2
2
  name: sassy-commit-push-pr
3
3
  description: >-
4
4
  Commit, push, and open a PR, then babysit it by default. Use when asked to
5
- ship/open a PR, or for a PR-description-only flow (writing, rewriting, or
5
+ open or update a PR, or for a PR-description-only flow (writing, rewriting, or
6
6
  describing a PR body).
7
7
  argument-hint: "[PR ref] [branch:new|current] [base:<branch>] [babysit:on|off] [checkpoint] [merge:on|off] [delete-branch:on|off]"
8
8
  disable-model-invocation: true
@@ -13,7 +13,7 @@ disable-model-invocation: true
13
13
 
14
14
  **Outcome:** a grounding brief on disk for the area you asked about, and a 3–5 line gist back in this context. Nothing else.
15
15
 
16
- **Orchestrator only.** Do not read the repo yourself. One `scout` dispatch per independent area, in parallel when the areas do not overlap.
16
+ **Orchestrator only.** Do not read the repo yourself. One `scout` dispatch per run: the brief is one file per worktree, so a second scout replaces the first one's brief. When several areas matter, scope them into that one dispatch.
17
17
 
18
18
  **Harness.** Loading another skill, dispatching an agent, and any command you hand the user follow the `sassy-setup` skill's `references/harness.md`. Read it once per run, before the first of those.
19
19
 
@@ -26,7 +26,7 @@ disable-model-invocation: true
26
26
 
27
27
  ## Workflow
28
28
 
29
- 1. **Scope.** Reduce the request to one question the brief will answer, in one line. If it is really two questions, use two dispatches.
29
+ 1. **Scope.** Reduce the request to the question the brief will answer, in one line — naming every area downstream needs, since there is only one brief.
30
30
  2. **Dispatch `scout`** with that scope, what the caller intends to do with it, and the paths or areas you already suspect. The brief also carries matching docs from the project's knowledge paths (`knowledge.read` in `.sassywares/config.yaml`, nearest walking up) — pass that section on to the caller rather than dropping it.
31
31
  3. **Keep the gist.** Read the returned gist; do not pull the brief's bulk into this context.
32
32
  4. **Report the brief path** to the caller, so downstream agents read it instead of scouting again.
@@ -50,7 +50,7 @@ It is fresh only while its `head` and `dirty` lines match the working tree. Afte
50
50
 
51
51
  | Rule | Requirement |
52
52
  |------|-------------|
53
- | One question | A brief answers one scoped question. Split, do not sprawl. |
53
+ | One brief | One dispatch, one brief per worktree. Cover every area the work needs in its scope; never run scouts side by side. |
54
54
  | Gist only | Return the gist and the brief path. Never paste the brief. |
55
55
  | No edits | Scouting is read-only. It never changes code or commits. |
56
56
  | Learnings are listed, not judged | Prior learnings come back as path and title. The consumer decides whether one applies; scout never ranks or recommends them. |
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  name: sassy-skill
3
3
  description: >-
4
- Create, retune, or improve an Agent Skill. Asks where the skill should live —
5
- inside this suite, in a project, or for one user — then writes it there with
6
- the rules and release steps that location requires. Use when asked to create a
4
+ Create, retune, or improve an Agent Skill for the user. Places it in the
5
+ project (preferred) or the user's own skills, asking when it can't infer
6
+ which, then writes it there with the rules that location requires. Use when asked to create a
7
7
  skill, turn a workflow into a skill, fix a description or triggering,
8
8
  restructure a bloated skill, or retune an existing one.
9
9
  argument-hint: "[mode:create|retune|verify] [name, idea, or skill path]"
@@ -16,7 +16,7 @@ disable-model-invocation: true
16
16
 
17
17
  **Modes.** `mode:create` writes a new skill. `mode:retune` changes the smallest thing that fixes a named failure in an existing skill. `mode:verify` checks an existing skill against the checklist and reports — it edits nothing. Omitted, detect it from the argument: something that already resolves to a skill directory is `retune`, or `verify` when the user only asked whether it is any good; anything else is `create`. State the mode you picked and why; when both are plausible, ask instead of guessing.
18
18
 
19
- **Locations are not interchangeable** — they decide who gets the skill, how it ships, and what it may be called. Ask before writing.
19
+ **Locations are not interchangeable** — they decide who gets the skill and what it may be called. Infer it when the request makes it clear; otherwise ask, recommending the project.
20
20
 
21
21
  **Scope:** skills only — not extensions, packages, or prompt templates.
22
22
 
@@ -50,17 +50,16 @@ The suite targets the **Agent Skills specification** (agentskills.io), so a skil
50
50
 
51
51
  ## Where the skill lives
52
52
 
53
- Ask which one, unless the request already made it obvious. The answer changes the name, the sharing, and whether a release is needed.
53
+ Infer it when the request makes it obvious; otherwise ask, recommending **project**. The answer changes the name and who gets it.
54
54
 
55
55
  | Location | Path | Who gets it | Extra work |
56
56
  |---|---|---|---|
57
- | **Internal** — part of this suite | `skills/<name>/` in the sassy-skills repo | Everyone, once pushed to `main` | Name it `sassy-<name>`, run `scripts/sync.sh` — it bumps the patch version, tags, and publishes |
58
57
  | **Project** — team workflow | `<repo>/.agents/skills/<name>/` | Everyone who clones that repo | Commit it; prefix the project (`tap2-…`) so it can't collide with a suite skill or a harness built-in |
59
58
  | **User** — personal workflow | `~/.agents/skills/<name>/` | Only this person, every repo on this machine | None — but nothing gates it either; never put something a teammate needs here |
60
59
 
61
- Recommend by audience: the team needs it → **project**; only the requester → **user**; it belongs to every project using this suite → **internal**.
60
+ Recommend by audience: the team needs it, or the audience is unclear → **project**; only the requester → **user**.
62
61
 
63
- Internal is the only one that ships to everyone. Never choose it silently: once it lands on `main`, every consumer gets it on their next `npx skills update`. Say that out loud when you do.
62
+ Never prefix a skill `sassy-`: that namespace belongs to the suite, and a matching name collides with it.
64
63
 
65
64
  Paths in the table are the defaults. `.agents/skills/` is read by pi and others; Claude Code reads only `.claude/skills/` (project) and `~/.claude/skills/` (user), so a hand-placed skill there also needs a link in those directories — `npx skills add` creates them for installed skills. Harnesses also read `skills` arrays in settings and installed packages, so a skill may live elsewhere — write down where it actually went.
66
65
 
@@ -98,10 +97,9 @@ The gate for a new or edited skill, and the instrument in `mode:verify`.
98
97
 
99
98
  | Rule | Requirement |
100
99
  |------|-------------|
101
- | Ask before writing | The location — internal, project, or user — is the user's call, never the cwd's. State the mode you inferred. |
100
+ | Location is clear before writing | Project or user — inferred from the request, never from the cwd alone; ask when unclear, recommending project. State the mode and location you picked. |
102
101
  | Verify writes nothing | `mode:verify` ends with a report. If you spot a fix while verifying, name it and let the user ask for the retune. |
103
102
  | Retune is minimal | One named failure, the smallest change that kills it. No drive-by rewrites, no tidy-ups nobody asked for. |
104
103
  | Split by outcome | Divergent paths get their own reference even when tiny; shared surfaces stay in the body. |
105
104
  | Name skills, not paths | Reference another skill by name so the suite stays portable across install locations. |
106
- | Internal is a release | Putting a skill in the suite ships it to every consumer on `main`. Never choose it silently. |
107
105
  | Nothing untestable | No secrets, and no capability the skill cannot actually perform. |
@@ -8,7 +8,7 @@ Settle three things by asking, not inferring:
8
8
 
9
9
  - **What it does** — the one outcome, stated as a result ("a merged PR", "a filed ticket", "a plan on disk"), not as an activity.
10
10
  - **When it fires** — the words a user will actually say. These become the description's *when* half.
11
- - **Where it lives** — internal, project, or user, per the location table. Ask; the cwd proves nothing.
11
+ - **Where it lives** — project or user, per the location table. Infer it from the request; when unclear, ask and recommend the project. The cwd alone proves nothing.
12
12
 
13
13
  If any of the three is missing, ask before writing a file. A skill authored on a guess is the one that gets retuned next week.
14
14
 
@@ -41,7 +41,6 @@ Plain English, no filler. Where the skill returns a result, give the shape of th
41
41
 
42
42
  ## 5. Place and install
43
43
 
44
- - **Internal:** `skills/<name>/` in the sassy-skills repo, named `sassy-<name>`; then `scripts/sync.sh` — it commits, bumps the patch version, tags, and publishes. Say that this ships to everyone before you do it.
45
44
  - **Project:** `<repo>/.agents/skills/<name>/`, prefixed with the project so it cannot collide with a suite skill or a harness built-in; then commit it.
46
45
  - **User:** `~/.agents/skills/<name>/` (plus a `~/.claude/skills/<name>` link for Claude Code). Nothing gates it, so check it actually works before trusting it.
47
46
 
@@ -15,7 +15,7 @@ Read the skill and say which of these it is, in one line. "It feels long" is not
15
15
  | **One path's rules bleed into another's** (a mode doing the neighbouring mode's job) | A shape bug, not a wording bug: split the divergent outcomes into `references/`, one file per path, and give the body a dispatch table naming exactly one file per mode. Rewording the paragraph does not fix adjacency. |
16
16
  | **Too long / bloated** | Extract conditional content to `references/`, or delete what never gets used. Never delete a hard rule to save lines. |
17
17
  | **Wrong or stale steps** | Correct the workflow against the current tree — read the files the steps name before trusting them. |
18
- | **Wrong scope** | Move it between internal, project, and user. Moving into the suite is a release; moving out means the next release drops the skill for everyone. |
18
+ | **Wrong scope** | Move it between project and user: into the project when the team needs it, out to the user when only one person does. |
19
19
  | **Oversplit** (five topic files, vague routing) | Fold shared surfaces back into the body and keep one reference per outcome. |
20
20
 
21
21
  If the request names no failure, ask for one. A retune without a failure is a rewrite with extra steps.
@@ -26,8 +26,7 @@ If the request names no failure, ask for one. A retune without a failure is a re
26
26
  - Re-read the surrounding lines so the fix does not contradict a rule elsewhere in the file.
27
27
  - If the fix moves content into `references/`, the body must dispatch to it by name and say to read only that one.
28
28
 
29
- ## 4. Ship and re-verify
29
+ ## 4. Save and re-verify
30
30
 
31
- - Internal skill → `scripts/sync.sh` (commit, bump, tag, publish; say so before running it).
32
- - Project or user skill → committed or written in place, as its location requires.
31
+ - Project skill → commit it. User skill → it is written in place.
33
32
  - Then run the skill's Verification section: reload, no load warning, invoking it behaves. A retune that was never invoked has not been verified.
@@ -8,7 +8,7 @@ Read the skill's shared sections first (locations, Agent Skills rules, shape rul
8
8
 
9
9
  - `SKILL.md`, then every file under `references/` — you cannot judge routing without seeing what it routes to.
10
10
  - Check the frontmatter parses and the directory name matches `name`.
11
- - If it ships from the suite or a package, note the pinned version: verification is against what consumers actually got.
11
+ - If it was installed from a package or another repo, note the pinned version: verification is against what was actually installed.
12
12
 
13
13
  ## 2. Run the checklist
14
14