gooseworks 0.4.2 → 0.4.4

package/skills/gooseworks/SKILL.md

@@ -5,6 +5,7 @@ description: >
   GooseWorks growth coworker and specialist-skill router. Research brands, customers, competitors,
   creators, markets, and prospects; analyze ads and performance; create ads, product photos,
   graphics, and video; search and scrape public web and social data; find and enrich leads.
+  Capture founder answers, brand rules, audience depth, and video taste in the existing brand.
   Use it as the single GooseWorks entry point for brand growth, B2B, sales, research, and GTM work.
 category: general
 version: 1.0.0
@@ -18,15 +19,72 @@ You have access to GooseWorks — an AI coworker with specialist skills for rese
 
 This skill is also the **parent router** for the GooseWorks family. Data/GTM work you handle here (see "How to Use"); specialized work you hand off to a dedicated `goose-*` skill.
 
+## How to talk to the customer (applies to every message you send them)
+
+The customer is a marketer or founder, not an engineer. Everything in this skill about tools,
+fields, files, polling, models and pipeline steps is for YOU. Never pass it on to them.
+
+- **Say what they get and what they need to decide, never how it's made.**
+  Bad: "Checking the media-proxy helpers for voiceover timestamps and lipsync." / "Generated with
+  gpt-image-2 at high quality, mouth closed, passes QC."
+  Good: "Recording the voices now." / "Here are your two hosts."
+- **Never mention** tool, file or field names, ids, JSON, commands, scripts, installed software,
+  uploads, model or vendor names, timings in seconds or frames, retries, polling, internal statuses
+  or your own quality checks. Fix what you can quietly. If they ask how something works, explain it
+  simply.
+- **Update them only at milestones they care about**: choices confirmed, script and voices done,
+  visuals done, ready to review, finished. One short line each, then stay quiet until the next
+  milestone. No update for setup, downloads, uploads or saving.
+- **Money is in credits, with a number**: "the full video uses about N credits". Never "the cheap
+  pieces" or "the expensive render".
+- **Problems:** say what it means for them and what they can do, in one or two sentences. No error
+  codes or stack traces. Only raise a problem that changes something for them.
+- **Use their words**: script, voice, hook, scene, host, ending, logo, the product shot.
+- **No filler**: no "Great question!", "Certainly!", "I hope this helps!", no restating what they
+  just said at length.
+
+Example. Instead of a dozen lines about render tools, scripts, uploads and portraits, send:
+"Got it: warm tone, home podcast studio, Brielle as the skeptic and Mark as the believer." then
+"Script and voices are done (about 34 seconds)." then "Ready for you to review: the script, voices,
+both hosts and the ending. You can also review your recipe ingredients in the app: <link>. Say go
+here and I'll make the full video (about N credits)."
+
+## Use current instructions for new work
+
+Before a new task in a terminal host, run `gooseworks skills status` once. It compares the
+installed entry files, running CLI and published npm release. An older CLI needs a package
+upgrade before `gooseworks update`; update alone only uses that CLI's bundled instructions.
+Preserve local edits or unknown install provenance. Review/back up before explicitly replacing
+modified files; never quietly reinstall over them. If the release check is unavailable, report
+that freshness is unknown rather than claiming the local copy is latest.
+
+For a new recipe run, fetch its package from the connected catalog. Retain the returned
+`version` / `contentHash` and every dependency's hash with the saved package. When reusing a
+saved fetch JSON, `gooseworks fetch <slug> --saved-package <file>` returns the current package
+and a hash comparison without changing that file. With MCP, if the advertised `catalog_fetch`
+schema accepts them, send `saved_content_hash` and `saved_dependency_hashes`; otherwise fetch
+normally and compare the returned hashes yourself. Missing hashes mean unknown, not current.
+The server cannot inspect a client's saved files; hash metadata does not certify later edits.
+Fetch current packages into a new run directory and report stale saved instructions. Preserve
+an existing approved run's recorded package; changing that harness requires a reviewed change
+and approval before spending. Hosted installed snapshots use the existing Skills Update action.
+Skill content and a host's cached MCP tool schemas are separate: refreshing one does not refresh
+the other. Check the actual advertised tools before using new fields.
+
 ## Route to the right skill FIRST
 
 First apply the **Common company onboarding** gate below. Preserve the user's original request while onboarding, then continue with it as soon as onboarding is complete. Then load the brand context (**"Load the brand context FIRST"**, immediately below). After that, check whether the request belongs to a specialized domain. If so, **switch to that skill** instead of the data flow below:
 
