@jesdi/skills 0.0.23 → 0.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "description": "jesdi's agent skills (content package consumed by @jesdi/skills-cli)",
   "license": "MIT",
   "repository": {

package/skills/implement-spec/SKILL.md

@@ -15,7 +15,8 @@ a per-ticket gate (check command + crap-gate) before DONE, re-run by the reviewe
 already-green locked tests need a demonstrated mutation; a Codex correctness
 pass per risky ticket; tickets touching the same functions run in sequence;
 check command after each merge; final /review-diff on the most capable model, one
-fixer; closes tickets only if they are issues. Review loop and ledger adapt
+fixer; closes tickets only if they are issues; no push and no PR until every
+ticket is merged and the final review has passed. Review loop and ledger adapt
 superpowers' subagent-driven-development (obra/superpowers, MIT).
 -->
 
@@ -41,7 +42,10 @@ Run ticket subagents in the background where possible for **maximum concurrency*
 
 2. Create a notes directory outside the repo, readable by all subagents, and start the ledger there. (optional) An **exploration subagent** saves its notes on relevant code and docs there, so implementers focus on implementation.
 
-3. Create a branch, and a draft PR. If the spec and tickets are issues, mark the PR as 'closing' them.
+3. Create the PR branch locally. Do **not** push it and do **not** open a PR yet: nothing leaves the
+   machine until every ticket is merged and the final review has passed (step 10). Intermediate
+   states (red tests, half-merged tickets) are never pushed. If the spec and tickets are issues,
+   note their numbers in the ledger so the PR can close them later.
 
 4. Each ticket gets its own worktree and branch. For a ticket with behavioral criteria, a **test-writer subagent** goes first. It sees ONLY the spec, the ticket, CONTEXT.md/ADRs and the public interface of the ticket's **Seam** line (pointers, not summaries), never the implementer's plan or code. It writes one black-box acceptance test per criterion through that interface (defining the interface if it doesn't exist yet), confirms each fails for the right reason (missing behavior, not an import or syntax error), commits them red, and reports the SHA and files. A test that is already green before any implementation is vacuous until proven otherwise (an earlier guard or early return often satisfies it for an unrelated reason): the test-writer rewrites it to fail, or, when the criterion truly holds already, reports the production-code mutation that turns it red and the red output. Those files are now **locked**. A ticket with no behavioral criteria (Seam: `none — refactor`) skips this: its existing tests are the contract, unmodified.
 
@@ -59,6 +63,8 @@ Run ticket subagents in the background where possible for **maximum concurrency*
 
 9. Once all tickets are complete, a reviewer on the most capable model runs /review-diff on the PR branch, given the ledger's minor findings and rulings. One **implementer subagent** fixes every finding, then re-review that fix once. Rule on anything left.
 
-10. Mark the PR as ready for review. List every ruling from the ledger in your final message.
+10. Now, and only now, push the PR branch once and open the PR, ready for review (not draft). If the
+    spec and tickets are issues, mark the PR as 'closing' them. List every ruling from the ledger in
+    your final message.
 
 11. Clean up all ticket worktrees.

package/skills/pr-visual-diff/SKILL.md

@@ -6,7 +6,8 @@ description: Capture before/after screenshots of UI views with Playwright and em
 # PR Visual Diff
 
 Produce before/after screenshots of the views affected by a branch's frontend
-changes, commit them on the PR branch, and embed them in the PR body. Reviewers
+changes, push them to a hidden ref (never the PR branch), and embed them in the
+PR body. Reviewers
 should see what changed visually without checking out the branch.
 
 The approach leans on the project's existing Playwright e2e harness with the
@@ -44,7 +45,6 @@ file as JSON:
 | `deviceProjects` | the config's `projects` (default to a desktop + a mobile project) |
 | `baseBranch` | the repo's default branch (`main`/`master`; `git symbolic-ref refs/remotes/origin/HEAD`) |
 | `packageManager` | infer from lockfile: `pnpm-lock.yaml`→pnpm, `package-lock.json`→npm, `yarn.lock`→yarn, `bun.lockb`→bun |
-| `screenshotDir` | default `docs/pr-screenshots` |
 | `spinnerSelector` | the app's loading-indicator selector (search for a spinner/`role="status"`/`aria-busy` component) |
 
 ### Preconditions gate
@@ -66,14 +66,14 @@ screenshots.
 ## Always run the capture in a subagent
 
 Steps 2–6 (writing the spec, capturing, **reading every PNG back to eyeball
-it**, committing, embedding) MUST run inside a single dispatched subagent — not
+it**, pushing them to the hidden ref, embedding) MUST run inside a single dispatched subagent — not
 in the main context. Reading screenshots back is this skill's dominant token
 cost, and those image bytes are worthless to the main thread; keeping them in a
 subagent's throwaway context is the whole savings, with no loss of verification.
 
 Main context does only: step 1 (map the diff, get the user's go-ahead), then
 dispatch a subagent with the plan and the config values. The subagent returns a
-compact report: the committed screenshot paths + pinned URLs, the PR-body
+compact report: the screenshot file names + pinned URLs, the PR-body
 markdown, and any views it flagged. The main context creates/edits the PR from
 that report — it never reads a PNG.
 
@@ -88,11 +88,11 @@ make it visible (open a modal, select a tab). Classify each view as **changed**
 (existed at the merge base) or **new** (introduced by this branch) — new ones
 get an after-only shot.
 
-This capture is heavy (temp worktree, two Playwright passes, a commit pushed to
-the branch, PR body rewritten). ALWAYS confirm with AskUserQuestion before
+This capture is heavy (temp worktree, two Playwright passes, images pushed to a
+hidden ref, PR body rewritten). ALWAYS confirm with AskUserQuestion before
 running any of it. The question must cover **both** (a) whether to run the whole
-before/after capture at all, and (b) that it will commit the screenshots and
-embed them in the PR. Include the proposed plan: which routes/states, and which
+before/after capture at all, and (b) that it will push the screenshots to a
+hidden ref on the remote and embed them in the PR. Include the proposed plan: which routes/states, and which
 device projects — default to the config's `deviceProjects`; add more only when
 the change is layout-sensitive. If they decline, create the PR normally and stop.
 
@@ -167,24 +167,43 @@ Remove the worktree when done:
 `git worktree remove --force <scratchpad>/pr-before-shots` (`--force` because
 install left untracked artifacts).
 
-### 5. Commit the images on the PR branch
+### 5. Push the images to a hidden ref
 
+The images must never land on the PR branch: once merged they would sit in the
+base branch's history forever and every clone would download them. Instead,
+build an orphan commit that holds only the PNGs and push it to a ref outside
+`refs/heads/*`, which clones and fetches never transfer (GitHub's own
+`refs/pull/*` works the same way). The working tree, the index and the PR
+branch are not touched.
+
+Collect the shots you'll reference into one flat directory, named
+`<view>--<project>--{before|after}.png`, then:
+
+```bash
+SLUG=$(git branch --show-current | tr / -)
+TREE=$(for f in <scratchpad>/shots/*.png; do
+  printf '100644 blob %s\t%s\n' "$(git hash-object -w "$f")" "$(basename "$f")"
+done | git mktree)
+SHA=$(git commit-tree "$TREE" -m "pr-screenshots: ${SLUG}")
+git push origin "${SHA}:refs/pr-screenshots/${SLUG}/${SHA}"
 ```
-<screenshotDir>/<branch-slug>/<view>--<project>--{before|after}.png
-```
 
-`<branch-slug>` = branch name with `/` → `-`. Keep only the shots you'll
-reference. Commit them, delete the temp spec, and push.
+Keep the braces in `${SHA}:` — zsh reads a bare `$SHA:r` as a modifier and
+mangles the refspec. Each capture gets its own ref (the commit SHA is part of
+the name), so a re-capture never needs a force push, two machines never
+collide, and URLs from earlier captures keep working. Never delete these refs:
+they are what keeps the images alive on GitHub.
+
+Delete the temp spec. Nothing from this skill is committed to the PR branch.
 
 ### 6. Embed in the PR body
 
-After pushing, pin image URLs to the exact commit so they keep rendering after
-later force-pushes or branch deletion:
+Pin image URLs to the orphan commit; they render regardless of what happens to
+the PR branch:
 
 ```bash
-SHA=$(git rev-parse HEAD)
 REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
-# → https://github.com/$REPO/blob/$SHA/<screenshotDir>/<slug>/<file>.png?raw=true
+# → https://github.com/$REPO/blob/$SHA/<file>.png?raw=true
 ```
 
 Per view, one table. Put **Before on the left and After on the right** (one
@@ -201,12 +220,11 @@ side:
 ```
 
 If the repo is private, GitHub's image proxy may refuse to inline blob URLs in
-the PR body. Add a one-line note under the tables linking to the
-`<screenshotDir>/<slug>/` directory on the branch as a fallback — the images
-always render in the Files-changed tab and in blob view for authenticated
-viewers.
+the PR body. Add a one-line note under the tables linking to the orphan
+commit's tree (`https://github.com/$REPO/tree/$SHA`) as a fallback — the images
+always render there for authenticated viewers.
 
-The subagent's job ends here: it has pushed the commit and produced the PR-body
+The subagent's job ends here: it has pushed the hidden ref and produced the PR-body
 markdown, and returns both. The **main context** creates (or edits) the PR with
 that body, then opens it (`gh pr view --web`) so the user can confirm the embeds
 render.

package/skills-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-30T22:33:10.162Z",
+  "generatedAt": "2026-10-01T01:49:46.043Z",
   "skills": [
     {
       "name": "backlog",
@@ -46,14 +46,14 @@
     },
     {
       "name": "implement-spec",
-      "version": "0.1.4",
-      "hash": "sha256-2912e2fef79d278bb7c59bd72e9d3705cfe4597f20c95fd8f839604cc7cd4ea0",
+      "version": "0.1.5",
+      "hash": "sha256-43b1b1b97386b96b2cc8124ca906ffc0a5a4b35362413b52ac154c1faaa0b43e",
       "description": "Implement a specification in code."
     },
     {
       "name": "pr-visual-diff",
-      "version": "0.1.0",
-      "hash": "sha256-4e386dd175a34e55e89e0e29e37f5d0afd927560b7e3ba4c5f3ef482fb73f722",
+      "version": "0.1.1",
+      "hash": "sha256-c90f308a7529ead883b4c379d034724a33da43e91f2d8ba0f2bdc5d79c894df2",
       "description": "Capture before/after screenshots of UI views with Playwright and embed them in a PR. Use this skill whenever creating or preparing a pull request that touches frontend code (components, views, styles, layout, Tailwind classes) — even if the user just says \"open a PR\" or \"create the PR\" after UI work, and especially if they mention screenshots, visual diff, before/after, or \"show what changed\". Also use when the user asks to add screenshots to an existing PR."
     },
     {