@jesdi/skills 0.0.24 → 0.0.26

package/package.json

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

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/to-openspec/SKILL.md

@@ -2,10 +2,12 @@
 name: to-openspec
 description: >-
   Turn settled discovery notes and a sketched data model into a spec folder
-  in openspec shape (proposal, spec, design, tasks) under specs/<slug>/.
-  Runs in two stages with a human review between them. No interview, just
-  synthesis of decisions already made. Trigger on "write the spec",
-  "to-openspec", or "/to-openspec <slug> [stage 2]".
+  in openspec shape (proposal, spec, design) under specs/<slug>/, plus ticket
+  files under .agent/tickets/ that implement-spec runs directly. Two stages:
+  stage 1 alone by default, with a human review before stage 2, or both at
+  once with "all". No interview, just synthesis of decisions already made.
+  Trigger on "write the spec", "to-openspec", or
+  "/to-openspec <slug> [stage 2 | all]".
 ---
 
 # To openspec
@@ -21,13 +23,16 @@ instead of inventing it. Never invent prices, policies, deadlines, or permission
   conversation.
 - Shape: read every file in the repo's `specs/_template/`, or in this skill's `templates/` when
   the repo has none. Keep the headings exactly; write "None." rather than dropping a section.
+  Ignore a `tasks.md` template: tickets replace it.
 - Check command: the one the repo documents (`make check`, or what AGENTS.md names).
+- Stages: no argument runs stage 1 and stops. `stage 2` runs stage 2 only. `all` runs both
+  without the stop in between.
 
 ## Stage 1: what and why
 
 Write `specs/<slug>/proposal.md` and `specs/<slug>/spec.md`.
 
-- **Goal** is one or two sentences. Every later task links back to it.
+- **Goal** is one or two sentences. Every ticket serves it.
 - **Non-goals** carry over every "later" or "never" verdict from discovery.
 - **Requirements** cover the v1 slice only: the smallest set that meets the goal. Each one is
   testable and maps to at least one scenario.
@@ -35,13 +40,14 @@ Write `specs/<slug>/proposal.md` and `specs/<slug>/spec.md`.
   Every invariant (overselling, expiry, refund permissions, and so on) gets a scenario for the
   boundary and one for the violation.
 
-Then **stop**. Print the requirement list and any open questions so the human can cut or correct
-the spec before the design is written. Don't write code.
+Then **stop**, unless invoked with `all`. Print the requirement list and any open questions so
+the human can cut or correct the spec before the design is written. Don't write code.
 
 ## Stage 2: how
 
-Run only when asked (for example "/to-openspec <slug> stage 2"), after the human has reviewed
-stage 1. Re-read `proposal.md` and `spec.md` first; the human may have edited them.
+Run only when asked: "/to-openspec <slug> stage 2" after the human has reviewed stage 1, or
+`all` straight after stage 1. On `stage 2`, re-read `proposal.md` and `spec.md` first; the
+human may have edited them.
 
 1. Run the `red-team-data-model` skill against the data model. Print the top 5, and its identity
    inventory when the change widens a key; don't write them to a file.
@@ -50,23 +56,24 @@ stage 1. Re-read `proposal.md` and `spec.md` first; the human may have edited th
    - **Data model**: every invariant a DB constraint can enforce (`CHECK`, `UNIQUE`, `NOT NULL`,
      FK, conditional `UPDATE ... WHERE`) goes in the table, not only in app code.
    - **Identities**: when the change widens a key, every item of the red-team's identity
-     inventory, marked covered (task IDs filled in step 3) or out of scope (why). Otherwise "None." Add the
+     inventory, marked covered (ticket numbers filled in step 3) or out of scope (why). Otherwise "None." Add the
      heading when the repo's template lacks it.
    - **Seams**: the endpoint, function, or command the tests drive through, marked existing or
      new. Prefer one high seam.
    - No implementation code anywhere in the spec folder. `implement-spec`'s test-writer reads it
      and must not know the solution. A decision's shape (a type, a schema, a state machine, a
