@gallopsystems/agent-skills 1.31.2 → 1.33.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/README.md +24 -0
- package/package.json +1 -1
- package/plugins/gallop-ui/skills/gallop-ui/SKILL.md +1 -1
- package/plugins/gallop-ui/skills/gallop-ui/api-principles.md +5 -2
- package/plugins/gallop-ui/skills/gallop-ui/finding-a-component.md +5 -0
- package/plugins/gallop-ui/skills/gallop-ui/pitfalls.md +5 -0
- package/plugins/gallop-ui/skills/gallop-ui/pulling-updates.md +14 -3
- package/plugins/gallop-ui/skills/gallop-ui/using-in-an-app.md +15 -0
- package/plugins/generate-documentation/.claude-plugin/plugin.json +8 -0
- package/plugins/generate-documentation/skills/generate-documentation/SKILL.md +186 -0
- package/plugins/generate-documentation/skills/generate-documentation/bin/capture-example.mjs +53 -0
- package/plugins/generate-documentation/skills/generate-documentation/bin/render.mjs +82 -0
- package/plugins/generate-documentation/skills/generate-documentation/bin/shots.mjs +139 -0
- package/plugins/generate-documentation/skills/generate-documentation/formats.md +71 -0
- package/plugins/generate-documentation/skills/generate-documentation/templates/guide.html +116 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/SKILL.md +17 -3
- package/plugins/kysely-postgres/skills/kysely-postgres/references/common-pitfalls.md +91 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/concurrency-and-transactions.md +155 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/full-text-and-grouping.md +13 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/migrations-and-codegen.md +50 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/query-patterns.md +65 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/set-lateral-locking.md +2 -0
- package/plugins/nitro-testing/skills/nitro-testing/SKILL.md +10 -0
- package/plugins/nitro-testing/skills/nitro-testing/proving-the-claim.md +240 -0
- package/plugins/nitro-testing/skills/nitro-testing/transaction-rollback.md +1 -0
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/SKILL.md +23 -12
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/auth-patterns.md +50 -0
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/error-handling.md +34 -3
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/examples/validation-endpoint.ts +2 -2
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/fetch-patterns.md +57 -0
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/nitro-tasks.md +2 -0
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/server-services.md +100 -1
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/sse.md +1 -1
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/validation.md +120 -14
- package/plugins/pr-review/.claude-plugin/plugin.json +8 -0
- package/plugins/pr-review/skills/pr-review/SKILL.md +68 -0
- package/plugins/pr-review/skills/pr-review/brief-prompt.md +33 -0
- package/plugins/pr-review/skills/pr-review/focus-areas.md +63 -0
- package/plugins/pr-review/skills/pr-review/judge.md +29 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md +29 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/async-state.md +229 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/component-authoring.md +45 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/editing-forms.md +137 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/formatters.md +8 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/slots.md +16 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/template-idioms.md +52 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/v-model.md +2 -1
- package/plugins/vue-nuxt/skills/vue-nuxt/watch.md +5 -1
package/README.md
CHANGED
|
@@ -21,6 +21,8 @@ Then install the skills you want:
|
|
|
21
21
|
/plugin install vue-nuxt@gallop-systems-agent-skills
|
|
22
22
|
/plugin install frontend-design@gallop-systems-agent-skills
|
|
23
23
|
/plugin install gallop-ui@gallop-systems-agent-skills
|
|
24
|
+
/plugin install generate-documentation@gallop-systems-agent-skills
|
|
25
|
+
/plugin install pr-review@gallop-systems-agent-skills
|
|
24
26
|
```
|
|
25
27
|
|
|
26
28
|
## Updating
|
|
@@ -180,6 +182,28 @@ Covers:
|
|
|
180
182
|
- Pulling a release: `yarn ui:pull`, `ui:migrate`, `ui:tokens`, `ui:check`, merge-commit subtree PRs
|
|
181
183
|
- Changing the layer, checking every app with `ui:impact` and screenshot sweeps, and working rules learned the hard way
|
|
182
184
|
|
|
185
|
+
### generate-documentation
|
|
186
|
+
|
|
187
|
+
Write a client-facing guide with real screenshots of the app, as a PDF, HTML page, email draft or WhatsApp messages.
|
|
188
|
+
Run it as `/generate-documentation <format> <what to document>`.
|
|
189
|
+
|
|
190
|
+
Covers:
|
|
191
|
+
- Two modes: **answer** (turn a client's questions into "you can already do this", "we changed it", "here's the fix") and **announce** (turn merged work into an unsolicited "you can now…" note)
|
|
192
|
+
- Checking each answer in the code and the running app before writing it
|
|
193
|
+
- Screenshots from a scratch copy of the app's fictional demo data only, never real data
|
|
194
|
+
- `bin/shots.mjs` Playwright helpers (sign-in, still captures, highlight rings, region and element shots) and `bin/render.mjs` (HTML to PDF, plus a contact sheet for reviewing page breaks)
|
|
195
|
+
- A guide template, writing rules for non-technical readers, and per-format rules
|
|
196
|
+
|
|
197
|
+
### pr-review
|
|
198
|
+
|
|
199
|
+
Review a branch or pull request for defects before a human sees it.
|
|
200
|
+
|
|
201
|
+
Covers:
|
|
202
|
+
- Building a context brief with a cheap model: the change's goal, callers, sibling code and stated claims
|
|
203
|
+
- Running `codex review` with the brief
|
|
204
|
+
- Judging every finding against the code (five keep-rules) before fixing or reporting it
|
|
205
|
+
- Deep mode: one focused reviewer per concern (tests, docs, migrations, UI state, races, agreeing paths, inputs, access)
|
|
206
|
+
|
|
183
207
|
## Contributing a Lesson Back
|
|
184
208
|
|
|
185
209
|
Every skill ends with a **Contributing Back** section: when Claude works through
|
package/package.json
CHANGED
|
@@ -68,7 +68,7 @@ Detail, and how to propose a component: [finding-a-component.md](finding-a-compo
|
|
|
68
68
|
## Pull an update (decision procedure)
|
|
69
69
|
|
|
70
70
|
New worktree from `origin/main` → `yarn ui:pull vX.Y.Z` (its own commit; needs a clean tree) → read `CHANGELOG.md`
|
|
71
|
-
and `migrations/` between the two versions →
|
|
71
|
+
and `migrations/` between the two versions → whenever there's a newer `migrations/` table (minor releases too), `yarn ui:migrate --dry`, then `yarn ui:migrate`
|
|
72
72
|
and work its checklist → `yarn ui:tokens`, `yarn ui:check` → remove workarounds the release makes unnecessary → full
|
|
73
73
|
tests and a before/after visual sweep → PR, merged with a **merge commit**.
|
|
74
74
|
Steps and commands: [pulling-updates.md](pulling-updates.md).
|
|
@@ -108,8 +108,8 @@ colours: an app's extra button colour maps onto an existing `color`.
|
|
|
108
108
|
## `pt` sections and slots
|
|
109
109
|
|
|
110
110
|
- `class` is always `pt.root`. An overlay's `root` is its panel; its backdrop is `overlay`.
|
|
111
|
-
- Inside a list, an item's parts are `item`, `itemLabel`, `itemDescription`, `itemIcon
|
|
112
|
-
`groupLabel`.
|
|
111
|
+
- Inside a list, an item's parts are `item`, `itemLabel`, `itemDescription`, `itemIcon`, and every other part of a
|
|
112
|
+
row is prefixed `item` too (`itemBadge`, `itemCount`, `itemKbd`, `itemMeta`); a group heading is `groupLabel`.
|
|
113
113
|
- `icon` is only the component's own leading icon; other icons are named for their job (`toggleIcon`, `zoneIcon`,
|
|
114
114
|
`checkIcon`).
|
|
115
115
|
- A field's popup is `panel`; Tabs' panels are `tabPanel`; a title-plus-description block is `text`; an inner
|
|
@@ -150,6 +150,9 @@ colours: an app's extra button colour maps onto an existing `color`.
|
|
|
150
150
|
without new evidence.
|
|
151
151
|
- **Backward compatible by default:** a new prop or option must leave every existing call site rendering exactly as
|
|
152
152
|
before. A look that changes without the caller touching `pt` is a breaking change.
|
|
153
|
+
- **A rename can ship in a minor release** when the old name keeps working until the next major: a `pt` section
|
|
154
|
+
through `usePt`'s `renamed` map (a deprecated alias with one dev warning per old name), a data attribute rendered
|
|
155
|
+
under both names. It still gets a codemod row, so apps stop using the old name before the major removes it.
|
|
153
156
|
- **Breaking changes after 1.0** need a major release, a `CHANGELOG.md` note, and a row per change in
|
|
154
157
|
`migrations/<version>/<area>.json` with a `codemod` the kit can apply (`rename`, `invert-to`, `wrap-array`…) or
|
|
155
158
|
`manual` with a `locate` and a note. `yarn ui:migrate` then rewrites apps and writes the checklist. Before 1.0,
|
|
@@ -50,6 +50,11 @@ instead of a choice), it is a different component.
|
|
|
50
50
|
While the layer change is pending, the app may carry a small, local workaround marked `TODO(gallop-ui): <what the
|
|
51
51
|
layer should do>`. The next `ui:pull` removes it.
|
|
52
52
|
|
|
53
|
+
**A list of rows you write yourself** (people with an avatar and actions, settings rows, a pick-one list, a list the
|
|
54
|
+
user reorders) is `List` with `ListItem` and `ListGroup`: slots for leading, content and actions; selection with
|
|
55
|
+
checkboxes or pick-one; reorder; ghost or outlined, ruled or gapped. Don't hand-roll a `<ul>` with borders and
|
|
56
|
+
checkboxes. A list of records with columns is still `DataTable`.
|
|
57
|
+
|
|
53
58
|
## 4. No match: compose, then propose
|
|
54
59
|
|
|
55
60
|
1. **Compose layer primitives in the app** (`Card` + `DescriptionList` + `Button`…), in an app component named for
|
|
@@ -66,6 +66,11 @@ Rules learned the hard way while building the layer and moving every app onto it
|
|
|
66
66
|
open must read it again.
|
|
67
67
|
- **DataTable cell state follows the position** on a page turn unless the stateful component has `:key="row.id"`.
|
|
68
68
|
- **Don't copy an old phone table** with `layout="table"`: phones get cards.
|
|
69
|
+
- **Default icons missing after a pull?** The app has no `gallopUi.icons` and no `@iconify-json/ph`, so the layer
|
|
70
|
+
draws Phosphor from a collection that isn't there. Run `yarn ui:migrate` (it writes `icons: "lucide"`), or install
|
|
71
|
+
Phosphor on purpose. The layer prints a `[gallop-ui]` warning at build time for this.
|
|
72
|
+
- **A dev warning `[gallop-ui] <Component> pt "<old>" is deprecated`** means the app uses a name a minor release
|
|
73
|
+
renamed. It still works; run `yarn ui:migrate` to rename it before the next major removes it.
|
|
69
74
|
- **`/_ui` shows the wrong font?** The app sets its font from a layout. Move it to `--font-sans` in `@theme`.
|
|
70
75
|
|
|
71
76
|
## Verifying and reporting
|
|
@@ -40,12 +40,23 @@ ls layers/gallop-ui/migrations/; cat layers/gallop-ui/docs/upgrading.md
|
|
|
40
40
|
```
|
|
41
41
|
|
|
42
42
|
For each entry, decide: does this app call it (`git grep -n "<Component\|propName" -- app tests`), and does the call
|
|
43
|
-
site need to change? Read the affected components' `.md` "Migrating" sections.
|
|
44
|
-
|
|
43
|
+
site need to change? Read the affected components' `.md` "Migrating" sections. Any release with renames has a
|
|
44
|
+
`migrations/<major.minor>/` folder, minor releases included (1.1 has one); `docs/upgrading.md` explains how to apply it. Jumping several releases is
|
|
45
45
|
fine as long as you read every entry in between. The kit only knows the versions it has tables for, so check the
|
|
46
46
|
migration doc for how far back it reaches.
|
|
47
47
|
|
|
48
|
-
## 3. Run the codemod
|
|
48
|
+
## 3. Run the codemod whenever there's a newer table
|
|
49
|
+
|
|
50
|
+
Run it whenever `layers/gallop-ui/migrations/` has a folder newer than the version you came from, minor or major.
|
|
51
|
+
|
|
52
|
+
- **Minor releases (1.1, 1.2…) rename without breaking.** A renamed `pt` section keeps its old name as a deprecated
|
|
53
|
+
alias until the next major, and a renamed data attribute is rendered under both names. So the app renders the same
|
|
54
|
+
before the codemod, but logs one dev warning per old name: `[gallop-ui] <Component> pt "<old>" is deprecated`. Run
|
|
55
|
+
the codemod anyway so the warnings stop and the next major is a non-event.
|
|
56
|
+
- **A minor release can also add settings for existing apps.** 1.1's `icons` row writes `icons: "lucide"` into
|
|
57
|
+
`app/app.config.ts` so an existing app keeps its icons. Commit that line with the codemod output, and keep it.
|
|
58
|
+
- **Major releases break.** The old names are gone; the codemod and its checklist are how the app keeps working.
|
|
59
|
+
- An app already on the newest table gets `nothing to migrate` (exit 0).
|
|
49
60
|
|
|
50
61
|
```sh
|
|
51
62
|
yarn ui:migrate --dry # the diff and counts; nothing written
|
|
@@ -69,6 +69,19 @@ a plain class chosen in script, so a caller's class always beats it. What that m
|
|
|
69
69
|
- Overlays (Modal, Drawer, Popover, Tooltip, DropdownMenu) portal their box away: that box is `root`, so `class`
|
|
70
70
|
still styles what you see. The backdrop is `overlay`.
|
|
71
71
|
|
|
72
|
+
## Icons
|
|
73
|
+
|
|
74
|
+
- **One icon set per app: `gallopUi.icons`** in `app/app.config.ts`, `"phosphor"` (the layer's default, and a new
|
|
75
|
+
app's) or `"lucide"` (apps from before 1.1; `ui:migrate` writes it so they keep their glyphs). The layer's own
|
|
76
|
+
icons (chevrons, close, check, search…) follow it. Write the app's own icons in the same set (`ph:*` or
|
|
77
|
+
`lucide:*`), never a mix.
|
|
78
|
+
- The set's collection must be installed (`@iconify-json/ph` or `@iconify-json/lucide`) and listed in
|
|
79
|
+
`icon.serverBundle.collections`. The layer warns at build time when it isn't; otherwise the default icons would
|
|
80
|
+
silently be missing. `layers/gallop-ui/docs/icons.md` has the setup and a name map between the sets.
|
|
81
|
+
- An `icon` prop takes any Iconify name and is never mapped: `icon="ph:users"` stays Phosphor whatever the setting.
|
|
82
|
+
- To change single layer icons, give `gallopUi.icons` a map of roles instead of a preset name: `icons: { close: "ph:x-circle" }`
|
|
83
|
+
overrides that role over Phosphor. The roles are in `layers/gallop-ui/docs/icons.md`.
|
|
84
|
+
|
|
72
85
|
## Tokens and dark mode
|
|
73
86
|
|
|
74
87
|
- **Dark mode is required in every app.** No light-only option, no pinned light colours.
|
|
@@ -76,6 +89,8 @@ a plain class chosen in script, so a caller's class always beats it. What that m
|
|
|
76
89
|
strategy: the OS (`:root { color-scheme: light dark }`, the template default), or an attribute on `<html>`
|
|
77
90
|
(`data-color-scheme="light|dark"`, set from a cookie by `useColorScheme()`; no flash on first paint).
|
|
78
91
|
`TOKENS.md` has the contract; `theme/neutral.css` has every value.
|
|
92
|
+
- **A bare `border` is the `line` colour** (the layer's base style), not `currentColor`. Add a colour class only to
|
|
93
|
+
change it; `border-current` brings back the text colour.
|
|
79
94
|
- In app code write token classes (`bg-surface`, `text-fg-muted`, `border-line`, `bg-danger-soft`), not
|
|
80
95
|
`bg-white dark:bg-zinc-900`. Status colours are the `danger | warning | success | info` families.
|
|
81
96
|
- `yarn ui:tokens` checks the app's theme CSS against the contract: what is missing, what still has an old name.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "generate-documentation",
|
|
3
|
+
"description": "Write a client-facing guide with screenshots of the app (PDF, HTML, email or WhatsApp): answer a client's questions, or announce what shipped. Screenshots come from fictional demo data only; includes Playwright capture helpers and a PDF renderer with a page-review contact sheet.",
|
|
4
|
+
"version": "1.0.0",
|
|
5
|
+
"author": {
|
|
6
|
+
"name": "Gallop Systems"
|
|
7
|
+
}
|
|
8
|
+
}
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: generate-documentation
|
|
3
|
+
description: Write a client-facing guide with screenshots of the app, as a PDF, HTML page, email or WhatsApp messages. Two modes. "answer" turns a client's questions into answers ("you can already do this, here's how", "we changed it, here's how it works", "here's why that happened and the fix"). "announce" turns merged work into an unsolicited "you can now…" note. Use when the user wants to send a client or their staff documentation, a how-to, release notes, a "what's new" or answers to their questions about a Gallop app, even if they don't say "documentation".
|
|
4
|
+
argument-hint: <pdf|html|email|whatsapp> <answer: pasted questions | announce: PR, branch, or "what merged since …">
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Generate client documentation
|
|
8
|
+
|
|
9
|
+
You are writing for the client's staff: people who use the app every day and do
|
|
10
|
+
not read code. The result is a document they can follow alone, with real
|
|
11
|
+
screenshots of the app, that never shows real client data.
|
|
12
|
+
|
|
13
|
+
Arguments: a **format** (`pdf`, `html`, `email`, `whatsapp`; default `pdf`) and
|
|
14
|
+
what to document. Work out the **mode** from what you are given:
|
|
15
|
+
|
|
16
|
+
- **answer**: their questions or messages (pasted, a screenshot, an email). Each
|
|
17
|
+
question gets a section.
|
|
18
|
+
- **announce**: work that shipped (a PR, a branch, "everything merged since
|
|
19
|
+
Monday", or "the feature we just built"). Each user-visible change gets a
|
|
20
|
+
section. Nobody asked; you are telling them what they can now do.
|
|
21
|
+
|
|
22
|
+
If the format or the mode is unclear, ask once. Everything else you decide.
|
|
23
|
+
|
|
24
|
+
Format-specific output rules are in [formats.md](formats.md). Read it before
|
|
25
|
+
writing.
|
|
26
|
+
|
|
27
|
+
## 1. Work out what is true
|
|
28
|
+
|
|
29
|
+
Do this before taking a single screenshot. A guide that confidently describes the
|
|
30
|
+
wrong thing is worse than no guide.
|
|
31
|
+
|
|
32
|
+
### answer mode
|
|
33
|
+
|
|
34
|
+
Split the messages into separate questions (people send several in a row). For
|
|
35
|
+
each one, find out from the code, the in-app docs and the data (read-only) which
|
|
36
|
+
of these it is:
|
|
37
|
+
|
|
38
|
+
| Kind | Tag in the guide | What the section does |
|
|
39
|
+
|---|---|---|
|
|
40
|
+
| They can already do it | **You can do this already** | Numbered steps with screenshots |
|
|
41
|
+
| It needed a change, and we made it | **New** | How it works now, with screenshots, and the rules |
|
|
42
|
+
| A setting, data or setup problem | **A setting to fix** | Why it happened, then the fix |
|
|
43
|
+
| Not possible yet | (leave out, or **Not yet**) | Say so plainly; ask the user whether to build it before you write anything |
|
|
44
|
+
| Something only they can tell you | **Needs your answer** | Ask the question; don't guess |
|
|
45
|
+
|
|
46
|
+
Look at how the status or behaviour they're asking about is *derived*, not just
|
|
47
|
+
what it is called. "Why does it say Ready to send?" is usually answered by the
|
|
48
|
+
rule behind the label (a list of required items, a permission, a filter on an import).
|
|
49
|
+
Fixing the input to that rule is usually something they can do themselves.
|
|
50
|
+
|
|
51
|
+
For a question about records that are missing or wrong, check the actual records
|
|
52
|
+
(read-only) and the job that is supposed to bring them in (when it last ran,
|
|
53
|
+
whether it failed, what it filters on). If you cannot read production, give the
|
|
54
|
+
user a read-only query to run and wait for the result. Don't write the section on
|
|
55
|
+
a guess.
|
|
56
|
+
|
|
57
|
+
### announce mode
|
|
58
|
+
|
|
59
|
+
Collect what shipped: `gh pr view <n> --json title,body,files`, `git log
|
|
60
|
+
<range>`, or the merged PRs since a date. Then keep only **user-visible
|
|
61
|
+
changes**. Drop refactors, tests, dependency bumps, internal tooling and
|
|
62
|
+
performance work nobody will notice.
|
|
63
|
+
|
|
64
|
+
For each change that is left:
|
|
65
|
+
|
|
66
|
+
- Read the diff for its real behaviour: what staff see, what they click, what
|
|
67
|
+
changes on its own, and what changes the day it goes live (existing records that
|
|
68
|
+
will suddenly look different). That last one is the thing clients most need to
|
|
69
|
+
hear in advance.
|
|
70
|
+
- Read the page's in-app doc if the repo has them (Gallop portals keep one beside
|
|
71
|
+
every page). If the PR changed behaviour and didn't update that doc, tell the
|
|
72
|
+
user. Don't paper over it in the guide.
|
|
73
|
+
- Check who can use it. Admin-only screens either go in an admin-only guide or
|
|
74
|
+
are marked "ask your admin".
|
|
75
|
+
- Check it has been merged, or deployed if the user says the client already has
|
|
76
|
+
it. Never announce work that is still in progress.
|
|
77
|
+
|
|
78
|
+
Several changes make one short "What's new" guide. One feature makes a one-pager.
|
|
79
|
+
|
|
80
|
+
## 2. Try every step in the app
|
|
81
|
+
|
|
82
|
+
Before writing a step, do it in the running app on demo data: click every button
|
|
83
|
+
you are about to tell them to click. This is where wrong answers show up. A
|
|
84
|
+
move the guide said would work gets refused because the target record lacks a permission.
|
|
85
|
+
A setting turns out to be admin-only. A label on screen differs from the code's
|
|
86
|
+
name for it. When doing it shows your earlier answer was wrong, fix the answer,
|
|
87
|
+
and tell the user what changed.
|
|
88
|
+
|
|
89
|
+
## 3. Screenshots, from demo data only
|
|
90
|
+
|
|
91
|
+
**Never capture from a database or environment holding real client data**, not
|
|
92
|
+
even "just to look". The pictures go to the client and may be forwarded on.
|
|
93
|
+
|
|
94
|
+
1. **Find the safe data.** Read the repo's CLAUDE.md. Gallop Nuxt apps usually
|
|
95
|
+
have a fictional demo database and a dev server for doc screenshots (for
|
|
96
|
+
example `yarn docs:demo-data` and `yarn docs:dev`), plus a dev-only preview
|
|
97
|
+
login (`/api/auth/preview-login`). Build a **scratch copy** of the demo
|
|
98
|
+
database under its own name, and serve it on its own port, so you don't clash
|
|
99
|
+
with other sessions. If the repo has no fictional data source, stop and tell
|
|
100
|
+
the user. Don't screenshot real data, and don't invent data in a real database.
|
|
101
|
+
2. **Stage the scenarios** in the scratch database with SQL: the record that
|
|
102
|
+
shows the problem, the setting before it is fixed, the record filed under the
|
|
103
|
+
wrong owner. Use the same kind of record the client described, with made-up names.
|
|
104
|
+
Remove anything that distracts from the point (an unrelated badge on the same
|
|
105
|
+
card).
|
|
106
|
+
3. **Script the captures.** Copy [bin/capture-example.mjs](bin/capture-example.mjs)
|
|
107
|
+
to a scratch directory and write one step per section; it imports
|
|
108
|
+
[bin/shots.mjs](bin/shots.mjs). Run it from the app repo
|
|
109
|
+
(`cd <repo> && node <scratch>/capture.mjs <out-dir> [step]`), so Playwright
|
|
110
|
+
resolves from there. For each step, capture before, the action and after.
|
|
111
|
+
Ring the thing to click with `mark()`.
|
|
112
|
+
4. **Look at every image** before using it. Common faults: the crop cuts off the
|
|
113
|
+
heading, the wrong column was clicked, a dialog is half-rendered, or the
|
|
114
|
+
picture shows a state from a previous run.
|
|
115
|
+
5. **Reset what a step changed**, at the start of that step, so any step can be
|
|
116
|
+
re-run alone.
|
|
117
|
+
|
|
118
|
+
Capture gotchas:
|
|
119
|
+
|
|
120
|
+
- Find table columns by their header text, never by position: an index that was
|
|
121
|
+
right for one table clicks the neighbouring column of the next. A cell that
|
|
122
|
+
cycles states (Required → Optional → none) will have been changed by the wrong
|
|
123
|
+
click, so check the data and put it back.
|
|
124
|
+
- Write capture scripts as `.mjs`. A `.ts` file run through `tsx` outside a
|
|
125
|
+
`"type": "module"` package fails on top-level `await`
|
|
126
|
+
(`ERR_REQUIRE_ASYNC_MODULE`).
|
|
127
|
+
- Use `element()` for dialogs and drawers. For a panel, frame it with `shot()`
|
|
128
|
+
on its heading and its last line, or find it with
|
|
129
|
+
`xpath=ancestor::*[.//button[normalize-space()='…']][1]`.
|
|
130
|
+
- A Nuxt dev server freshly started after a lockfile change can 500 every
|
|
131
|
+
request with "IPC connection closed" while Vite re-optimizes. Restart it once.
|
|
132
|
+
- Image viewers, the Read tool included, can cache an image by its path.
|
|
133
|
+
When you regenerate a review image, give it a new name.
|
|
134
|
+
|
|
135
|
+
## 4. Write it
|
|
136
|
+
|
|
137
|
+
The writing rules hold in every format:
|
|
138
|
+
|
|
139
|
+
- **Their words, the app's labels.** Head each section with their question or the
|
|
140
|
+
feature in plain words. Name every button, menu and field exactly as it appears
|
|
141
|
+
on screen, in bold. No file paths, routes, table names, code or developer terms.
|
|
142
|
+
- **Second person, short sentences, one action per step.**
|
|
143
|
+
- **Say why before how**, in a sentence: "An order says Ready to ship once every
|
|
144
|
+
required document is in, and this product line doesn't require the signed
|
|
145
|
+
form." Then the steps.
|
|
146
|
+
- **Say who can do it.** If a step needs an admin, or a particular sign-in, say so
|
|
147
|
+
at the top of the guide and at the step.
|
|
148
|
+
- **Say what else it changes.** A setting changed for one record usually applies
|
|
149
|
+
to all of them. Say so, and give the narrower alternative when there is one.
|
|
150
|
+
- **Warn about day one.** If going live will change how many existing records
|
|
151
|
+
look, say what they'll see and that it is expected.
|
|
152
|
+
- **Warn about doing both.** When there are two ways to fix something and doing
|
|
153
|
+
both creates a duplicate, say "pick one".
|
|
154
|
+
- **"Please confirm first"** when the right fix depends on a fact only they know
|
|
155
|
+
(is this supplier the contract holder, or working under someone else's?). Give both branches.
|
|
156
|
+
- **Note the demo data** once, near the top: the screenshots use made-up records,
|
|
157
|
+
so the names differ but the screens are the same.
|
|
158
|
+
- Don't apologise, don't mention AI, and don't describe how you investigated.
|
|
159
|
+
|
|
160
|
+
## 5. Render, review, deliver
|
|
161
|
+
|
|
162
|
+
- **pdf and html:** start from [templates/guide.html](templates/guide.html) (its
|
|
163
|
+
header comment lists the building blocks), then render with
|
|
164
|
+
`node <skill-dir>/bin/render.mjs <guide.html> <out.pdf> --footer "<App name>"`,
|
|
165
|
+
run from the app repo. **Look at the contact sheet it prints.** Fix a heading
|
|
166
|
+
stranded at the foot of a page, a page holding a single note, or a figure
|
|
167
|
+
separated from its step: use `.keep` wrappers, a smaller figure width, or move a
|
|
168
|
+
note above its figures. Re-render, and look again.
|
|
169
|
+
- **email and whatsapp:** see [formats.md](formats.md).
|
|
170
|
+
- Save the deliverable where the user can open it, and hand it over (attach it
|
|
171
|
+
where your environment can). **Never send it yourself.** Emails are drafts,
|
|
172
|
+
WhatsApp text is for the user to paste, and publishing anything waits for
|
|
173
|
+
their yes.
|
|
174
|
+
- Then clean up: stop the dev servers you started, drop the scratch databases,
|
|
175
|
+
and undo any launch-config entries you added. Keep the capture script in
|
|
176
|
+
scratch so the user can ask for a retake.
|
|
177
|
+
|
|
178
|
+
In your reply, give the user the file, a line per section, and anything you
|
|
179
|
+
found that changes an earlier answer. Also list any open question the guide asks
|
|
180
|
+
the client to confirm.
|
|
181
|
+
|
|
182
|
+
## Contributing Back
|
|
183
|
+
|
|
184
|
+
This skill grows by capturing what it missed. If you just worked through something in this domain that this skill did not cover — an error you had to figure out, a behavior that contradicts what is documented above, a workflow knot — ask the user: **"Want me to contribute this back to the generate-documentation skill?"**
|
|
185
|
+
|
|
186
|
+
If yes, run `/contribute-skill`. If that command is not available, do the equivalent inline: distill the generic lesson (placeholders only — no project names, IDs, domains, or secrets), then branch or fork [gallop-systems/agent-skills](https://github.com/gallop-systems/agent-skills) and open a PR editing this skill.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Example per-job capture script. Copy it to a scratch directory, edit the
|
|
3
|
+
* steps, and run it from the app repo:
|
|
4
|
+
*
|
|
5
|
+
* cd <app repo> && node <scratch>/capture.mjs <out-dir> [only-step]
|
|
6
|
+
*
|
|
7
|
+
* Paths, labels and SQL below are placeholders for a typical Gallop Nuxt app.
|
|
8
|
+
*/
|
|
9
|
+
import { open, run, sql } from "<skill-dir>/bin/shots.mjs";
|
|
10
|
+
|
|
11
|
+
const [outDir, only] = process.argv.slice(2);
|
|
12
|
+
const BASE = "http://localhost:3100"; // the demo-data dev server, never one on real data
|
|
13
|
+
const DB = "postgresql://localhost:5432/<app>-docs-scratch"; // a scratch copy of the demo DB
|
|
14
|
+
const db = (q) => sql(DB, q);
|
|
15
|
+
|
|
16
|
+
const { browser, page, kit } = await open({ base: BASE, login: "/api/auth/preview-login" });
|
|
17
|
+
kit.out(outDir);
|
|
18
|
+
|
|
19
|
+
await run(
|
|
20
|
+
{
|
|
21
|
+
// A thing the user can already do: show before, the click, and after.
|
|
22
|
+
async setting() {
|
|
23
|
+
db("update widgets set required = false where code = 'example'"); // reset, so the step re-runs
|
|
24
|
+
await kit.go("/admin/widgets");
|
|
25
|
+
const table = page.locator("table").first();
|
|
26
|
+
const heads = await table.locator("thead th").allInnerTexts();
|
|
27
|
+
const col = heads.findIndex((h) => h.trim() === "Example"); // find columns by header text, never by index
|
|
28
|
+
const cell = table.locator("tbody tr", { hasText: "Row label" }).first().locator("th, td").nth(col);
|
|
29
|
+
await kit.mark(cell);
|
|
30
|
+
await kit.shot("setting-1-before", [table.locator("thead"), cell]);
|
|
31
|
+
await kit.unmark();
|
|
32
|
+
await cell.locator("button").first().click();
|
|
33
|
+
await page.waitForTimeout(1000);
|
|
34
|
+
await kit.mark(cell);
|
|
35
|
+
await kit.shot("setting-2-after", [table.locator("thead"), cell]);
|
|
36
|
+
await kit.unmark();
|
|
37
|
+
},
|
|
38
|
+
|
|
39
|
+
// A dialog or drawer: shoot the element itself.
|
|
40
|
+
async dialog() {
|
|
41
|
+
await kit.go("/records/1");
|
|
42
|
+
await page.getByRole("button", { name: "Outcome" }).first().click();
|
|
43
|
+
await kit.settle(500);
|
|
44
|
+
const dialog = page.getByRole("dialog").last();
|
|
45
|
+
await kit.mark(dialog.getByRole("button", { name: "Transfer…" }));
|
|
46
|
+
await kit.element("dialog-1", dialog);
|
|
47
|
+
await kit.unmark();
|
|
48
|
+
},
|
|
49
|
+
},
|
|
50
|
+
{ only },
|
|
51
|
+
);
|
|
52
|
+
|
|
53
|
+
await browser.close();
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Render a guide's HTML to PDF, and make a contact sheet of its pages to review.
|
|
3
|
+
* Run it from the app repo, so Playwright resolves from there:
|
|
4
|
+
*
|
|
5
|
+
* cd <app repo> && node <skill-dir>/bin/render.mjs <guide.html> <out.pdf> [--footer "Product name"]
|
|
6
|
+
*
|
|
7
|
+
* Prints the page count and the path of `<out>.sheet.png` (every page side by
|
|
8
|
+
* side). Look at the sheet before sending: it is how you catch a heading left at
|
|
9
|
+
* the bottom of a page, a page holding one note, or a screenshot split from its
|
|
10
|
+
* step. The sheet needs `pdftoppm` (poppler) and ImageMagick; without them it is
|
|
11
|
+
* skipped and only the page count is printed.
|
|
12
|
+
*/
|
|
13
|
+
import { createRequire } from "node:module";
|
|
14
|
+
import { execFileSync } from "node:child_process";
|
|
15
|
+
import fs from "node:fs";
|
|
16
|
+
import os from "node:os";
|
|
17
|
+
import path from "node:path";
|
|
18
|
+
|
|
19
|
+
const require = createRequire(path.join(process.cwd(), "package.json"));
|
|
20
|
+
const { chromium } = require("playwright");
|
|
21
|
+
|
|
22
|
+
const args = process.argv.slice(2);
|
|
23
|
+
const footerAt = args.indexOf("--footer");
|
|
24
|
+
const footer = footerAt >= 0 ? args.splice(footerAt, 2)[1] : "";
|
|
25
|
+
const [html, out] = args.map((p) => path.resolve(p));
|
|
26
|
+
if (!html || !out) {
|
|
27
|
+
console.error("usage: render.mjs <guide.html> <out.pdf> [--footer text]");
|
|
28
|
+
process.exit(1);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
const escape = (s) => s.replace(/[&<>"]/g, (c) => ({ "&": "&", "<": "<", ">": ">", '"': """ })[c]);
|
|
32
|
+
const browser = await chromium.launch();
|
|
33
|
+
const page = await browser.newPage();
|
|
34
|
+
await page.goto(`file://${html}`, { waitUntil: "networkidle" });
|
|
35
|
+
await page.evaluate(() => document.fonts.ready);
|
|
36
|
+
await page.pdf({
|
|
37
|
+
path: out,
|
|
38
|
+
format: "Letter",
|
|
39
|
+
printBackground: true,
|
|
40
|
+
preferCSSPageSize: true,
|
|
41
|
+
displayHeaderFooter: true,
|
|
42
|
+
headerTemplate: "<span></span>",
|
|
43
|
+
footerTemplate: `<div style="font-size:7pt;color:#8a847b;width:100%;text-align:center;font-family:sans-serif">${
|
|
44
|
+
footer ? `${escape(footer)} · ` : ""
|
|
45
|
+
}<span class="pageNumber"></span> of <span class="totalPages"></span></div>`,
|
|
46
|
+
});
|
|
47
|
+
await browser.close();
|
|
48
|
+
|
|
49
|
+
const has = (bin) => {
|
|
50
|
+
try {
|
|
51
|
+
execFileSync("which", [bin], { stdio: "ignore" });
|
|
52
|
+
return true;
|
|
53
|
+
} catch {
|
|
54
|
+
return false;
|
|
55
|
+
}
|
|
56
|
+
};
|
|
57
|
+
|
|
58
|
+
if (has("pdftoppm") && has("magick")) {
|
|
59
|
+
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "gd-pages-"));
|
|
60
|
+
execFileSync("pdftoppm", ["-r", "60", "-png", out, path.join(dir, "p")]);
|
|
61
|
+
const pages = fs.readdirSync(dir).filter((f) => f.endsWith(".png")).sort((a, b) =>
|
|
62
|
+
a.localeCompare(b, undefined, { numeric: true }),
|
|
63
|
+
);
|
|
64
|
+
// A new name every run: an image viewer that caches by path would show the old sheet.
|
|
65
|
+
const sheet = out.replace(/\.pdf$/i, `.sheet-${Date.now()}.png`);
|
|
66
|
+
const cols = Math.min(5, pages.length);
|
|
67
|
+
execFileSync("magick", [
|
|
68
|
+
"montage",
|
|
69
|
+
...pages.map((p) => path.join(dir, p)),
|
|
70
|
+
"-tile", `${cols}x`,
|
|
71
|
+
"-geometry", "+6+6",
|
|
72
|
+
"-background", "#999",
|
|
73
|
+
sheet,
|
|
74
|
+
]);
|
|
75
|
+
console.log(`${pages.length} pages`);
|
|
76
|
+
console.log(`sheet: ${sheet}`);
|
|
77
|
+
console.log(`pages: ${dir}`);
|
|
78
|
+
} else {
|
|
79
|
+
const count = (fs.readFileSync(out, "latin1").match(/\/Type\s*\/Page[^s]/g) ?? []).length;
|
|
80
|
+
console.log(`${count} pages (install poppler and imagemagick for a contact sheet)`);
|
|
81
|
+
}
|
|
82
|
+
console.log(`pdf: ${out}`);
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Screenshot helpers for /generate-documentation.
|
|
3
|
+
*
|
|
4
|
+
* Import this from a per-job capture script (see capture-example.mjs). Playwright
|
|
5
|
+
* is resolved from the APP repo (the current working directory), not from this
|
|
6
|
+
* skill, so nothing needs installing here:
|
|
7
|
+
*
|
|
8
|
+
* cd <app repo> && node <scratch>/capture.mjs <out-dir> [only-step]
|
|
9
|
+
*
|
|
10
|
+
* Every helper works on one page that is already signed in. Captures are 2x,
|
|
11
|
+
* light theme, reduced motion, with dev chrome (Nuxt devtools, loading bar,
|
|
12
|
+
* scrollbars) hidden, so re-running a step gives the same picture.
|
|
13
|
+
*/
|
|
14
|
+
import { createRequire } from "node:module";
|
|
15
|
+
import { execFileSync } from "node:child_process";
|
|
16
|
+
import path from "node:path";
|
|
17
|
+
import fs from "node:fs";
|
|
18
|
+
|
|
19
|
+
const require = createRequire(path.join(process.cwd(), "package.json"));
|
|
20
|
+
const { chromium } = require("playwright");
|
|
21
|
+
|
|
22
|
+
export const STILL_CSS = `
|
|
23
|
+
*, *::before, *::after { transition: none !important; animation: none !important; caret-color: transparent !important; }
|
|
24
|
+
nuxt-devtools-frame, nuxt-devtools-inspect-panel, #nuxt-devtools-container, #nuxt-devtools-anchor,
|
|
25
|
+
[id^="nuxt-devtools"], #vue-tracer-overlay, vite-error-overlay, .nuxt-loading-indicator { display: none !important; }
|
|
26
|
+
::-webkit-scrollbar { display: none; }
|
|
27
|
+
.gd-mark { outline: 3px solid #e4572e !important; outline-offset: 3px; border-radius: 6px; }
|
|
28
|
+
`;
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Open a browser signed in to `base`.
|
|
32
|
+
* `login` is a path that signs in on GET (a dev/preview login route), or an
|
|
33
|
+
* async function `(page) => {}` that signs in some other way.
|
|
34
|
+
*/
|
|
35
|
+
export async function open({ base, login, width = 1440, height = 900, timeZone = "America/New_York" }) {
|
|
36
|
+
const browser = await chromium.launch();
|
|
37
|
+
const context = await browser.newContext({
|
|
38
|
+
viewport: { width, height },
|
|
39
|
+
deviceScaleFactor: 2,
|
|
40
|
+
colorScheme: "light",
|
|
41
|
+
reducedMotion: "reduce",
|
|
42
|
+
timezoneId: timeZone,
|
|
43
|
+
});
|
|
44
|
+
// esbuild's keepNames helper, which some dev bundles reference before defining.
|
|
45
|
+
await context.addInitScript("globalThis.__name = (fn) => fn;");
|
|
46
|
+
const page = await context.newPage();
|
|
47
|
+
if (typeof login === "string") await page.goto(new URL(login, base).href);
|
|
48
|
+
else if (login) await login(page);
|
|
49
|
+
return { browser, page, kit: kit(page, base) };
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
function kit(page, base) {
|
|
53
|
+
let outDir = ".";
|
|
54
|
+
const k = {
|
|
55
|
+
page,
|
|
56
|
+
/** Where `shot`/`full`/`element` write. */
|
|
57
|
+
out(dir) {
|
|
58
|
+
outDir = dir;
|
|
59
|
+
fs.mkdirSync(dir, { recursive: true });
|
|
60
|
+
},
|
|
61
|
+
/** Go to a path and wait for it to be still. */
|
|
62
|
+
async go(p) {
|
|
63
|
+
await page.goto(new URL(p, base).href);
|
|
64
|
+
await k.settle();
|
|
65
|
+
},
|
|
66
|
+
/** Wait for the network, fonts and a beat for skeletons; re-apply the still CSS. */
|
|
67
|
+
async settle(ms = 700) {
|
|
68
|
+
await page.waitForLoadState("networkidle").catch(() => {});
|
|
69
|
+
await page.addStyleTag({ content: STILL_CSS });
|
|
70
|
+
await page.evaluate(() => document.fonts.ready);
|
|
71
|
+
await page.waitForTimeout(ms);
|
|
72
|
+
},
|
|
73
|
+
/** Ring the given elements (call `unmark` after the shot). */
|
|
74
|
+
async mark(...locators) {
|
|
75
|
+
for (const l of locators) await l.evaluate((el) => el.classList.add("gd-mark"));
|
|
76
|
+
},
|
|
77
|
+
async unmark() {
|
|
78
|
+
await page.evaluate(() =>
|
|
79
|
+
document.querySelectorAll(".gd-mark").forEach((el) => el.classList.remove("gd-mark")),
|
|
80
|
+
);
|
|
81
|
+
},
|
|
82
|
+
/**
|
|
83
|
+
* Screenshot the box that covers every locator, padded. Use two locators to
|
|
84
|
+
* frame a region (a heading and the last thing under it).
|
|
85
|
+
*/
|
|
86
|
+
async shot(name, locators, pad = 14) {
|
|
87
|
+
for (const l of locators) await l.scrollIntoViewIfNeeded().catch(() => {});
|
|
88
|
+
const boxes = [];
|
|
89
|
+
for (const l of locators) {
|
|
90
|
+
const box = await l.boundingBox();
|
|
91
|
+
if (!box) throw new Error(`shot ${name}: a locator is not visible`);
|
|
92
|
+
boxes.push(box);
|
|
93
|
+
}
|
|
94
|
+
const vw = page.viewportSize().width;
|
|
95
|
+
const x = Math.max(0, Math.min(...boxes.map((b) => b.x)) - pad);
|
|
96
|
+
const y = Math.max(0, Math.min(...boxes.map((b) => b.y)) - pad);
|
|
97
|
+
const right = Math.min(vw, Math.max(...boxes.map((b) => b.x + b.width)) + pad);
|
|
98
|
+
const bottom = Math.max(...boxes.map((b) => b.y + b.height)) + pad;
|
|
99
|
+
await page.screenshot({
|
|
100
|
+
path: path.join(outDir, `${name}.png`),
|
|
101
|
+
clip: { x, y, width: right - x, height: bottom - y },
|
|
102
|
+
});
|
|
103
|
+
console.log("shot", name);
|
|
104
|
+
},
|
|
105
|
+
/** One element exactly (a dialog, a drawer). */
|
|
106
|
+
async element(name, locator) {
|
|
107
|
+
await locator.screenshot({ path: path.join(outDir, `${name}.png`) });
|
|
108
|
+
console.log("shot", name);
|
|
109
|
+
},
|
|
110
|
+
/** The whole viewport. */
|
|
111
|
+
async full(name) {
|
|
112
|
+
await page.screenshot({ path: path.join(outDir, `${name}.png`) });
|
|
113
|
+
console.log("shot", name);
|
|
114
|
+
},
|
|
115
|
+
};
|
|
116
|
+
return k;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* Run the named steps in order, or just `only`. Each step is an async function
|
|
121
|
+
* taking the kit. Steps should reset the demo data they change (with `sql`) so
|
|
122
|
+
* any one of them can be re-run alone.
|
|
123
|
+
*/
|
|
124
|
+
export async function run(steps, { only } = {}) {
|
|
125
|
+
for (const [name, step] of Object.entries(steps)) {
|
|
126
|
+
if (only && only !== name) continue;
|
|
127
|
+
await step();
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/** Run SQL against a SCRATCH database (never a real-data one). */
|
|
132
|
+
export function sql(databaseUrl, query) {
|
|
133
|
+
if (!/demo|docs|scratch|fixture|seed|test/i.test(databaseUrl)) {
|
|
134
|
+
throw new Error(
|
|
135
|
+
`refusing to write to ${databaseUrl}: name it as a demo/docs/scratch database, or edit this guard deliberately`,
|
|
136
|
+
);
|
|
137
|
+
}
|
|
138
|
+
return execFileSync("psql", [databaseUrl, "-qAtc", query], { encoding: "utf8" });
|
|
139
|
+
}
|