+For "interview me about the brand", "save our brand rules", "refine our audience", or "remember
+our video taste", stay here and follow **Guided brand capture** below. This extends the current
+brand and onboarding flow; it does not create another onboarding checklist.
+
 | If the user wants… | Route to | How |
 | --- | --- | --- |
 | Remix/make an ad, research a brand for ads, OR analyze ad performance — Meta/Google ad campaigns, creative fatigue, CAC/lead quality, competitor ad intel, ad angles & hooks | **`goose-ads`** | Installed locally as an entry skill. Just use it. If unavailable, run `gooseworks install --claude`. |
 | Charts, infographics, slides, social graphics, branded visual designs from a style/format | **`goose-graphics`** | If installed locally, use it. Otherwise `gooseworks fetch goose-graphics` (or `gooseworks install --claude --with goose-graphics`). |
-| Order a **video** ad in chat — "make me a video ad for <brand>", a UGC / iMessage / explainer video; renders on the GooseWorks server | **`goose-video`** | Installed locally as an entry skill. Just use it. If unavailable, run `gooseworks install --claude`. |
+| Make a **video** ad from a template or an original brief. Template-free briefs and Instagram/direct video references route to make-custom-video. Growth renders in its sandbox; connected coding agents use their local toolchain. | **`goose-video`** | Installed locally as an entry skill. Just use it. If unavailable, run `gooseworks install --claude`. |
+| Create an original branded video without a template, adapt an Instagram/direct video reference, or resume a generated custom project; separate Studio script and ingredient approvals are required | **`make-custom-video`** | Use the installed GooseWorks connection entry, or fetch make-custom-video through the catalog. It loads video-production-harness; Growth uses its sandbox and connected agents use their local tools. |
 | Render an EXISTING app video project or batch on this machine — the app's "copy for Claude" command names it | **`goose-video-local`** | Installed locally as an entry skill. Just use it. If unavailable, run `gooseworks install --claude`. |
 | Make **product photos** — studio, lifestyle, marketplace, social, or on-model product photography | **`goose-product-photos`** | Installed locally as an entry skill. Just use it. If unavailable, run `gooseworks install --claude`. |
 | Animate an approved static ad or product image | **`animate-image`** | Fetch with `gooseworks fetch animate-image` and follow its GooseWorks MCP workflow. |
@@ -36,7 +94,7 @@ Examples — all of these route to `goose-ads`, not the data flow: "remix this a
 
 ## Load the brand context FIRST (mandatory — before you route, and before you ask anything)
 
-**Call `brand_get_context` before the first substantive step of ANY task**, and before you route to a specialist skill. It is a cheap, read-only call that returns the brand's canonical facts:
+**Call `brand_read { brand_id, sections: ["summary", "kit", "products", "learnings", "onboarding"] }` before the first substantive step of ANY task**, and before you route to a specialist skill. Older clients can use `brand_get_context` with the same sections only when that tool is advertised. It is a read-only call that returns the brand's canonical facts and saved rules:
 
 | It returns | Use it for |
 | --- | --- |
@@ -51,8 +109,8 @@ Then:
 1. **Pass what it returned INTO the routed skill.** When you hand off to `goose-ads`, `goose-video`, `goose-product-photos`, `goose-graphics`, or a fetched Brand Growth recipe, carry the voice / products / audience / positioning with you. Do **not** make the routed skill re-derive them, and do **not** re-run brand research when the context is already there.
 2. **Never re-ask the user for something the brand context already answers.** If a routed skill's own prose asks a question the context answers, the context wins — answer it yourself and move on. Ask only for what is genuinely missing or ambiguous.
 3. **If research status is not complete**, say so in one line, use what you have, and continue. Only run brand research when the context comes back empty or the user asks for it.
