goosetools-worker 0.2.4 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goosetools-worker",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "The Goose Tools carousel worker — your computer drafts and renders carousel slides for goosetools.com using your own Claude account.",
   "repository": {
     "type": "git",
@@ -13,7 +13,8 @@
     "styles/polka-dot",
     "carousels/demo/slides.yml",
     "brand.yml",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "type": "module",
   "bin": {

package/skills/reference-analysis.md

@@ -0,0 +1,149 @@
+# Reference Analysis Methodology
+
+How to study a set of reference images, map them onto something new, and check
+the finished render against them. Shared by the Carousel Maker (slides) and the
+Overlay Factory (overlays on reels) — the reference images are the source of
+truth for EVERY behavior described here; there are no hardcoded rules. Worker
+prompts splice individual sections by the SECTION markers below.
+
+SHARED FILE: the source of truth is workers/shared/reference-analysis.md in the
+goosetools repo, copied into each worker's skills/ by `npm run workers:sync`.
+
+<!-- SECTION: principles -->
+## Principles — both tools
+
+- **Purpose first, paint second.** Work out what each reference is FOR — the
+  recurring format a follower would recognize — before its colours and fonts.
+  A copy that nails the palette but misses the format is wrong.
+- **Variance vs constants.** Across the set, note what varies and what never
+  changes. Freedom lives exactly where the references vary; fidelity is owed
+  everywhere they don't.
+- **Same-account test.** The finished thing should read as the same account's
+  work if posted next to the references — same format, same typographic
+  voice, same palette logic. Pixel-matching any one reference is NOT the goal.
+- **Look, don't assume.** Read every image before deciding anything, and judge
+  your own output by looking at the render, not by re-reading your markup.
+
+<!-- SECTION: analyze -->
+## Phase A — understand what each reference is DOING
+
+Read every reference image first. For each one, work out:
+
+- **Role**: is this the cover (the hook slide), a middle content slide, or
+  the closer/CTA? The first reference is usually the cover; use layout and
+  copy cues (page counters, "swipe", "follow") to confirm.
+- **Content job**: what is the slide FOR? Presenting a color palette with
+  labeled swatches? Comparing a before vs an after? Listing tips? Showcasing
+  a product photo? The recurring format a follower would recognize is the
+  thing to reproduce — purpose first, paint second.
+- **Photo and subject**: where does the photo's main subject sit in the
+  frame? How tight is the crop?
+- **Overlays**: where do overlays (swatch stacks, badges, labels, text
+  blocks) sit relative to the subject? Record which behavior this set uses:
+  some styles keep overlays OFF the subject (overlays live in the empty
+  side of the frame); others deliberately lay elements OVER the photo as
+  part of the look. Both are legitimate — copy whichever these references do.
+- **Variance vs constants**: across the whole set, what varies (number of
+  swatches, which side the overlay sits on, crop tightness) and what never
+  changes (the format, the typography, the palette treatment, the border
+  style)? Freedom lives exactly where the references vary; fidelity is owed
+  everywhere they don't.
+
+<!-- SECTION: map -->
+## Phase B — map references onto the new carousel, role to role
+
+Match by ROLE and FORMAT, never image-to-image: your cover should do what
+the reference cover does, your closer what their closer does, and every
+middle slide should follow the references' middle-slide format. Your slide 3
+does not need to mirror reference slide 3.
+
+- **Colors**: if the user's photos share a coherent palette (e.g. they are
+  all sunsets, all one product line), sample the carousel's colors from THE
+  USER'S PHOTOS so the deck feels made from their images. If the photos are
+  visually unrelated, keep the references' original colors. Never mix in
+  colors from anywhere else.
+- **Variance**: whatever varied across the references may vary across your
+  slides the same way — swatch counts, overlay side, crop tightness. Do not
+  make every slide identical when the references weren't.
+- **Overlay placement**: follow the coverage behavior recorded in Phase A.
+  If the references keep overlays clear of the subject, look at each of the
+  user's photos (and what the user's prompt says the photo is about) and
+  place overlays on the empty side — use `variant: flip` on a slide to
+  mirror a template's overlay to the other side. If the references overlay
+  the photo deliberately, do the same.
+- **Photo count adaptation** — the references decide the slide mix:
+  - More photos than slides: choose the photos that best serve each slide's
+    message, but if the user's prompt asks to show something specific, the
+    photo showing it MUST be used.
+  - Fewer photos than the format wants: if the references put a photo on
+    every slide, reuse a photo with a DIFFERENT focus/zoom crop so it reads
+    as a new frame; if the references include photo-free formats (statement
+    slides, text slides), use those instead. Never pad with invented filler
+    content.
+
+<!-- SECTION: compare -->
+## Phase C — compare each rendered slide against the references
+
+For each rendered slide, find the reference(s) with the same ROLE (slide 1 =
+cover, last slide = CTA/closer, everything else = middle) and ask:
+
+- **Same-account test**: if this slide were posted next to the references,
+  would it read as the same account's work — same format, same typographic
+  voice, same palette logic? Exact alignment with any single reference is
+  NOT required; matching the format is.
+- **Overlay-behavior test**: does the slide follow the references' coverage
+  behavior? If they keep overlays off the subject, is this slide's subject
+  (or a face) hidden under a swatch stack, badge, or caption? If so it
+  fails — fix with `variant: flip` (mirror the overlay side) or a focus/zoom
+  change that moves the subject clear.
+- **Framing test**: is the thing the slide is about actually prominent and
+  centered by the crop, exactly as the reference format frames its subjects?
+
+Fix vocabulary (per slide): `focus` ("X% Y%" on the original photo),
+`zoom` (1–3), `variant: flip` (mirror the overlay side), `swatches`
+(recount/recolor a swatch list — only on slides that already have one).
+Never rewrite a slide's text or switch its template during comparison.
+
+<!-- SECTION: overlay-analyze -->
+## Overlay Phase A — understand what the references are DOING
+
+These are frames from reels (or screenshots of them) with text or graphics laid
+over footage. For the set, work out:
+
+- **Format**: what one episode of this is — a question, a hot take, a stat, a
+  quote, a before/after label? That is what the fields should capture.
+- **Hierarchy**: what the eye reads first, second, third, and how that is
+  achieved (size, weight, colour, a box, a bar, a label above the main line).
+- **Type**: weight, case, letter-spacing, serif vs sans vs mono, line length,
+  how many lines the main text runs to.
+- **Containers**: solid box, translucent scrim, outline, shadow only, or text
+  straight on footage — and corner radius, border, padding.
+- **Placement**: where on the 9:16 frame each element sits, and how much of
+  the frame the overlay takes. Note anything placed where Instagram's UI would
+  cover it — keep the format but move it into the safe band.
+- **Colour logic**: which colours are fixed accents and which come from the
+  footage; how contrast is kept over busy or bright video.
+- **Variance vs constants** across the set (see Principles).
+
+<!-- SECTION: overlay-compare -->
+## Overlay Phase C — compare the rendered frame against the references
+
+Look at the rendered frame (sample text in every field, over grey) next to the
+references and ask:
+
+- **Same-account test**: would this sit next to the references as the same
+  series? Same format, hierarchy, type treatment, container style, colour
+  logic.
+- **Hierarchy test**: does the eye land where it lands in the references, in
+  the same order?
+- **Proportion test**: is the overlay roughly the size the references use — not
+  a tiny label where they fill the band, not a slab where they are a caption?
+- **Legibility test**: would it read over ANY footage, on a phone at arm's
+  length? Thin text straight on video fails.
+- **Safe-area test**: is anything in Instagram's top bar, right action rail or
+  bottom caption zone?
+
+Fix by editing the templates (sizes, weights, spacing, colours, containers,
+widthPct, anchor). Never change field keys, the content brief, or wording that
+the user typed or asked for.
+