-     seam's signature) may appear; the function bodies that make the tasks pass may not.
-3. Write `specs/<slug>/tasks.md`: vertical slices, each small enough for one commit and one green
-   check command. Tests come first in each slice.
-   - Every task has its `_Goal:_` line, its **Seam** (one of the seams from `design.md`, precise
-     enough to write a black-box test against) and its **Blocked by** (task IDs, or none). That
-     makes the list a task graph `implement-spec` can run directly.
+     seam's signature) may appear; the function bodies that make the tickets pass may not.
+3. Run the `to-tickets` skill on `specs/<slug>/`, skipping its quiz (step 4): it writes
+   `.agent/tickets/<NN>-<slug>.md`, the task graph `implement-spec` runs directly. Don't write a
+   `tasks.md`. On top of its rules:
+   - Every scenario in `spec.md` is an acceptance criterion of some ticket.
+   - Each ticket's **Seam** is one of the seams from `design.md`.
    - A slice adds only the tables and columns its own scenarios need, not the whole model up front.
-   - No standalone "run the checks" task: every task already ends with the check command green.
-   - Then fill the task IDs into `design.md`'s **Identities**: every identity marked covered names
-     the task that rekeys it. A covered identity with no task is a missing task; add it.
+   - No standalone "run the checks" ticket: every ticket already ends with the check command green.
+   - Then fill the ticket numbers into `design.md`'s **Identities**: every identity marked covered
+     names the ticket that rekeys it. A covered identity with no ticket is a missing ticket; add it.
 
-Print the task list, then **Open questions**: every red-team finding the design leaves
+Print the ticket list (number, title, blocked by, seam, touches), then **Open questions**: every
+red-team finding the design leaves
 unresolved, and every input the design assumes but the sources don't provide. Then stop. Don't
 write code.

package/skills/to-openspec/templates/design.md

@@ -17,10 +17,10 @@ Tables/fields touched or added, and the invariants that go in DB constraints (no
 ## Identities
 
 When this change widens a key, each identity built from the old key (file names, hashes,
-dedupe keys, command args, dict keys): covered by which task, or out of scope and why. Otherwise
+dedupe keys, command args, dict keys): covered by which ticket, or out of scope and why. Otherwise
 "None."
 
-- `<identity>` — covered by <task> | out of scope: <why>.
+- `<identity>` — covered by <ticket> | out of scope: <why>.
 
 ## Seams
 

package/skills/to-openspec/templates/proposal.md

@@ -10,8 +10,7 @@ The actor(s) this serves (e.g. customer, staff, owner).
 
 ## Goal
 
-What "done" looks like for this slice. One or two sentences — this is what every task links back
-to.
+What "done" looks like for this slice. One or two sentences — this is what every ticket serves.
 
 ## Non-goals
 

package/skills-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-30T22:48:58.981Z",
+  "generatedAt": "2026-10-02T10:20:34.972Z",
   "skills": [
     {
       "name": "backlog",
@@ -52,8 +52,8 @@
     },
     {
       "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."
     },
     {
@@ -76,9 +76,9 @@
     },
     {
       "name": "to-openspec",
-      "version": "0.1.2",
-      "hash": "sha256-80d168bfb69993b2977f6b6bcec9657e020f79e7cd61347a0f514755014e4c38",
-      "description": "Turn settled discovery notes and a sketched data model into a spec folder in openspec shape (proposal, spec, design, tasks) under specs/<slug>/. Runs in two stages with a human review between them. No interview, just synthesis of decisions already made. Trigger on \"write the spec\", \"to-openspec\", or \"/to-openspec <slug> [stage 2]\"."
+      "version": "0.1.3",
+      "hash": "sha256-fa982c0960a4b07d6ec9c54076f831c1fb16a4e46b8ddd62acf86e5316345be7",
+      "description": "Turn settled discovery notes and a sketched data model into a spec folder in openspec shape (proposal, spec, design) under specs/<slug>/, plus ticket files under .agent/tickets/ that implement-spec runs directly. Two stages: stage 1 alone by default, with a human review before stage 2, or both at once with \"all\". No interview, just synthesis of decisions already made. Trigger on \"write the spec\", \"to-openspec\", or \"/to-openspec <slug> [stage 2 | all]\"."
     },
     {
       "name": "to-spec",

package/skills/to-openspec/templates/tasks.md

@@ -1,9 +0,0 @@
-# <Feature title> — Tasks
-
-Each task links to the goal in proposal.md. Work the frontier (tasks whose blockers are done);
-commit per task with its ID.
-
-- [ ] **T1** — <task>. _Goal: <one line, why this task serves proposal.md's goal>._
-  Seam: <endpoint / function / command from design.md>. Blocked by: none.
-- [ ] **T2** — <task>. _Goal: ..._
-  Seam: .... Blocked by: T1.