-4. **If `brand_get_context` is unavailable** (no MCP connection), fall back to `get_brand_kit` for the selected brand and treat its fields the same way. If neither is available, tell the user the GooseWorks MCP connection is needed rather than guessing brand facts.
-5. **Treat it as read-only.** Writing brand facts back is the reconciliation flow in `goose-ads` (ask first, then `update_brand_kit`) — not something this router does.
+4. **If `brand_read` is unavailable**, refresh the GooseWorks connection or tool list. An older connection may expose `brand_get_context` / `get_brand_kit`; use those only when actually advertised. Never require a legacy tool name or guess brand facts.
+5. **A read grants no write permission.** Save explicit durable answers/corrections with the capture policy below. Propose agent-derived changes for review; never overwrite confirmed knowledge with research or a guess.
 
 Never invent a brand fact. If it isn't in the brand context and the user hasn't said it, ask.
 
@@ -109,16 +167,144 @@ When onboarding returns a review link, show that single link and ask the user to
 Use the host's native question controls. Ask one short group at a time and rely on the live tool schema for accepted values.
 
 1. **Start** — If status returns `start`, ask for the company website or Apple App Store URL. Also offer the optional hero product URL and “Where do you do your work?” choices: Slack, WhatsApp, iMessage, Claude Code, Claude, Codex, and ChatGPT. Call `action: "start"`; server-side research begins immediately. If status returns `select_brand`, ask which company/client to use. Otherwise reuse the only brand automatically.
-2. **Your coworker** — Ask what they want to name their Growth Coworker. A text-only client may keep the default avatar; do not block on an image. Save with `action: "save_coworker"`.
-3. **Your company** — Use the returned `company_draft` as the starting point and ask the user to verify or edit: what they sell (`marketCategory`), where people buy (`appPlatforms`), primary customer, customer problem, promised outcome, and optional differentiator. Save with `action: "save_company"`.
-4. **Your taste** — In a terminal or CLI host, use the returned `taste_url`: open it when the host supports opening links and always show one clickable **Choose your taste in GooseWorks** link. Ask the user to heart or skip ads on that page, click **Continue** or **Skip this**, return to the agent, and reply `done`. Do not print, enumerate, or summarize `taste_deck` in the terminal. After `done`, call `brand_onboarding { action: "status" }` again and follow the refreshed `next_step`. In a chat host that renders images, show only the one image attached by the tool and save each Love/Skip decision with `action: "save_taste"`; send `complete: true` after three hearts or an explicit skip.
-5. **First campaign** — Ask **“What’s happening right now?”**: launch `launch`, promotion `promo`, seasonal moment `seasonal`, or nothing special `nothing`, plus an optional note. Call `action: "propose_campaign"`, show the returned editable card (name, objective, offer, audience, 2–3 angles, CTA, and product URL), and save edits with `action: "save_campaign"`. Send `accept: true` only after approval; acceptance can start the complimentary first creatives.
-6. **Where you are** — Ask monthly ad spend (`none`, `under_1k`, `1k_5k`, `5k_25k`, `25k_plus`), annual revenue (`under_1m`, `1m_10m`, `10m_100m`, `100m_plus`), the 90-day goal, current channels (an empty list is a valid “nothing yet”), and at least one channel they are willing to use. Channel values: `paid_social`, `search_ads`, `content`, `creators`, `seo`, `communities`, `referrals`, `partnerships`, `outbound`, `app_stores`, `other`. Save with `action: "save_progress"`.
-7. **Review** — Show the returned founder, researched, and inferred facts with their provenance. The user may correct positioning, audience, voice, value propositions, proof points, or competitors through `action: "review_research"`. Complete the review even when research is still running, failed, or sparse; never trap the user waiting for it.
-8. **Channels** — If `channel_connected` is already true, this is complete automatically. Otherwise ask whether they want to connect Slack, WhatsApp, or iMessage later, or skip for now. An explicit skip is valid; call `action: "complete_channels"`.
+2. **Your coworker** — The current flow accepts the default coworker automatically. If an older session returns `coworker`, refresh `status`; do not introduce a naming/avatar question. Rename only when the user asks and the live tool supports it.
+3. **Your company** — Use the returned `company_draft` plus the user's existing answers. Ask only to verify missing or ambiguous details: what they sell (`marketCategory`), where people buy (`appPlatforms`), primary customer, customer problem, promised outcome, and optional differentiator. Monthly Meta ad spend belongs here when absent: `none`, `under_10k`, `10k_50k`, `50k_150k`, `150k_plus`, or `not_sure`. Save the merged required company object with `action: "save_company", company: { … }`; read `status` back.
+4. **Your taste** — In a terminal or CLI host, use the returned `taste_url`: open it when the host supports opening links and always show one clickable **Choose your taste in GooseWorks** link. Ask the user to heart or skip ads on that page, click **Continue** or **Skip this**, return to the agent, and reply `done`. Do not print, enumerate, or summarize `taste_deck` in the terminal. After `done`, call `brand_onboarding { action: "status" }` again and follow the refreshed `next_step`. In a chat host that renders images, show only the one image attached by the tool and save each Love/Skip decision with `action: "save_taste", taste: { hearted_ids, skipped_ids, complete }`; set `taste.complete: true` after three hearts or an explicit skip.
+5. **First campaign** — Ask **“What’s happening right now?”**: launch `launch`, promotion `promo`, seasonal moment `seasonal`, or nothing special `nothing`, plus an optional note. Call `action: "propose_campaign"`, show the returned editable card (name, objective, offer, audience, 2–3 angles, CTA, and product URL), and save edits with `action: "save_campaign"`. Send `campaign.accept: true` only after approval; acceptance can start the complimentary first creatives.
+6. **Review** — Show the returned founder, researched, and inferred facts with their provenance. The user may correct positioning, audience, voice, value propositions, proof points, or competitors through `action: "review_research", review: { action: "correct", field, value }`. A proof-point edit does not approve a claim. Complete with `review: { action: "complete" }` even when research is still running, failed, or sparse; never trap the user waiting for it.
+7. **Channels** — If `channel_connected` is already true, this is complete automatically. Otherwise ask whether they want to connect Slack, WhatsApp, or iMessage later, or skip for now. An explicit skip is valid; call `action: "complete_channels"`.
+
+The former revenue / 90-day-goal / `save_progress` screen is retired. Do not insert it into
+onboarding. Ask those human-only questions later only when the user's task needs them.
 
 Do not ask for role, discovery source, who makes creatives, who manages ads, or a separate “what do you want to do first?” menu. Those belonged to the retired CLI questionnaire. The task the user already asked for is their first task.
 
+## Guided brand capture
+
+Use this when the user requests a founder interview, audience/rules capture, or video taste.
+Keep their original task pending. Load the current brand first, compare it with information
+already volunteered in this chat, and **save known information first** using the canonical
+mapping below. Do not run a long questionnaire as a prerequisite for making an ad.
+
+For facts needed by the task but absent from the read, call `knowledge_search` first if it is
+registered. Use returned citations and states honestly: an empty, building or failed index is
+not proof that the brand has no answer. Do not re-scrape or ask the founder for a fact already
+answered by trustworthy saved knowledge.
+
+Ask one short group of missing human-only facts at a time, in plain language, with the relevant
+known answer in that same question. "Skip" or "not sure" is valid. Examples, **only for gaps**:
+
+| Gap | Useful question |
+| --- | --- |
+| Founder origin or conviction | "What made you start this, and what do you believe that alternatives get wrong?" |
+| Audience depth | "Who buys first, what problem pushes them to act, and what nearly stops them?" |
+| Buying trigger or alternatives | "What happens just before they look for you, and what do they use instead?" |
+| Rules | "What must we always say or show, and what must we never say or imply?" |
+| Proof | "What evidence supports that result, and do we have permission to quote the customer?" Keep unsupported claims pending. |
+| Video taste | "Share a video you like and what you would keep or avoid: pace, voice, captions, or look." |
+
+Keep skipped or uncertain answers as gaps in the brief; do not save them as confirmed facts.
+Save each answered group and read it back before the next group. Stop when the requested capture
+is covered or the user skips; resume from canonical saved answers after interruption. Present a
+short brief containing verified answers, attribution, pending proposals and remaining gaps, then
+continue the original task. Review happens in this chat plus any proposal review link returned
+by the tools. Do not promise an unavailable evidence, claims or plan write.
+
+## Save durable brand answers, then verify them
+
+Read the selected brand with `brand_read { brand_id, sections: ["summary", "kit", "products", "learnings", "onboarding"] }`
+(fallback: `brand_get_context` with the same sections). Keep founder answers, user corrections,
+research and your own hypotheses distinct. Reuse matching saved answers; ask only about gaps.
+
+When the user asks to remember a rule, answers a brand interview, or explicitly corrects a
+standing fact, save that answer in the same turn. The capture request authorizes those answers;
+do not ask for approval again. A direction for this one video stays in its brief. If the scope
+is genuinely ambiguous, ask whether it applies to future videos before saving a standing rule.
+
+Use the **live registered schema**. Where supported, call `brand_update` with
+`knowledge_intent: "user_correction"` and `user_statement` containing the user's exact,
+verbatim answer, not your paraphrase or researched text.
+For an inference or suggested improvement, use `knowledge_intent: "agent_proposal"`. Show the
+before/after change from your prior read and proposed value; retain the returned proposal IDs
+and say the user must accept it in the app. Link only a review surface actually returned by a
+tool; the compact `knowledge_updates` response does not itself contain a diff or URL.
+A pending proposal is not a saved fact. Never call an unavailable
+tool or silently relabel research or your inference as something the user said.
+
+The safe structured shape is `patch: { knowledge: { positioning?, audience?, voice?,
+instructions?, brandType?, tagline?, valueProps? } }`, using only fields present in the live
+schema. Inferred rules/taste go in an `instructions` proposal with a rationale, never in
+`patch.facts`. Prefix every video-only preference in that proposed text with "Video preference:"
+so it remains production direction after acceptance. Preserve unrelated instructions when
+proposing a merged replacement.
+
+| User answer | Canonical write |
+| --- | --- |
+| Primary audience, positioning or voice correction | `patch.knowledge: { audience/positioning/voice: <answer> }` (one actual key). During onboarding, `brand_onboarding { action: "review_research", review: { action: "correct", field, value } }` writes these existing corrections with provenance. |
+| Founder story, customer pains, objections, buying trigger or useful audience detail without a structured field | `patch.facts: [{ kind: "insight", text }]`; retain attribution such as "Founder reports: …" rather than turn a belief into a verified result. |
+| Required wording or pronunciation | `patch.facts: [{ kind: "must", text }]`; pronunciation is exactly `Pronounce "<term>" as "<say_as>"`. |
+| Forbidden claim, word or visual | `patch.facts: [{ kind: "dont", text }]`. |
+| Durable visual, voice or pacing preference | `patch.facts: [{ kind: "do", text }]` for a preference; `dont` for an avoidance; `template_hint` for a preferred format. Prefix video-only preferences with "Video preference:". |
+
+Facts are existing `ad_brand_learning` rows with user provenance; they are not a second profile.
+Update a matching rule by its returned `id` instead of adding duplicates. Preserve unrelated
+rules and the user's exact meaning. Only use the legacy facts shape for explicitly user-authored
+answers when the live schema lacks intent fields; agent suggestions still need a proposal path.
+
+**Claims and plans have separate gates.** A founder assertion or proof point is not an approved,
+evidence-backed claim or consent to quote a customer. Use the existing evidence/claims and
+operating-plan tools only if registered, following their proposal, evidence and confirmation
+requirements. Never encode a spend cap, approver or emergency stop as a learning. If that write
+path is missing, report the specific unsaved item and keep it pending for the supported review
+surface; do not claim it was saved or create a parallel local profile.
+
+After every write, **read back before saying saved**: use `brand_read` with `kit`, `learnings`
+or `onboarding` as appropriate, or `brand_onboarding { action: "status", brand_id }` after an
+onboarding answer. Verify the intended field/rule, its source and the absence of a conflicting
+duplicate. A generic success response, pending proposal, ignored key or truncated result is not
+proof. Report partial saves honestly. Carry the verified rules into the current task and the
+routed skill; claims still pass their own safety gate.
+
+## Video taste — reuse examples and preferences
+
+When asked to capture video taste, or when the user volunteers a durable video preference,
+first read the saved learnings and `media_list { brand_id, scope: "brand", scope_id: brand_id,
+tags: ["video-taste"], limit: 100 }`. Follow `next_cursor` before deciding an example is absent.
+Do not force a taste interview before an unrelated task or ask again for an existing preference.
+
+Save what the user has already supplied first. Then ask only the missing useful question, for
+example: "What do you like about this video—its pace, voice, captions, or look?" An inaccessible
+link can still be saved as a link with the user's explanation; do not pretend you watched it.
+
+- **Direct clip or video file:** register with `media_upload { brand_id, scope: "brand",
+  scope_id: brand_id, kind: "video", source: { type: "url", url }, tags: ["video-taste", "reference-only"],
+  metadata: { purpose: "video_taste", source_url: url, provenance: "user", captured_at: <ISO timestamp>,
+  preference: <the user's explanation> } }`. For a file use the live file/bytes upload flow and
+  `media_confirm` after a presigned upload. Registration of a URL does not copy or inspect it.
+- **Instagram/post/page link:** the same registration with `kind: "document"`; it is a link
+  bookmark, not downloadable footage or an indexed transcript. Do not fabricate a direct clip URL.
+- **Preferences:** save the user's reasons, likes and dislikes through the facts mapping above.
+  Read and preserve existing facts before updating one. Do not invent `video_preferences` or
+  new `video_lab` keys; the live kit patch accepts only its documented asset fields.
+- **Deduplicate:** reuse a matching returned media row, then `media_update` its title/tags/metadata
+  if needed; preserve existing metadata and tags. Do not create another row for the same example.
+  Read back with `media_list` and `brand_read` learnings before claiming it was saved.
+  Check the returned row belongs to this brand: URL deduplication may return another brand's
+  existing row. Do not relabel that row or claim success unless the current brand's scoped read
+  actually returns it. Report an unsaved association if no supported attach path is available.
+
+Never put third-party taste examples into kit reference images: `kind: "reference"` at brand
+scope writes there. The tags and metadata above record purpose and provenance; **they do not
+grant or enforce usage rights**. Study the structure, pacing and look only. Never use the example's
+footage, face, product, testimonial or claims in a new ad without independently verified permission.
+
+Read video-only entries prefixed `Video preference:` from both saved learnings and
+`kit.instructions`, including accepted proposals. Keep them out of required or forbidden
+dialogue. Build a brief from the verified readback: preferred pace, voice, caption treatment, visual style,
+formats to favour/avoid, reference links and the user's reasons. Say what is still unknown.
+Pass it with the brand rules into the existing video workflow. A one-video request overrides a
+default for that project; it does not silently rewrite the brand's standing preference.
+
 ## Brand Growth discovery
 
 Brand Growth is a collection inside the normal skill catalog, not a command or installable pack. Use these known routes when relevant, while preserving all existing B2B, sales, research, lead-generation, and data behavior:
@@ -140,7 +326,7 @@ Brand Growth is a collection inside the normal skill catalog, not a command or i
 | Written content and repurposing | `content-repurposing` |
 | Graphics and animation | `goose-graphics`, `animate-image` |
 
-Fetch the named public skill before following it. You already called `brand_get_context` — hand the brand's voice, products, audience, and positioning to the fetched skill instead of letting it re-derive or re-ask them. Provider helpers such as `scrapecreators-api` and `transcript-intelligence` are dependencies, not user-facing results.
+Fetch the named public skill before following it. You already called `brand_read` — hand the brand's voice, products, audience, and positioning to the fetched skill instead of letting it re-derive or re-ask them. Provider helpers such as `scrapecreators-api` and `transcript-intelligence` are dependencies, not user-facing results.
 
 For a multi-part request, repeat this routing check before each new job. Fetch and follow the
 closest outcome skill first (for example, `comment-mining`, `creator-profile-teardown`, or
@@ -270,7 +456,7 @@ The `gooseworks` CLI sends authenticated requests (Bearer `GOOSEWORKS_API_KEY`)
 
 ## Rules
 
-0. **Call `brand_get_context` before anything else**, pass what it returns into whatever skill you route to, and never re-ask the user for a fact it already answers (see "Load the brand context FIRST").
+0. **Read the canonical brand context before substantive work**, pass what it returns into whatever skill you route to, and never re-ask the user for a fact it already answers (see "Load the brand context FIRST").
 1. **Consider a GooseWorks skill when it fits the task** — scraping, research, lead gen, enrichment, especially at scale, behind auth, or from a specific source. For a quick lookup your built-in tools are fine; use your judgement and pick the best tool for the user.
 2. **Before paid operations**, tell the user the estimated credit cost
 3. **If a `gooseworks` command exits with "Not logged in"**: tell the user to run `npx gooseworks login`