gooseworks 0.5.0-dev.9.d3e7757f → 0.5.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 +17 -26
- package/dist/auth/device-flow.d.ts +10 -0
- package/dist/auth/device-flow.d.ts.map +1 -1
- package/dist/auth/device-flow.js +39 -1
- package/dist/auth/device-flow.js.map +1 -1
- package/dist/commands/doctor.d.ts.map +1 -1
- package/dist/commands/doctor.js +3 -1
- package/dist/commands/doctor.js.map +1 -1
- package/dist/commands/video.d.ts +5 -0
- package/dist/commands/video.d.ts.map +1 -0
- package/dist/commands/video.js +117 -0
- package/dist/commands/video.js.map +1 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +5 -2
- package/dist/config.js.map +1 -1
- package/dist/environment.d.ts.map +1 -1
- package/dist/environment.js +4 -2
- package/dist/environment.js.map +1 -1
- package/dist/kit/core/bind.d.ts +12 -0
- package/dist/kit/core/bind.d.ts.map +1 -0
- package/dist/kit/core/bind.js +77 -0
- package/dist/kit/core/bind.js.map +1 -0
- package/dist/kit/core/canonical.d.ts +30 -0
- package/dist/kit/core/canonical.d.ts.map +1 -0
- package/dist/kit/core/canonical.js +67 -0
- package/dist/kit/core/canonical.js.map +1 -0
- package/dist/kit/core/check.d.ts +22 -0
- package/dist/kit/core/check.d.ts.map +1 -0
- package/dist/kit/core/check.js +53 -0
- package/dist/kit/core/check.js.map +1 -0
- package/dist/kit/core/device.d.ts +17 -0
- package/dist/kit/core/device.d.ts.map +1 -0
- package/dist/kit/core/device.js +153 -0
- package/dist/kit/core/device.js.map +1 -0
- package/dist/kit/core/errors.d.ts +22 -0
- package/dist/kit/core/errors.d.ts.map +1 -0
- package/dist/kit/core/errors.js +49 -0
- package/dist/kit/core/errors.js.map +1 -0
- package/dist/kit/core/files.d.ts +49 -0
- package/dist/kit/core/files.d.ts.map +1 -0
- package/dist/kit/core/files.js +213 -0
- package/dist/kit/core/files.js.map +1 -0
- package/dist/kit/core/host.d.ts +26 -0
- package/dist/kit/core/host.d.ts.map +1 -0
- package/dist/kit/core/host.js +10 -0
- package/dist/kit/core/host.js.map +1 -0
- package/dist/kit/core/log.d.ts +17 -0
- package/dist/kit/core/log.d.ts.map +1 -0
- package/dist/kit/core/log.js +82 -0
- package/dist/kit/core/log.js.map +1 -0
- package/dist/kit/core/paths.d.ts +27 -0
- package/dist/kit/core/paths.d.ts.map +1 -0
- package/dist/kit/core/paths.js +103 -0
- package/dist/kit/core/paths.js.map +1 -0
- package/dist/kit/core/pieces.d.ts +84 -0
- package/dist/kit/core/pieces.d.ts.map +1 -0
- package/dist/kit/core/pieces.js +374 -0
- package/dist/kit/core/pieces.js.map +1 -0
- package/dist/kit/core/progress-reporter.d.ts +30 -0
- package/dist/kit/core/progress-reporter.d.ts.map +1 -0
- package/dist/kit/core/progress-reporter.js +106 -0
- package/dist/kit/core/progress-reporter.js.map +1 -0
- package/dist/kit/core/progress.d.ts +22 -0
- package/dist/kit/core/progress.d.ts.map +1 -0
- package/dist/kit/core/progress.js +90 -0
- package/dist/kit/core/progress.js.map +1 -0
- package/dist/kit/core/run.d.ts +35 -0
- package/dist/kit/core/run.d.ts.map +1 -0
- package/dist/kit/core/run.js +850 -0
- package/dist/kit/core/run.js.map +1 -0
- package/dist/kit/core/save.d.ts +43 -0
- package/dist/kit/core/save.d.ts.map +1 -0
- package/dist/kit/core/save.js +265 -0
- package/dist/kit/core/save.js.map +1 -0
- package/dist/kit/core/schema.d.ts +5 -0
- package/dist/kit/core/schema.d.ts.map +1 -0
- package/dist/kit/core/schema.js +183 -0
- package/dist/kit/core/schema.js.map +1 -0
- package/dist/kit/core/secrets.d.ts +9 -0
- package/dist/kit/core/secrets.d.ts.map +1 -0
- package/dist/kit/core/secrets.js +60 -0
- package/dist/kit/core/secrets.js.map +1 -0
- package/dist/kit/core/style.d.ts +59 -0
- package/dist/kit/core/style.d.ts.map +1 -0
- package/dist/kit/core/style.js +179 -0
- package/dist/kit/core/style.js.map +1 -0
- package/dist/kit/core/toolchain.d.ts +52 -0
- package/dist/kit/core/toolchain.d.ts.map +1 -0
- package/dist/kit/core/toolchain.js +321 -0
- package/dist/kit/core/toolchain.js.map +1 -0
- package/dist/kit/core/version.d.ts +18 -0
- package/dist/kit/core/version.d.ts.map +1 -0
- package/dist/kit/core/version.js +33 -0
- package/dist/kit/core/version.js.map +1 -0
- package/dist/kit/env.d.ts +42 -0
- package/dist/kit/env.d.ts.map +1 -0
- package/dist/kit/env.js +76 -0
- package/dist/kit/env.js.map +1 -0
- package/dist/kit/line/client.d.ts +82 -0
- package/dist/kit/line/client.d.ts.map +1 -0
- package/dist/kit/line/client.js +325 -0
- package/dist/kit/line/client.js.map +1 -0
- package/dist/kit/line/types.d.ts +178 -0
- package/dist/kit/line/types.d.ts.map +1 -0
- package/dist/kit/line/types.js +18 -0
- package/dist/kit/line/types.js.map +1 -0
- package/dist/kit/maker/browser.d.ts +114 -0
- package/dist/kit/maker/browser.d.ts.map +1 -0
- package/dist/kit/maker/browser.js +547 -0
- package/dist/kit/maker/browser.js.map +1 -0
- package/dist/kit/maker/encode.d.ts +27 -0
- package/dist/kit/maker/encode.d.ts.map +1 -0
- package/dist/kit/maker/encode.js +58 -0
- package/dist/kit/maker/encode.js.map +1 -0
- package/dist/kit/maker/images.d.ts +14 -0
- package/dist/kit/maker/images.d.ts.map +1 -0
- package/dist/kit/maker/images.js +174 -0
- package/dist/kit/maker/images.js.map +1 -0
- package/dist/kit/maker/inputs.d.ts +81 -0
- package/dist/kit/maker/inputs.d.ts.map +1 -0
- package/dist/kit/maker/inputs.js +235 -0
- package/dist/kit/maker/inputs.js.map +1 -0
- package/dist/kit/maker/make.d.ts +19 -0
- package/dist/kit/maker/make.d.ts.map +1 -0
- package/dist/kit/maker/make.js +272 -0
- package/dist/kit/maker/make.js.map +1 -0
- package/dist/kit/maker/page.d.ts +19 -0
- package/dist/kit/maker/page.d.ts.map +1 -0
- package/dist/kit/maker/page.js +276 -0
- package/dist/kit/maker/page.js.map +1 -0
- package/dist/kit/maker/parts/html-frames/1.0.0/part.json +183 -0
- package/dist/kit/maker/parts/html-frames/src/part.d.ts +3 -0
- package/dist/kit/maker/parts/html-frames/src/part.d.ts.map +1 -0
- package/dist/kit/maker/parts/html-frames/src/part.js +10 -0
- package/dist/kit/maker/parts/html-frames/src/part.js.map +1 -0
- package/dist/kit/maker/runtime.d.ts +7 -0
- package/dist/kit/maker/runtime.d.ts.map +1 -0
- package/dist/kit/maker/runtime.js +571 -0
- package/dist/kit/maker/runtime.js.map +1 -0
- package/dist/kit/maker/unzip.d.ts +3 -0
- package/dist/kit/maker/unzip.d.ts.map +1 -0
- package/dist/kit/maker/unzip.js +133 -0
- package/dist/kit/maker/unzip.js.map +1 -0
- package/dist/kit/parts/catalog.d.ts +47 -0
- package/dist/kit/parts/catalog.d.ts.map +1 -0
- package/dist/kit/parts/catalog.js +198 -0
- package/dist/kit/parts/catalog.js.map +1 -0
- package/dist/kit/parts/fs-safe.d.ts +32 -0
- package/dist/kit/parts/fs-safe.d.ts.map +1 -0
- package/dist/kit/parts/fs-safe.js +185 -0
- package/dist/kit/parts/fs-safe.js.map +1 -0
- package/dist/kit/parts/loader.d.ts +50 -0
- package/dist/kit/parts/loader.d.ts.map +1 -0
- package/dist/kit/parts/loader.js +395 -0
- package/dist/kit/parts/loader.js.map +1 -0
- package/dist/kit/parts/semver.d.ts +6 -0
- package/dist/kit/parts/semver.d.ts.map +1 -0
- package/dist/kit/parts/semver.js +44 -0
- package/dist/kit/parts/semver.js.map +1 -0
- package/dist/program.d.ts.map +1 -1
- package/dist/program.js +6 -6
- package/dist/program.js.map +1 -1
- package/dist/skills/installer.d.ts +22 -0
- package/dist/skills/installer.d.ts.map +1 -1
- package/dist/skills/installer.js +56 -8
- package/dist/skills/installer.js.map +1 -1
- package/dist/skills/master-skill.d.ts +11 -70
- package/dist/skills/master-skill.d.ts.map +1 -1
- package/dist/skills/master-skill.js +120 -2900
- package/dist/skills/master-skill.js.map +1 -1
- package/dist/skills/package-freshness.d.ts +19 -0
- package/dist/skills/package-freshness.d.ts.map +1 -1
- package/dist/skills/package-freshness.js +37 -2
- package/dist/skills/package-freshness.js.map +1 -1
- package/dist/skills/routes.d.ts +7 -2
- package/dist/skills/routes.d.ts.map +1 -1
- package/dist/skills/routes.js +21 -25
- package/dist/skills/routes.js.map +1 -1
- package/dist/skills/server-entry-skills.d.ts +14 -0
- package/dist/skills/server-entry-skills.d.ts.map +1 -0
- package/dist/skills/server-entry-skills.js +119 -0
- package/dist/skills/server-entry-skills.js.map +1 -0
- package/dist/skills/staging-content.js +1 -1
- package/package.json +10 -6
- package/skills/goose-ads/SKILL.md +27 -605
- package/skills/goose-product-photos/SKILL.md +24 -217
- package/skills/goose-video/SKILL.md +23 -610
- package/skills/goose-video-local/SKILL.md +3 -1609
- package/skills/gooseworks/SKILL.md +58 -529
- package/skills/make-custom-video/SKILL.md +23 -725
- package/skills/manifest.json +7 -7
- package/skills/routes.json +10 -24
- package/dist/commands/video-local.d.ts +0 -9
- package/dist/commands/video-local.d.ts.map +0 -1
- package/dist/commands/video-local.js +0 -83
- package/dist/commands/video-local.js.map +0 -1
- package/dist/commands/video-save.d.ts +0 -3
- package/dist/commands/video-save.d.ts.map +0 -1
- package/dist/commands/video-save.js +0 -83
- package/dist/commands/video-save.js.map +0 -1
- package/dist/lib/video-local-captions.d.ts +0 -83
- package/dist/lib/video-local-captions.d.ts.map +0 -1
- package/dist/lib/video-local-captions.js +0 -261
- package/dist/lib/video-local-captions.js.map +0 -1
- package/dist/lib/video-local-runtime.d.ts +0 -8
- package/dist/lib/video-local-runtime.d.ts.map +0 -1
- package/dist/lib/video-local-runtime.js +0 -201
- package/dist/lib/video-local-runtime.js.map +0 -1
- package/dist/lib/video-save-mcp.d.ts +0 -9
- package/dist/lib/video-save-mcp.d.ts.map +0 -1
- package/dist/lib/video-save-mcp.js +0 -162
- package/dist/lib/video-save-mcp.js.map +0 -1
- package/dist/lib/video-save.d.ts +0 -77
- package/dist/lib/video-save.d.ts.map +0 -1
- package/dist/lib/video-save.js +0 -440
- package/dist/lib/video-save.js.map +0 -1
- package/dist/skills/custom-video-skill.d.ts +0 -3
- package/dist/skills/custom-video-skill.d.ts.map +0 -1
- package/dist/skills/custom-video-skill.js +0 -6
- package/dist/skills/custom-video-skill.js.map +0 -1
|
@@ -1,419 +1,43 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.
|
|
3
|
+
exports.KIT_MAKE_COMMAND = void 0;
|
|
4
4
|
exports.getEntrySkills = getEntrySkills;
|
|
5
5
|
exports.getEntrySkillNames = getEntrySkillNames;
|
|
6
6
|
exports.getMasterSkillContent = getMasterSkillContent;
|
|
7
7
|
exports.getGooseAdsSkillContent = getGooseAdsSkillContent;
|
|
8
|
-
exports.getGooseVideoSkillContent = getGooseVideoSkillContent;
|
|
9
|
-
exports.getGooseVideoLocalSkillContent = getGooseVideoLocalSkillContent;
|
|
10
8
|
exports.getGooseProductPhotosSkillContent = getGooseProductPhotosSkillContent;
|
|
9
|
+
exports.getGooseVideoSkillContent = getGooseVideoSkillContent;
|
|
11
10
|
exports.getMakeCustomVideoSkillContent = getMakeCustomVideoSkillContent;
|
|
11
|
+
exports.getGooseVideoLocalSkillContent = getGooseVideoLocalSkillContent;
|
|
12
12
|
/**
|
|
13
|
-
* The
|
|
14
|
-
*
|
|
15
|
-
* PLUS a domain router that hands ads/graphics/video work to the dedicated
|
|
16
|
-
* `goose-*` skills below.
|
|
17
|
-
* - `goose-ads` — the ads entry/contract (getGooseAdsSkillContent): ad creative
|
|
18
|
-
* (remix, brand research) AND ad analytics/intelligence. Formerly `ads-remix`.
|
|
19
|
-
* Each is a separate Claude Code skill; Claude auto-loads whichever matches the
|
|
20
|
-
* task by its description. They are domain-scoped on purpose — do NOT merge them.
|
|
13
|
+
* The entry skills the CLI installs into ~/.agents/skills/ and commits under
|
|
14
|
+
* skills/ (the backend serves the committed copies to chat apps):
|
|
21
15
|
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
16
|
+
* - `gooseworks` the router: hands specialist work to its skill and
|
|
17
|
+
* does data work with the gooseworks commands.
|
|
18
|
+
* - `goose-ads` image ads: make, edit and study them.
|
|
19
|
+
* - `goose-product-photos` product photos.
|
|
20
|
+
* - `goose-video`, `make-custom-video`
|
|
21
|
+
* our server's video entry skills, copied as built
|
|
22
|
+
* (server-entry-skills.ts). Every answer's next_step
|
|
23
|
+
* carries the step for the video's stage.
|
|
24
|
+
* - `goose-video-local` one line: run the kit when a next_step says so.
|
|
25
25
|
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
* - `goose-video-local` — render an existing app project/batch LOCALLY
|
|
31
|
-
* (Playwright + ffmpeg + media proxies) (getGooseVideoLocalSkillContent).
|
|
32
|
-
*
|
|
33
|
-
* Recipe skills (remix-graphic-ad-from-reference, brand-research, meta-ads-analyzer,
|
|
34
|
-
* …) are NOT vendored here — they live in goose-skills and are fetched live on
|
|
35
|
-
* demand from the connected catalog; saved packages retain their recorded hashes.
|
|
26
|
+
* Each skill names only the actions in the action contract, states no price,
|
|
27
|
+
* asks for no install and stays within the rulebook's size limit; the rules
|
|
28
|
+
* block of every skill comes from the rulebook (tests/skills/skill-lint.test.ts).
|
|
29
|
+
* Recipe skills live in goose-skills and are fetched when needed.
|
|
36
30
|
*/
|
|
37
31
|
const routes_1 = require("./routes");
|
|
38
|
-
const
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
* How every entry skill talks to the customer. Shared so the five skills can't
|
|
42
|
-
* drift. The customer is a marketer or founder, not an engineer: everything the
|
|
43
|
-
* skills say about tools, fields, polling and pipeline steps is for the agent,
|
|
44
|
-
* and a run that narrated it ("checking the media-proxy helpers for voiceover
|
|
45
|
-
* timestamps and lipsync", "generated with gpt-image-2") read as noise.
|
|
46
|
-
*/
|
|
47
|
-
const SKILL_FRESHNESS = `## Use current instructions for new work
|
|
48
|
-
|
|
49
|
-
Before a new task in a terminal host, run \`gooseworks skills status\` once. It compares the
|
|
50
|
-
installed entry files, running CLI and published npm release. An older CLI needs a package
|
|
51
|
-
upgrade before \`gooseworks update\`; update alone only uses that CLI's bundled instructions.
|
|
52
|
-
Preserve local edits or unknown install provenance. Review/back up before explicitly replacing
|
|
53
|
-
modified files; never quietly reinstall over them. If the release check is unavailable, report
|
|
54
|
-
that freshness is unknown rather than claiming the local copy is latest.
|
|
55
|
-
|
|
56
|
-
For a new recipe run, fetch its package from the connected catalog. Retain the returned
|
|
57
|
-
\`version\` / \`contentHash\` and every dependency's hash with the saved package. When reusing a
|
|
58
|
-
saved fetch JSON, \`gooseworks fetch <slug> --saved-package <file>\` returns the current package
|
|
59
|
-
and a hash comparison without changing that file. With MCP, if the advertised \`catalog_fetch\`
|
|
60
|
-
schema accepts them, send \`saved_content_hash\` and \`saved_dependency_hashes\`; otherwise fetch
|
|
61
|
-
normally and compare the returned hashes yourself. Missing hashes mean unknown, not current.
|
|
62
|
-
The server cannot inspect a client's saved files; hash metadata does not certify later edits.
|
|
63
|
-
Fetch current packages into a new run directory and report stale saved instructions. Preserve
|
|
64
|
-
an existing approved run's recorded package; changing that harness requires a reviewed change
|
|
65
|
-
and approval before spending. Hosted installed snapshots use the existing Skills Update action.
|
|
66
|
-
Skill content and a host's cached MCP tool schemas are separate: refreshing one does not refresh
|
|
67
|
-
the other. Check the actual advertised tools before using new fields.`;
|
|
68
|
-
const VIDEO_GUIDE_COMPATIBILITY = `**Follow the connector's full-guide requirement when available.** Fetch
|
|
69
|
-
\`catalog_fetch { type: "skill", slug: "gooseworks-guide" }\` when the connector requires it.
|
|
70
|
-
The only older-server exception is below; it never removes brand preparation or approvals.
|
|
71
|
-
|
|
72
|
-
| Returned guide/workflow state on the selected connection | Required action |
|
|
73
|
-
| --- | --- |
|
|
74
|
-
| Guide returns \`not_found\`, and this same connection already returned the complete current matching video entry with its required dependencies | Continue with that authoritative entry's workflow, full brand preparation and existing approvals. |
|
|
75
|
-
| Guide has another error, no response, or incomplete content; or the matching entry/dependencies are missing, incomplete or from another connection | Stop before creative work, project writes or paid calls; resolve a compatible connection on this same environment. |
|
|
76
|
-
|
|
77
|
-
A missing custom entry or required custom tool/schema remains unavailable: never substitute
|
|
78
|
-
a template or an import to bypass it. Never hide other fetch errors or continue from cached
|
|
79
|
-
instructions merely because the guide was not found.`;
|
|
80
|
-
/**
|
|
81
|
-
* The Brain-first entry contract, shared by the router, goose-ads and every video
|
|
82
|
-
* entry. A fresh agent read the Kit, then asked the user for angles and proof
|
|
83
|
-
* the Brand Brain already held: no entry made the search a step, and several
|
|
84
|
-
* told it to ask. Searching is free and read-only, so it needs no approval.
|
|
85
|
-
*/
|
|
86
|
-
const BRAIN_FIRST_ENTRY = `## Search the Brand Brain, then propose — before any creative choice or question
|
|
87
|
-
|
|
88
|
-
The Brand Kit is a summary. The brand's saved knowledge (its Brain) holds what the Kit does not:
|
|
89
|
-
rules from past feedback, approved and rejected creatives, customer evidence, approved claims,
|
|
90
|
-
reports and documents. **After \`brand_read\`, and before you choose an angle, claim, hook,
|
|
91
|
-
product emphasis, format or source ad — and before you ask the user for any brand fact — call
|
|
92
|
-
\`knowledge_search { brand_id, query }\`** when it is registered. It is free and read-only: no
|
|
93
|
-
approval, no announcement to the customer and no questionnaire.
|
|
94
|
-
|
|
95
|
-
1. **Search for this task, not the whole Brain.** Run one short query (under 500 characters) in
|
|
96
|
-
the user's own words plus the product (for example "ads for <product>: what worked, what to
|
|
97
|
-
avoid") and one with
|
|
98
|
-
\`source_types: ["evidence", "claim", "learning", "creative", "document"]\` for proof and past
|
|
99
|
-
creative results. Add a query only for a specific open question. Reuse results from this run.
|
|
100
|
-
2. **Keep these states distinct** and record which one each query returned:
|
|
101
|
-
|
|
102
|
-
| Result | Means | Do |
|
|
103
|
-
| --- | --- | --- |
|
|
104
|
-
| \`status: "ok"\` with matches | Saved knowledge exists | Use it; keep each fact's citation in your working brief |
|
|
105
|
-
| \`status: "empty"\` | Nothing saved matches this query | Say "no saved evidence for <topic>", never "the brand has no proof" |
|
|
106
|
-
| \`refresh_required\` | The results shown are current; some changed sources were left out | Use them; search again shortly for anything missing |
|
|
107
|
-
| \`building\` | The index is not ready | Retry once shortly, then continue with the gap stated |
|
|
108
|
-
| An error, or the tool is not registered | Retrieval failed or is unavailable | Retry an error once, then continue from \`brand_read\` and treat evidence as unchecked |
|
|
109
|
-
| An empty Kit field | Only that field is blank | Not a search result: still search before asking |
|
|
110
|
-
|
|
111
|
-
3. **Let the findings change the plan.** A \`dont\`/\`must\` learning or a rejected creative rules
|
|
112
|
-
options out; an approved or well-rated past creative is a proven angle to lead with; a report
|
|
113
|
-
shows what worked. Claim-grade proof is a result with \`approved_ad_claim: true\` or the kit's
|
|
114
|
-
\`approvedClaims\` within their stated applicability; the kit's \`proofPoints\` are what the
|
|
115
|
-
backend allows an ad to state, used as written. Other Kit text, documents and performance
|
|
116
|
-
numbers are context, never public claims. Never invent an offer, price or result. Judge
|
|
117
|
-
relevance and skip results about another product or business.
|
|
118
|
-
4. **Propose; don't interview.** Lead with one recommended direction (angle, product, source or
|
|
119
|
-
format) and a one-line reason naming what you found, with up to two alternatives. When several
|
|
120
|
-
directions fit (two audiences, products or campaigns), pick the one the evidence favours, such
|
|
121
|
-
as an active campaign or approved past creatives, and name the other as an alternative instead
|
|
122
|
-
of asking. Ask only for a decision the brand read and the search cannot settle, or for spend
|
|
123
|
-
approval. Never ask the user for a fact the Brain already answered.
|
|
124
|
-
Keep directions already chosen (the user's words, a project's creative brief, handed-off
|
|
125
|
-
defaults, approved plans): search only to fill empty fields and to apply saved rules. When a
|
|
126
|
-
returned card or picker presents the choice, your recommendation is its one acknowledgement
|
|
127
|
-
line and the saved plan's defaults, not a separate list.
|
|
128
|
-
5. **Carry an evidence brief** into the routed skill, writer or plan: findings with citations,
|
|
129
|
-
the state of each query, what it ruled out and the open gaps. Tell the customer the findings
|
|
130
|
-
in plain words; the citations stay in the brief.
|
|
131
|
-
|
|
132
|
-
On an approved resume, keep the saved brief and evidence; search again only for a new decision.`;
|
|
133
|
-
/** One prerequisite for template, custom and delegated video entry. */
|
|
134
|
-
function videoEntryPreparation(slug) {
|
|
135
|
-
return `## Prepare the video workflow and brand before creative work
|
|
136
|
-
|
|
137
|
-
**Installed entry files are bootstrap instructions.** For new work started from an installed
|
|
138
|
-
file or an old chat, fetch \`catalog_fetch { type: "skill", slug: "${slug}" }\` on the selected
|
|
139
|
-
connection and read its returned content and dependencies before continuing. Use the already
|
|
140
|
-
fetched body when this entry came from that connection in this run; do not recursively fetch
|
|
141
|
-
the same entry. A CLI freshness warning does not block using the current connected package.
|
|
142
|
-
Keep the fetched package and hashes in a new run folder; do not replace edited installed files.
|
|
143
|
-
If current instructions cannot be loaded, resolve the connection before format suggestions,
|
|
144
|
-
script writing or production. Do not continue from an old installed workflow or session notes.
|
|
145
|
-
|
|
146
|
-
${VIDEO_GUIDE_COMPATIBILITY}
|
|
147
|
-
|
|
148
|
-
**For an existing project or batch, read \`video_project_read\` first.** Determine its actual
|
|
149
|
-
route and saved review state before fetching a recipe or doing local work. Resume an approved
|
|
150
|
-
run with its recorded packages, brand inputs, script and ingredients; do not silently replace
|
|
151
|
-
them with today's release or brand rules. Follow returned preparation requirements and use
|
|
152
|
-
the existing affected review/approval flow for an intentional change. Reads, free drafts,
|
|
153
|
-
imports and existing-job retrieval do not grant permission for new paid production.
|
|
154
|
-
|
|
155
|
-
**For every new plan, resolve the brand and call**
|
|
156
|
-
\`brand_read { brand_id, sections: ["summary", "kit", "products", "learnings"] }\` **before**
|
|
157
|
-
suggesting formats, mining video angles, writing any script, creating a production plan or
|
|
158
|
-
handing the work to another agent. Use \`brand_get_context\` with those same four sections only
|
|
159
|
-
when advertised. Reuse a complete read from this run on the same connection and brand.
|
|
160
|
-
Onboarding completion, a summary-only response and earlier session notes do not supply the
|
|
161
|
-
kit, selected product facts or saved rules. If the full read is unavailable, resolve it before
|
|
162
|
-
creative work. Use known kit facts while research is incomplete; do not restart research
|
|
163
|
-
solely because its status is pending. Never invent a product fact or accept a campaign to
|
|
164
|
-
bypass preparation. Then search the Brand Brain (next section) before suggesting formats,
|
|
165
|
-
choosing an angle or asking the user for a brand fact.
|
|
166
|
-
|
|
167
|
-
Carry that context through custom/template/idea routing and delegation. Before writing, make
|
|
168
|
-
the workflow's brand-rules file from those sources: pronunciations, required spoken copy,
|
|
169
|
-
prohibited claims, real logo, font, palette and the selected product's supported facts.
|
|
170
|
-
Entries prefixed \`Video preference:\` and visual/pacing instructions are creative direction,
|
|
171
|
-
not spoken lines. Use the kit's audience, offer and voice as defaults without an interview.
|
|
172
|
-
The rules file mirrors context; it is not proof of a read or permission to spend. Keep the
|
|
173
|
-
route's existing script, ingredient and budget approvals, including its allowed previews.
|
|
174
|
-
|
|
175
|
-
**Use the server's brand bundle when the selected API returns it.** Project create/read may
|
|
176
|
-
return top-level
|
|
177
|
-
\`brand_context\`: \`{ version: 1, brand_id, digest, loaded_at, sections, brand, kit, products,
|
|
178
|
-
learnings }\`. Its sections cover summary, kit, products and learnings.
|
|
179
|
-
|
|
180
|
-
| Returned brand/project response on the selected connection | Required action |
|
|
181
|
-
| --- | --- |
|
|
182
|
-
| A complete authoritative version-1 \`brand_context\` is returned | Binding is required: use its contents for the plan/rules and include \`script_drafts.brand_context_digest = brand_context.digest\` with each new/changed script save. |
|
|
183
|
-
| An older API returns the actual four brand sections but no \`brand_context\` in either the brand read or project response | Prepare from those full sections, write the brand rules and follow the selected connection's existing approval flow and advertised fields. Do not fabricate a receipt or send nonexistent bundle/digest fields. |
|
|
184
|
-
|
|
185
|
-
An incomplete/malformed bundle or missing brand section is a preparation failure, never the
|
|
186
|
-
older-API exception. Once this connection returns an authoritative bundle, use its binding
|
|
187
|
-
contract. \`script_drafts.video_brand_context\` is server-owned: do not author, replace or forge
|
|
188
|
-
it, and do not invent a read receipt or hash local brand facts into one. Keep the full bundle
|
|
189
|
-
out of client review payloads. If managed generation returns HTTP 409
|
|
190
|
-
\`video_brand_context_required\`, reload the project and bind the plan to its returned bundle
|
|
191
|
-
through the normal review flow before retrying. That refusal never permits the older-API
|
|
192
|
-
fallback, skipping sections or retrying paid calls blindly. Unchanged approved legacy resumes
|
|
193
|
-
retain their package, context and approvals; an upgrade alone needs no extra approval.
|
|
194
|
-
|
|
195
|
-
**To apply a deliberate brand correction to a new or revised plan**, make a fresh, unfiltered
|
|
196
|
-
\`brand_read\` of those four sections. When it returns the authoritative bundle, use its
|
|
197
|
-
returned \`brand_context.digest\` in the complete revised \`script_drafts\` through the existing
|
|
198
|
-
\`video_project_upsert\` \`patch.script\` save; the server verifies the current brand and replaces
|
|
199
|
-
its snapshot with the saved plan. On an older API with no bundle contract, apply the actual
|
|
200
|
-
four-section correction and save the revised draft through its existing flow without inventing
|
|
201
|
-
digest fields. If a connection that already returned a bundle cannot supply the fresh bundle,
|
|
202
|
-
resolve that failure before rebinding. Review and approve the affected script, ingredients and
|
|
203
|
-
budget through the normal flow. Never refresh an ongoing approved run automatically; its
|
|
204
|
-
recorded package and brand inputs stay pinned until an intentional change.
|
|
205
|
-
|
|
206
|
-
${BRAIN_FIRST_ENTRY}`;
|
|
207
|
-
}
|
|
208
|
-
/**
|
|
209
|
-
* Who makes an agent-made video: one rule, in the same words as the server's
|
|
210
|
-
* (gooseworks-app lib/who-makes-the-video.ts). The agent decides; the server
|
|
211
|
-
* never guesses it from the host.
|
|
212
|
-
*/
|
|
213
|
-
const WHO_MAKES_THE_VIDEO = `**Who makes the video (one rule).** If you can run shell commands on the customer's own
|
|
214
|
-
computer, you make it there with \`goose-video-local\`: check the toolchain first and, if it
|
|
215
|
-
can't be fixed, hand it off. If you can't, hand it to the GooseWorks coworker with
|
|
216
|
-
\`goose_run_task { brand_id, project_id, message: the customer's words }\`; the one approval,
|
|
217
|
-
Stop and fixes stay in this chat. Inside the GooseWorks coworker's own sandbox you are the
|
|
218
|
-
coworker: make it yourself and never hand off. A hosted code sandbox is not the customer's
|
|
219
|
-
computer. Decide this yourself, never from the host's name; the server needs no flag for it.`;
|
|
220
|
-
const CUSTOMER_TALK = `## How to talk to the customer (applies to every message you send them)
|
|
221
|
-
|
|
222
|
-
The customer is a marketer or founder, not an engineer. Everything in this skill about tools,
|
|
223
|
-
fields, files, polling, models and pipeline steps is for YOU. Never pass it on to them.
|
|
224
|
-
|
|
225
|
-
- **Say what they get and what they need to decide, never how it's made.**
|
|
226
|
-
Bad: "Checking the media-proxy helpers for voiceover timestamps and lipsync." / "Generated with
|
|
227
|
-
gpt-image-2 at high quality, mouth closed, passes QC."
|
|
228
|
-
Good: "Recording the voices now." / "Here are your two hosts."
|
|
229
|
-
- **Never mention** tool, file or field names, ids, JSON, commands, scripts, installed software,
|
|
230
|
-
uploads, model or vendor names, timings in seconds or frames, retries, polling, internal statuses
|
|
231
|
-
or your own quality checks. Fix what you can quietly. If they ask how something works, explain it
|
|
232
|
-
simply.
|
|
233
|
-
- **Update them only at milestones they care about**: choices confirmed, script and voices done,
|
|
234
|
-
visuals done, ready to review, finished. One short line each, then stay quiet until the next
|
|
235
|
-
milestone. No update for setup, downloads, uploads or saving.
|
|
236
|
-
- **Money is in credits, with a number**: "the full video uses about N credits". Never "the cheap
|
|
237
|
-
pieces" or "the expensive render".
|
|
238
|
-
- **Problems:** say what it means for them and what they can do, in one or two sentences. No error
|
|
239
|
-
codes or stack traces. Only raise a problem that changes something for them.
|
|
240
|
-
- **Use their words**: script, voice, hook, scene, host, ending, logo, the product shot.
|
|
241
|
-
- **No filler**: no "Great question!", "Certainly!", "I hope this helps!", no restating what they
|
|
242
|
-
just said at length.
|
|
243
|
-
|
|
244
|
-
Example. Instead of a dozen lines about render tools, scripts, uploads and portraits, send:
|
|
245
|
-
"Got it: warm tone, home podcast studio, Brielle as the skeptic and Mark as the believer." then
|
|
246
|
-
"Script and voices are done (about 34 seconds)." then "Ready for you to review: the script, voices,
|
|
247
|
-
both hosts and the ending. You can also review your recipe ingredients in the app: <link>. Say go
|
|
248
|
-
here and I'll make the full video (about N credits)."
|
|
249
|
-
|
|
250
|
-
${SKILL_FRESHNESS}`;
|
|
251
|
-
// GOOSE-3937: a cloud agent's sandbox (ChatGPT agent, Meta AI, Grok) has a
|
|
252
|
-
// shell but no GooseWorks connector, because those apps load tools from their
|
|
253
|
-
// own settings. `gooseworks tool` calls the same MCP tools with the CLI login.
|
|
254
|
-
const CLI_TOOL_BRIDGE = `## No GooseWorks tools in this session? Call them through the CLI
|
|
255
|
-
|
|
256
|
-
The GooseWorks tools named here (for example \`account_whoami\`, \`brand_onboarding\`,
|
|
257
|
-
\`brand_read\`) normally come from the GooseWorks connector. If they are not registered in this
|
|
258
|
-
session but you have a shell with the \`gooseworks\` CLI signed in (a cloud sandbox such as
|
|
259
|
-
ChatGPT agent, Meta AI or Grok), call the same tool from the shell:
|
|
260
|
-
|
|
261
|
-
\`\`\`bash
|
|
262
|
-
npx gooseworks tool <name> '<arguments as a JSON object>'
|
|
263
|
-
\`\`\`
|
|
264
|
-
|
|
265
|
-
- Run \`npx gooseworks tool --list\` once first. It prints the server's rules for using the tools
|
|
266
|
-
and every tool name; \`npx gooseworks tool <name> --schema\` shows one tool's arguments.
|
|
267
|
-
- The result prints as JSON. When a tool answers with a one-line summary, the fields you act on
|
|
268
|
-
(such as \`next_step\` and ids) follow under "Data:". It exits 1 when the tool reports an error.
|
|
269
|
-
- Nothing renders as a widget here, so tell the user the result in plain words.
|
|
270
|
-
- The same rules apply as over the connector: state the credit total and get the user's yes
|
|
271
|
-
before paid work.
|
|
272
|
-
- If it says you are not logged in, run \`npx gooseworks login --device --no-wait\`, show the
|
|
273
|
-
user the link and code it prints, and run \`npx gooseworks login --device\` once they approve.
|
|
274
|
-
|
|
275
|
-
When the tools are registered in this session, call them directly instead.`;
|
|
276
|
-
const ENVIRONMENT_IDENTITY = `## Keep the selected connection for the whole run
|
|
277
|
-
|
|
278
|
-
Call \`account_whoami\` on the connection that owns the brand/project before the first write.
|
|
279
|
-
Keep \`environment.name\` and the public \`environment.api_origin\` with this run. Respect the
|
|
280
|
-
user's selected production or staging connection. If multiple connections are available and
|
|
281
|
-
none was selected, resolve that once. Missing or unknown identity is uncertainty, not
|
|
282
|
-
permission to switch. Never infer the environment from credits, billing links or Node mode.
|
|
283
|
-
|
|
284
|
-
Reads, project creation, uploads, generation, polling and final updates all use that same
|
|
285
|
-
connection. If a production request fails, resume or report the failure on production;
|
|
286
|
-
never retry it on staging or recreate the project there. Before retrying a timed-out write,
|
|
287
|
-
read back the existing project or paid request on the selected connection.
|
|
288
|
-
|
|
289
|
-
Local/CLI proxy origin must match \`environment.api_origin\`. If it differs, use the MCP
|
|
290
|
-
relay on the selected connection (\`GW_MEDIA_VIA=mcp\`) before paid calls. Do not change
|
|
291
|
-
credentials or API origins to recover a failed write. An explicit user-requested move is
|
|
292
|
-
a separate operation, with the existing project and paid requests reconciled first.`;
|
|
293
|
-
const ASSET_READINESS = `## Check assets for the selected format before spending
|
|
294
|
-
|
|
295
|
-
For a template, read its structured \`asset_readiness\` from
|
|
296
|
-
\`video_catalog_list { kind: "formats", brand_id }\`. \`missing\` names gaps;
|
|
297
|
-
\`needs_review\` means suitability is unverified, including older recipes without
|
|
298
|
-
structured requirements. \`ready\` describes assets only, not script or budget approval.
|
|
299
|
-
For a custom video, derive requirements from its actual approved scenes.
|
|
300
|
-
|
|
301
|
-
Inspect candidate files for the chosen product and format. A catalog photo can contain
|
|
302
|
-
multiple objects, other products or a person; its existence or approved status does not
|
|
303
|
-
make it a standalone image of the selected product. Check object count, framing, readable
|
|
304
|
-
print and real image bytes. A service conversation has no automatic packshot requirement.
|
|
305
|
-
|
|
306
|
-
Reuse a suitable approved image first. A free crop or cutout is a new file: keep the
|
|
307
|
-
original, inspect the result and include it in the normal ingredient review. When no
|
|
308
|
-
usable input exists, explain the gap before generation. Estimate any paid preparation
|
|
309
|
-
separately before spending. Record the selected asset and inspection in the project
|
|
310
|
-
review set; do not add a separate approval round.`;
|
|
311
|
-
/** Same canonical capture policy for the router and both video entrypoints. */
|
|
312
|
-
const DURABLE_BRAND_CAPTURE = `## Save durable brand answers, then verify them
|
|
313
|
-
|
|
314
|
-
Read the selected brand with \`brand_read { brand_id, sections: ["summary", "kit", "products", "learnings", "onboarding"] }\`
|
|
315
|
-
(older clients: \`brand_get_context\` with the same sections, only when that tool is advertised).
|
|
316
|
-
Keep founder answers, user corrections, research and your own hypotheses distinct. Reuse
|
|
317
|
-
matching saved answers; ask only about gaps.
|
|
318
|
-
|
|
319
|
-
When the user asks to remember a rule, answers a brand interview, or explicitly corrects a
|
|
320
|
-
standing fact, save that answer in the same turn. The capture request authorizes those answers;
|
|
321
|
-
do not ask for approval again. A direction for this one video stays in its brief. If the scope
|
|
322
|
-
is genuinely ambiguous, ask whether it applies to future videos before saving a standing rule.
|
|
323
|
-
|
|
324
|
-
Use the **live registered schema**. Where supported, call \`brand_update\` with
|
|
325
|
-
\`knowledge_intent: "user_correction"\` and \`user_statement\` containing the user's exact,
|
|
326
|
-
verbatim answer, not your paraphrase or researched text.
|
|
327
|
-
For an inference or suggested improvement, use \`knowledge_intent: "agent_proposal"\`. Show the
|
|
328
|
-
before/after change from your prior read and proposed value; retain the returned proposal IDs
|
|
329
|
-
and say the user must accept it in the app. Link only a review surface actually returned by a
|
|
330
|
-
tool; the compact \`knowledge_updates\` response does not itself contain a diff or URL.
|
|
331
|
-
A pending proposal is not a saved fact. Never call an unavailable
|
|
332
|
-
tool or silently relabel research or your inference as something the user said.
|
|
333
|
-
|
|
334
|
-
The safe structured shape is \`patch: { knowledge: { positioning?, audience?, voice?,
|
|
335
|
-
instructions?, brandType?, tagline?, valueProps? } }\`, using only fields present in the live
|
|
336
|
-
schema. Inferred rules/taste go in an \`instructions\` proposal with a rationale, never in
|
|
337
|
-
\`patch.facts\`. Prefix every video-only preference in that proposed text with "Video preference:"
|
|
338
|
-
so it remains production direction after acceptance. Preserve unrelated instructions when
|
|
339
|
-
proposing a merged replacement.
|
|
340
|
-
|
|
341
|
-
| User answer | Canonical write |
|
|
342
|
-
| --- | --- |
|
|
343
|
-
| 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. |
|
|
344
|
-
| 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. |
|
|
345
|
-
| Required wording or pronunciation | \`patch.facts: [{ kind: "must", text }]\`; pronunciation is exactly \`Pronounce "<term>" as "<say_as>"\`. |
|
|
346
|
-
| Forbidden claim, word or visual | \`patch.facts: [{ kind: "dont", text }]\`. |
|
|
347
|
-
| 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:". |
|
|
348
|
-
|
|
349
|
-
Facts are existing \`ad_brand_learning\` rows with user provenance; they are not a second profile.
|
|
350
|
-
Update a matching rule by its returned \`id\` instead of adding duplicates. Preserve unrelated
|
|
351
|
-
rules and the user's exact meaning. Only use the legacy facts shape for explicitly user-authored
|
|
352
|
-
answers when the live schema lacks intent fields; agent suggestions still need a proposal path.
|
|
353
|
-
|
|
354
|
-
**Claims and plans have separate gates.** A founder assertion or proof point is not an approved,
|
|
355
|
-
evidence-backed claim or consent to quote a customer. Use the existing evidence/claims and
|
|
356
|
-
operating-plan tools only if registered, following their proposal, evidence and confirmation
|
|
357
|
-
requirements. Never encode a spend cap, approver or emergency stop as a learning. If that write
|
|
358
|
-
path is missing, report the specific unsaved item and keep it pending for the supported review
|
|
359
|
-
surface; do not claim it was saved or create a parallel local profile.
|
|
360
|
-
|
|
361
|
-
After every write, **read back before saying saved**: use \`brand_read\` with \`kit\`, \`learnings\`
|
|
362
|
-
or \`onboarding\` as appropriate, or \`brand_onboarding { action: "status", brand_id }\` after an
|
|
363
|
-
onboarding answer. Verify the intended field/rule, its source and the absence of a conflicting
|
|
364
|
-
duplicate. A generic success response, pending proposal, ignored key or truncated result is not
|
|
365
|
-
proof. Report partial saves honestly. Carry the verified rules into the current task and the
|
|
366
|
-
routed skill; claims still pass their own safety gate.`;
|
|
367
|
-
/** The existing media library and learnings are sufficient for a minimal taste brief. */
|
|
368
|
-
const VIDEO_TASTE_CAPTURE = `## Video taste — reuse examples and preferences
|
|
369
|
-
|
|
370
|
-
When asked to capture video taste, or when the user volunteers a durable video preference,
|
|
371
|
-
first read the saved learnings and \`media_list { brand_id, scope: "brand", scope_id: brand_id,
|
|
372
|
-
tags: ["video-taste"], limit: 100 }\`. Follow \`next_cursor\` before deciding an example is absent.
|
|
373
|
-
Do not force a taste interview before an unrelated task or ask again for an existing preference.
|
|
374
|
-
|
|
375
|
-
Save what the user has already supplied first. Then ask only the missing useful question, for
|
|
376
|
-
example: "What do you like about this video—its pace, voice, captions, or look?" An inaccessible
|
|
377
|
-
link can still be saved as a link with the user's explanation; do not pretend you watched it.
|
|
378
|
-
|
|
379
|
-
- **Direct clip or video file:** register with \`media_upload { brand_id, scope: "brand",
|
|
380
|
-
scope_id: brand_id, kind: "video", source: { type: "url", url }, tags: ["video-taste", "reference-only"],
|
|
381
|
-
metadata: { purpose: "video_taste", source_url: url, provenance: "user", captured_at: <ISO timestamp>,
|
|
382
|
-
preference: <the user's explanation> } }\`. For a file use the live file/bytes upload flow and
|
|
383
|
-
\`media_confirm\` after a presigned upload. Registration of a URL does not copy or inspect it.
|
|
384
|
-
- **Instagram/post/page link:** the same registration with \`kind: "document"\`; it is a link
|
|
385
|
-
bookmark, not downloadable footage or an indexed transcript. Do not fabricate a direct clip URL.
|
|
386
|
-
- **Preferences:** save the user's reasons, likes and dislikes through the facts mapping above.
|
|
387
|
-
Read and preserve existing facts before updating one. Do not invent \`video_preferences\` or
|
|
388
|
-
new \`video_lab\` keys; the live kit patch accepts only its documented asset fields.
|
|
389
|
-
- **Deduplicate:** reuse a matching returned media row, then \`media_update\` its title/tags/metadata
|
|
390
|
-
if needed; preserve existing metadata and tags. Do not create another row for the same example.
|
|
391
|
-
Read back with \`media_list\` and \`brand_read\` learnings before claiming it was saved.
|
|
392
|
-
Check the returned row belongs to this brand: URL deduplication may return another brand's
|
|
393
|
-
existing row. Do not relabel that row or claim success unless the current brand's scoped read
|
|
394
|
-
actually returns it. Report an unsaved association if no supported attach path is available.
|
|
395
|
-
|
|
396
|
-
Never put third-party taste examples into kit reference images: \`kind: "reference"\` at brand
|
|
397
|
-
scope writes there. The tags and metadata above record purpose and provenance; **they do not
|
|
398
|
-
grant or enforce usage rights**. Study the structure, pacing and look only. Never use the example's
|
|
399
|
-
footage, face, product, testimonial or claims in a new ad without independently verified permission.
|
|
400
|
-
|
|
401
|
-
Read video-only entries prefixed \`Video preference:\` from both saved learnings and
|
|
402
|
-
\`kit.instructions\`, including accepted proposals. Keep them out of required or forbidden
|
|
403
|
-
dialogue. Build a brief from the verified readback: preferred pace, voice, caption treatment, visual style,
|
|
404
|
-
formats to favour/avoid, reference links and the user's reasons. Say what is still unknown.
|
|
405
|
-
Pass it with the brand rules into the existing video workflow. A one-video request overrides a
|
|
406
|
-
default for that project; it does not silently rewrite the brand's standing preference.`;
|
|
32
|
+
const server_entry_skills_1 = require("./server-entry-skills");
|
|
33
|
+
/** The kit command, as the server's next_step gives it. */
|
|
34
|
+
exports.KIT_MAKE_COMMAND = 'gooseworks video make <id>';
|
|
407
35
|
/**
|
|
408
36
|
* THE registry of entry skills (GOOSE-3190) — one list, four consumers:
|
|
409
37
|
* - `gooseworks install` / `update` / login-refresh write exactly these dirs,
|
|
410
38
|
* - `npm run generate:skills` regenerates exactly these `skills/<name>/SKILL.md`,
|
|
411
39
|
* - `skills/names.ts` derives which dirs the CLI is allowed to delete,
|
|
412
|
-
* - the backend raw-fetches these paths for
|
|
413
|
-
*
|
|
414
|
-
* `goose-product-photos` used to be a hand-maintained `skills/…/SKILL.md` that
|
|
415
|
-
* was on disk and served by the backend but absent here — so it was never
|
|
416
|
-
* regenerated and never refreshed on install. Adding it closes that drift.
|
|
40
|
+
* - the backend raw-fetches these paths for chat apps.
|
|
417
41
|
*/
|
|
418
42
|
function getEntrySkills() {
|
|
419
43
|
return [
|
|
@@ -429,2575 +53,171 @@ function getEntrySkills() {
|
|
|
429
53
|
function getEntrySkillNames() {
|
|
430
54
|
return getEntrySkills().map((s) => s.name);
|
|
431
55
|
}
|
|
432
|
-
/**
|
|
433
|
-
* Returns the GTM master SKILL.md content (the `gooseworks` entry skill).
|
|
434
|
-
* It teaches the coding agent how to discover and use GooseWorks skills on
|
|
435
|
-
* demand via the `gooseworks` CLI commands.
|
|
436
|
-
*
|
|
437
|
-
* The CLI handles credentials loading internally, so the agent does not
|
|
438
|
-
* need to read ~/.gooseworks/credentials.json or set environment
|
|
439
|
-
* variables — every command auto-loads the API key.
|
|
440
|
-
*/
|
|
56
|
+
/** The router (`gooseworks`): specialist routes, the video pointer and the terminal data commands. */
|
|
441
57
|
function getMasterSkillContent() {
|
|
442
58
|
return `---
|
|
443
59
|
name: gooseworks
|
|
444
60
|
slug: gooseworks
|
|
445
61
|
description: >
|
|
446
|
-
GooseWorks growth coworker and
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
Use it as the single GooseWorks entry point for brand growth, B2B, sales, research, and GTM work.
|
|
62
|
+
GooseWorks growth coworker and router. Research brands, customers, competitors, creators,
|
|
63
|
+
markets and prospects; make and study ads, product photos, graphics and video; search and
|
|
64
|
+
scrape public web and social data; find and enrich leads. The one GooseWorks entry point
|
|
65
|
+
for brand growth, B2B, sales, research and GTM work.
|
|
451
66
|
category: general
|
|
452
|
-
version:
|
|
67
|
+
version: 2.0.0
|
|
453
68
|
author: GooseWorks
|
|
454
|
-
tags: [gooseworks, data, scraping, search,
|
|
69
|
+
tags: [gooseworks, data, scraping, search, research, gtm, leads, prospecting, ads, video]
|
|
455
70
|
---
|
|
456
71
|
|
|
457
72
|
# GooseWorks
|
|
458
73
|
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
${CUSTOMER_TALK}
|
|
74
|
+
GooseWorks is a coworker with specialist skills for research, analysis, creative work, lead
|
|
75
|
+
generation, enrichment and public web and social data. Hand specialist work to its skill; do
|
|
76
|
+
data work here.
|
|
464
77
|
|
|
465
|
-
|
|
78
|
+
## First steps
|
|
466
79
|
|
|
467
|
-
|
|
80
|
+
1. If the customer has no brand yet, call brand_setup and follow its next_step. Keep their
|
|
81
|
+
request and carry on with it once the brand is ready.
|
|
82
|
+
2. Read the brand with brand_read, then knowledge_search for this task. Pass both to the skill
|
|
83
|
+
you route to, and never ask the customer for something they already answer.
|
|
84
|
+
3. When the customer states a lasting fact or rule about the brand, save it with brand_update
|
|
85
|
+
and check it with brand_read before saying it is saved.
|
|
468
86
|
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
${VIDEO_GUIDE_COMPATIBILITY}
|
|
472
|
-
|
|
473
|
-
For "interview me about the brand", "save our brand rules", "refine our audience", or "remember
|
|
474
|
-
our video taste", stay here and follow **Guided brand capture** below. This extends the current
|
|
475
|
-
brand and onboarding flow; it does not create another onboarding checklist.
|
|
87
|
+
## Route to the right skill
|
|
476
88
|
|
|
477
89
|
| If the user wants… | Route to | How |
|
|
478
90
|
| --- | --- | --- |
|
|
479
91
|
${(0, routes_1.renderDomainRouteTable)()}
|
|
480
|
-
| Anything else
|
|
481
|
-
|
|
482
|
-
Examples — all of these route to \`goose-ads\`, not the data flow: "remix this ad with project id 123", "make an ad for my product", "research my brand", "why is my Meta campaign underperforming", "which creatives should I cut".
|
|
483
|
-
|
|
484
|
-
## Load the brand context FIRST (mandatory — before you route, and before you ask anything)
|
|
485
|
-
|
|
486
|
-
**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:
|
|
487
|
-
|
|
488
|
-
For videos, read the current workflow first as described above, then load all four creative
|
|
489
|
-
sections (summary, kit, products and learnings) before suggesting formats, choosing angles or
|
|
490
|
-
writing a script. Onboarding facts alone are insufficient. Carry saved rules and kit assets
|
|
491
|
-
into the specialist's brand preparation. \`Video preference:\` rules describe the look, voice
|
|
492
|
-
and pacing; they are not lines to read aloud. On an approved resume, preserve the saved brand
|
|
493
|
-
inputs and packages; an intentional change uses the existing affected review/approval gates.
|
|
494
|
-
|
|
495
|
-
| It returns | Use it for |
|
|
496
|
-
| --- | --- |
|
|
497
|
-
| **voice** — tone, style, banned phrasing | Any copy, script, caption, hook, or headline. Don't ask "what tone?" |
|
|
498
|
-
| **products** — names, descriptions, pricing, links, imagery | Picking the product to feature. Don't ask "which product?" — offer the list. |
|
|
499
|
-
| **audience** — segments, demographics, jobs-to-be-done | Targeting, angles, creator fit. Don't ask "who is this for?" |
|
|
500
|
-
| **positioning** — category, value props, proof points, tagline | Angles, offers, competitive framing. Don't ask "what makes you different?" Kit proof points are proof an ad may state as written; other positioning text is context. |
|
|
501
|
-
| **research status** — whether the brand's research pass has completed | Whether the facts are trustworthy yet, or still being filled in. |
|
|
502
|
-
|
|
503
|
-
Then:
|
|
504
|
-
|
|
505
|
-
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, plus the evidence brief from the Brain search below. Do **not** make the routed skill re-derive them, and do **not** re-run brand research when the context is already there.
|
|
506
|
-
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 or the Brain search answers, they win — answer it yourself and move on. Ask only for what is genuinely missing after both, or a decision that is the user's to make.
|
|
507
|
-
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.
|
|
508
|
-
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.
|
|
509
|
-
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.
|
|
510
|
-
|
|
511
|
-
Never invent a brand fact. If it isn't in the brand context and the user hasn't said it, search
|
|
512
|
-
the Brand Brain next. Ask the user only when that search cannot answer it and the answer is
|
|
513
|
-
theirs to give.
|
|
514
|
-
|
|
515
|
-
${BRAIN_FIRST_ENTRY}
|
|
516
|
-
|
|
517
|
-
## Setup
|
|
518
|
-
|
|
519
|
-
All commands below auto-load credentials from \`~/.gooseworks/credentials.json\`. If a command exits with "Not logged in", tell the user to run: \`npx gooseworks login\`. In a cloud sandbox or over SSH, sign in with a code instead: run \`npx gooseworks login --device --no-wait\` yourself, show the user the link and code it prints, and run \`npx gooseworks login --device\` once they have approved. To log out: \`npx gooseworks logout\`.
|
|
520
|
-
|
|
521
|
-
### Choose the available runtime — MCP first, then CLI
|
|
522
|
-
|
|
523
|
-
Skills may describe a managed provider request as an environment-neutral operation with
|
|
524
|
-
\`provider\`, \`method\`, \`path\`, and optional \`query\` or \`body\`. Execute the operation through
|
|
525
|
-
the first available runtime:
|
|
526
|
-
|
|
527
|
-
1. If the matching GooseWorks MCP tool is registered, use it. For ScrapeCreators, pass a GET
|
|
528
|
-
operation directly to \`data_call_provider\` (\`provider\`, \`path\`, \`query\`) and a POST
|
|
529
|
-
operation to \`data_post_provider\` (\`provider\`, \`path\`, \`body\`, optional \`query\`).
|
|
530
|
-
This is the preferred path in ChatGPT, Cowork, and other terminal-free clients.
|
|
531
|
-
Do not shell out and do not ask for a separate provider key.
|
|
532
|
-
2. Otherwise, if a local terminal and the \`gooseworks\` CLI are available, translate the same
|
|
533
|
-
operation into \`gooseworks call <provider> <path>\` with its method, query, and body options.
|
|
534
|
-
3. Otherwise, follow the provider dependency's direct-key path only when the user has supplied
|
|
535
|
-
their own key. If no runtime is available, explain what connection is missing; never pretend
|
|
536
|
-
the provider call ran.
|
|
537
|
-
|
|
538
|
-
Managed provider calls are paid on the MCP and CLI runtimes alike (a ScrapeCreators call costs 1
|
|
539
|
-
credit today, and each result reports what it charged). Before a skill's first paid call, tell the
|
|
540
|
-
user roughly how many calls it will make and the credit total, and get their yes.
|
|
541
|
-
|
|
542
|
-
The same selection applies to catalog and account operations. When the CLI is unavailable but the
|
|
543
|
-
GooseWorks MCP tools are connected, use these equivalents. Match on the tool name: a coding agent
|
|
544
|
-
may show a server prefix (for example \`mcp__gooseworks__catalog_search\`), a chat app may not.
|
|
545
|
-
- \`gooseworks search <q>\` → **\`catalog_search { type: "skill", query: "<q>" }\`**.
|
|
546
|
-
- \`gooseworks fetch <slug>\` → **\`catalog_fetch { type: "skill", slug: "<slug>" }\`** (same content/scripts/files/deps).
|
|
547
|
-
- \`gooseworks credits\` → **\`account_whoami\`** (the balance is \`credits.available_credits\`).
|
|
548
|
-
|
|
549
|
-
If one of these tools is missing, the GooseWorks connection or its tool list is stale: ask the
|
|
550
|
-
user to reconnect or refresh GooseWorks. Installing or updating the \`gooseworks\` CLI never fixes
|
|
551
|
-
a missing connector tool, so never send a chat-app user to a terminal for it. An agent that has
|
|
552
|
-
its own shell and a signed-in CLI can call the tool with \`npx gooseworks tool\` instead (see
|
|
553
|
-
"No GooseWorks tools in this session?" above).
|
|
554
|
-
|
|
555
|
-
Discovery, skill fetching, and ScrapeCreators-backed Brand Growth workflows work fully CLI-free
|
|
556
|
-
this way. Task skills own the endpoint and analysis workflow; this runtime rule owns how the same
|
|
557
|
-
provider operation is executed.
|
|
558
|
-
|
|
559
|
-
To check credit balance:
|
|
560
|
-
\`\`\`bash
|
|
561
|
-
gooseworks credits
|
|
562
|
-
\`\`\`
|
|
563
|
-
|
|
564
|
-
## Common company onboarding
|
|
565
|
-
|
|
566
|
-
Onboarding happens inside the current agent and is the first-run gate for every GooseWorks task. It uses the exact same saved state and step order as the web onboarding. The user does not need to type **\`/gooseworks onboard me\`**; that explicit command only starts or resumes the same flow.
|
|
567
|
-
|
|
568
|
-
Keep the user's original task pending. Call **\`brand_onboarding { action: "status" }\`** before routing or executing it, then:
|
|
569
|
-
|
|
570
|
-
- follow only the returned \`next_step\`;
|
|
571
|
-
- save each answer immediately with \`brand_onboarding\` so web, Claude, Codex, ChatGPT, and Cowork can resume one another;
|
|
572
|
-
- continue the original request immediately when \`onboarding_completed\` is true.
|
|
573
|
-
|
|
574
|
-
If \`brand_onboarding\` is unavailable, explain that the GooseWorks MCP connection must be enabled. Do not write a parallel local profile and do not run the retired role / discovery-source / ad-owner questionnaire.
|
|
575
|
-
|
|
576
|
-
When onboarding returns a review link, show that single link and ask the user to review the creatives and reply \`done\`. When they reply \`done\`, do not restart onboarding: continue the task they originally asked for. If there was no earlier task, ask: **“Let’s start your next campaign. What are you promoting, and what result do you want?”** Use the same preserved-task-or-campaign handoff if onboarding completes while the creatives are still being prepared or could not be generated.
|
|
577
|
-
|
|
578
|
-
### Shared flow
|
|
579
|
-
|
|
580
|
-
Use the host's native question controls. Ask one short group at a time and rely on the live tool schema for accepted values.
|
|
581
|
-
|
|
582
|
-
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.
|
|
583
|
-
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.
|
|
584
|
-
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.
|
|
585
|
-
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.
|
|
586
|
-
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.
|
|
587
|
-
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.
|
|
588
|
-
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"\`.
|
|
589
|
-
|
|
590
|
-
The former revenue / 90-day-goal / \`save_progress\` screen is retired. Do not insert it into
|
|
591
|
-
onboarding. Ask those human-only questions later only when the user's task needs them.
|
|
592
|
-
|
|
593
|
-
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.
|
|
594
|
-
|
|
595
|
-
## Guided brand capture
|
|
596
|
-
|
|
597
|
-
Use this when the user requests a founder interview, audience/rules capture, or video taste.
|
|
598
|
-
Keep their original task pending. Load the current brand first, compare it with information
|
|
599
|
-
already volunteered in this chat, and **save known information first** using the canonical
|
|
600
|
-
mapping below. Do not run a long questionnaire as a prerequisite for making an ad.
|
|
601
|
-
|
|
602
|
-
For facts needed by the task but absent from the read, call \`knowledge_search\` first if it is
|
|
603
|
-
registered, as in **"Search the Brand Brain, then propose"**. Use returned citations and states
|
|
604
|
-
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
|
|
605
|
-
answered by trustworthy saved knowledge.
|
|
606
|
-
|
|
607
|
-
Ask one short group of missing human-only facts at a time, in plain language, with the relevant
|
|
608
|
-
known answer in that same question. "Skip" or "not sure" is valid. Examples, **only for gaps**:
|
|
609
|
-
|
|
610
|
-
| Gap | Useful question |
|
|
611
|
-
| --- | --- |
|
|
612
|
-
| Founder origin or conviction | "What made you start this, and what do you believe that alternatives get wrong?" |
|
|
613
|
-
| Audience depth | "Who buys first, what problem pushes them to act, and what nearly stops them?" |
|
|
614
|
-
| Buying trigger or alternatives | "What happens just before they look for you, and what do they use instead?" |
|
|
615
|
-
| Rules | "What must we always say or show, and what must we never say or imply?" |
|
|
616
|
-
| Proof | "What evidence supports that result, and do we have permission to quote the customer?" Keep unsupported claims pending. |
|
|
617
|
-
| Video taste | "Share a video you like and what you would keep or avoid: pace, voice, captions, or look." |
|
|
92
|
+
| Anything else: scraping, research, lead lists, enrichment, any data lookup | (stay here) | Follow "Data work" below. |
|
|
618
93
|
|
|
619
|
-
|
|
620
|
-
Save each answered group and read it back before the next group. Stop when the requested capture
|
|
621
|
-
is covered or the user skips; resume from canonical saved answers after interruption. Present a
|
|
622
|
-
short brief containing verified answers, attribution, pending proposals and remaining gaps, then
|
|
623
|
-
continue the original task. Review happens in this chat plus any proposal review link returned
|
|
624
|
-
by the tools. Do not promise an unavailable evidence, claims or plan write.
|
|
94
|
+
When the server's next_step says to make a video on this computer, run \`${exports.KIT_MAKE_COMMAND}\`.
|
|
625
95
|
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
${VIDEO_TASTE_CAPTURE}
|
|
629
|
-
|
|
630
|
-
## Brand Growth discovery
|
|
631
|
-
|
|
632
|
-
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:
|
|
96
|
+
## Brand growth skills
|
|
633
97
|
|
|
634
98
|
| Job | Skill |
|
|
635
99
|
| --- | --- |
|
|
636
100
|
${(0, routes_1.renderBrandGrowthTable)()}
|
|
637
101
|
|
|
638
|
-
Fetch
|
|
639
|
-
|
|
640
|
-
For a multi-part request, repeat this routing check before each new job. Fetch and follow the
|
|
641
|
-
closest outcome skill first (for example, \`comment-mining\`, \`creator-profile-teardown\`, or
|
|
642
|
-
\`content-repurposing\`) before calling provider APIs or improvising a workflow. Provider calls
|
|
643
|
-
collect inputs for the outcome skill; they do not replace it.
|
|
644
|
-
|
|
645
|
-
## How to Use
|
|
646
|
-
|
|
647
|
-
### If a specific skill is requested (e.g. --skill <slug> or "use the <name> skill")
|
|
648
|
-
Skip search and go directly to **Step 2** with the given slug.
|
|
649
|
-
|
|
650
|
-
### Step 1: Search for a skill
|
|
651
|
-
When the user asks you to do ANY data task (scrape reddit, find emails, research competitors, etc.) **without specifying a skill name**, search the skill catalog first:
|
|
652
|
-
\`\`\`bash
|
|
653
|
-
gooseworks search "reddit scraping"
|
|
654
|
-
\`\`\`
|
|
655
|
-
|
|
656
|
-
### Step 2: Fetch the skill
|
|
657
|
-
Once you have a skill slug, fetch its full content and scripts:
|
|
658
|
-
\`\`\`bash
|
|
659
|
-
gooseworks fetch <slug>
|
|
660
|
-
\`\`\`
|
|
661
|
-
|
|
662
|
-
This prints a JSON object with:
|
|
663
|
-
- **content**: The skill's instructions (SKILL.md) — follow these step by step
|
|
664
|
-
- **scripts**: Python scripts the skill uses — save them locally and run them
|
|
665
|
-
- **files**: Extra files the skill needs (configs, shared tools like \`tools/apify_guard.py\`) — save them relative to \`/tmp/gooseworks-scripts/\`
|
|
666
|
-
- **requiresSkills**: Array of dependency skill slugs (for composite skills)
|
|
667
|
-
- **dependencySkills**: Full content and scripts for each dependency
|
|
668
|
-
|
|
669
|
-
### Step 3: Set up dependency skills (if any)
|
|
670
|
-
If the response includes \`dependencySkills\` (non-empty array), set up each dependency BEFORE running the main skill:
|
|
671
|
-
1. For each dependency in \`dependencySkills\`:
|
|
672
|
-
- Save its scripts to \`/tmp/gooseworks-scripts/<dep-slug>/\`
|
|
673
|
-
- Install any pip dependencies it needs
|
|
674
|
-
2. When the main skill's instructions reference a dependency script (e.g. \`python3 skills/reddit-scraper/scripts/scrape_reddit.py\`), run it from \`/tmp/gooseworks-scripts/<dep-slug>/\` instead
|
|
675
|
-
|
|
676
|
-
### Step 4: Set up and run the skill
|
|
677
|
-
Follow the instructions in the skill's \`content\` field. **Save ALL files from both \`scripts\` AND \`files\` before running anything:**
|
|
678
|
-
|
|
679
|
-
> **Credential translation rule:** Individual skill instructions may contain a legacy \`## Setup\` block with \`export GOOSEWORKS_API_KEY=$(python3 ...)\` and raw \`curl\` commands. **Replace those with the clean equivalents below.**
|
|
680
|
-
> - **Credentials (only needed before running Python scripts, NOT before gooseworks commands):** replace the python one-liner exports with \`eval $(gooseworks env)\`. Skip entirely if you are only using \`gooseworks call\` — it loads credentials automatically.
|
|
681
|
-
> - **Orthogonal run:** replace \`curl ... /v1/proxy/orthogonal/run ... -d '{"api":"X","path":"/Y","body":{...}}'\` with \`gooseworks call X /Y --body='{...}'\`
|
|
682
|
-
> - **Direct proxy:** replace \`curl ... /v1/proxy/<provider>/<path> ... -d '{...}'\` with \`gooseworks call <provider> <path> --body='{...}'\`
|
|
683
|
-
> - **ScrapeCreators:** call its first-party GooseWorks proxy directly with \`gooseworks call scrapecreators <path> --query='{...}'\`. Use ScrapeCreators' official OpenAPI for endpoint parameters; do not use Orthogonal as its endpoint catalog. GET is the default; add \`--method POST --body='{...}'\` only for an official POST operation.
|
|
684
|
-
> - **Orthogonal search:** replace \`curl ... /v1/proxy/orthogonal/search ... -d '{"prompt":"..."}'\` with \`gooseworks orthogonal find "..."\`
|
|
685
|
-
|
|
686
|
-
1. Save each script from \`scripts\` to \`/tmp/gooseworks-scripts/<slug>/scripts/\` — **NEVER save scripts into the user's project directory**
|
|
687
|
-
2. **IMPORTANT: Also save everything from \`files\`** — these contain required modules (like \`tools/apify_guard.py\`) that scripts import at runtime:
|
|
688
|
-
- Files starting with \`tools/\` → save to \`/tmp/gooseworks-scripts/tools/\` (shared path, NOT inside the skill dir)
|
|
689
|
-
- All other files → save to \`/tmp/gooseworks-scripts/<slug>/<path>\`
|
|
690
|
-
- **If you skip this step, scripts will crash with ImportError**
|
|
691
|
-
3. Install any required pip dependencies mentioned in the instructions
|
|
692
|
-
4. Run the script with the parameters described in the instructions
|
|
693
|
-
5. When instructions reference dependency scripts, use paths from Step 3: \`/tmp/gooseworks-scripts/<dep-slug>/<script>\`
|
|
694
|
-
|
|
695
|
-
## Raw API Discovery (fallback)
|
|
102
|
+
Fetch a skill before following it, and hand it the brand you read.
|
|
696
103
|
|
|
697
|
-
|
|
104
|
+
## Data work
|
|
698
105
|
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
\`\`\`bash
|
|
702
|
-
gooseworks orthogonal find "find email by name and company"
|
|
703
|
-
\`\`\`
|
|
704
|
-
Returns matching APIs with endpoint descriptions and per-call pricing.
|
|
106
|
+
In a chat app use the actions: catalog_search finds a skill, catalog_fetch opens it, data_get
|
|
107
|
+
and data_post make its paid data calls, and account_whoami shows the credit balance.
|
|
705
108
|
|
|
706
|
-
|
|
707
|
-
Before calling an API, check its parameters:
|
|
708
|
-
\`\`\`bash
|
|
709
|
-
gooseworks orthogonal describe hunter /v2/email-finder
|
|
710
|
-
\`\`\`
|
|
109
|
+
In a terminal use the commands:
|
|
711
110
|
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
gooseworks
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
-
|
|
720
|
-
|
|
111
|
+
- \`gooseworks search "<task>"\` finds a skill; \`gooseworks fetch <slug>\` prints its instructions,
|
|
112
|
+
scripts, files and dependencies.
|
|
113
|
+
- Save every script and file under \`/tmp/gooseworks-scripts/<slug>/\` (files under \`tools/\` go to
|
|
114
|
+
\`/tmp/gooseworks-scripts/tools/\`), never in the user's project, then follow the skill's steps.
|
|
115
|
+
- \`gooseworks call <provider> <path>\` calls a provider through GooseWorks; \`--query\` and \`--body\`
|
|
116
|
+
take JSON. Use it in place of any raw request a skill shows. A script that needs the GooseWorks
|
|
117
|
+
settings gets them from \`gooseworks env\`.
|
|
118
|
+
- When no skill fits, \`gooseworks orthogonal find "<task>"\` finds an API,
|
|
119
|
+
\`gooseworks orthogonal describe <api> <path>\` shows its parameters and \`gooseworks call\` runs it.
|
|
120
|
+
- \`gooseworks credits\` shows the balance. If a command says you are not signed in, run
|
|
121
|
+
\`gooseworks login\` and let the customer finish signing in. In a cloud sandbox or over SSH,
|
|
122
|
+
run \`gooseworks login --device --no-wait\`, show the customer its link and code, and run
|
|
123
|
+
\`gooseworks login --device\` once they approve.
|
|
124
|
+
- No GooseWorks actions here but a signed-in CLI? \`gooseworks tool --list\` lists them;
|
|
125
|
+
\`gooseworks tool <name> '<json>'\` calls one.
|
|
126
|
+
- Results go in \`~/Gooseworks/\` unless the customer names a place. Ask before saving, and never
|
|
127
|
+
overwrite a file.
|
|
721
128
|
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
gooseworks call apify acts/parseforge~reddit-posts-scraper/runs --body='{"subreddit":"ClaudeAI"}'
|
|
725
|
-
gooseworks call scrapecreators /v2/instagram/post/comments --query='{"url":"https://www.instagram.com/p/POST_ID/"}'
|
|
726
|
-
\`\`\`
|
|
727
|
-
|
|
728
|
-
### Workflow
|
|
729
|
-
1. Search first (\`gooseworks orthogonal find\`) — pick the best API + endpoint
|
|
730
|
-
2. Get details (\`gooseworks orthogonal describe\`) — understand required parameters
|
|
731
|
-
3. Call (\`gooseworks call\`) — invoke with the right parameters
|
|
732
|
-
4. Parse the JSON output for the actual API result
|
|
733
|
-
|
|
734
|
-
## Working Directory & Output Files
|
|
735
|
-
|
|
736
|
-
- **Scripts** always go to \`/tmp/gooseworks-scripts/<slug>/\` — NEVER the user's project directory
|
|
737
|
-
- **Output files** (CSVs, reports, data exports) go to a **GooseWorks working directory**:
|
|
738
|
-
1. If the user specifies where to save results, use that location
|
|
739
|
-
2. Otherwise, default to \`~/Gooseworks/\` — create it if it doesn't exist
|
|
740
|
-
3. **Before saving output**, confirm with the user: *"I'll save the results to ~/Gooseworks/<filename>. Would you like a different location?"*
|
|
741
|
-
4. Organize outputs in subfolders by task type when it makes sense (e.g. \`~/Gooseworks/reddit-scrapes/\`, \`~/Gooseworks/research/\`)
|
|
742
|
-
- **Never overwrite existing files** without asking. If a file already exists, append a timestamp or ask the user
|
|
743
|
-
|
|
744
|
-
## External Endpoints
|
|
745
|
-
|
|
746
|
-
The \`gooseworks\` CLI sends authenticated requests (Bearer \`GOOSEWORKS_API_KEY\`) to:
|
|
747
|
-
|
|
748
|
-
| Endpoint | Method | Wrapped by |
|
|
749
|
-
|----------|--------|------------|
|
|
750
|
-
| \`$GOOSEWORKS_API_BASE/api/skills/search\` | POST | \`gooseworks search\` |
|
|
751
|
-
| \`$GOOSEWORKS_API_BASE/api/skills/catalog/:slug\` | GET | \`gooseworks fetch\` |
|
|
752
|
-
| \`$GOOSEWORKS_API_BASE/v1/credits\` | GET | \`gooseworks credits\` |
|
|
753
|
-
| \`$GOOSEWORKS_API_BASE/v1/proxy/orthogonal/search\` | POST | \`gooseworks orthogonal find\` |
|
|
754
|
-
| \`$GOOSEWORKS_API_BASE/v1/proxy/orthogonal/details\` | POST | \`gooseworks orthogonal describe\` |
|
|
755
|
-
| \`$GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run\` | POST | \`gooseworks call\` (orthogonal-routed providers) |
|
|
756
|
-
| \`$GOOSEWORKS_API_BASE/v1/proxy/{apify,apollo,crustdata,scrapecreators}/*\` | Various | \`gooseworks call\` (direct-proxy providers; ScrapeCreators uses its managed first-party key) |
|
|
757
|
-
|
|
758
|
-
## Security & Privacy
|
|
759
|
-
|
|
760
|
-
- All API calls are authenticated via Bearer token stored locally in \`~/.gooseworks/credentials.json\` (file mode 0600)
|
|
761
|
-
- No credentials are hardcoded or sent to third parties
|
|
762
|
-
- API keys for external services (Apify, Apollo, etc.) are managed server-side — your token never touches them
|
|
763
|
-
- Scripts run locally on your machine; only API requests go through GooseWorks servers. Skill scripts are open source (github.com/gooseworks-ai/goose-skills) — read or pin them before running
|
|
764
|
-
- Credit usage is tracked per-call and visible via \`gooseworks credits\`
|
|
129
|
+
Before paid calls, tell the customer how many calls it will take and the credit total, and wait
|
|
130
|
+
for their yes. Each paid answer says what it charged.
|
|
765
131
|
|
|
766
132
|
## Rules
|
|
767
133
|
|
|
768
|
-
|
|
769
|
-
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.
|
|
770
|
-
2. **Before paid operations**, tell the user the estimated credit cost and get their yes
|
|
771
|
-
3. **If a \`gooseworks\` command exits with "Not logged in"**: tell the user to run \`npx gooseworks login\` (in a cloud sandbox or over SSH, use the code sign-in described in Setup)
|
|
772
|
-
4. **Parse JSON responses** and present data in a readable format to the user
|
|
773
|
-
5. **When running scripts**: save to \`/tmp/gooseworks-scripts/\`, install pip deps, then execute. NEVER pollute the user's project directory
|
|
774
|
-
6. **Output files default to \`~/Gooseworks/\`** — always confirm with the user before saving
|
|
775
|
-
7. **Prefer \`gooseworks call\` over raw curl** — if it returns an error, first fix the parameters (check types, required fields, format) and retry. Only fall back to raw curl if you have strong reason to believe it is a CLI bug, not a parameter issue.
|
|
134
|
+
${server_entry_skills_1.SERVER_ENTRY_SKILL_RULES.all}
|
|
776
135
|
`;
|
|
777
136
|
}
|
|
778
|
-
/**
|
|
779
|
-
* How an entry skill that runs on the GooseWorks connector says what to do when
|
|
780
|
-
* a tool is missing (QA-26 / VWR14). A chat agent that could not find a tool
|
|
781
|
-
* used to tell the customer to run `gooseworks install` in a terminal they do
|
|
782
|
-
* not have; a missing connector tool is fixed by reconnecting, never by a CLI.
|
|
783
|
-
*/
|
|
784
|
-
function connectorPrerequisite(exampleTool, extra = '') {
|
|
785
|
-
return `## Prerequisite — the GooseWorks connector tools
|
|
786
|
-
|
|
787
|
-
Everything below runs through the GooseWorks connector's tools, by the names this skill uses.
|
|
788
|
-
Match on the tool name: a coding agent may show a server prefix (for example
|
|
789
|
-
\`mcp__gooseworks__${exampleTool}\`), a chat app may not.${extra}
|
|
790
|
-
|
|
791
|
-
If a tool named here is missing, the GooseWorks connection or its tool list is stale: ask the
|
|
792
|
-
user to reconnect or refresh GooseWorks in their app's connector settings. Installing or
|
|
793
|
-
updating the \`gooseworks\` CLI never fixes a missing connector tool, so never send a chat-app
|
|
794
|
-
user to a terminal for it. Only a terminal coding agent (Claude Code, Codex, Cursor) that has no
|
|
795
|
-
GooseWorks tools at all connects them, in that terminal, with \`gooseworks install --mcp\` plus
|
|
796
|
-
\`--claude\`, \`--codex\` or \`--cursor\`, then a restart.
|
|
797
|
-
|
|
798
|
-
Older notes or skill copies may name tools the connector no longer lists. Use the tool this skill
|
|
799
|
-
names instead; \`catalog_fetch { type: "skill", slug: "gooseworks-guide" }\` maps every old name.`;
|
|
800
|
-
}
|
|
801
|
-
/**
|
|
802
|
-
* Returns the goose-ads entry SKILL.md content (the `goose-ads` entry skill,
|
|
803
|
-
* formerly `ads-remix`).
|
|
804
|
-
*
|
|
805
|
-
* This is the ads domain skill and a THIN WRAPPER over the backend's single ad
|
|
806
|
-
* generation workflow (adRemixBatchesService, exposed on the connector as
|
|
807
|
-
* `ads_generate` / `ads_creative_edit` — the SAME workflow the ads frontend
|
|
808
|
-
* uses). The skill never generates images, manages renders, or uploads files
|
|
809
|
-
* itself; the backend reserves credits, runs the cloud pipeline, and bills. The
|
|
810
|
-
* skill ALSO routes ad analytics/intelligence to recipe skills fetched on demand
|
|
811
|
-
* from goose-skills. Chat apps reach it through `catalog_fetch`, so every tool it
|
|
812
|
-
* names must be one the connector lists (QA-26 / VWR14; guarded by
|
|
813
|
-
* tests/skills/master-skill.test.ts against tests/fixtures/connector-tool-names.json).
|
|
814
|
-
*/
|
|
137
|
+
/** Image ads: make, edit and study them. */
|
|
815
138
|
function getGooseAdsSkillContent() {
|
|
816
139
|
return `---
|
|
817
140
|
name: goose-ads
|
|
818
141
|
slug: goose-ads
|
|
819
|
-
description:
|
|
820
|
-
GooseWorks ads skill — create, edit, AND analyze ad creative. Turn an approved source ad
|
|
821
|
-
into a branded ad for the user's product, edit/re-roll an existing creative,
|
|
822
|
-
research a brand for ads, OR analyze ad performance (Meta/Google campaign diagnostics,
|
|
823
|
-
creative fatigue, CAC & lead quality, competitor ad intelligence, ad angles & hooks). Use
|
|
824
|
-
when the user says "remix this ad", references a static ad template id/slug, asks to "make
|
|
825
|
-
an ad", "edit this ad", "research my brand", or asks to analyze/diagnose ad campaigns.
|
|
826
|
-
Generation runs through the GooseWorks backend's single cloud workflow (the same one the ads
|
|
827
|
-
app uses) — credits are reserved and billed server-side. Analytics recipes are fetched from
|
|
828
|
-
goose-skills on demand.
|
|
142
|
+
description: Make, edit and study image ads with GooseWorks in this chat, from the brand's own products and approved sources. Start with brand_read and follow the next_step in every answer.
|
|
829
143
|
category: ads
|
|
830
|
-
version:
|
|
144
|
+
version: 3.0.0
|
|
831
145
|
author: GooseWorks
|
|
832
|
-
tags: [gooseworks, ads, remix, static-ad, brand, creative, image, analytics, meta-ads, performance]
|
|
833
146
|
---
|
|
834
147
|
|
|
835
|
-
# GooseWorks
|
|
836
|
-
|
|
837
|
-
The GooseWorks ads skill. Two jobs:
|
|
838
|
-
|
|
839
|
-
1. **Create / edit ad creative** — a **thin wrapper** over the backend's single generation
|
|
840
|
-
workflow. You pick the brand + approved source ad(s) and submit ONE batch; the **backend** runs the
|
|
841
|
-
whole pipeline (compose → generate → persist → judge), reserves and bills credits, and
|
|
842
|
-
stores the renders. You do NOT generate images, call FAL, manage render rows, or upload
|
|
843
|
-
files — those are gone. This is the exact same workflow the GooseWorks ads app uses, so the
|
|
844
|
-
skill and the app can never drift.
|
|
845
|
-
2. **Analyze ad performance** — fetch ad-analytics recipes from goose-skills on demand
|
|
846
|
-
(these are unrelated to generation; see "Analyze / intelligence" below).
|
|
847
|
-
|
|
848
|
-
It works the same in a chat app (ChatGPT, claude.ai, Cowork) and in a terminal coding agent:
|
|
849
|
-
everything except the few steps labelled terminal-only goes through the connector's tools.
|
|
850
|
-
|
|
851
|
-
${CUSTOMER_TALK}
|
|
852
|
-
|
|
853
|
-
${CLI_TOOL_BRIDGE}
|
|
854
|
-
|
|
855
|
-
${connectorPrerequisite('ads_generate', ' There is no HTTP or file fallback: the REST ad\nendpoints are session-cookie-only and reject your token.')}
|
|
856
|
-
|
|
857
|
-
## Start from the brand context — don't re-ask what it already answers
|
|
858
|
-
|
|
859
|
-
If the \`gooseworks\` router handed you brand context and an evidence brief, USE THEM. If you were
|
|
860
|
-
invoked directly, call \`brand_read { brand_id, sections: ["summary","kit","products","learnings"] }\`
|
|
861
|
-
first, then search the Brand Brain (next section). Together they answer most of what the flows
|
|
862
|
-
below would otherwise ask the user:
|
|
863
|
-
|
|
864
|
-
- **Which product to feature** → \`products.items\`. Recommend one real catalog entry; never guess a
|
|
865
|
-
product name and never ask the user to list their products.
|
|
866
|
-
- **The vibe / tone of the copy** → the brand's **voice**. Use it; don't ask "what tone?".
|
|
867
|
-
- **Who the ad is for** → the brand's **audience**. Don't ask "who's the target?".
|
|
868
|
-
- **The angle and offer framing** → **positioning** and value props, sharpened by the Brain:
|
|
869
|
-
lead with an angle past approved creatives proved, and drop anything a saved rule forbids.
|
|
870
|
-
- **What to claim** → only claim-grade proof: a search result with \`approved_ad_claim: true\`, the
|
|
871
|
-
kit's approved claims, or its proof points as written. Other Kit text, documents and
|
|
872
|
-
performance numbers are context.
|
|
873
|
-
- **Logo, colors, fonts** → owned by the backend research pass. **Never re-derive them.**
|
|
874
|
-
- **Whether the facts are trustworthy yet** → **research status**. If it isn't complete, say so in
|
|
875
|
-
one line and continue; the batch queues and runs when research finishes.
|
|
876
|
-
|
|
877
|
-
Don't ask for the angle, product or tone: recommend them with a one-line reason. Ask only for a
|
|
878
|
-
decision the brand read and the Brain search cannot settle (for example an offer or season the
|
|
879
|
-
user hasn't mentioned) and for anything the user must consent to (rights, spend).
|
|
880
|
-
|
|
881
|
-
${BRAIN_FIRST_ENTRY}
|
|
882
|
-
|
|
883
|
-
## Credits — state the total, then get a yes
|
|
884
|
-
|
|
885
|
-
- One token authenticates the GooseWorks tools and resolves your org; never print it. The
|
|
886
|
-
generation tools need no \`target\`.
|
|
887
|
-
- **Nothing paid runs without the user's explicit yes in this chat, given after you state the
|
|
888
|
-
credit total.** The paid calls are \`ads_generate\` (without \`dry_run\`), every
|
|
889
|
-
\`ads_creative_edit\` action, \`ads_approval_decide\` with \`decision: "approve"\`, and every
|
|
890
|
-
\`data_call_provider\` / \`data_post_provider\` call (the data calls an analysis recipe or brand
|
|
891
|
-
research makes; \`gooseworks call\` in a terminal). Reads, dry runs, \`ads_creative_update\` and
|
|
892
|
-
\`request_campaign_generation\` (it only composes plans) are free.
|
|
893
|
-
- The balance is \`credits.available_credits\` from \`account_whoami\`; a dry-run \`estimate\` also
|
|
894
|
-
carries \`available_credits\`.
|
|
895
|
-
- The backend reserves the quoted credits when a paid call starts and bills only the images
|
|
896
|
-
that complete. A rejection with \`insufficient_credits\` means the wallet is short: tell the
|
|
897
|
-
user the total and their balance in plain words, offer fewer images or a top-up, and stop.
|
|
898
|
-
Never retry blindly.
|
|
899
|
-
|
|
900
|
-
How to get the total for each paid call:
|
|
901
|
-
|
|
902
|
-
| Paid call | Credit total to state |
|
|
903
|
-
| --- | --- |
|
|
904
|
-
| \`ads_generate\` with \`source.template_ids\` | The same call with \`dry_run: true\` returns \`estimate\`: \`total_credits\` for \`images\` images (plus \`credits_per_image\`, \`rates\` and \`unknown_template_ids\`). |
|
|
905
|
-
| \`ads_generate\` with \`source.community_ad_ids\` or \`source.creative_ids\` | No dry run (it returns \`not_available\`; these are priced when submitted). Pass \`quality\` explicitly (the user's choice, else \`high\`, the app default) and quote the images (each source's \`variants\` × its \`ratios\`) × \`estimate.rates.<quality>\` as the most it will cost (an engine without quality tiers costs the lower \`rates.low\`). \`rates\` comes with any template dry run; with no template at hand, dry-run one Surprise-me pick. |
|
|
906
|
-
| \`ads_creative_edit\` \`animate\` | The same call with \`dry_run: true\` returns its \`estimate\`. |
|
|
907
|
-
| \`ads_creative_edit\` \`regenerate\` / \`precision_edit\` | No dry run. Pass \`quality\` in the action's payload (without it \`precision_edit\` copies the source render's tier) and quote the images × \`estimate.rates.<quality>\` as the most it will cost: \`regenerate\` with \`mode: "variation"\` makes one per ratio (omitted \`ratios\` make three); \`edit\`, \`exact\` and \`precision_edit\` make one. |
|
|
908
|
-
| \`ads_creative_edit\` \`resize\` | No dry run and no quality setting: it renders at the server's default tier (\`high\` today). Quote one image per placement × the larger of \`estimate.rates.high\` and \`credits_per_image\` from a template dry run without \`quality\` (that dry run uses the server's default tier) as the most it will cost. \`platforms\` expands to every placement: meta 4, google 4, tiktok 2, linkedin 3, reddit 3, x 2; pass \`targets\` for fewer. |
|
|
909
|
-
| \`ads_creative_edit\` \`layerize\` | No dry run. It holds about 80 credits while it runs and charges the actual cost of the split (usually less). Say so and get the yes before sending \`layerize: { confirmed: true }\`. |
|
|
910
|
-
| \`ads_approval_decide\` approve | The \`credits\` that \`request_campaign_generation\` and \`ads_creative_read { brand_id, view: "approvals", batch_id }\` return for those plans. |
|
|
911
|
-
| \`data_call_provider\` / \`data_post_provider\` | The calls a recipe will make × their price: a ScrapeCreators call costs 1 credit today, and each result reports what it charged. A fal or ElevenLabs POST quotes free with the same call plus \`query: { quote_only: true }\`. State the rough total for the whole recipe once, before its first paid call. |
|
|
912
|
-
|
|
913
|
-
## Live MCP contract — inspect it before asking
|
|
914
|
-
|
|
915
|
-
The currently registered MCP tool schemas are the source of truth for inputs, supported choices,
|
|
916
|
-
and defaults. Do not copy an exhaustive input list from this skill or rely on remembered fields.
|
|
917
|
-
|
|
918
|
-
Before each tool call:
|
|
919
|
-
|
|
920
|
-
1. Inspect the live schema for the tool you are about to use.
|
|
921
|
-
2. Fill required inputs already known from the Brand Kit, selected source, or conversation.
|
|
922
|
-
3. Ask the user only for required inputs that cannot be inferred and for choices that materially
|
|
923
|
-
change the result. Do not turn every optional field into a questionnaire.
|
|
924
|
-
4. Omit unspecified optional settings so the backend applies its current app defaults. Two
|
|
925
|
-
exceptions: always pass \`ratios\` on every source (omitted ratios make three images per
|
|
926
|
-
variant), and keep the same \`quality\` setting in the quote and the paid call (both omitted
|
|
927
|
-
for a template dry run, or the explicit \`quality\` the credits table asks for).
|
|
928
|
-
5. If the live schema conflicts with this workflow, follow the live schema and report the drift
|
|
929
|
-
(see "Report problems" in the rules).
|
|
930
|
-
|
|
931
|
-
## The ad tools
|
|
148
|
+
# GooseWorks ads
|
|
932
149
|
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
picks, Community rows whose \`item_type\` is \`template\`), \`community_ad_ids: [{ community_id,
|
|
936
|
-
variants?, ratios }]\` (Community rows whose \`item_type\` is \`creative\`; the backend snapshots
|
|
937
|
-
them), or \`creative_ids: [{ project_id, render_id?, variants?, ratios }]\` (remix the user's own
|
|
938
|
-
finished ads). Optional: \`product_name\` (a real product), \`prompt\` (a short steering note),
|
|
939
|
-
\`reference_image_urls\`, \`quality\`. \`dry_run: true\` quotes template sources and reserves
|
|
940
|
-
nothing. A real call GENERATES at once and returns \`{ job_id }\` (\`kind: "ads_batch"\`) and the
|
|
941
|
-
\`batch\`, which already carries its \`links\` (below). If the
|
|
942
|
-
brand's research is still running the batch is \`queued\` and starts on its own when research
|
|
943
|
-
finishes: tell the user it'll appear shortly, don't error.
|
|
944
|
-
- \`job_get { job_id, kind: "ads_batch" }\` — poll a batch. \`status\` is \`queued\`, \`running\`,
|
|
945
|
-
\`complete\`, \`partial_failure\` or \`failed\`; \`progress\` counts \`completed\` / \`failed\` /
|
|
946
|
-
\`pending\` images. \`result.creatives[]\` carry each creative's \`renders[]\` (\`id\`, \`status\`,
|
|
947
|
-
\`ratio\`, \`output_url\`, \`age_seconds\` since queued, \`elapsed_seconds\` generating). A creative
|
|
948
|
-
is done when its \`pending\` is 0, NOT when \`current_render_url\` is set (during a regenerate it
|
|
949
|
-
still points at the prior image). A render only failed when its \`status\` is \`"failed"\`: a slow
|
|
950
|
-
render is healthy, and re-submitting it double-bills. \`result.links\` holds the app links you end
|
|
951
|
-
the run with: \`brand_url\` (the brand's page, with all its ads) and \`creative_links: [{
|
|
952
|
-
project_id, app_url }]\` (each creative's page). \`brand_url\` is \`null\` and the list empty only
|
|
953
|
-
if the link lookup failed; the ads are still made. A server older than this skill returns no
|
|
954
|
-
\`links\` (and no \`app_url\` / \`brand_url\` on creative reads): then hand back the images
|
|
955
|
-
only and don't mention links.
|
|
956
|
-
- \`ads_creative_read { brand_id }\` — the brand's generated creatives, newest first (filter with
|
|
957
|
-
\`batch_id\`, \`tags\`, \`approved_only\`); each row has its \`app_url\` and the list has the
|
|
958
|
-
\`brand_url\`. \`creative_id\` reads one with its \`renders\`, plus \`creative.app_url\` and
|
|
959
|
-
\`creative.brand_url\`.
|
|
960
|
-
- \`ads_template_read\` — find or inspect a source (see "Picking source ads"). \`template_id\` reads one.
|
|
961
|
-
- \`ads_creative_edit { brand_id, creative_id, action }\` — every paid edit of one creative, one
|
|
962
|
-
\`action\` per call: \`regenerate\` (\`regenerate: { mode: "variation" }\` for another take;
|
|
963
|
-
\`mode: "edit"\` or \`"exact"\` with \`source_render_id\` and \`prompt\`), \`precision_edit\` (\`source_render_id\`
|
|
964
|
-
plus a \`note\` or region \`annotations\`), \`resize\` (\`source_render_id\` plus \`platforms\` or
|
|
965
|
-
\`targets\`), \`layerize\` (\`confirmed: true\`), \`animate\` (\`source_image_url\`; only when
|
|
966
|
-
\`account_whoami\` shows the Animate Images feature; for the full flow fetch the \`animate-image\`
|
|
967
|
-
skill). Returns \`{ job_id }\`: poll \`job_get\` with \`kind: "ads_batch"\` (regenerate, resize,
|
|
968
|
-
precision_edit) or \`kind: "animate"\`; for layerize read
|
|
969
|
-
\`ads_creative_read { brand_id, creative_id, include: ["layers"] }\`. While the brand's research is
|
|
970
|
-
still running, \`regenerate\`, \`resize\` and \`precision_edit\` refuse with
|
|
971
|
-
\`brand_research_in_progress\`: tell the user and try again when it finishes.
|
|
972
|
-
- \`ads_creative_update { brand_id, creative_id, patch }\` — free. \`patch.feedback: { render_id, rating:
|
|
973
|
-
"happy" | "neutral" | "sad", comment?, reasons? }\` records the user's reaction (it feeds the
|
|
974
|
-
quality loop); \`patch.tags\` replaces the creative's tags.
|
|
975
|
-
- \`ads_template_create { brand_id, source, rights_attested? }\` — register the user's own image as a
|
|
976
|
-
private source template (see "Upload" below).
|
|
150
|
+
Use GooseWorks to make and improve the customer's image ads, here in this chat. Recommend one
|
|
151
|
+
direction with a one-line reason and offer at most two others.
|
|
977
152
|
|
|
978
|
-
|
|
153
|
+
- New ads: pick a source from the brand's own ads and templates, or find one with catalog_search
|
|
154
|
+
and open it with catalog_fetch. ads_generate makes the ads: get its price first, tell the
|
|
155
|
+
customer the credit total, and make them only after their yes.
|
|
156
|
+
- A batch on its way: job_get. Finished ads: ads_read.
|
|
157
|
+
- One ad: another take, an edit, a new size, an animation, its tags or the customer's rating, all
|
|
158
|
+
with ads_edit.
|
|
159
|
+
- The customer's own image as a template: ads_template_save. Their files: media_upload.
|
|
160
|
+
- Campaigns: campaign_read, campaign_save and campaign_ideas. campaign_generate plans and prices a
|
|
161
|
+
campaign's ads; ads_review makes them once the customer says yes to the total.
|
|
162
|
+
- How ads are doing: meta_read, or an analysis skill found with catalog_search, whose data comes
|
|
163
|
+
through data_get and data_post.
|
|
979
164
|
|
|
980
|
-
|
|
981
|
-
submit generates at once. Never promise a review step before the images render. Plans exist only
|
|
982
|
-
for a campaign's concepts (planned with \`campaign_read\`, \`campaign_upsert\` and
|
|
983
|
-
\`add_campaign_concept\`; follow the connector guide for those):
|
|
984
|
-
|
|
985
|
-
1. \`request_campaign_generation { campaign_id }\` composes the plans for the concepts with no
|
|
986
|
-
creatives yet (\`concept_ids\` re-runs chosen ones; \`count\` only for a number the user named). It
|
|
987
|
-
spends nothing and returns \`batch_ids\` and \`credits\`. Never say generation has started.
|
|
988
|
-
2. Tell the user what will be made and the credit total, and wait for their explicit yes in this
|
|
989
|
-
chat. Never send them to a button in the app; a campaign link is only a place to look.
|
|
990
|
-
3. Read \`ads_creative_read { brand_id, view: "approvals", batch_id }\` until that batch's plans are
|
|
991
|
-
\`awaiting_approval\` and none is \`composing\`. If its credit total differs from what they
|
|
992
|
-
agreed to, state the new total and ask again.
|
|
993
|
-
4. \`ads_approval_decide { brand_id, decision: "approve", batch_id, user_quote: "<their exact words>" }\`
|
|
994
|
-
for each batch, then poll the batch ids it returns with \`job_get\` (\`kind: "ads_batch"\`) and
|
|
995
|
-
end with each batch's \`result.links\`, as in step 7 of the workflow below.
|
|
996
|
-
|
|
997
|
-
Before approving, a steer is free: \`ads_approval_decide { brand_id, creative_id, decision: "revise",
|
|
998
|
-
revise: { message } }\` recomposes that plan (read the approvals view again), and
|
|
999
|
-
\`decision: "edit_plan"\` patches it directly. Editing the campaign in between discards these plans.
|
|
1000
|
-
|
|
1001
|
-
## Keep the brand kit in sync — reconcile, then save or propose
|
|
1002
|
-
|
|
1003
|
-
The brand kit is the source of truth every generation reads. During ANY task, when the user
|
|
1004
|
-
**tells you something about the brand or asks to change something brand-level** — a different
|
|
1005
|
-
tagline, audience, voice, a product's name/price/description, "our logo is X", "we don't sell Y
|
|
1006
|
-
anymore", a new product photo — treat it as a possible kit update, don't just use it for this one
|
|
1007
|
-
ad and forget it:
|
|
1008
|
-
|
|
1009
|
-
1. **Check it against the kit.** Call \`brand_read\` with \`kit\` and \`learnings\` for the active brand and see whether what the user said
|
|
1010
|
-
matches, is missing from, or contradicts the kit.
|
|
1011
|
-
2. **If it's already in the kit and matches** — nothing to do; proceed.
|
|
1012
|
-
3. **If it's new or different**, persist an explicit request to correct or remember the brand
|
|
1013
|
-
through the policy below; that request is already authorization. For an ambiguous one-ad
|
|
1014
|
-
direction, ask once whether it should stick. Agent-derived suggestions become proposals.
|
|
1015
|
-
4. **Persist with the canonical write tools** (send only changed fields):
|
|
1016
|
-
- \`brand_update\` with explicit user-correction intent — structured brand fields or products;
|
|
1017
|
-
an inferred structured field uses agent-proposal intent instead. Follow the live schema.
|
|
1018
|
-
- \`media_upload\` / \`media_update\` — the user's own product and reference photos.
|
|
1019
|
-
Inspect each live schema and send only the fields needed for the confirmed change.
|
|
1020
|
-
5. **Read back what changed** before saying saved, then continue the task. (Use the research
|
|
1021
|
-
workflow for researched logo/colors/fonts; explicit user edits use only fields supported by
|
|
1022
|
-
the canonical tool schema and the correction policy below.)
|
|
1023
|
-
|
|
1024
|
-
This is the parity gap the app closes in-product: a brand fact the user gives mid-task should be
|
|
1025
|
-
able to flow back into the kit — with their ok — instead of being lost.
|
|
1026
|
-
|
|
1027
|
-
${DURABLE_BRAND_CAPTURE}
|
|
1028
|
-
|
|
1029
|
-
## Picking source ads — use approved sources, not the retired catalog
|
|
1030
|
-
|
|
1031
|
-
When the user wants to make ads but has NOT named a specific template (id/slug/Community
|
|
1032
|
-
ad/upload), do NOT silently browse the raw catalog and hand-pick for them. Instead send **one
|
|
1033
|
-
proposal** — it mirrors the web app and keeps the human in the loop without an interview:
|
|
1034
|
-
|
|
1035
|
-
1. **Propose the direction yourself.** From the brand read and the evidence brief, recommend the
|
|
1036
|
-
product, angle/offer and tone, with a one-line reason naming what the Brain showed (a past
|
|
1037
|
-
approved angle, a rule it respects). **Do NOT ask what kind of ads they want, which product,
|
|
1038
|
-
or the vibe.** Keep any direction the user already gave. This shapes both the source choice
|
|
1039
|
-
and your steering \`prompt\`.
|
|
1040
|
-
2. **Recommend a source in the same message: their own ads, Community, upload, or "Surprise me".**
|
|
1041
|
-
Default to their own approved ads when suitable ones exist, otherwise Surprise-me picks for
|
|
1042
|
-
the brand; list the other paths as one-line alternatives. You may resolve the picks and run the
|
|
1043
|
-
free dry run first so the proposal already carries the credit total. Show a list of sources as
|
|
1044
|
-
one table with every row and its image link, and mark your one suggestion.
|
|
1045
|
-
- **Their own ads** → \`ads_template_read { brand_id, mode: "mine", filters: { relationship: "self" } }\`
|
|
1046
|
-
and let them choose. \`mode: "competitor"\` rows are research and inspiration, never proof that
|
|
1047
|
-
the user owns the ad.
|
|
1048
|
-
- **Community** → \`ads_template_read { brand_id, mode: "query", query: "<the angle and look>" }\`
|
|
1049
|
-
ranks Community ads by meaning; each row's \`sourceId\` (with \`title\` and \`thumbnailUrl\`) goes
|
|
1050
|
-
in \`source.community_ad_ids[].community_id\`. To browse the feed instead, use \`mode:
|
|
1051
|
-
"community"\`: its rows carry \`item_type\`, and a \`template\` id goes in \`source.template_ids\`,
|
|
1052
|
-
a \`creative\` id in \`source.community_ad_ids\`. The backend snapshots a Community creative
|
|
1053
|
-
itself; there is no separate step. Let the user choose.
|
|
1054
|
-
- **Upload** → the user's own image becomes a private template: \`media_upload\` it (\`scope:
|
|
1055
|
-
"brand"\`, \`scope_id: <brand_id>\`, \`kind: "image"\`; in a chat app \`source.type: "bytes"\`), then
|
|
1056
|
-
\`ads_template_create { brand_id, source: { type: "media", media_id } }\` (or \`source: { type:
|
|
1057
|
-
"url", url }\` for a public image). Set \`rights_attested: true\` only after the user explicitly
|
|
1058
|
-
confirms they own it; this is the ownership/rights input. Never claim rights for a competitor
|
|
1059
|
-
ad or an image found online.
|
|
1060
|
-
- **Surprise me** (they want you/the app to pick) → \`ads_template_read { brand_id, mode:
|
|
1061
|
-
"surprise", count: 4 }\` picks remixable Community ads for the brand, shuffled so picks stay
|
|
1062
|
-
fresh. Every pick is a template: show them, and generate
|
|
1063
|
-
from the ones the user keeps (or from all of them if they said "just make them").
|
|
1064
|
-
- **Browse in the app** → the one link you build yourself: \`<app>/create?brand=<brand-slug>&cli=true\`,
|
|
1065
|
-
with the active brand's slug, where \`<app>\` is the origin of a \`brand_url\` a tool returned
|
|
1066
|
-
(the part before \`/?brand=\`: \`https://ads-staging.gooseworks.ai/?brand=acme\` gives
|
|
1067
|
-
\`https://ads-staging.gooseworks.ai\`), so it opens on the user's own environment. Reuse a
|
|
1068
|
-
\`brand_url\` you already have from this run, or read one cheaply with
|
|
1069
|
-
\`ads_creative_read { brand_id, limit: 1 }\`; if none comes back, use \`https://make.gooseworks.ai\`.
|
|
1070
|
-
In this mode the app shows a copyable remix prompt at the bottom (dismissable / switchable
|
|
1071
|
-
back to the UI composer). They browse their own and Community sources and copy the prompt.
|
|
1072
|
-
3. **Close the loop.** When the user **pastes back the copyable remix prompt** from the app
|
|
1073
|
-
(it names the brand + the templates they chose), THAT is your cue to generate: resolve the
|
|
1074
|
-
named source(s) with \`ads_template_read\`, quote, and collect only the unresolved required inputs.
|
|
1075
|
-
|
|
1076
|
-
If the user already named an owned source (id/slug), a Community ad, or an upload, skip the source
|
|
1077
|
-
choice. Competitor ads may inform the angle or structure, but describe them as inspiration, never
|
|
1078
|
-
claim ownership, and never attest rights for the user. Never use the retired curated third-party
|
|
1079
|
-
catalog.
|
|
1080
|
-
|
|
1081
|
-
## Workflow — make ads from a template
|
|
1082
|
-
|
|
1083
|
-
1. **Resolve the brand and its evidence.** List brands with \`brand_read\` (no \`brand_id\`), then
|
|
1084
|
-
read the selected brand's summary, kit, products and
|
|
1085
|
-
learnings and search the Brand Brain as above. If research isn't \`complete\`, you can still
|
|
1086
|
-
submit (the batch queues and runs when research finishes) — just tell the user. Use the read to
|
|
1087
|
-
pick \`product_name\` (a real entry from \`products.items\`, not a guess) and, if the user supplied
|
|
1088
|
-
product photos, \`reference_image_urls\` (public URLs; \`media_upload\` a local file first).
|
|
1089
|
-
2. **Pick the source ad(s) via the proposal above.** Read each chosen template with
|
|
1090
|
-
\`ads_template_read { brand_id, template_id }\`. Community creatives (a query row's \`sourceId\`,
|
|
1091
|
-
a feed row with \`item_type: "creative"\`) and the user's own finished ads go straight into
|
|
1092
|
-
\`source.community_ad_ids\` / \`source.creative_ids\`.
|
|
1093
|
-
3. **(Optional) Craft the steering prompt.** The \`prompt\` is OPTIONAL — this is where the skill
|
|
1094
|
-
adds value: turn the user's intent (from step 1) into a concise steering note (e.g. tone,
|
|
1095
|
-
season, emphasis). Don't over-specify; the backend pipeline + brand kit handle palette, fonts,
|
|
1096
|
-
product swap.
|
|
1097
|
-
4. **Quote the cost.** Call \`ads_generate\` with the exact arguments you will submit plus
|
|
1098
|
-
\`dry_run: true\` (template sources), or work out the total as in the credits table. Drop or
|
|
1099
|
-
replace anything in \`unknown_template_ids\`. State the image count and credit total in one line
|
|
1100
|
-
and wait for the user's explicit yes.
|
|
1101
|
-
5. **Submit ONE batch** after that yes: the same \`ads_generate\` call without \`dry_run\`. Keep the
|
|
1102
|
-
returned \`job_id\`.
|
|
1103
|
-
6. **Poll until done.** \`job_get { job_id, kind: "ads_batch" }\` every ~20-30s until every creative's
|
|
1104
|
-
\`pending\` is 0. Most images finish in a few minutes; text-heavy templates and \`quality: high\`
|
|
1105
|
-
take longer. Read each render's \`elapsed_seconds\` rather than guessing; do NOT re-submit
|
|
1106
|
-
thinking it stalled (that double-bills). If \`ads_generate\` refused with
|
|
1107
|
-
\`brand_research_required\`, the brand was never researched: run "Brand research" below, then
|
|
1108
|
-
quote and submit again.
|
|
1109
|
-
7. **Hand back the ads with their links.** Show every finished image (\`renders[].output_url\` of
|
|
1110
|
-
completed renders) and say in one line what failed, if anything. Then give the links from the
|
|
1111
|
-
last \`job_get\`'s \`result.links\`, copied verbatim: the \`brand_url\` where all the brand's
|
|
1112
|
-
ads are, and the \`app_url\` of each creative with a finished image (match
|
|
1113
|
-
\`creative_links[].project_id\` to \`result.creatives[].id\`; skip a creative whose renders all
|
|
1114
|
-
failed). For a big batch (more than about 8 creatives) give the \`brand_url\` and offer the
|
|
1115
|
-
rest. Skip a missing or \`null\` link; never build an app URL yourself. Never end on just
|
|
1116
|
-
"done" or a file path.
|
|
1117
|
-
|
|
1118
|
-
## Workflow — edit an existing ad
|
|
1119
|
-
|
|
1120
|
-
User wants to tweak a creative they already made → \`ads_creative_edit\`. Read the creative first
|
|
1121
|
-
(\`ads_creative_read { brand_id, creative_id }\`) to get the render they mean. Infer the action
|
|
1122
|
-
from their request: another take (\`regenerate\`, \`mode: "variation"\`), a targeted change
|
|
1123
|
-
(\`regenerate\` with \`mode: "edit"\`, or \`precision_edit\` when they point at a region), an exact
|
|
1124
|
-
instructed change (\`mode: "exact"\`), new placements (\`resize\`), editable layers (\`layerize\`) or a
|
|
1125
|
-
short video (\`animate\`). Ask only for a required source or instruction that is still missing,
|
|
1126
|
-
state the credit total from the credits table, get the yes, submit, poll as above, and hand back
|
|
1127
|
-
the new images with their links: \`result.links\` from \`job_get\` for \`regenerate\`, \`resize\` and
|
|
1128
|
-
\`precision_edit\`; \`creative.app_url\` and \`creative.brand_url\` from \`ads_creative_read { brand_id,
|
|
1129
|
-
creative_id }\` for \`animate\` and \`layerize\`.
|
|
1130
|
-
|
|
1131
|
-
## Brand research
|
|
1132
|
-
|
|
1133
|
-
Prefer the backend's result. \`brand_read { brand_id, sections: ["summary"] }\`: if
|
|
1134
|
-
\`research_status\` is \`complete\`, REUSE it — never re-research. Proof points and the full product
|
|
1135
|
-
catalog keep arriving until \`enrichment.settled\` is true.
|
|
1136
|
-
|
|
1137
|
-
**The split — backend owns visuals, you own the qualitative depth:**
|
|
1138
|
-
|
|
1139
|
-
- **Backend LIGHT pass (automatic).** A new brand comes from the connector's setup flow
|
|
1140
|
-
(\`brand_onboarding { action: "status" }\`, then its \`next_step\`). For an additional brand, check
|
|
1141
|
-
it is absent (\`brand_read\` with no \`brand_id\`), then \`brand_create { name, website_url }\` (free).
|
|
1142
|
-
The website starts the same backend research the web app uses: it resolves the
|
|
1143
|
-
**authoritative logo, colors, and fonts** plus a baseline kit and returns \`research_job_id\`; poll
|
|
1144
|
-
\`job_get { job_id: research_job_id, kind: "brand_research" }\` (or \`brand_read\`) until
|
|
1145
|
-
\`research_status\` is \`complete\` — usually under a minute. If it returns \`reused_existing: true\`,
|
|
1146
|
-
tell the user and use that brand. You can't reproduce those visual signals, so **never
|
|
1147
|
-
re-derive logo/colors/fonts.**
|
|
1148
|
-
- **Your DEEP pass (optional).** You add the qualitative depth the light pass leaves thin —
|
|
1149
|
-
positioning, audience, voice, brand type, value props, proof points, products — grounded on
|
|
1150
|
-
the actual site.
|
|
1151
|
-
|
|
1152
|
-
**Deep research flow:**
|
|
1153
|
-
|
|
1154
|
-
1. Fetch the \`brand-research\` skill (\`catalog_fetch { type: "skill", slug: "brand-research" }\` in a
|
|
1155
|
-
chat app; \`gooseworks fetch brand-research\` in a terminal) and follow its phases. Its data
|
|
1156
|
-
calls are paid: state the credit total (credits table) and get the yes first. **Ground every
|
|
1157
|
-
fact on the brand's own site** — if the site can't be read, say so and ask the user; never
|
|
1158
|
-
guess a category from the brand name alone.
|
|
1159
|
-
2. **Save what you improved.**
|
|
1160
|
-
- **As proposals (the default):** \`brand_update { brand_id,
|
|
1161
|
-
knowledge_intent: "agent_proposal", rationale, patch: { knowledge: { positioning?, audience?,
|
|
1162
|
-
voice?, brandType?, tagline?, valueProps? } } }\`. They stay pending until the user accepts
|
|
1163
|
-
them in the app.
|
|
1164
|
-
- **As the full research pack (only when you wrote all of it; in a chat app, only for a brand
|
|
1165
|
-
with no website, see below):** with \`file_write\`, under
|
|
1166
|
-
\`agent-config/brands/<slug>/brand-research/\`, write all four docs \`brand-summary.md\`,
|
|
1167
|
-
\`visual-identity.md\`, \`audience.md\` and \`competitors.md\` (real content, at least a few
|
|
1168
|
-
sentences each) plus \`kit-patch.json\`: \`{ positioning?, audience?, voice?, brandType?,
|
|
1169
|
-
tagline?, valueProps?: string[], proofPoints?: [{ text, source_url }], products?: [{ name,
|
|
1170
|
-
description?, link?, pricing?, imageUrls?: string[] }] }\` with only the fields you improved;
|
|
1171
|
-
every proof point copied word for word from the brand's own page at \`source_url\`; product
|
|
1172
|
-
images only from URLs already in GooseWorks storage; **no logo / colors / fonts**. Then
|
|
1173
|
-
\`brand_update { brand_id, patch: { finalize_research: true } }\` merges it NON-CLOBBERINGLY
|
|
1174
|
-
(never over the backend's visuals or a user edit). **If any of the four docs is missing or
|
|
1175
|
-
nearly empty, finalize fails and marks the brand's research as failed**, so never finalize a
|
|
1176
|
-
partial pack.
|
|
1177
|
-
3. **Verify:** \`brand_read\` again (\`summary\`, \`kit\`) and confirm what you saved before generating.
|
|
1178
|
-
|
|
1179
|
-
**If the brand has NO website**, the backend light pass can't run and generation goes ahead with
|
|
1180
|
-
an empty kit, so ads come out off-brand. Do the deep pass from what the user tells you and save the
|
|
1181
|
-
full research pack, so the brand has a kit and a record to debug a wrong run (this is how a bad
|
|
1182
|
-
classification, e.g. mislabelling a SaaS as a "drink company", used to vanish).
|
|
1183
|
-
|
|
1184
|
-
## Analyze / intelligence (fetched recipes — NOT generation)
|
|
1185
|
-
|
|
1186
|
-
These are analysis recipes you fetch and follow; they don't use the generation tools, but their
|
|
1187
|
-
data calls are paid (credits table: state the total and get the yes before the first one). Fetch with \`catalog_fetch { type: "skill", slug: "<slug>" }\` in a chat app or
|
|
1188
|
-
\`gooseworks fetch <slug>\` in a terminal. Pick the closest match; if unsure, search first with
|
|
1189
|
-
\`catalog_search { type: "skill", query: "<what the user wants>" }\` (terminal:
|
|
1190
|
-
\`gooseworks search "<what the user wants>"\`):
|
|
1191
|
-
- **Campaign performance diagnosis** ("why is my Meta/Google campaign underperforming",
|
|
1192
|
-
creative fatigue, learning phase, pacing, auction overlap) → \`meta-ads-analyzer\`
|
|
1193
|
-
(or \`ad-campaign-analyzer\` for cross-platform).
|
|
1194
|
-
- **Lead/CAC quality** ("are these ads driving qualified leads", true CAC vs vanity CPA,
|
|
1195
|
-
Scale/Keep/Investigate/Cut) → \`ad-lead-quality-analyzer\`.
|
|
1196
|
-
- **Competitor ad intelligence** ("what ads are competitors running") →
|
|
1197
|
-
\`competitor-ad-intelligence\` (Meta Ad Library: \`meta-ad-scraper\`; Google: \`google-ad-scraper\`).
|
|
1198
|
-
- **Creative ideation** (ad angles, winning hooks) → \`ad-angle-miner\` / \`trending-ad-hook-spotter\`.
|
|
1199
|
-
- **Policy / landing-page checks** → \`meta-ad-policy-checker\` / \`ad-to-landing-page-auditor\`.
|
|
1200
|
-
|
|
1201
|
-
A recipe's provider calls go through the connector in a chat app (\`data_call_provider\` for GET,
|
|
1202
|
-
\`data_post_provider\` for POST) and through \`gooseworks call\` in a terminal; both are billed. Saving and running
|
|
1203
|
-
its scripts (under \`/tmp/gooseworks-scripts/<slug>/\`) is terminal-only: without a terminal, do
|
|
1204
|
-
that step's analysis yourself from the data the tools return, and never ask the user to run a
|
|
1205
|
-
command.
|
|
165
|
+
Then follow the next_step in every answer.
|
|
1206
166
|
|
|
1207
167
|
## Rules
|
|
1208
168
|
|
|
1209
|
-
|
|
1210
|
-
GooseWorks connection is stale: ask the user to reconnect or refresh GooseWorks. Never send a
|
|
1211
|
-
chat-app user to a terminal or a CLI install.
|
|
1212
|
-
- **One backend workflow** — generation is \`ads_generate\` / \`ads_creative_edit\` ONLY.
|
|
1213
|
-
Do NOT call FAL, the media proxy, \`submit_render\`, \`update_render_status\`, or upload render
|
|
1214
|
-
files yourself; do NOT fetch a local remix recipe to generate. The backend owns it.
|
|
1215
|
-
- **State the credit total and get an explicit yes before every paid call** (credits table above).
|
|
1216
|
-
Relay \`insufficient_credits\` plainly if the submit is rejected — don't retry blindly.
|
|
1217
|
-
- **No plan step for one-off ads.** Only a campaign's plans wait for approval
|
|
1218
|
-
(\`request_campaign_generation\` → \`ads_approval_decide\` with the user's words as \`user_quote\`).
|
|
1219
|
-
- **Always end a successful run with the finished images and their links**, copied verbatim:
|
|
1220
|
-
each creative's \`app_url\` and the \`brand_url\` from \`result.links\`, or from the creative
|
|
1221
|
-
read (\`creative.app_url\`, \`creative.brand_url\`) after \`animate\` or \`layerize\`. When the
|
|
1222
|
-
server returns no links, end with the images only. Never end on just "done" or a file path, and
|
|
1223
|
-
never build an app URL yourself (the one exception is the browse link below).
|
|
1224
|
-
- **Search the Brain before proposing.** After the brand read and before choosing an angle,
|
|
1225
|
-
claim or source — or asking for a brand fact — run the task's \`knowledge_search\` and carry
|
|
1226
|
-
its evidence brief. A failed or empty search is stated as such, never as "no evidence exists".
|
|
1227
|
-
- **Use approved source paths.** If the user didn't name a source, recommend one in the single
|
|
1228
|
-
proposal (own ads, Community, upload, Surprise me, or browse in the app). Surprise me is
|
|
1229
|
-
\`ads_template_read\` with \`mode: "surprise"\`; browsing uses \`/create?brand=<slug>&cli=true\`.
|
|
1230
|
-
Never use the retired curated third-party catalog. Generate when they paste the app's copyable
|
|
1231
|
-
remix prompt back, or when they accept the surprise picks.
|
|
1232
|
-
- **Treat competitor ads as inspiration** — never attest rights, imply ownership, or promise to
|
|
1233
|
-
copy a competitor's distinctive expression.
|
|
1234
|
-
- **Reconcile brand facts into the kit** — when the user states or changes something brand-level
|
|
1235
|
-
mid-task, compare it with \`brand_read\`. Save explicitly authorized corrections through
|
|
1236
|
-
\`brand_update\` with correction intent and the user's exact statement, or the user's own
|
|
1237
|
-
images through \`media_upload\`; read back before saying saved. Proposed improvements stay
|
|
1238
|
-
pending. Ask only when it is unclear whether a one-ad direction should apply to future ads.
|
|
1239
|
-
- **Record feedback** — when the user reacts to a generated image, call \`ads_creative_update\`
|
|
1240
|
-
with \`patch.feedback\` so the quality loop learns.
|
|
1241
|
-
- **Don't busy-loop** — poll \`job_get\` on a sensible interval (~20-30s); a \`queued\` batch is
|
|
1242
|
-
waiting on research and will start on its own.
|
|
1243
|
-
- **Report problems so we can fix them** — when a batch fails or is rejected and you can't resolve
|
|
1244
|
-
it, a required brand input/asset is missing, or an instruction is ambiguous or contradictory:
|
|
1245
|
-
in a terminal run \`gooseworks log "<what happened>" --event-type <error|blocker|missing_input|confusion> --details '<json with the real error and step>'\`,
|
|
1246
|
-
or call the \`log_cli_event\` tool if your connection lists it. A chat app without either skips
|
|
1247
|
-
this step. Always tell the user too.
|
|
169
|
+
${server_entry_skills_1.SERVER_ENTRY_SKILL_RULES.ads}
|
|
1248
170
|
`;
|
|
1249
171
|
}
|
|
1250
|
-
/**
|
|
1251
|
-
function getGooseVideoSkillContent() {
|
|
1252
|
-
return `---
|
|
1253
|
-
name: goose-video
|
|
1254
|
-
slug: goose-video
|
|
1255
|
-
description: >
|
|
1256
|
-
Start a video ad in the same chat. Resolve the brand and suggest supported formats with a
|
|
1257
|
-
picker or the returned text choices. An agent that can run shell commands on the customer's
|
|
1258
|
-
computer makes the video with goose-video-local; otherwise the GooseWorks coworker makes it.
|
|
1259
|
-
Review one complete template plan and total credits before production. Custom videos retain two authenticated review gates in this chat.
|
|
1260
|
-
category: ads
|
|
1261
|
-
version: 3.1.0
|
|
1262
|
-
author: GooseWorks
|
|
1263
|
-
tags: [gooseworks, ads, video, local-render, coworker, chat]
|
|
1264
|
-
---
|
|
1265
|
-
|
|
1266
|
-
# GooseWorks Video Ads — choose, review, make
|
|
1267
|
-
|
|
1268
|
-
${CUSTOMER_TALK}
|
|
1269
|
-
|
|
1270
|
-
${CLI_TOOL_BRIDGE}
|
|
1271
|
-
|
|
1272
|
-
## Purpose
|
|
1273
|
-
|
|
1274
|
-
Resolve the brand, show supported formats and create one saved project. This is agent
|
|
1275
|
-
execution, not a recipe server-order API.
|
|
1276
|
-
|
|
1277
|
-
${WHO_MAKES_THE_VIDEO}
|
|
1278
|
-
|
|
1279
|
-
**Cards and execution are separate.** A terminal may render without drawing a picker; a chat
|
|
1280
|
-
app may draw a picker while the coworker renders. Follow \`card.display_hint\` for how to show
|
|
1281
|
-
things; who makes the video is the rule above. Template-remix review stays in this
|
|
1282
|
-
chat. Custom videos use separate authenticated script and ingredient approvals in this same chat.
|
|
1283
|
-
Studio is an optional review surface.
|
|
1284
|
-
|
|
1285
|
-
${videoEntryPreparation('goose-video')}
|
|
1286
|
-
|
|
1287
|
-
## Custom videos: check formats first
|
|
1288
|
-
|
|
1289
|
-
First check the catalog: when the brief names or implies a listed format (for example a street interview, testimonial, podcast or chat video), show that format and its fit through the format flow below, including its support status. Go custom only when no format fits and the customer chooses custom after hearing why; custom keeps that format's hard constraints. For an original brief without a reference template, an Instagram reel/post URL or a direct video URL to study, fetch \`catalog_fetch { type: "skill", slug: "make-custom-video" }\` and follow it in this same session. It creates format:"custom", custom_mode:"generate" with the brief and optional reference_url. Growth executes in its managed sandbox; connected agents use their shell. Script and actual ingredients are reviewed and separately approved in the same chat before paid production; Studio is optional. Do not force a template that does not fit or that the customer declined, and do not import the reference as a finished video.
|
|
1290
|
-
|
|
1291
|
-
## Run the format's route check before proposing it
|
|
1292
|
-
|
|
1293
|
-
A catalog row says what a format is best for and ranks it for the brand. It does not say whether
|
|
1294
|
-
the format can make the setup the customer asked for (how many people, mic only, no product).
|
|
1295
|
-
Some renderers declare a route selector that decides that; today that is the street interview
|
|
1296
|
-
(\`render-street-interview\`). Before you propose, script or create a street-interview project,
|
|
1297
|
-
template or custom, check the request against its routes:
|
|
1298
|
-
|
|
1299
|
-
| Street route | On screen | Needs | Makes |
|
|
1300
|
-
| --- | --- | --- | --- |
|
|
1301
|
-
| Guessing (\`product-guess\`) | Interviewer and up to four people | A physical product to hand over, photographed on its own | A finished video |
|
|
1302
|
-
| Conversation (\`mic-only\`, \`product-sample\`, \`concept-challenge\`) | Interviewer and one person | No product photo, phone, screen or UI | A script and prompt preview only, no finished video yet |
|
|
1303
|
-
| Street testimonial (its own format) | One person talking to camera, no interviewer | The creator still its recipe prescribes | A finished video, when the catalog lists it |
|
|
1304
|
-
|
|
1305
|
-
Neither interview route takes a photo of a person: people are described in text, so never
|
|
1306
|
-
propose putting a founder's or creator's face in one. Keep the customer's named setup: never
|
|
1307
|
-
change the interaction, mode or number of people just to make a check pass.
|
|
1308
|
-
|
|
1309
|
-
- **Without a shell on the customer's computer**, decide from this table. Do not fetch the renderer: its
|
|
1310
|
-
package is far too large for a chat.
|
|
1311
|
-
- **With a shell** (the customer's computer or the coworker sandbox), also run its free
|
|
1312
|
-
selector, which makes no paid call. If the fetch or the run fails, decide from the table.
|
|
1313
|
-
1. Fetch the renderer to a file, not into the conversation: its inline package is over a
|
|
1314
|
-
million characters. Either save the JSON from \`gooseworks fetch render-street-interview > <file.json>\`,
|
|
1315
|
-
then write each \`scripts\` entry as
|
|
1316
|
-
\`/tmp/gooseworks-scripts/render-street-interview/scripts/<name>\` and each \`files\` entry at
|
|
1317
|
-
\`/tmp/gooseworks-scripts/render-street-interview/<path>\`. Or call
|
|
1318
|
-
\`catalog_fetch { type: "skill", slug: "render-street-interview", delivery: "archive" }\`,
|
|
1319
|
-
extract the ZIP, check each file against its \`manifest.json\` hashes and copy the contents of its
|
|
1320
|
-
\`agent-config/skills/render-street-interview/\` folder into
|
|
1321
|
-
\`/tmp/gooseworks-scripts/render-street-interview/\`. Either way the selector reads
|
|
1322
|
-
\`references/street-reference-library.json\` from that folder.
|
|
1323
|
-
2. Write a brief JSON. \`mode\` and \`interaction_type\` go in pairs: \`product-guess\` with
|
|
1324
|
-
\`product-guess\`, or \`conversation\` with \`mic-only\`, \`product-sample\` or \`concept-challenge\`.
|
|
1325
|
-
\`offering_type\` is exactly \`physical\`, \`service\` or \`digital\` (software, SaaS and apps are
|
|
1326
|
-
\`digital\`). \`participants\` is a whole number: people interviewed on screen, not counting
|
|
1327
|
-
the interviewer. Leave it out when the customer named no count; the selector then uses the
|
|
1328
|
-
route's usual cast. When the customer named no interaction, run each mode that could fit.
|
|
1329
|
-
3. Run \`python3 /tmp/gooseworks-scripts/render-street-interview/scripts/prepare_script_context.py --brief <brief.json> --out <context.json>\`.
|
|
1330
|
-
Read \`status\` and \`brief_gaps\` in the output file, not the exit code: it exits 2 for every
|
|
1331
|
-
status except \`ready-for-writing\`. A Python traceback is not a verdict: the brief or the
|
|
1332
|
-
saved files are wrong (for example the reference library in the wrong folder). Fix them and
|
|
1333
|
-
run it again.
|
|
1334
|
-
4. A run with any \`brief_gaps\` has not checked the route. Fix every gap and run it again.
|
|
1335
|
-
|
|
1336
|
-
**An unsupported setup is a stop.** \`unsupported-route\`, or a request the table rules out,
|
|
1337
|
-
means this setup can't be made. Tell the customer plainly, in one line, for example: "A
|
|
1338
|
-
three-person mic-only street interview isn't something we can make yet: that version takes one
|
|
1339
|
-
person, and the three-person version needs a physical product to hand over." Then offer the
|
|
1340
|
-
closest supported options in plain words, each with how it differs. With a shell, these are the
|
|
1341
|
-
selector's \`alternatives\`. Without one, take them from the table:
|
|
1342
|
-
|
|
1343
|
-
- when only the number of people was the problem, the same setup within its limit: guessing
|
|
1344
|
-
(a physical product only) with up to four people, a finished video; or a conversation with
|
|
1345
|
-
one person, a script preview only;
|
|
1346
|
-
- for something people can't hold (software, a service), a one-person conversation instead
|
|
1347
|
-
of guessing;
|
|
1348
|
-
- one person talking to camera with no interviewer, if the catalog lists that format;
|
|
1349
|
-
- a custom video, untested, that keeps the street format's limits.
|
|
1350
|
-
|
|
1351
|
-
Never use route names or the script's wording. Do not create the project or write a script for
|
|
1352
|
-
it. Go custom only if the customer picks it; a custom video keeps the street format's hard
|
|
1353
|
-
constraints, which make-custom-video lists.
|
|
1354
|
-
|
|
1355
|
-
**A supported setup.** With empty \`brief_gaps\`, any other status means the route exists.
|
|
1356
|
-
\`needs-reference\` means no observed reference ad matched yet: it does not block proposing the
|
|
1357
|
-
format; carry it into the handoff so the script step resolves or reports it before script
|
|
1358
|
-
approval. Carry the route too: which one, how many people, finished video or preview only, and
|
|
1359
|
-
no person photos. A preview-only route makes a script and prompt preview, not a finished video:
|
|
1360
|
-
say so before the customer chooses it.
|
|
1361
|
-
|
|
1362
|
-
## Route first: is this a new video?
|
|
1363
|
-
|
|
1364
|
-
Hand off to **\`goose-video-local\`** now, and stop following this skill, for:
|
|
1365
|
-
|
|
1366
|
-
- an existing **project** id or a **video batch** id;
|
|
1367
|
-
- the app's copy-for-Claude command (it names \`goose-video-local\`);
|
|
1368
|
-
- "remix this video ad template" for a specific app template.
|
|
1369
|
-
|
|
1370
|
-
Load the current \`goose-video-local\` entry with
|
|
1371
|
-
\`catalog_fetch { type: "skill", slug: "goose-video-local" }\` on the GooseWorks MCP (older clients:
|
|
1372
|
-
\`fetch_skill("goose-video-local")\`), unless already fetched on this connection in this run.
|
|
1373
|
-
It reads the project first and retains an approved run's recorded recipe packages.
|
|
1374
|
-
|
|
1375
|
-
When they ask **what** to make ("give me video ad ideas", "what angles should I use?", "what's
|
|
1376
|
-
working for my competitors?"), fetch **\`ad-angle-miner\`** (\`catalog_fetch { type: "skill", slug: "ad-angle-miner" }\`,
|
|
1377
|
-
using its advertised tools) and run it with the **video** output. It returns ranked
|
|
1378
|
-
video ideas mapped to formats and hands the picked ones to \`goose-video-local\`.
|
|
1379
|
-
|
|
1380
|
-
Everything else, including "make me a video ad for <brand>", starts at step 1 below.
|
|
1381
|
-
|
|
1382
|
-
${ENVIRONMENT_IDENTITY}
|
|
1383
|
-
|
|
1384
|
-
${ASSET_READINESS}
|
|
1385
|
-
|
|
1386
|
-
## Inputs
|
|
1387
|
-
|
|
1388
|
-
- A brand, usually named in the request. Resolve it from the accessible brands; one brand needs no question.
|
|
1389
|
-
- The customer's goal, occasion, audience, selected angle and constraints when supplied; otherwise propose defaults from the verified kit.
|
|
1390
|
-
- The selected format's required assets. Presence does not prove suitability; uncertain assets remain “needs review.”
|
|
1391
|
-
|
|
1392
|
-
${DURABLE_BRAND_CAPTURE}
|
|
1393
|
-
|
|
1394
|
-
${VIDEO_TASTE_CAPTURE}
|
|
1395
|
-
|
|
1396
|
-
## Composed Atoms
|
|
1397
|
-
|
|
1398
|
-
Use the live canonical schemas: brand_read, brand_create, video_catalog_list,
|
|
1399
|
-
video_project_upsert, video_project_read, catalog_fetch, goose_run_task and job_cancel.
|
|
1400
|
-
An old tool name in a recipe is not grounds for terminal-update advice in a chat host.
|
|
1401
|
-
|
|
1402
|
-
## Paid media: images, clips, voice
|
|
1403
|
-
|
|
1404
|
-
**No FAL_KEY, ElevenLabs key or \`fal_client\` is ever needed.** Use
|
|
1405
|
-
\`data_post_provider { provider: "fal", path: <model id, e.g. "fal-ai/nano-banana/edit">, body: <model input>, project_id }\`
|
|
1406
|
-
then \`job_get { job_id }\`; voice/music use provider:"elevenlabs". Upload local inputs through
|
|
1407
|
-
media_upload first. **A missing key is never a blocker.** \`photos_generate\` is **not** a general
|
|
1408
|
-
image tool: it photographs physical catalog products only. Use goose-video-local for the
|
|
1409
|
-
runtime, paid approval, asset saving and quality checks.
|
|
1410
|
-
|
|
1411
|
-
## Workflow
|
|
1412
|
-
|
|
1413
|
-
### 1. Resolve the brand, quietly when you can
|
|
1414
|
-
|
|
1415
|
-
Call brand_read without brand_id to list accessible brands. Resolve the customer's name from
|
|
1416
|
-
actual returned names. One brand, or exactly one match: state it and continue. Several possible
|
|
1417
|
-
brands: show names and websites and ask once. No match: show accessible brands and offer to add
|
|
1418
|
-
one only when the customer asks and supplies its website; never guess the URL.
|
|
1419
|
-
|
|
1420
|
-
Read \`brand_read { brand_id, sections: ["summary","kit","products","learnings"] }\` before
|
|
1421
|
-
choosing a format. Reconcile explicit brand corrections through the durable capture rules.
|
|
1422
|
-
A direct video request does not require first-campaign acceptance. Follow any returned
|
|
1423
|
-
request-specific setup requirement; never mark research complete or accept a campaign to
|
|
1424
|
-
bypass setup. Keep the original request.
|
|
1425
|
-
|
|
1426
|
-
### 2. Keep the goal and propose defaults
|
|
1427
|
-
|
|
1428
|
-
Never ask what the ad is for before showing formats. Keep the customer's exact direction.
|
|
1429
|
-
Otherwise propose defaults from the verified kit's products, audience, offer and voice and the
|
|
1430
|
-
Brain search's evidence brief (proven angles, saved rules, approved claims). Show those defaults
|
|
1431
|
-
in the saved plan so any can be changed. Never invent proof or product facts.
|
|
1432
|
-
Idea requests still follow ad-angle-miner with the video output.
|
|
1433
|
-
|
|
1434
|
-
### 3. Show the picker or its text fallback
|
|
1435
|
-
|
|
1436
|
-
Call \`video_catalog_list { kind: "formats", brand_id }\`. Every caller gets every format.
|
|
1437
|
-
Respect requested limit and next_cursor for more item pages; the card may
|
|
1438
|
-
contain a full picker independently of the item page.
|
|
1439
|
-
|
|
1440
|
-
- **card.display_hint:"widget"**: the picker replaces a format table. Write at most one short
|
|
1441
|
-
acknowledgement, print no table or list of the formats, and wait for the selection.
|
|
1442
|
-
- **Otherwise**: print card.text_summary as returned. Without a card, show returned rows with
|
|
1443
|
-
names, faithful descriptions, needs and demo links, respecting the requested page size.
|
|
1444
|
-
Write "no demo yet" when absent. Never put links only in a question control.
|
|
1445
|
-
- A format whose card contradicts what they asked for is never Suggested. A \`needs_browser\`
|
|
1446
|
-
format is made only on the customer's computer (the coworker has no browser): if you have no
|
|
1447
|
-
shell there and the customer picks one, say it needs GooseWorks running on their computer and
|
|
1448
|
-
offer another.
|
|
1449
|
-
- \`suggested\` ranks a row for the brand; it never means the row makes the setup they named.
|
|
1450
|
-
Never tell the customer a row is "exactly" what they asked for beyond what its card says. A
|
|
1451
|
-
street interview still needs the route check above first.
|
|
1452
|
-
- Missing required assets are missing; unknown suitability is “needs review.” Inspect the
|
|
1453
|
-
selected format's candidates before spending. Never promise an unverified asset is ready.
|
|
1454
|
-
- Template formats use **one plan, one approval with the total in credits**, not approval for
|
|
1455
|
-
each paid step. Custom videos retain separate authenticated script/ingredient/budget gates in this chat.
|
|
1456
|
-
|
|
1457
|
-
### 4. Check this machine can render it
|
|
1458
|
-
|
|
1459
|
-
- **No shell on the customer's computer:** skip local checks and hand the project off in Step 5.
|
|
1460
|
-
Never tell the customer they need Claude Code to start. Give computer setup guidance only if
|
|
1461
|
-
asked how to make a \`needs_browser\` format.
|
|
1462
|
-
- **Local shell:** run \`gooseworks doctor --no-browser\` for common setup (auth/MCP, Node 18+,
|
|
1463
|
-
ffmpeg with libx264 (libass only for an ASS caption route), ffprobe). Then fetch the selected template and its capabilities,
|
|
1464
|
-
and install documented dependencies in its fetched folder. Do not guess a renderer from a
|
|
1465
|
-
format name. For each Node renderer using default Playwright Chromium, run
|
|
1466
|
-
\`gooseworks doctor --renderer-script "/absolute/path/to/the/fetched/scripts/record.js"\` with
|
|
1467
|
-
the exact environment used to render, including NODE_PATH and PLAYWRIGHT_BROWSERS_PATH.
|
|
1468
|
-
Use the actual script path. Custom browser launch settings need their equivalent exact-runtime
|
|
1469
|
-
check. Non-browser capabilities need only their documented runtime checks.
|
|
1470
|
-
Never create paid ingredients before the selected renderer passes. Repair and recheck under
|
|
1471
|
-
existing setup permissions. If it cannot be fixed, hand the project off in Step 5 (a
|
|
1472
|
-
\`needs_browser\` format can't be: offer another); never silently change the selected format.
|
|
1473
|
-
- **Coworker sandbox:** you are the renderer. Follow goose-video-local's sandbox checks; never
|
|
1474
|
-
hand off recursively or claim browser capability that the sandbox lacks.
|
|
1475
|
-
|
|
1476
|
-
### 5. Create the project and hand it off, in this session
|
|
1477
|
-
|
|
1478
|
-
1. \`video_project_upsert { brand_id, name, format: <template_id> }\` with no brief (a brief creates
|
|
1479
|
-
a concept batch). A street interview is created only after its route check found a supported
|
|
1480
|
-
setup. Default
|
|
1481
|
-
creation_intent:"format" keeps the style with this brand's content; source_remix requires an
|
|
1482
|
-
explicit choice to use source content.
|
|
1483
|
-
If they already chose a campaign/concept, include its verified campaign_id and optional
|
|
1484
|
-
campaign_concept_id. Read the IDs from that brand's saved campaign; the concept must belong
|
|
1485
|
-
to it. Omit unknown IDs and never infer a link or create a campaign solely to file a video.
|
|
1486
|
-
2. **You make it** (a shell on the customer's computer, or the coworker sandbox): load
|
|
1487
|
-
\`catalog_fetch { type: "skill", slug: "goose-video-local" }\` and follow it on the same project_id.
|
|
1488
|
-
Carry the customer's words, verified defaults, campaign, selected angle and a street
|
|
1489
|
-
interview's route check result into its brief.
|
|
1490
|
-
3. **No shell there:** \`goose_run_task { brand_id, project_id, message }\` with the request, selected
|
|
1491
|
-
format, defaults and a street interview's route check result. Keep task_id. Continue questions/edits with the same task and project.
|
|
1492
|
-
A saved free draft is not a started worker or a complete plan. Follow actual saved state.
|
|
1493
|
-
4. When follow.card_follows is true, the card follows progress: do not re-read it in a loop.
|
|
1494
|
-
Read again on a customer reply, card action or requested update. A failure or missing saved
|
|
1495
|
-
plan needs the returned recovery action; never claim completion or approve an empty plan.
|
|
1496
|
-
Approval requires the current complete plan and total. Insufficient balance: offer a shorter
|
|
1497
|
-
video or top-up. “Not now” keeps the saved plan.
|
|
1498
|
-
5. On the customer's yes, record it with \`video_project_upsert { brand_id, project_id, patch:
|
|
1499
|
-
{ approve: { user_quote, total_credits } } }\`. Its reply says what comes next: the coworker
|
|
1500
|
-
gets the approval when it is making the video; otherwise you render it.
|
|
1501
|
-
|
|
1502
|
-
Do not hand the customer a command to paste somewhere else.
|
|
1503
|
-
|
|
1504
|
-
## Decision Rules
|
|
1505
|
-
|
|
1506
|
-
- One sentence is a complete request. Resolve the brand and show formats without a goal interview.
|
|
1507
|
-
- One brand in the org: never ask which brand. Cards decide presentation; checks decide execution.
|
|
1508
|
-
- Use canonical tools. Preserve campaign context, selected script angles and custom authenticated review gates.
|
|
1509
|
-
- Never fabricate readiness, completion, approval or a second project.
|
|
1510
|
-
|
|
1511
|
-
## Output
|
|
1512
|
-
|
|
1513
|
-
One project, one current saved plan in this chat, then the finished video. With a widget write one
|
|
1514
|
-
line and do not add app_url, brand_url or duplicate video links. A text host gets text_summary
|
|
1515
|
-
and its usable delivery link.
|
|
1516
|
-
|
|
1517
|
-
## Quality Checks
|
|
1518
|
-
|
|
1519
|
-
- No forced goal question, duplicate table or unsupported shell claim.
|
|
1520
|
-
- The exact renderer passed before local paid ingredients; uncertain assets stay uncertain.
|
|
1521
|
-
- Selected campaign and angle survive; a single template project has no brief.
|
|
1522
|
-
- Current complete plan and total precede approval. Custom script and ingredient gates remain independent; Studio is optional.
|
|
1523
|
-
|
|
1524
|
-
## Failure Modes
|
|
1525
|
-
|
|
1526
|
-
| Symptom | Cause | Fix |
|
|
1527
|
-
| --- | --- | --- |
|
|
1528
|
-
| Picker plus table | Ignored display_hint | Widget: one line; otherwise text_summary |
|
|
1529
|
-
| Agent with a shell hands off | Decided from the host, not the rule | Make it here; hand off only without a shell or a fixable toolchain |
|
|
1530
|
-
| Chat told it cannot start | Only local execution considered | Create once and delegate to coworker |
|
|
1531
|
-
| Worker ends without a plan | Assumed completion means ready | Follow actual failure/recovery state |
|
|
1532
|
-
| Two projects for one video | Recreated instead of resuming | Continue same project and task |
|
|
1533
|
-
${STORED_FOOTAGE_GUIDANCE}`;
|
|
1534
|
-
}
|
|
1535
|
-
/**
|
|
1536
|
-
* The canonical render-row actions for a client/agent-rendered video
|
|
1537
|
-
* (GOOSE-3725): `video_render_run kind:"full"` (no dry_run) on a sample-remix
|
|
1538
|
-
* project OPENS a queued ad_render row and returns `render_id`;
|
|
1539
|
-
* `video_render_run { render: { render_id, status, ... } }` UPDATES it
|
|
1540
|
-
* (← update_render_status). If those names change, edit ONLY these constants:
|
|
1541
|
-
* every mention in the goose-video-local skill text is built from them.
|
|
1542
|
-
*/
|
|
1543
|
-
exports.RENDER_ROW_TOOL = 'video_render_run';
|
|
1544
|
-
exports.RENDER_OPEN_ARGS = 'kind: "full"';
|
|
1545
|
-
exports.RENDER_UPDATE_KEY = 'render';
|
|
1546
|
-
/**
|
|
1547
|
-
* Returns the goose-video-local entry SKILL.md content (GOOSE-3677, GOOSE-3726).
|
|
1548
|
-
*
|
|
1549
|
-
* The local-render runtime. VIDEO projects made in the app (template remixes,
|
|
1550
|
-
* concept batches, anything that is not a recipe order) render wherever the
|
|
1551
|
-
* agent runs: the user's own Claude Code (with or without the gooseworks CLI)
|
|
1552
|
-
* OR an agent inside the GooseWorks E2B workspace sandbox (canonical MCP tools
|
|
1553
|
-
* + Bash, no CLI, no credentials.json; media proxies via GW_MEDIA_PROXY_TOKEN).
|
|
1554
|
-
* It fetches the per-format recipe, renders (ffmpeg, PIL, Playwright where
|
|
1555
|
-
* available), mirrors the review set for a free in-app review, then saves the
|
|
1556
|
-
* finished MP4 back over MCP using the canonical tools (video_project_*,
|
|
1557
|
-
* catalog_fetch, media_upload, the video_render_run render-row actions).
|
|
1558
|
-
*/
|
|
1559
|
-
function getGooseVideoLocalSkillContent() {
|
|
1560
|
-
return `---
|
|
1561
|
-
name: goose-video-local
|
|
1562
|
-
slug: goose-video-local
|
|
1563
|
-
description: >
|
|
1564
|
-
Render an EXISTING GooseWorks video ad project or video batch with ffmpeg (plus Playwright for
|
|
1565
|
-
phone-mockup formats) and the GooseWorks media proxies, then save the finished MP4 back to the
|
|
1566
|
-
project over MCP. Runs on the user's own machine (Claude Code / desktop app, with or without the
|
|
1567
|
-
gooseworks CLI) OR inside a GooseWorks workspace sandbox (canonical MCP tools + Bash, no CLI).
|
|
1568
|
-
Use for a client-side format project (created by goose-video), a template-remix project or a
|
|
1569
|
-
video batch. A copy-for-Claude command or project id must first be checked with
|
|
1570
|
-
video_project_read. An agent that can't run shell commands on the customer's computer hands this same project to the GooseWorks coworker. To start a NEW video ad in chat,
|
|
1571
|
-
use goose-video first.
|
|
1572
|
-
category: ads
|
|
1573
|
-
version: 0.7.0
|
|
1574
|
-
author: GooseWorks
|
|
1575
|
-
tags: [gooseworks, ads, video, remix, imessage, podcast, ugc, local-render, sandbox, byoa]
|
|
1576
|
-
---
|
|
1577
|
-
|
|
1578
|
-
# GooseWorks Video Ads — local remix runtime
|
|
1579
|
-
|
|
1580
|
-
${CUSTOMER_TALK}
|
|
1581
|
-
|
|
1582
|
-
${CLI_TOOL_BRIDGE}
|
|
1583
|
-
|
|
1584
|
-
${videoEntryPreparation('goose-video-local')}
|
|
1585
|
-
|
|
1586
|
-
## Chat hosts and cards
|
|
1587
|
-
|
|
1588
|
-
${WHO_MAKES_THE_VIDEO}
|
|
1589
|
-
|
|
1590
|
-
First perform the mandatory route check below. Then, if you can't run shell commands on the
|
|
1591
|
-
customer's computer, hand a verified template
|
|
1592
|
-
project to \`goose_run_task { brand_id, project_id, message }\`, or a verified template batch to
|
|
1593
|
-
\`goose_run_task { brand_id, batch_id, message }\` (never send both ids). Keep task_id and the
|
|
1594
|
-
same project or batch. Generated custom children keep their separate make-custom-video flow.
|
|
1595
|
-
Inside a coworker sandbox you are the renderer: never delegate recursively.
|
|
1596
|
-
With card.display_hint:"widget", say at most one line and never duplicate its plan, total or
|
|
1597
|
-
links. Otherwise print card.text_summary. Read again on customer input, not in a polling loop.
|
|
1598
|
-
A free saved draft is not proof that planning started or a complete plan exists.
|
|
1599
|
-
|
|
1600
|
-
## Mandatory route check before any local work or spend
|
|
1601
|
-
|
|
1602
|
-
For every existing \`project_id\` (including one supplied by the app's copy-for-Claude command),
|
|
1603
|
-
call \`video_project_read { brand_id, project_id }\` **before** template lookup, toolchain setup,
|
|
1604
|
-
media-proxy calls, or a review-set upload. For a batch, inspect each child project.
|
|
1605
|
-
|
|
1606
|
-
- **A server-rendered order** — the response has \`creative_plan\`,
|
|
1607
|
-
\`project.creative_spec_revision_id\`, \`order.creative_spec_revision_id\`, a planning
|
|
1608
|
-
\`lifecycle\`, or an \`order\` / \`script_drafts.recipe\` on a server format → **stop.**
|
|
1609
|
-
Server video orders are paused, and there is **no vetted local node-execution API** for them:
|
|
1610
|
-
do not rebuild one locally. Tell the customer this project was made for the server flow, which
|
|
1611
|
-
is paused; offer to start the same ad on a client-side format (\`goose-video\`, fetched with
|
|
1612
|
-
\`catalog_fetch { type: "skill", slug: "goose-video" }\`, older clients:
|
|
1613
|
-
\`fetch_skill("goose-video")\`). An order already holding credits can be released with
|
|
1614
|
-
\`job_cancel\`.
|
|
1615
|
-
- **A client-side format or template remix** (a \`source_sample_id\` / \`template_id\` and none of
|
|
1616
|
-
the above) → continue below.
|
|
1617
|
-
- **Generated custom video** (\`project.custom_video_state.mode === "generate"\`) → fetch \`catalog_fetch { type: "skill", slug: "make-custom-video" }\`, follow it on this same project and stop following the template flow. Record independent authenticated script/ingredient approvals in this chat with the current custom_review.approval_quote phase, review_token and cumulative total; Studio is optional. A handed-off coworker cannot self-approve; do not report approval_not_required.
|
|
1618
|
-
- **Unclear** → read again or ask; never guess and generate. A copy prompt that names this skill
|
|
1619
|
-
is not proof of which kind the project is.
|
|
1620
|
-
|
|
1621
|
-
Continue below only for a verified client-side format or template remix.
|
|
1622
|
-
|
|
1623
|
-
For client-side formats and template remixes, you produce **video** ad creative wherever THIS agent runs and sync
|
|
1624
|
-
the result back to the GooseWorks app over MCP. This document is the **runtime contract** (auth,
|
|
1625
|
-
credits, the media proxies, data I/O, the review gate). A separate **recipe** — the template's
|
|
1626
|
-
\`recipe\`, plus the capability skills it names — tells you *what to make* (the pieces, prompts,
|
|
1627
|
-
models, order of assembly).
|
|
1628
|
-
|
|
1629
|
-
**Division of authority: read both, but when they disagree THIS doc wins on the environment AND the
|
|
1630
|
-
review/approval flow.** The recipe governs WHAT to make; this doc governs WHEN you pause, generate,
|
|
1631
|
-
and spend. In particular: a recipe may spell out a **multi-phase, multi-gate** flow — "generate the
|
|
1632
|
-
still [GATE] → approve → author the prompt [GATE] → approve → render [GATE] → approve", several
|
|
1633
|
-
separate pauses. **Do NOT run it that way.** Collapse every one of those gates into the single
|
|
1634
|
-
**review-once** flow below: one review set, one approval (Step 3). Take the recipe's pieces, prompts
|
|
1635
|
-
and models; ignore its intermediate pauses. This is the exact contradiction that confused past runs
|
|
1636
|
-
(GOOSE-2542) — there is no ambiguity: review-once wins.
|
|
1637
|
-
|
|
1638
|
-
The app NEVER runs this skill by itself — it is the viewer + review surface; you are the renderer.
|
|
1639
|
-
|
|
1640
|
-
${ENVIRONMENT_IDENTITY}
|
|
1641
|
-
|
|
1642
|
-
${ASSET_READINESS}
|
|
1643
|
-
|
|
1644
|
-
## Where am I running? (decide once, first)
|
|
1645
|
-
|
|
1646
|
-
With no shell on the customer's computer at all, you don't render here: hand the project off
|
|
1647
|
-
(Chat hosts and cards above). Otherwise check in Bash, without printing any secret value:
|
|
1648
|
-
|
|
1649
|
-
\`\`\`bash
|
|
1650
|
-
[ -n "$GW_MEDIA_PROXY_TOKEN" ] && echo sandbox || echo local
|
|
1651
|
-
command -v gooseworks >/dev/null && echo cli || echo no-cli
|
|
1652
|
-
\`\`\`
|
|
1653
|
-
|
|
1654
|
-
| Mode | How you know | Skills / atoms | Media-proxy auth |
|
|
1655
|
-
|---|---|---|---|
|
|
1656
|
-
| **GooseWorks sandbox** | \`GW_MEDIA_PROXY_TOKEN\` is set | \`catalog_fetch { type: "skill" }\` | env: \`GW_MEDIA_PROXY_TOKEN\` + \`GW_*_PROXY_URL\` |
|
|
1657
|
-
| **Local, CLI installed** | \`gooseworks\` on PATH | \`gooseworks fetch <slug>\` or \`catalog_fetch\` | \`~/.gooseworks/credentials.json\` |
|
|
1658
|
-
| **Local, no CLI** (Claude desktop app / Codex without login) | neither | \`catalog_fetch { type: "skill" }\` | \`~/.gooseworks/credentials.json\` if present, else **paid media over the MCP** (below) |
|
|
1659
|
-
|
|
1660
|
-
The \`gooseworks\` CLI and \`~/.gooseworks/credentials.json\` are **optional**. Everything this skill
|
|
1661
|
-
needs from the app goes through the GooseWorks MCP tools below; the atoms' \`media_proxy.py\` reads
|
|
1662
|
-
credentials.json when it exists and falls back to the \`GW_MEDIA_PROXY_TOKEN\` env otherwise.
|
|
1663
|
-
|
|
1664
|
-
### Paid media over the MCP: no key, no CLI needed
|
|
1665
|
-
|
|
1666
|
-
Every paid generation goes through the GooseWorks media proxy and is billed to the project. **You
|
|
1667
|
-
never need FAL_KEY, an ElevenLabs key or \`fal_client\`.** An atom, a recipe or an open-source
|
|
1668
|
-
skill that lists \`FAL_KEY\` in its environment is describing a standalone setup; here the proxy
|
|
1669
|
-
satisfies it. Never stop, and never ask anyone to set a key, because one is missing.
|
|
1670
|
-
|
|
1671
|
-
**A one-off image or clip — call the MCP directly.** A frame placed in a laptop, a product cutout,
|
|
1672
|
-
a creator still, a restyle, an animated shot, with any fal model (Nano Banana, GPT-image, Seedream,
|
|
1673
|
-
Seedance, Kling). No atom script is needed:
|
|
1674
|
-
|
|
1675
|
-
1. A local input (a frame pulled from a screen recording, a screenshot) must be a public URL first:
|
|
1676
|
-
\`media_upload { brand_id, scope: "video_project", scope_id: project_id, source: { type: "file" | "bytes", … } }\`
|
|
1677
|
-
(no \`path\`). For a file, PUT its bytes to \`upload.url\` with \`upload.required_headers\`,
|
|
1678
|
-
then call \`media_confirm { brand_id, media_id: media.id }\`. Use the returned \`media.url\`.
|
|
1679
|
-
2. \`data_post_provider { provider: "fal", path: <model id, e.g. "fal-ai/nano-banana/edit">, body: <model input>, project_id }\`
|
|
1680
|
-
returns \`{ job_id: "fal:<request_id>" }\`. Pass an \`idempotency_key\` so a retry isn't billed twice.
|
|
1681
|
-
3. Poll \`job_get { job_id }\` every few seconds until \`complete\`; the \`*.fal.media\` URLs are in
|
|
1682
|
-
\`result\`. Download each and QC it (open the image) before using it.
|
|
1683
|
-
|
|
1684
|
-
For a set that must match (every laptop shot, every creator still), use ONE prompt and the same
|
|
1685
|
-
model for all of them and change only the input image. Voice and music:
|
|
1686
|
-
\`data_post_provider { provider: "elevenlabs", path: "/v1/text-to-speech/{voice_id}" | "/v1/music", body, project_id }\`
|
|
1687
|
-
(synchronous; the audio lands in the project folder).
|
|
1688
|
-
|
|
1689
|
-
\`photos_generate\` is **not** a general image tool: it only photographs a physical catalog
|
|
1690
|
-
product (apparel, beauty, CPG) and needs a \`product_id\`. A software screenshot or app mockup is a
|
|
1691
|
-
fal image edit, above.
|
|
1692
|
-
|
|
1693
|
-
**Atom scripts — the MCP relay.** With neither \`GW_MEDIA_PROXY_TOKEN\` nor
|
|
1694
|
-
\`~/.gooseworks/credentials.json\`, the atoms' \`media_proxy.py\` RELAYS each paid call through you
|
|
1695
|
-
instead of calling the proxies over HTTP. Before running any atom,
|
|
1696
|
-
\`export GW_PROJECT_ID=<project_id> GW_BRAND_ID=<brand_id>\` (every call is billed to that
|
|
1697
|
-
project). When a script **exits with code 3** it wrote a request file under
|
|
1698
|
-
\`working/mcp-requests/\`: make exactly that MCP call — fal:
|
|
1699
|
-
\`data_post_provider { provider: "fal", path, body, project_id }\` then \`job_get { job_id }\` until
|
|
1700
|
-
\`complete\`, saving \`result.output\`; ElevenLabs: \`data_post_provider { provider: "elevenlabs", … }\`,
|
|
1701
|
-
saving the reply; a local file: \`media_upload\` with its bytes, saving \`{"url": …}\`. Write that JSON
|
|
1702
|
-
to the request's \`save_result_to\` and **re-run the same command**; repeat until the script
|
|
1703
|
-
finishes. Same server proxy and price as the CLI path. If the CLI is logged in to a DIFFERENT
|
|
1704
|
-
environment than this MCP connector (prod vs staging), set \`GW_MEDIA_VIA=mcp\` so the spend lands
|
|
1705
|
-
where the project lives.
|
|
1706
|
-
|
|
1707
|
-
## MCP tools — canonical names (use these)
|
|
1708
|
-
|
|
1709
|
-
Use the canonical GooseWorks MCP tools. Legacy names are listed only as a fallback for an older
|
|
1710
|
-
client that does not expose the canonical tool; never mix both for one step.
|
|
1711
|
-
|
|
1712
|
-
| Step | Canonical tool (use this) | Legacy fallback |
|
|
1713
|
-
|---|---|---|
|
|
1714
|
-
| Read a project / batch | \`video_project_read { brand_id, project_id }\` / \`video_project_read { brand_id, batch_id }\` | \`get_ad_project\` / \`get_ad_video_batch\` |
|
|
1715
|
-
| Template recipe | \`catalog_fetch { type: "template", slug: <source_sample_id> }\` | \`get_ad_template\` |
|
|
1716
|
-
| Capability skill (atom) + its scripts | \`catalog_fetch { type: "skill", slug }\` | \`gooseworks fetch <slug>\` / \`fetch_skill\` |
|
|
1717
|
-
| Brand kit, products, rules | \`brand_read { brand_id, sections: ["summary","kit","products","learnings"] }\` | \`brand_get_context\` / \`get_brand_kit\` |
|
|
1718
|
-
| Save a brand rule (a correction) | \`brand_update { brand_id, knowledge_intent: "user_correction", user_statement: <the user's exact words>, patch: { facts: [{ id?, kind, text }] } }\` | none |
|
|
1719
|
-
| Mirror the review set | \`video_project_upsert { brand_id, project_id, patch: { script: { script_drafts, script } } }\` | \`update_ad_project_script\` |
|
|
1720
|
-
| Project assets | \`video_project_upsert { …, patch: { assets: [...] } }\` | \`update_ad_project_asset\` |
|
|
1721
|
-
| Progress note | \`video_project_upsert { …, patch: { message: { role: "agent", content } } }\` | \`append_project_message\` |
|
|
1722
|
-
| Batch status | \`video_project_upsert { brand_id, batch_id, patch: { batch: { status } } }\` | \`update_ad_video_batch\` |
|
|
1723
|
-
| Upload a file to the project | \`media_upload { brand_id, scope: "video_project", scope_id: project_id, kind, path, source: { type: "file", filename, content_type } }\` → PUT → \`media_confirm { brand_id, media_id: media.id }\` | \`get_upload_url\` / \`get_ad_upload_url\` |
|
|
1724
|
-
| Save / find a finished piece (resume) | \`media_upload { …, path, ingredient_key, input_digest }\` / \`media_list { brand_id, scope: "video_project", scope_id: project_id, ingredient_key_prefix: "" }\` (see "Save as you go") | none |
|
|
1725
|
-
| Open the render row | \`${exports.RENDER_ROW_TOOL} { brand_id, project_id, ${exports.RENDER_OPEN_ARGS} }\` (no \`dry_run\`; returns \`render_id\`) | \`submit_render { project_id, kind: "full" }\` |
|
|
1726
|
-
| Update the render row | \`${exports.RENDER_ROW_TOOL} { brand_id, project_id, ${exports.RENDER_UPDATE_KEY}: { render_id, status, output_url?, thumbnail_url?, error_message?, quality_status?, quality_report? } }\` | \`update_render_status\` |
|
|
1727
|
-
| Pin the final render | \`video_project_upsert { brand_id, project_id, patch: { final_render_id: render_id } }\` | \`set_final_render\` |
|
|
1728
|
-
| Credits / identity | \`account_whoami\` | \`get_ad_credits\` |
|
|
1729
|
-
|
|
1730
|
-
\`list_accessible_scopes\` and the \`target: { type: "agent", agent_id }\` dance are **not needed**:
|
|
1731
|
-
\`media_upload\` with \`scope: "video_project"\` derives the right storage key (org-default Ads agent
|
|
1732
|
-
+ brand slug + project folder) on the server.
|
|
1733
|
-
|
|
1734
|
-
## Running in a GooseWorks sandbox
|
|
1735
|
-
|
|
1736
|
-
You are an agent inside the user's GooseWorks workspace sandbox (Claude Code harness, Bash, the
|
|
1737
|
-
GooseWorks MCP with canonical tools only). There is **no \`gooseworks\` CLI** and **no
|
|
1738
|
-
\`~/.gooseworks/credentials.json\`**. The environment carries \`GW_MEDIA_PROXY_TOKEN\`, \`GW_API_BASE\`,
|
|
1739
|
-
\`GW_FAL_PROXY_URL\`, \`GW_FAL_STORAGE_PROXY_URL\`, \`GW_ELEVENLABS_PROXY_URL\`, \`GW_WHISPER_PROXY_URL\`
|
|
1740
|
-
and usually \`GW_PROJECT_ID\`.
|
|
1741
|
-
|
|
1742
|
-
- **Formats:** only formats that need **no Chromium** run here — podcast skits and UGC /
|
|
1743
|
-
talking-head formats (ffmpeg + PIL assembly). If the template's recipe or an atom needs
|
|
1744
|
-
Playwright/Chromium with no PIL fallback (iMessage / ChatGPT / Notes phone mockups,
|
|
1745
|
-
hyperframes, HTML recorders), **stop before any spend** and say so plainly: "This format needs
|
|
1746
|
-
a browser renderer that this workspace doesn't have. Run it in your own Claude Code with the
|
|
1747
|
-
GooseWorks CLI (\`goose-video-local\`), or pick a podcast/UGC format." Do not half-render.
|
|
1748
|
-
- **Toolchain:** check \`ffmpeg -version\` and \`ffprobe -version\`. Install Python deps only when an
|
|
1749
|
-
atom needs them: \`pip install --quiet pillow\` when a render atom uses PIL (captions, end card),
|
|
1750
|
-
\`pip install --quiet requests\` if \`import requests\` fails. Never \`npx playwright install\` here.
|
|
1751
|
-
- **Atoms:** \`catalog_fetch { type: "skill", slug }\` returns \`content\`, \`scripts\`, \`files\` and
|
|
1752
|
-
\`dependencySkills\`. Write \`content\` to \`/tmp/gooseworks-scripts/<slug>/SKILL.md\`, each
|
|
1753
|
-
\`scripts\` entry to \`/tmp/gooseworks-scripts/<slug>/scripts/<name>\` and each \`files\` entry to
|
|
1754
|
-
\`/tmp/gooseworks-scripts/<slug>/<name>\` (keep the key as the relative path; do the same for
|
|
1755
|
-
each dependency skill). Run scripts from their \`scripts/\` folder so \`import media_proxy\` resolves.
|
|
1756
|
-
- **Project attribution:** \`export GW_PROJECT_ID=<project_id>\` in the shell **before running any
|
|
1757
|
-
atom** for that project (re-export per concept in a batch). The proxies bill the workspace
|
|
1758
|
-
agent and attribute spend to that project.
|
|
1759
|
-
- **Never call a provider with a raw key.** All FAL / ElevenLabs / Whisper traffic goes through
|
|
1760
|
-
the \`GW_*_PROXY_URL\` bases with \`GW_MEDIA_PROXY_TOKEN\`. \`FAL_KEY\` / \`ELEVENLABS_API_KEY\` in
|
|
1761
|
-
this environment are proxy tokens, not provider keys — never send them to \`fal.run\`,
|
|
1762
|
-
\`queue.fal.run\` or \`api.elevenlabs.io\` directly. Never print any token.
|
|
1763
|
-
- **Whisper for QC:** \`export OPENAI_BASE_URL="$GW_WHISPER_PROXY_URL/v1"\` before running
|
|
1764
|
-
\`review-ugc-render\` / \`watch\` transcripts.
|
|
1765
|
-
- **The operator may be absent.** Keep every quality gate and checkpoint below, but decide
|
|
1766
|
-
defaults yourself from the project brief and the recipe, and record them in the review set.
|
|
1767
|
-
Ask in the chat **only for a true taste call** (a creative choice the brief and recipe leave
|
|
1768
|
-
open and that changes the ad), never for a mechanical or recoverable decision. The Step 3
|
|
1769
|
-
approval still applies: ask for it in this chat and record the yes with
|
|
1770
|
-
\`video_project_upsert patch.approve\`.
|
|
1771
|
-
- **Outputs:** keep working files under \`/tmp/gooseworks-video/<project_id>/\` (local disk — never
|
|
1772
|
-
the s3fs workspace mount, which is slow and can drop writes); anything the user must see goes to
|
|
1773
|
-
the project via \`media_upload\` (never leave the result only in the sandbox). Every paid piece is
|
|
1774
|
-
also SAVED to the project as soon as it passes QC — see "Save as you go — and resume".
|
|
1775
|
-
|
|
1776
|
-
## Report problems so we can fix them (telemetry — do this, don't skip it)
|
|
1777
|
-
|
|
1778
|
-
If anything blocks or degrades this run — a media/proxy call fails or errors, a required input or
|
|
1779
|
-
asset is missing, a recipe instruction is ambiguous or contradictory, the render toolchain won't set
|
|
1780
|
-
up, or you hit a bug you can't work around — **report it** so the team gets visibility and can fix
|
|
1781
|
-
the skill. It's fire-and-forget, never counts against you, and never blocks your work.
|
|
1782
|
-
|
|
1783
|
-
- **First, set a stable run id** so every event (yours + the auto-logged media calls) groups together:
|
|
1784
|
-
\`export GW_RUN_ID="vid-<project_or_batch_id>"\` (and \`export GW_SKILL="<recipe-slug>"\`) in the
|
|
1785
|
-
shell you render from. The media proxies read \`GW_RUN_ID\` automatically.
|
|
1786
|
-
- **CLI present →** \`gooseworks log "<what happened>" --event-type <type> --level error --details '{"error":"...","step":"...","model":"..."}'\`
|
|
1787
|
-
- **No CLI (sandbox / cowork) →** from any atom's \`scripts/\` folder:
|
|
1788
|
-
\`python3 -c 'from media_proxy import gw_log; gw_log("<what happened>", event_type="blocker", level="error", details={"step": "..."})'\`
|
|
1789
|
-
(or the \`log_cli_event\` MCP tool if your client has it).
|
|
1790
|
-
- Event types: \`api_failure\` (a proxy/model call failed) · \`missing_input\` · \`blocker\` ·
|
|
1791
|
-
\`confusion\` (unclear/contradictory instruction) · \`error\` (a bug) · \`step\`/\`info\` (progress notes).
|
|
1792
|
-
- Put the **real error text + the step you were on** in the details. Paid FAL/ElevenLabs calls
|
|
1793
|
-
ALREADY auto-log their own failures, so focus your manual logs on what the proxy can't see:
|
|
1794
|
-
missing inputs, confusing/contradictory recipe instructions, toolchain/setup failures, and bugs.
|
|
1795
|
-
- Logging is FOR US — it does not replace telling the user. When a problem blocks the run, still
|
|
1796
|
-
explain it to the user (and ask if you need a decision); just also log it so we can fix the skill.
|
|
1797
|
-
|
|
1798
|
-
## Prerequisite — MCP + a render toolchain (Phase 0 preflight)
|
|
1799
|
-
|
|
1800
|
-
- The GooseWorks MCP tools are REQUIRED. If they're unavailable, stop and tell the user
|
|
1801
|
-
to connect the GooseWorks MCP server (or run \`gooseworks install --claude --mcp\` on the CLI)
|
|
1802
|
-
and restart. There is no REST fallback.
|
|
1803
|
-
- **The render runs wherever THIS agent runs, and it needs a real toolchain:** \`ffmpeg\` +
|
|
1804
|
-
\`ffprobe\` always, plus a Playwright **Chromium** for browser-rendered formats (phone mockups,
|
|
1805
|
-
HTML end cards without a PIL fallback). Establish it in this priority order, and do NOT start
|
|
1806
|
-
rendering until one is confirmed:
|
|
1807
|
-
1. **Sandbox →** see "Running in a GooseWorks sandbox": ffmpeg + ffprobe (+ PIL on demand); no
|
|
1808
|
-
Chromium, so browser formats stop there.
|
|
1809
|
-
2. **CLI present →** run \`gooseworks doctor --no-browser\` for login, MCP, Node 18+, ffmpeg
|
|
1810
|
-
with libx264, and ffprobe. Require libass only for a selected ASS caption route; caption-burn uses Pillow overlays and does not need it. This is common setup only. After fetching the selected
|
|
1811
|
-
capabilities in Step 2, check each browser renderer's actual launch before ANY paid
|
|
1812
|
-
ingredient. An unscoped \`gooseworks doctor\` checks only the calling folder's browser;
|
|
1813
|
-
it cannot certify a different fetched renderer.
|
|
1814
|
-
3. **No CLI →** check the toolchain yourself: \`node --version\` (18+), \`ffmpeg -version\`,
|
|
1815
|
-
\`ffprobe -version\`, plus \`ffmpeg -hide_banner -encoders\` (libx264) and
|
|
1816
|
-
\`ffmpeg -hide_banner -filters\` (ass). After fetching, use the exact-package free launch
|
|
1817
|
-
check in Step 2; resolving a package or finding a cache folder does not prove its browser
|
|
1818
|
-
can launch. The \`watch\` QC step later needs the same ffmpeg and,
|
|
1819
|
-
for transcripts, a Whisper backend — without one it degrades to frames only.
|
|
1820
|
-
4. **Docker available →** the most reliable way to get the toolchain on a host that lacks it:
|
|
1821
|
-
run the render steps inside the prebuilt image
|
|
1822
|
-
**\`ghcr.io/gooseworks-ai/goose-video-render\`** (ffmpeg + ffprobe + Playwright Chromium baked
|
|
1823
|
-
in), mounting the project working directory. (Nested Docker is usually disabled inside
|
|
1824
|
-
managed sandboxes — treat this as an option, not a guarantee.)
|
|
1825
|
-
5. **None of the above works →** on the customer's computer, hand the project to the GooseWorks
|
|
1826
|
-
coworker with \`goose_run_task\` (a \`needs_browser\` format can't be: offer another). Inside the
|
|
1827
|
-
coworker sandbox, or when the customer wants it made on their own machine, STOP and tell the
|
|
1828
|
-
user plainly, e.g.: *"Video rendering needs
|
|
1829
|
-
ffmpeg (and, for this format, a Playwright Chromium) on the machine running this agent. This
|
|
1830
|
-
environment doesn't have them and I can't install them here. Options: (a) enable Docker so I
|
|
1831
|
-
can use the goose-video-render image, (b) install ffmpeg + \`npx playwright install chromium\`,
|
|
1832
|
-
or (c) run this skill in your own Claude Code where the toolchain is available."* Do not
|
|
1833
|
-
half-render or fake a result. Static image ads (the \`goose-ads\` skill) do NOT need any of this
|
|
1834
|
-
and work anywhere — offer that as the fallback if they just want an ad now.
|
|
1835
|
-
|
|
1836
|
-
## Identity, token, credits
|
|
1837
|
-
|
|
1838
|
-
- **Sandbox:** the token is \`GW_MEDIA_PROXY_TOKEN\` (already scoped to this workspace's agent and
|
|
1839
|
-
org); the API base is \`GW_API_BASE\`. Never print either.
|
|
1840
|
-
- **Local:** read \`~/.gooseworks/credentials.json\` → \`api_key\` (your agent token), \`api_base\`,
|
|
1841
|
-
\`agent_id\`. Never print the token.
|
|
1842
|
-
- **Uploads go through \`media_upload\` with \`scope: "video_project"\`** — pass \`path\` = the
|
|
1843
|
-
project-relative path (\`working/final.mp4\`, \`working/review/end-card.png\`). The server stores it
|
|
1844
|
-
in the project folder of the org-default Ads agent (where the app's render-file route reads) and
|
|
1845
|
-
returns \`upload.url\` (presigned PUT), \`upload.required_headers\` and
|
|
1846
|
-
\`upload.render_file_url\`. PUT the bytes with exactly those headers, check the PUT returned
|
|
1847
|
-
2xx, then call \`media_confirm { brand_id, media_id: media.id }\` and require success before
|
|
1848
|
-
using the file in ingredients or completing a render. This applies to project-path and
|
|
1849
|
-
path-less file uploads. Confirmation verifies the stored file; Goose performs this tool step
|
|
1850
|
-
without asking the user for another approval. On failure, report or repair the upload before
|
|
1851
|
-
continuing. Never hand-build storage paths or agent prefixes; a bare workspace upload is
|
|
1852
|
-
invisible in the app.
|
|
1853
|
-
- Media generation (FAL / ElevenLabs) through the GooseWorks proxies is the **REAL spend** — billed
|
|
1854
|
-
per call as you generate (Step 4). The render row (\`${exports.RENDER_ROW_TOOL} ${exports.RENDER_OPEN_ARGS}\`) charges the flat
|
|
1855
|
-
**video base fee once, when a full render is reported \`complete\`**. Open one row immediately
|
|
1856
|
-
after recorded approval, BEFORE paid production (Step 4.1), and reuse that render_id for progress
|
|
1857
|
-
and completion. Never open a second row on a guess (a second completed row bills again). The final-video QC gate (Step 4.3) then sits between
|
|
1858
|
-
that master and PINNING it. Call \`account_whoami\` first to see the credit balance.
|
|
1859
|
-
|
|
1860
|
-
## Save as you go — and resume (never pay twice for a piece)
|
|
1861
|
-
|
|
1862
|
-
A sandbox can die mid-run (timeout, restart, a new session picks the project up). Anything that
|
|
1863
|
-
lives only in \`/tmp\` is then gone, and regenerating it pays again. So: **save every piece to the
|
|
1864
|
-
project the moment it passes its QC, and start every run by loading what is already saved.**
|
|
1865
|
-
Working files stay in \`/tmp/gooseworks-video/<project_id>/\` (never the s3fs workspace mount);
|
|
1866
|
-
the project is the durable copy.
|
|
1867
|
-
|
|
1868
|
-
**Ingredient keys.** Give every planned piece a stable key before you generate it, the same on
|
|
1869
|
-
every run: \`vo/scene-03\`, \`vo/sample-her\`, \`still/her-base\`, \`still/scene-05\`,
|
|
1870
|
-
\`clip/scene-05\` (a lipsync / video clip), \`music/bed\`, \`endcard\`, \`captions\`, \`final\`,
|
|
1871
|
-
\`final-thumb\`. Upload path = \`working/<role>/<file>\` (\`working/vo/scene-03.mp3\`,
|
|
1872
|
-
\`working/clip/scene-05.mp4\`); the review set keeps its \`working/review/<name>\` paths.
|
|
1873
|
-
|
|
1874
|
-
**Input digest.** Name the exact inputs of each generation with \`input_digest\` from
|
|
1875
|
-
\`media_proxy\` (in every media capability's \`scripts/\` folder):
|
|
1876
|
-
|
|
1877
|
-
\`\`\`python
|
|
1878
|
-
from media_proxy import input_digest
|
|
1879
|
-
digest = input_digest(model_path, args) # the model + the EXACT payload you send
|
|
1880
|
-
\`\`\`
|
|
1881
|
-
|
|
1882
|
-
Hash only what decides the output (prompt, voice_id, model_id, seed, duration, aspect…). An input
|
|
1883
|
-
that is a presigned or proxy URL changes every run, so swap it for that input's own identity
|
|
1884
|
-
before hashing, e.g. \`{**args, "image_url": {"ingredient": "still/her-base", "digest": her_digest}}\`
|
|
1885
|
-
— then a changed still correctly invalidates every clip made from it. For a piece you build
|
|
1886
|
-
locally (ffmpeg stitch, PIL end card, captions) use \`input_digest("local/<step>", {params,
|
|
1887
|
-
inputs: {key: digest, …}})\`.
|
|
1888
|
-
|
|
1889
|
-
**1. At the START of every run (first run, resume, new sandbox), load what exists — one call:**
|
|
1890
|
-
\`media_list { brand_id, scope: "video_project", scope_id: project_id, ingredient_key_prefix: "",
|
|
1891
|
-
limit: 100 }\`. It returns ONE compact row per \`ingredient_key\` (the newest):
|
|
1892
|
-
\`{ id, ingredient_key, input_digest, kind, status, mime, bytes, url, path, created_at }\`. Every
|
|
1893
|
-
status except archived is included. Project-path uploads remain \`pending\` until
|
|
1894
|
-
\`media_confirm\` succeeds. Confirm a pending project-path upload before reusing it; if
|
|
1895
|
-
confirmation fails, repair the upload before treating it as a verified save.
|
|
1896
|
-
Page with \`cursor\` if \`next_cursor\` is set (keep the first row you see per key — it is the newest). Also read \`script_drafts.ingredients\` from
|
|
1897
|
-
\`video_project_read\`: it records which pieces were already approved in the review.
|
|
1898
|
-
|
|
1899
|
-
**2. For each planned piece:** compute its digest from the args you WOULD send now. If a saved row
|
|
1900
|
-
has the same \`ingredient_key\` AND the same \`input_digest\`, **download it instead of
|
|
1901
|
-
generating**:
|
|
1902
|
-
|
|
1903
|
-
\`\`\`bash
|
|
1904
|
-
curl -fsSL "$URL" -o /tmp/gooseworks-video/<project_id>/<path> # URL = that row's \`url\`
|
|
1905
|
-
\`\`\`
|
|
1906
|
-
|
|
1907
|
-
That \`url\` is a short-lived (~15 min) presigned S3 GET the server signs for you, so it needs no
|
|
1908
|
-
auth header — download right after listing (list again if it expired). **Never fetch the
|
|
1909
|
-
\`/api/ads/projects/<id>/render-file?path=…\` route from the sandbox:** it needs the app's
|
|
1910
|
-
browser session and answers 401 to a token. Check the file is non-empty and plays (ffprobe for
|
|
1911
|
-
audio/video, open the image); if the download fails or the file is broken, regenerate the piece.
|
|
1912
|
-
Only generate what is missing or whose digest changed — a changed digest means the inputs changed,
|
|
1913
|
-
so the old file is stale.
|
|
1914
|
-
|
|
1915
|
-
**Pass the digest to the proxy too:** \`fal_generate(..., input_digest=digest)\` (and
|
|
1916
|
-
\`fal_generate_video\` / \`fal_whisper\`). A piece that was generated but never saved (the sandbox
|
|
1917
|
-
died between the fal result and the upload) is then handed back by the proxy instead of paid for
|
|
1918
|
-
again, even though its input URLs changed. Only pass \`new_take=True\` when the user wants a
|
|
1919
|
-
different take of the same inputs.
|
|
1920
|
-
|
|
1921
|
-
**3. After EACH piece is generated AND passes its own QC, upload it right away** — don't batch
|
|
1922
|
-
the uploads to the end:
|
|
1923
|
-
\`media_upload { brand_id, scope: "video_project", scope_id: project_id, kind, path:
|
|
1924
|
-
"working/<role>/<file>", ingredient_key, input_digest, source: { type: "file", filename,
|
|
1925
|
-
content_type } }\` → PUT the bytes to \`upload.url\` with \`upload.required_headers\` →
|
|
1926
|
-
\`media_confirm { brand_id, media_id: media.id }\`. Require a successful confirmation.
|
|
1927
|
-
Kind: \`audio\` (VO), \`music\`, \`image\` (a still),
|
|
1928
|
-
\`video\` (a clip), \`endcard\`, \`document\` (captions / a JSON sidecar), \`render\` (the master),
|
|
1929
|
-
\`thumbnail\`. Re-uploading the same key is fine — the newest wins. A piece that FAILED QC is never
|
|
1930
|
-
uploaded under its key. **Save a piece's sidecars with it** under \`<key>.<name>\` — e.g. the VO's
|
|
1931
|
-
char-level timestamps as \`vo/scene-03.timestamps\` (\`kind: "document"\`, same digest). Captions are
|
|
1932
|
-
built from them; without them a resumed run has to fall back to Whisper timings, which mis-case
|
|
1933
|
-
brand names.
|
|
1934
|
-
|
|
1935
|
-
**4. Keep the approved review unchanged during production.** Record each confirmed piece's
|
|
1936
|
-
\`media_id\`, \`path\`, \`ingredient_key\` and \`input_digest\` locally; the confirmed media rows
|
|
1937
|
-
and render progress are the durable resume record. Before approval, mirror the draft ingredients
|
|
1938
|
-
as part of Step 3. After approval, do NOT write \`patch.script\` or \`script_drafts\` during any
|
|
1939
|
-
paid production, QC or repair step, or while provider work is pending. A review-set write clears
|
|
1940
|
-
approval and can stop the next paid step, including a batch concept. Save the final descriptive
|
|
1941
|
-
review once all paid work is finished and settled, as Step 4.5 requires.
|
|
1942
|
-
|
|
1943
|
-
Any material creative change or ANY change the user asked for in this chat must stop production:
|
|
1944
|
-
save the changed complete plan and full credit total, then obtain fresh approval before continuing.
|
|
1945
|
-
Never reuse the earlier yes for a changed plan. A repair that restores the approved choices can
|
|
1946
|
-
continue within the existing allowance and Stop guards without rewriting the approved review.
|
|
1947
|
-
|
|
1948
|
-
The \`final\` master and \`final-thumb\` poster (Step 4.4) carry \`ingredient_key\` too, so a
|
|
1949
|
-
resumed run that finds a passing \`final\` with the same digest only needs to publish.
|
|
1950
|
-
|
|
1951
|
-
## Finished video, interrupted saving — resume the same version
|
|
1952
|
-
|
|
1953
|
-
If the final already passed QC and the customer says **"finish saving this video"**, start here.
|
|
1954
|
-
Do not restart the recipe, choose another format, open another render, generate a take, or run a
|
|
1955
|
-
paid transcript check again. Saving uses the **same render_id**. The ordinary first-completion
|
|
1956
|
-
video fee can still apply; its existing same-render idempotency prevents a duplicate fee. Never
|
|
1957
|
-
promise that all saving is free.
|
|
1958
|
-
|
|
1959
|
-
**Before the first final upload**, save the final review set and production manifest from Step
|
|
1960
|
-
4.5/4.6 (including any QC repairs) only after all paid work is finished and settled. Preserve the
|
|
1961
|
-
approved creative choices; a material change requires the changed-plan approval flow first.
|
|
1962
|
-
After that final save, start no new provider or render work: prepare the checkpoint and finish
|
|
1963
|
-
the same opened render using its existing finishing allowance and guards. A released allowance
|
|
1964
|
-
or stopped/capped render requires normal recovery; never reopen or bypass approval.
|
|
1965
|
-
Write a durable local checkpoint outside the fetched-scripts cache. Keep the actual
|
|
1966
|
-
final, JPEG poster, structured passing quality report, and review evidence files alongside it in
|
|
1967
|
-
a retained local working folder. Record their SHA-256 **at the time those exact bytes pass QC**;
|
|
1968
|
-
never attach an old verdict to a newly hashed replacement. A sandbox's local disk can disappear:
|
|
1969
|
-
this checkpoint recovers connection interruptions, not lost storage. Save ingredients remotely
|
|
1970
|
-
as above and tell the customer if the checked local output is no longer available.
|
|
1971
|
-
|
|
1972
|
-
With the current CLI and its normal login to the selected environment, write a manifest like:
|
|
1973
|
-
|
|
1974
|
-
\`\`\`json
|
|
1975
|
-
{
|
|
1976
|
-
"brand_id": "<owning brand>", "project_id": "<same project>", "render_id": "<already opened render>",
|
|
1977
|
-
"input_digest": "<assembly input digest>",
|
|
1978
|
-
"final_path": "/absolute/retained/working/final.mp4",
|
|
1979
|
-
"poster_path": "/absolute/retained/working/final-thumb.jpg",
|
|
1980
|
-
"qc": {
|
|
1981
|
-
"final_sha256": "<64 lowercase hex characters recorded during final QC>",
|
|
1982
|
-
"poster_sha256": "<64 lowercase hex characters recorded during poster review>",
|
|
1983
|
-
"report_path": "/absolute/retained/working/quality-report.json",
|
|
1984
|
-
"evidence_paths": ["/absolute/retained/working/review/finished-ad.json"]
|
|
1985
|
-
}
|
|
1986
|
-
}
|
|
1987
|
-
\`\`\`
|
|
1988
|
-
|
|
1989
|
-
Run \`gooseworks video-save prepare --manifest <manifest.json> --checkpoint <retained/save-<render_id>.json>\`
|
|
1990
|
-
before any upload, then \`gooseworks video-save resume --checkpoint <same checkpoint>\` for both
|
|
1991
|
-
normal saving and recovery. The helper uses the saved login and canonical MCP connection; it does
|
|
1992
|
-
not copy credentials or use a raw Ads REST fallback. Its atomic private checkpoint binds the
|
|
1993
|
-
environment, account, project owner, project/render, final/poster bytes, assembly digest, passing
|
|
1994
|
-
quality report, review set, evidence files and stage receipts. Preserve it until delivery. Never
|
|
1995
|
-
edit the checkpoint to clear a failed check. Keep checkpoint and manifest files out of commits.
|
|
1996
|
-
|
|
1997
|
-
The helper reads remote state before writes. It keeps \`final\` / \`final-thumb\` ingredient keys
|
|
1998
|
-
and writes per-render paths \`working/final-<render_id>.mp4\` / \`working/final-<render_id>-thumb.jpg\`
|
|
1999
|
-
so saving this version cannot overwrite an older one. It confirms pending uploads, checks remote
|
|
2000
|
-
bytes against the QC hashes, and reuses confirmed media. A request with missing stored bytes can
|
|
2001
|
-
get a fresh upload URL at that same path. A lost completion reply is unknown until project read
|
|
2002
|
-
confirms the same render's output and passing report; then only final selection remains.
|
|
2003
|
-
|
|
2004
|
-
**No CLI / a host-selected MCP connection:** keep the same protocol with the host's canonical
|
|
2005
|
-
tools. Atomically write versioned JSON locally (write a private same-directory temporary file,
|
|
2006
|
-
flush/fsync, rename, then fsync the directory) before any upload and between each upload request,
|
|
2007
|
-
PUT, confirmation, completion and final selection. Persist only public environment identity,
|
|
2008
|
-
account/owner/project/render IDs, file paths/sizes/hashes, input digest, exact quality report and
|
|
2009
|
-
evidence fingerprints, saved-review digest, media IDs and stage states; **no tokens, session IDs,
|
|
2010
|
-
signed URLs or auth headers**. On reconnect call \`account_whoami\`,
|
|
2011
|
-
\`video_project_read { brand_id, project_id, include: ["renders"] }\` and
|
|
2012
|
-
\`media_list { brand_id, scope: "video_project", scope_id: project_id, ingredient_key, input_digest }\`
|
|
2013
|
-
on the original connection. Compare identities, local/evidence hashes and saved review; verify
|
|
2014
|
-
confirmed remote bytes too. Treat a lost reply as unknown and read back before retrying. Use only
|
|
2015
|
-
the missing \`media_upload\` → PUT → \`media_confirm\`, same-render \`video_render_run { render: … }\`
|
|
2016
|
-
callback and \`video_project_upsert\` with only \`patch.final_render_id\` and
|
|
2017
|
-
\`patch.final_selection_guard: { expected_final_render_id, expected_review_digest }\`; never a
|
|
2018
|
-
render-open call. The expected final is the last read's pin, including explicit \`null\`; the
|
|
2019
|
-
review digest is SHA-256 of recursively sorted-key JSON
|
|
2020
|
-
\`{script: project.script ?? null, script_drafts: project.script_drafts ?? null}\` saved at checkpoint
|
|
2021
|
-
creation. First confirm the selected server advertises this guard in \`tools/list\`. If absent,
|
|
2022
|
-
stop and request the normal server update/reconnect; an unguarded pin is unsafe. A
|
|
2023
|
-
\`final_selection_conflict\` means the choice or review changed: keep the checkpoint and explain
|
|
2024
|
-
that saving stopped without overwriting it. Retain the
|
|
2025
|
-
strict Step 4.3/4.4 report and Step 4.5 review-set requirements.
|
|
2026
|
-
|
|
2027
|
-
If authorization expired, reconnect/sign in through the normal host/CLI flow on the original
|
|
2028
|
-
connection, then resume. Missing tools are a reconnect requirement, not permission to switch
|
|
2029
|
-
environments. Missing/changed files, stale/missing QC, changed account/owner/review, another final
|
|
2030
|
-
selection, or a stopped/capped/failed/blocked render require diagnosis; do not reopen it or
|
|
2031
|
-
regenerate automatically. If saving stops, say: **"Your video is finished locally, but saving to
|
|
2032
|
-
Goose was interrupted."** Link the actual local file and preserve its checkpoint. Claim saved
|
|
2033
|
-
delivery only after a fresh project read verifies completion and selection of that exact render.
|
|
2034
|
-
|
|
2035
|
-
## Step 0 — project id, or video BATCH id? (fan out before anything else)
|
|
2036
|
-
|
|
2037
|
-
The handoff is EITHER a single \`project <id>\` OR a \`video batch <id>\`. A batch is
|
|
2038
|
-
the app's "N concepts" flow: one composer submission fans out into **N independent concept projects**
|
|
2039
|
-
(the user picked a concept count, default 3), and the app expects EACH to be rendered. **Handle both:**
|
|
2040
|
-
|
|
2041
|
-
- **\`project <id>\`** → you have one project. Treat it as a batch of one and continue to Step 1.
|
|
2042
|
-
- **\`video batch <id>\`** → call \`video_project_read { brand_id, batch_id }\`. It returns every child
|
|
2043
|
-
concept under \`projects[]\` — each is a normal project with its own \`id\`, \`variant_index\`
|
|
2044
|
-
(Concept 1..N), and its own \`creative_brief\` (the per-concept angle/hook/offer/message). **You
|
|
2045
|
-
MUST process every concept, not just the first** — dropping concepts 2..N is the #1 batch bug.
|
|
2046
|
-
|
|
2047
|
-
**Loop shape (ONE approval for the batch, isolated work per concept):**
|
|
2048
|
-
1. Run **Step 1 + Step 1.5 + Step 2 + Step 2.5 + Step 3-assemble** for EACH concept project (each
|
|
2049
|
-
has its own \`project_id\`, brief, \`GW_PROJECT_ID\` and \`working/\` folder — never cross-write
|
|
2050
|
-
between concepts). The brand read (Step 1 item 2) and \`brand-rules.json\` (Step 1.7) are per
|
|
2051
|
-
BRAND: do them once for the batch and copy the file into each concept's \`working/\`. The read is
|
|
2052
|
-
~90K characters. Step 2.5's angle bank is shared per brand AND product: load or build it once, and
|
|
2053
|
-
give every concept whose angle is \`auto\` a DIFFERENT angle from that list, so the batch is N
|
|
2054
|
-
different ads, not one ad N times.
|
|
2055
|
-
2. Mirror EVERY concept's review set (Step 3's \`video_project_upsert patch.script\` per project),
|
|
2056
|
-
then stop for **ONE** approval in this chat that covers all concepts. Save each render_estimate.total_credits
|
|
2057
|
-
(previews + render + the 200 base fee) and the batch total. Widget: one line; text: card.text_summary. Set the batch to \`review\` (\`video_project_upsert
|
|
2058
|
-
{ brand_id, batch_id, patch: { batch: { status: "review" } } }\`).
|
|
2059
|
-
3. On an explicit yes, record it ONCE for the whole batch: \`video_project_upsert { brand_id, batch_id,
|
|
2060
|
-
patch: { approve: { user_quote: "<their exact words>", total_credits: <the saved total> } } }\`. Check its \`not_ready\` list is
|
|
2061
|
-
empty (a concept listed there has no saved review set: save it, show it, ask again). If they
|
|
2062
|
-
approve only some concepts ("1 and 3 are good, redo 2"), record each approved one with its
|
|
2063
|
-
\`project_id\` instead, and redo the rest. Then set the batch to \`rendering\` and run **Step 4 (the expensive render)** for each
|
|
2064
|
-
concept with up to 8 isolated workers when the machine can sustain them. Retry
|
|
2065
|
-
concurrency_limit after retry_after_seconds; reduce concurrency on a limited machine. Deliver each (Step 5). When every concept is pinned, set the batch to
|
|
2066
|
-
\`complete\`. A concept the Step 4.3 gate leaves \`blocked\` cannot be pinned (a batch concept
|
|
2067
|
-
needs \`passed\`): finish the others, set the batch to \`blocked\`, and tell the user which
|
|
2068
|
-
concepts passed and which are blocked, with each one's failing checks.
|
|
2069
|
-
|
|
2070
|
-
If a single concept fails, keep going with the rest, mark that concept blocked, and report which
|
|
2071
|
-
ones shipped — never abort the whole batch on one bad concept. Everything below (Steps 1–5) is
|
|
2072
|
-
written per-project; a batch just runs it N times with the shared approval gate above.
|
|
2073
|
-
|
|
2074
|
-
## Step 1 — resolve the project, source, brand
|
|
2075
|
-
|
|
2076
|
-
1. \`video_project_read { brand_id, project_id }\` → keep \`brand_id\`, \`source_sample_id\`, \`name\`,
|
|
2077
|
-
\`status\`, the **top-level** \`app_url\` + \`brand_url\` (the links you hand the user for the in-app
|
|
2078
|
-
review in Step 3 and delivery in Step 5), AND the user's **\`creative_brief\`**, project
|
|
2079
|
-
**\`assets\`**, \`character_id\`, \`default_voice_id\` — these are the authoritative inputs the user
|
|
2080
|
-
chose in the composer (see Step 1.5). Do NOT discard them. Then \`export GW_PROJECT_ID=<project_id>\`.
|
|
2081
|
-
Keep its saved \`campaign_id\` and \`campaign_concept_id\` too. If the customer explicitly
|
|
2082
|
-
wants to attach this existing video to a known campaign/concept, verify the IDs with the
|
|
2083
|
-
campaign read and use \`video_project_upsert { brand_id, project_id, patch: {
|
|
2084
|
-
campaign_association: { campaign_id, campaign_concept_id? } } }\` as a separate, sole-field
|
|
2085
|
-
patch. Read back the same project and confirm the saved IDs. Linking never needs a new
|
|
2086
|
-
project, render, generation call or approval. A conflicting saved link stays intact; explain
|
|
2087
|
-
it instead of silently moving the video. Leave unlinked legacy videos alone unless asked.
|
|
2088
|
-
|
|
2089
|
-
### Step 1.5 — the project brief is AUTHORITATIVE (honor it; don't re-ask)
|
|
2090
|
-
|
|
2091
|
-
The composer already collected the user's creative direction onto the project. **Read it and treat
|
|
2092
|
-
it as ground truth — it OVERRIDES the template recipe's defaults, and it REPLACES the clarifying
|
|
2093
|
-
questions you would otherwise ask.** For a field the brief leaves empty, use the Brain search's
|
|
2094
|
-
evidence brief first, then the recipe default, then (last) asking. Map the fields you WILL honor:
|
|
2095
|
-
|
|
2096
|
-
- \`creative_brief.productName\` / \`.offer\` / \`.angle\` → the product, offer/code, and angle. Do
|
|
2097
|
-
**not** ask "which product / what offer / what angle" if these are set.
|
|
2098
|
-
- \`creative_brief.concept\` (on a batch child) → this concept's **\`angle\` / \`hook\` / \`offer\` /
|
|
2099
|
-
\`message\` / \`note\`** — the per-concept differentiator. Honor it verbatim; it's WHY the user asked
|
|
2100
|
-
for N concepts. \`angle: "auto"\` or empty means "you choose."
|
|
2101
|
-
- Project \`assets\` + \`creative_brief.reference_image_urls\` → the user's **own reference images**.
|
|
2102
|
-
Use them as the product/brand refs (alongside the brand kit), don't ignore them for generic recipe
|
|
2103
|
-
assets.
|
|
2104
|
-
- \`character_id\` → the avatar/creator to use. \`default_voice_id\` → the voice for any VO (put its
|
|
2105
|
-
NAME in the review \`subtitle\`). Use these instead of picking your own.
|
|
2106
|
-
- \`creative_brief.durationSeconds\` → target length; honor it when the format allows.
|
|
2107
|
-
\`creative_brief.ratio\` → video ads are ALWAYS 9:16 (1080×1920). If the brief asks for another
|
|
2108
|
-
ratio, make 9:16 anyway and say so in the review; never export another size (a recipe's
|
|
2109
|
-
"also 1:1" option included).
|
|
2110
|
-
- \`polish_policy\` (\`standard\` | \`extra\`) → \`extra\` means spend the extra pass on QC/polish.
|
|
2111
|
-
|
|
2112
|
-
2. Brand gate: \`brand_read { brand_id, sections: ["summary", "kit", "products", "learnings"] }\`
|
|
2113
|
-
(older clients: \`brand_get_context\` with the same sections). Ask for all four: the default
|
|
2114
|
-
leaves out the kit and the brand's saved rules, and a video made without them is off-brand.
|
|
2115
|
-
If the kit's \`researchStatus\` (or the brand's \`research_status\`) is \`complete\`, REUSE it —
|
|
2116
|
-
never re-research. A pending status alone does not require research; use verified stored
|
|
2117
|
-
facts and ask only for an actual gap. If the context is empty or the customer requests
|
|
2118
|
-
research, load \`catalog_fetch { type: "skill", slug:
|
|
2119
|
-
"brand-research" }\` and follow its stored-pack workflow. Only when that verified pack is
|
|
2120
|
-
saved in the supported research workspace, finalize with
|
|
2121
|
-
\`brand_update { brand_id, patch: { finalize_research: true } }\`, then read the brand back.
|
|
2122
|
-
Never send raw research JSON through \`kit_patch\`: the public tool accepts only the existing
|
|
2123
|
-
\`video_lab\` asset slot there. If there is no verified stored pack, submit researched facts
|
|
2124
|
-
through typed \`patch.knowledge\` / \`patch.kit\` as pending agent proposals; do not pretend
|
|
2125
|
-
research is finalized or its proposals are approved. Then do Step 1.7 with verified facts.
|
|
2126
|
-
3. For a new plan, \`catalog_fetch { type: "template", slug: <source_sample_id> }\` → the source
|
|
2127
|
-
video: \`media_url\`, \`recipe\`, \`format\` (e.g. "podcast-skit", "imessage"),
|
|
2128
|
-
\`extracted_script\`, \`how_to\`, \`remix_spec\`. For an approved resume, restore the recorded
|
|
2129
|
-
package and dependencies instead of fetching today's recipe over the saved plan.
|
|
2130
|
-
|
|
2131
|
-
### Step 1.6 — a remix of a FINISHED video (the project read has a \`remix\` block)
|
|
2132
|
-
|
|
2133
|
-
A project made from **Community videos** remakes another customer's finished video for THIS brand.
|
|
2134
|
-
Its \`video_project_read\` returns a top-level \`remix\` block
|
|
2135
|
-
(\`{ remix_of_project_id, instruction, direction }\`), and \`reference_video_url\` is that finished video.
|
|
2136
|
-
|
|
2137
|
-
- **Watch the reference video first** (download \`reference_video_url\`, pull frames + the transcript).
|
|
2138
|
-
It is the target: match its structure, beat order, pacing, framing, look, voice and tone.
|
|
2139
|
-
- **\`remix.direction\` is its approved review set** (scenes and lines, set/look notes, take prompts,
|
|
2140
|
-
captions, music, voice). Start your review set from it instead of the template's defaults; it
|
|
2141
|
-
already carries every change that customer made to the template.
|
|
2142
|
-
- **\`remix.direction.implementation\`, when present, is HOW it was made**: the pipeline and the model
|
|
2143
|
-
each step used, the style and negative prompts, the character and per-scene still/motion prompts
|
|
2144
|
-
with their guards, voice and music settings, the mix, and \`fixes\` (what went wrong and how it was
|
|
2145
|
-
fixed). Reuse the same models, style/negative prompts and guards, rewrite the prompts' subjects for
|
|
2146
|
-
this brand, and apply every \`fix\` up front so you don't repeat the same mistake.
|
|
2147
|
-
- **Rewrite everything for THIS brand.** "[source brand]", "[source product]", "[link]", "[email]"
|
|
2148
|
-
and "[code]" mark the other customer's details: never write them, and never reuse their claims,
|
|
2149
|
-
numbers, URLs, offers or CTA. Every product, claim, name, image and CTA comes from this brand's
|
|
2150
|
-
kit, products and media. Their footage (screen recordings, product shots) and their creator face
|
|
2151
|
-
are NOT carried over: use this brand's own assets and make a new creator from the description.
|
|
2152
|
-
- Precedence: this project's own \`creative_brief\` and assets (Step 1.5) > \`remix.direction\` >
|
|
2153
|
-
the template recipe's defaults.
|
|
2154
|
-
- In the Step 3 review, say it is a remix of that video and list what you kept vs. changed.
|
|
2155
|
-
|
|
2156
|
-
### Step 1.7 — the brand rules file and the brand assets (every run, before any writing)
|
|
2157
|
-
|
|
2158
|
-
Before new writing, write \`working/brand-rules.json\` from the Step 1 brand read. Preserve an
|
|
2159
|
-
approved run's saved rules on resume; reconcile an intentional rule change through the existing
|
|
2160
|
-
review gate. Every later step reads THIS file, not your memory of the chat:
|
|
2161
|
-
|
|
2162
|
-
\`\`\`json
|
|
2163
|
-
{
|
|
2164
|
-
"name": "Acme",
|
|
2165
|
-
"pronunciations": [{ "term": "Acme", "say_as": "ak-mee", "learning_id": "…" }],
|
|
2166
|
-
"must_say": [{ "text": "…", "learning_id": "…" }],
|
|
2167
|
-
"never_say": [{ "text": "Never claim it cures insomnia", "learning_id": "…" }],
|
|
2168
|
-
"products": [{ "id": "…", "name": "…", "facts": ["size, flavour, price, ingredients as stored"], "images": ["…"] }],
|
|
2169
|
-
"logo": { "url": "…", "confidence": "<kit.logoConfidence>" },
|
|
2170
|
-
"fonts": ["…"],
|
|
2171
|
-
"palette": ["#…"]
|
|
2172
|
-
}
|
|
2173
|
-
\`\`\`
|
|
2174
|
-
|
|
2175
|
-
- **Video taste is direction, not dialogue.** Before mapping brand rules, extract entries
|
|
2176
|
-
prefixed \`Video preference:\` from both \`learnings\` and \`kit.instructions\` into the verified
|
|
2177
|
-
taste brief, including accepted proposals. They govern pacing, voices, captions, visuals and
|
|
2178
|
-
format choice; do not copy them into \`must_say\` / \`never_say\` or read them aloud. Carry the
|
|
2179
|
-
brief into the choices, scene planning and review.
|
|
2180
|
-
- **Sources.** \`learnings\` are the brand's saved rules (the user's past corrections among them):
|
|
2181
|
-
\`must\` / \`do\` → \`must_say\`, \`dont\` → \`never_say\`, and a \`must\` whose text reads
|
|
2182
|
-
\`Pronounce "<term>" as "<say_as>"\` (straight or curly quotes) → \`pronunciations\`. Add \`kit.instructions\` (free-text
|
|
2183
|
-
standing rules) only when they require actual spoken wording or prohibit a claim. Production
|
|
2184
|
-
directions stay in the brief. A required spoken line or prohibited claim remains its own
|
|
2185
|
-
ordinary \`must\` / \`dont\` rule.
|
|
2186
|
-
- **Which product.** The one the brief names (\`creative_brief.productName\`); with none, the row
|
|
2187
|
-
whose name matches the product the user asked for, or the brand itself for a one-product
|
|
2188
|
-
brand. Product lists often hold other brands' items or old ads saved as products: if more than
|
|
2189
|
-
one row could be it, ask in the choices round. Never mix facts across rows.
|
|
2190
|
-
- **Product facts** come from that row (name, description, variant, price) and, when the row is
|
|
2191
|
-
empty, from the kit (\`valueProps\`, \`description\`, \`tagline\`): nothing else. Write them to
|
|
2192
|
-
\`products[].facts\`; the script may only state what is there.
|
|
2193
|
-
- **Logo.** Download the kit's logo FILE (\`kit.logoUrl\`, else \`kit.logos[0]\`) to \`working/brand/\`,
|
|
2194
|
-
keeping its real extension (an SVG stays \`.svg\`; rasterise it to a 1024px-wide PNG with
|
|
2195
|
-
\`rsvg-convert\` or \`cairosvg\` when a renderer needs pixels). It is used as-is on every scene and
|
|
2196
|
-
end card that shows a logo: **never generate, redraw, re-letter or restyle a logo with an image
|
|
2197
|
-
model.** If the kit's \`logoConfidence\` says favicon-grade, or the file's long side is under
|
|
2198
|
-
256 px (or it is under 40,000 px²), it is a site favicon, not a logo: do not upscale it. Ask the user for a real logo (or offer the brand name
|
|
2199
|
-
set as text in the brand font) in the SAME question round as the recipe's \`choices\`.
|
|
2200
|
-
- **Font.** \`kit.typography.heading\` when its \`source\` is \`user\` (the user chose it), else
|
|
2201
|
-
\`kit.fonts.heading\`. Download the font file (the kit's own, or the same family from Google
|
|
2202
|
-
Fonts) to \`working/brand/\` and use it for every on-screen line. With no match, use the closest
|
|
2203
|
-
free font and say so in the review.
|
|
2204
|
-
- **No wordmark file.** When a recipe wants a wordmark SVG and the kit has only a logo image, set
|
|
2205
|
-
the brand name as text in the brand font beside the logo file. Never generate one.
|
|
2206
|
-
- Record in \`brand-rules.json\` which logo the video will actually composite (\`logo.file\`), or
|
|
2207
|
-
\`"logo": { "mode": "text" }\` when it will show only the brand name set in the brand font.
|
|
2208
|
-
- **Product images.** Download this product's own images to \`working/brand/\`. Use only images of
|
|
2209
|
-
THIS product: never a catalogue image of another product, a mascot, a lifestyle photo of a
|
|
2210
|
-
person, or a stand-in. If the product has no usable image, ask in the choices round.
|
|
2211
|
-
|
|
2212
|
-
### Brand corrections stick — save them to the brand the moment they are made
|
|
2213
|
-
|
|
2214
|
-
When the user corrects something about the BRAND in chat — how a name is said, a claim that may
|
|
2215
|
-
not be made, a product fact, a visual rule ("never use red", "the logo goes top-left") — save it
|
|
2216
|
-
in the SAME turn, before anything else:
|
|
2217
|
-
|
|
2218
|
-
\`brand_update { brand_id, knowledge_intent: "user_correction", user_statement: <the user's exact correction>, patch: { facts: [{ kind, text }] } }\`
|
|
2219
|
-
|
|
2220
|
-
| Correction | \`kind\` | \`text\` |
|
|
2221
|
-
|---|---|---|
|
|
2222
|
-
| Pronunciation | \`must\` | \`Pronounce "Acme" as "ak-mee"\` (exactly this form) |
|
|
2223
|
-
| A claim or word to avoid | \`dont\` | \`Never say or imply: <the claim>\` |
|
|
2224
|
-
| Something that must be said | \`must\` | \`<the rule>\` |
|
|
2225
|
-
| A product fact | \`must\` | \`<product name>: <the fact>\` |
|
|
2226
|
-
| A visual rule | \`do\` / \`dont\` | \`<the rule>\` |
|
|
2227
|
-
|
|
2228
|
-
- If it changes an EXISTING rule (a new pronunciation for the same term), update that rule by id
|
|
2229
|
-
(\`facts: [{ id: <learning_id>, text }]\`) instead of adding a second one.
|
|
2230
|
-
- Use the correction intent and user's statement when supported, as described below. Read
|
|
2231
|
-
\`brand_read\` learnings back and verify the rule and source before claiming it was saved.
|
|
2232
|
-
- Then tell the user in one line: "Saved to your brand for future videos." Update
|
|
2233
|
-
\`working/brand-rules.json\` and apply the rule to THIS video too.
|
|
2234
|
-
- A one-off note about this video ("make it shorter", "use the blue background here") is NOT a
|
|
2235
|
-
brand rule: don't save it.
|
|
2236
|
-
|
|
2237
|
-
${DURABLE_BRAND_CAPTURE}
|
|
2238
|
-
|
|
2239
|
-
${VIDEO_TASTE_CAPTURE}
|
|
2240
|
-
|
|
2241
|
-
## Step 2 — read the template's recipe (it carries everything; NO hardcoded format map)
|
|
2242
|
-
|
|
2243
|
-
The ad format is a **template (data) in the ad_sample DB**, not a per-format skill.
|
|
2244
|
-
\`catalog_fetch { type: "template" }\` returns the template's \`recipe\` — a self-contained brief you
|
|
2245
|
-
read and execute. **Do NOT map \`format\` to a hardcoded recipe slug** (there is no such table):
|
|
2246
|
-
|
|
2247
|
-
- \`recipe.format\` — the format label (e.g. \`vignette\`), for display only.
|
|
2248
|
-
- \`recipe.atoms\` — the **capabilities** this template composes (e.g. \`create-vo-elevenlabs\`,
|
|
2249
|
-
\`create-image-gpt-image-fal\`, \`render-podcast-skit\`, \`review-ugc-render\`, \`watch\`). Fetch each
|
|
2250
|
-
with \`catalog_fetch { type: "skill", slug }\` (or \`gooseworks fetch <name>\` when the CLI is
|
|
2251
|
-
installed) — they are reused across templates.
|
|
2252
|
-
- \`recipe.instructions\` — the **playbook** to follow: \`instructions.inline\` prose, or
|
|
2253
|
-
\`instructions.doc_url\` (an S3 markdown doc — fetch it).
|
|
2254
|
-
- \`recipe.config\` — every param (prompts, layout, timings, palette, model choices).
|
|
2255
|
-
- \`recipe.inputs\` — the brand-asset contract (which product / logo / offer this template needs).
|
|
2256
|
-
- \`recipe.choices\` — the creative calls the USER makes (who is on screen, narrator, tone, setting,
|
|
2257
|
-
art style, music). Ask every unanswered one in ONE round before any paid step, with its options plus
|
|
2258
|
-
"you pick". Its \`reference\` is what the demo used: an example, never the default.
|
|
2259
|
-
- \`recipe.assets\` — reference material as S3 links (reference render, style guide, example frames) —
|
|
2260
|
-
fetch as needed.
|
|
2261
|
-
|
|
2262
|
-
Runtime: **read the recipe → fetch each capability in \`recipe.atoms\` → follow
|
|
2263
|
-
\`recipe.instructions\` with \`recipe.config\` + the brand's bound \`inputs\`.** The template IS the recipe;
|
|
2264
|
-
there is no \`format → recipe-slug\` table and no per-format skill to fetch.
|
|
2265
|
-
|
|
2266
|
-
Save each fetched capability's content, scripts + files under \`/tmp/gooseworks-scripts/<name>/\`
|
|
2267
|
-
(layout in "Running in a GooseWorks sandbox"). If a capability is a Node package (a phone-mockup
|
|
2268
|
-
renderer), install its documented dependencies in the folder containing its \`package.json\`,
|
|
2269
|
-
and preserve the recorder's documented \`NODE_PATH\` — local machines only; in a sandbox that
|
|
2270
|
-
format stops (no Chromium).
|
|
2271
|
-
|
|
2272
|
-
**Selected browser readiness — before ANY paid ingredient:** identify the actual browser script
|
|
2273
|
-
from the fetched capability's instructions (including an HTML end-card renderer if used).
|
|
2274
|
-
For Node scripts using \`require('playwright')\` with default \`chromium.launch()\`, run
|
|
2275
|
-
\`gooseworks doctor --renderer-script "/absolute/path/to/the/fetched/scripts/record.js"\`.
|
|
2276
|
-
Substitute the actual script, and keep the same cwd and environment as the render, including
|
|
2277
|
-
\`NODE_PATH\` and \`PLAYWRIGHT_BROWSERS_PATH\`. It resolves Playwright relative to that script,
|
|
2278
|
-
launches and closes Chromium with the default settings and bounded waits, and downloads nothing.
|
|
2279
|
-
On failure, stop before spending, show its folder-specific repair and recheck after setup.
|
|
2280
|
-
For non-browser formats use \`doctor --no-browser\` plus their documented runtime checks;
|
|
2281
|
-
never combine \`--no-browser\` with \`--renderer-script\` or use it to bypass a browser renderer.
|
|
2282
|
-
|
|
2283
|
-
**No CLI or CLI without these flags:** run an equivalent free probe in a separate Node process: use
|
|
2284
|
-
\`require('node:module').createRequire(require('node:path').resolve(actualRendererScript))\`
|
|
2285
|
-
to load \`playwright\`; keep the render's cwd, environment and default launch settings. Await
|
|
2286
|
-
\`chromium.launch({ timeout: 15000 })\`, then await \`browser.close()\` (bound close to 3 seconds).
|
|
2287
|
-
Bound the whole process to 20 seconds and stop its own process tree on failure or timeout.
|
|
2288
|
-
Report the resolved module path/version and error without credentials. Missing module, executable,
|
|
2289
|
-
headless runtime or failed launch is a failed check; a cache folder, executablePath alone or
|
|
2290
|
-
another project's browser is not a pass. Other browser packages, Python renderers or custom
|
|
2291
|
-
launch settings need the same free launch/close check through their documented runtime and
|
|
2292
|
-
actual settings. Do not replace their browser/channel/flags to get a pass. Setup is a separate
|
|
2293
|
-
action under existing permissions; this check never silently installs or downloads anything.
|
|
2294
|
-
|
|
2295
|
-
> **Migration note:** older phone-mockup formats (\`imessage\` / \`chatgpt\` / \`apple-notes\`) whose DB
|
|
2296
|
-
> recipe does not yet carry \`atoms\` / \`instructions\` still hold the legacy \`recipe.thread\` payload;
|
|
2297
|
-
> migrate them to this shape (capabilities + instructions in the DB) — do not reintroduce a CLI map.
|
|
2298
|
-
|
|
2299
|
-
## Step 2.5 — plan words and visuals with \`write-video-ad-script\`
|
|
2300
|
-
|
|
2301
|
-
Every video concept gets creative strategy, including silent formats. Fetch
|
|
2302
|
-
**\`write-video-ad-script\`** through the skill catalogue and follow it before assembling
|
|
2303
|
-
review ingredients. It reuses or fetches **\`ad-angle-miner\`**, binds the researched promise
|
|
2304
|
-
to this template's full recipe, writes words and visuals together, and checks product
|
|
2305
|
-
claims and production fit. Its independent critic is a quality screen, not a forecast
|
|
2306
|
-
of ad performance. The existing Step 3 review and approval remain unchanged.
|
|
2307
|
-
|
|
2308
|
-
- **Carry the research into the writer.** Pass the brand and exact product, audience,
|
|
2309
|
-
objective, offer, CTA, selected template recipe, available assets and the full miner
|
|
2310
|
-
bank or its readable workspace pointer. A selected miner idea includes its angle id,
|
|
2311
|
-
evidence and proof plan, not only its hook. Reuse the shared video-angle-bank.v1 from
|
|
2312
|
-
the brand's video-scripts workspace or this run. Prepare angle-context.json with the
|
|
2313
|
-
writer's preparation script with \`--brief working/script/creative-brief.json\` and use
|
|
2314
|
-
its strict rule check before review. First run the fetched writer's free
|
|
2315
|
-
\`python3 <saved-writer-package>/scripts/verify_handoff.py --package-dir <saved-writer-package> --out working/script/writer-handoff-check.json\` check against those
|
|
2316
|
-
actual saved prepare/lint scripts. Retain the result and script hashes with the run.
|
|
2317
|
-
A provided writer package with a missing checker, failed check or unsupported flag
|
|
2318
|
-
is incompatible: stop this handoff and refresh the package on the same connection.
|
|
2319
|
-
Never use the provisional agent path after a provided package fails validation.
|
|
2320
|
-
Only an actual \`not_found\` for an optional writer permits the explicit provisional
|
|
2321
|
-
agent check below; a required writer remains blocked. Never silently remove the brief,
|
|
2322
|
-
strict check or new shape requirement to run an older parser.
|
|
2323
|
-
Save the sourced brief in the writer's documented
|
|
2324
|
-
shape: exact product/variant, buyer situation, supported mechanism, offer/CTA, constraints,
|
|
2325
|
-
delivery intent, source references, locked copy, applicable prior decisions and unknowns.
|
|
2326
|
-
New custom/template shapes set \`requires_creative_brief: true\`; both writer and critic
|
|
2327
|
-
receive the same angle-context. Carry that brief revision into the scene/tool plan and
|
|
2328
|
-
production manifest; missing evidence stays explicit rather than becoming a claim.
|
|
2329
|
-
- **Already decided stays decided.** The user's angle, hook, batch concept, recipe choice
|
|
2330
|
-
or remix direction is binding. Preserve the selected angle id. Compare executions or
|
|
2331
|
-
hooks inside it; do not reopen the angle choice. An incompatible promise needs a
|
|
2332
|
-
supported execution or an explicit format change before production.
|
|
2333
|
-
- **The recipe owns the production contract.** Its story mechanism, speakers, timing,
|
|
2334
|
-
text limits and visual capabilities win. Inspect the actual recipe and available assets;
|
|
2335
|
-
a catalogue card alone cannot establish fit. An impossible essential visual blocks
|
|
2336
|
-
the proposal until repaired. Do not force a testimonial into every format.
|
|
2337
|
-
- **Research only what is missing.** Fetching the miner does not spend or rerun research.
|
|
2338
|
-
Reuse current facts and prior evidence. The Brain search's evidence brief (citations, the
|
|
2339
|
-
state of each query and open gaps) is the first source for the brief's source references and
|
|
2340
|
-
prior decisions. If paid collection is needed, its permission
|
|
2341
|
-
rides in the existing choices round. A new product with no reviews can use verified
|
|
2342
|
-
facts and a feasible demo; do not require paid research merely to fill a quote quota.
|
|
2343
|
-
- **Choose eligible concepts only.** Take the strongest supported concept and validated
|
|
2344
|
-
hook into review, with up to two viable alternatives when the direction is open.
|
|
2345
|
-
Do not pad three concepts or select the highest-ranked rejected one. If all fail,
|
|
2346
|
-
repair within the brief and recipe before Step 3.
|
|
2347
|
-
- **Optional writer not found or unavailable research.** Only when the optional writer
|
|
2348
|
-
returns \`not_found\`, complete an explicit agent check of claim support, recipe limits,
|
|
2349
|
-
visual feasibility and hook payoff. Record missing provenance and say in the review when
|
|
2350
|
-
research is provisional. A provided incompatible writer or another fetch error stops
|
|
2351
|
-
the handoff. Never report a failed check as a pass.
|
|
2352
|
-
- **The user's exact lines** remain verbatim; use report-only checks and raise material
|
|
2353
|
-
timing, claim or format conflicts without silently rewriting them.
|
|
2354
|
-
- **No spoken words.** Still fit the visual promise, reveal, cards and CTA to the silent
|
|
2355
|
-
recipe. Skip speech writing and spoken checks, not the strategy step.
|
|
2356
|
-
- **Keep private provenance separate.** Store source quotes and links in the research
|
|
2357
|
-
workspace; put only a concise strategy explanation in remixable review data.
|
|
2358
|
-
|
|
2359
|
-
## Shared editorial craft inside this template flow
|
|
2360
|
-
|
|
2361
|
-
Fetch \`video-production-harness\` and read its \`references/editorial-review.md\`,
|
|
2362
|
-
\`references/specialist-handoff.md\` and \`references/hook-compatibility.md\`, plus the
|
|
2363
|
-
review/edit/polish/promote/wrap steps when used. Verify every named file is returned as
|
|
2364
|
-
nonempty text before relying on that package. A version/content hash alone cannot establish
|
|
2365
|
-
that the required guides were published. Missing guides block new template creative work
|
|
2366
|
-
before project writes or paid previews; resolve the package on this same connection. Keep
|
|
2367
|
-
an unchanged approved resume on its recorded package and approvals.
|
|
2368
|
-
Save the fetched version/content hash with this run's capability records. These supply
|
|
2369
|
-
craft and evidence rules inside the template flow; this entry's existing review, paid
|
|
2370
|
-
approval, storage and two-repair limit still apply.
|
|
2371
|
-
Do not turn a template into a custom project or import the custom host's extra gates.
|
|
2372
|
-
|
|
2373
|
-
Before executing a fetched recipe atom, pass the exact brief/script revision, scene/beat IDs,
|
|
2374
|
-
timing, selected product/assets/source windows, performance choice and expected output roles.
|
|
2375
|
-
Check actual scripts/dependencies and free runtime readiness, then validate returned media
|
|
2376
|
-
against that handoff. An interrupted run reuses valid approved media with matching digest;
|
|
2377
|
-
a file merely existing does not prove validity. A missing package/required renderer blocks
|
|
2378
|
-
that route before paid generation, with a concrete supported alternative for review.
|
|
2379
|
-
|
|
2380
|
-
Rough review asks what the cut communicates and whether the proof/payoff serves the hook;
|
|
2381
|
-
fine review diagnoses performance, sequence and local execution; final review checks each
|
|
2382
|
-
actual export. Save the received message from the cut before comparing with the brief where
|
|
2383
|
-
possible. A technically clean incoherent cut returns to script/sequence work; a local caption
|
|
2384
|
-
defect gets a local repair. These internal questions share existing review surfaces.
|
|
2385
|
-
|
|
2386
|
-
Before a hook change, classify same-promise compatible opening versus new-promise/body recut.
|
|
2387
|
-
For example, an automatic report supports “stop copying campaign results”; it does not alone
|
|
2388
|
-
prove “know where to spend the next dollar.” Propose required script/body/coverage changes for
|
|
2389
|
-
the latter. Every restyled opening gets fresh image/action/audio/text review even when words
|
|
2390
|
-
are unchanged. Fetch the existing \`render-hook-replacement\` before selecting that route;
|
|
2391
|
-
a not-found/empty result stops it before generation. Use its actual preflight and preservation
|
|
2392
|
-
checks when available; never build a duplicate renderer or infer publication from source.
|
|
2393
|
-
Compare complete labeled candidates, retain source/body/ending and record the hypothesis.
|
|
2394
|
-
No quality score or recommendation is an observed performance winner.
|
|
2395
|
-
|
|
2396
|
-
## Step 3 — assemble the review set, then get ONE approval (before the expensive render)
|
|
2397
|
-
|
|
2398
|
-
This is a **review-once** flow: save the whole review set to the project, get ONE approval in this
|
|
2399
|
-
chat, then run the
|
|
2400
|
-
expensive render + any remaining paid work end-to-end. Never spend on the expensive render before
|
|
2401
|
-
approval, and don't drip pieces out one at a time and re-pause.
|
|
2402
|
-
|
|
2403
|
-
**What goes in the review — show the REAL cheap pieces, PROMPT only the expensive render.** Split
|
|
2404
|
-
every piece three ways by cost, NOT just "free vs paid":
|
|
2405
|
-
- **FREE** (an iMessage / Apple-Notes HTML mockup, a text/CTA line — rendered locally, no proxy
|
|
2406
|
-
call) → generate NOW and mirror the real asset.
|
|
2407
|
-
- **CHEAP paid** — a single still/image, the creator/avatar frame, the end card, a short voiceover
|
|
2408
|
-
or music bed (each costs cents → roughly **≤ 100 credits**) → **generate these NOW too** and
|
|
2409
|
-
mirror the real asset. The few credits buy a real review: the user SEES the actual creator face
|
|
2410
|
-
and end card and HEARS the VO, instead of judging a prompt. **This OVERRIDES any recipe rule that
|
|
2411
|
-
says to gate ALL paid calls** — only the expensive render below is gated.
|
|
2412
|
-
- **EXPENSIVE paid** — the video take / final AI render / per-line lipsync clips (hundreds of
|
|
2413
|
-
credits) → do NOT generate. Put its **exact prompt/spec** (+ ref image URLs) in the tile. This is
|
|
2414
|
-
the ONE thing approved as a prompt (you can't preview a hundreds-of-credits video for free); it's
|
|
2415
|
-
generated only in Step 4.
|
|
2416
|
-
|
|
2417
|
-
**The expensive render's exact prompt must be in the panel BEFORE you ask for approval** — so a
|
|
2418
|
-
single "go" runs it (plus any remaining paid work) without re-pausing mid-run.
|
|
2419
|
-
|
|
2420
|
-
**Show every cost in CREDITS, never dollars.** 1 credit = $0.01 and media generations bill at
|
|
2421
|
-
provider-cost × 1.2, so **credits ≈ round-up(provider-$ × 120)** per generation, plus a flat
|
|
2422
|
-
**200-credit base per video**. Convert any $ figures to credits and show ONLY credits to the user —
|
|
2423
|
-
never print a "$…" amount.
|
|
2424
|
-
|
|
2425
|
-
**Never assemble/stitch the finished video for review.** The review is of the individual pieces (or
|
|
2426
|
-
their prompts) — never a "full cascade" / "approved cut" clip. Building the whole video before
|
|
2427
|
-
approval defeats the gate (the user opens the review to an already-finished video) and wastes the
|
|
2428
|
-
render (GOOSE-2542). The full video is assembled ONLY in Step 4, after approval. A \`video\`
|
|
2429
|
-
ingredient here is only a genuinely separate SOURCE clip the format needs (e.g. supplied b-roll).
|
|
2430
|
-
|
|
2431
|
-
1. **Assemble every piece the format needs — not just the script.** Read the recipe for the exact
|
|
2432
|
-
list. For a podcast skit that's the **script** (both hosts' lines), the two **host stills**,
|
|
2433
|
-
one **voice sample per host**, and the **end card**; an iMessage video has the bubble thread,
|
|
2434
|
-
the conversation image(s) and the end card. For each piece, decide FREE / CHEAP-paid /
|
|
2435
|
-
EXPENSIVE-paid (above):
|
|
2436
|
-
- **FREE or CHEAP paid** (≤ ~100 credits) → generate it now and upload it with
|
|
2437
|
-
\`media_upload { brand_id, scope: "video_project", scope_id: project_id, kind, path:
|
|
2438
|
-
"working/review/<name>", ingredient_key, input_digest, source: { type: "file", filename:
|
|
2439
|
-
"<name>", content_type } }\` → PUT → \`media_confirm { brand_id, media_id: media.id }\`;
|
|
2440
|
-
after confirmation succeeds, set that
|
|
2441
|
-
piece's \`path\` (+ \`media_id\`, \`ingredient_key\`) in \`script_drafts\` to the project-relative
|
|
2442
|
-
\`working/review/<name>\`. First check "Save as you go" — a piece already saved with the same
|
|
2443
|
-
digest is downloaded, not regenerated.
|
|
2444
|
-
- **EXPENSIVE paid** → do NOT generate. Put the **exact prompt/spec** (and any ref image URLs)
|
|
2445
|
-
in the tile's \`text\` / \`subtitle\` so the user reviews what will be spent on. No \`path\` yet —
|
|
2446
|
-
it's generated in Step 4.
|
|
2447
|
-
Save **render_estimate.total_credits**: previews already spent + pending render + the 200 base fee.
|
|
2448
|
-
Use current server pricing, never a catalog range in place of the full total.
|
|
2449
|
-
**Brand check of the script, before it goes in the panel:** every line, caption and on-screen
|
|
2450
|
-
text is checked against \`working/brand-rules.json\`. Nothing in \`never_say\` appears, in words or
|
|
2451
|
-
in meaning (a paraphrase of a banned claim is still banned). Every product detail (name,
|
|
2452
|
-
flavour, size, price, ingredient, result) comes from \`products[]\` or the kit: anything else is
|
|
2453
|
-
cut, not invented. Add a \`note\` ingredient labelled "Brand rules applied" that lists the
|
|
2454
|
-
pronunciations used and the rules the script respects, so the user sees them.
|
|
2455
|
-
**Answer clarifying questions
|
|
2456
|
-
from the project brief FIRST (Step 1.5)** — only ask the user for a field (angle, which product,
|
|
2457
|
-
offer/code) the \`creative_brief\` leaves empty AND the recipe can't default. Do not re-ask for
|
|
2458
|
-
anything the composer already captured.
|
|
2459
|
-
2. **Mirror the whole ingredient set for review** — \`video_project_upsert { brand_id, project_id,
|
|
2460
|
-
patch: { script: { script_drafts, script } } }\`. \`script_drafts\` is a structured payload of
|
|
2461
|
-
**container-tagged ingredients** so the app renders each piece the right way:
|
|
2462
|
-
\`{ format, scenes?, ingredients: [{ container, label, subtitle?, path?, url?, text? }], render_estimate? }\`.
|
|
2463
|
-
Each ingredient's \`container\` tells the app HOW to show it:
|
|
2464
|
-
- \`image\` (a frame shown in the video), \`endcard\` (the end card), \`avatar\` (a character
|
|
2465
|
-
headshot), \`background\` → rendered as an image tile.
|
|
2466
|
-
- \`voice\` (a voiceover clip — put the voice NAME in \`subtitle\`), \`music\` (the bed),
|
|
2467
|
-
\`audio\` → rendered as an audio player.
|
|
2468
|
-
- \`video\` (a clip) → a video player. \`text\` (a copy line like the CTA) → a text tile.
|
|
2469
|
-
- \`script\` / \`thread\` / \`note\` / \`conversation\` → the written script (or set \`scenes[]\`
|
|
2470
|
-
for the podcast shape, or pass the readable \`script\` string).
|
|
2471
|
-
**Label every ingredient** ("Hook image", "End card", "Voiceover", "Host A", "HER"). The upsert
|
|
2472
|
-
writes no render and costs no credits — it just populates the review panel.
|
|
2473
|
-
3. **STOP for ONE approval, in this chat.** Only a complete current saved review set with
|
|
2474
|
-
render_estimate.total_credits can be approved. Widget: one line, no duplicate plan or app
|
|
2475
|
-
link; otherwise print card.text_summary. The choices are Approve, Change and Not now.
|
|
2476
|
-
“Not now” keeps the plan. In a coworker sandbox end the turn after saving the review set;
|
|
2477
|
-
the customer's approval arrives as the next message.
|
|
2478
|
-
Record the explicit yes with \`video_project_upsert { brand_id, project_id, patch: { approve:
|
|
2479
|
-
{ user_quote: "<their exact words>", total_credits: <the saved total> } } }\` before rendering;
|
|
2480
|
-
its reply says what comes next. A single project requires recorded approval too; never treat an absent approval as permission.
|
|
2481
|
-
Changes require an updated saved review, clearing prior approval, and approval of the new
|
|
2482
|
-
total. One yes authorizes the remaining approved chain. On insufficient_balance start
|
|
2483
|
-
nothing; offer a shorter video or top-up. Remove batch concepts with patch.concepts remove:true,
|
|
2484
|
-
then show the changed total before approval.
|
|
2485
|
-
|
|
2486
|
-
## Step 4 — render, report stages, publish
|
|
2487
|
-
|
|
2488
|
-
1. **Open the render row FIRST** — right after recording the Step 3 approval, before any paid
|
|
2489
|
-
generation (if this returns \`approval_required\`, the approval is missing or was cleared: go
|
|
2490
|
-
back to Step 3 and ask in this chat, don't retry; if it returns \`coworker_makes_it\`, the video
|
|
2491
|
-
was handed to the GooseWorks coworker, so don't render it: the coworker is making it):
|
|
2492
|
-
\`${exports.RENDER_ROW_TOOL} { brand_id, project_id, ${exports.RENDER_OPEN_ARGS} }\` (no \`dry_run\`; returns
|
|
2493
|
-
\`render_id\`) → keep \`render_id\`, then mark it running:
|
|
2494
|
-
\`${exports.RENDER_ROW_TOOL} { brand_id, project_id, ${exports.RENDER_UPDATE_KEY}: { render_id, status: "running",
|
|
2495
|
-
workflow_stage: "preparing", progress_note: "starting", progress_percent: 5 } }\`. The user sees this
|
|
2496
|
-
live in the app and gets a WhatsApp "started" message automatically — don't message them yourself
|
|
2497
|
-
about start / blocked / complete.
|
|
2498
|
-
After EVERY progress callback inspect stop. If true, start no new paid step; record
|
|
2499
|
-
status:"stopped" with a plain note and report what is kept and credits used. SPEND_CAP_REACHED
|
|
2500
|
-
stops the same way. Never raise a video's budget on your own judgment. Raise it only when a paid
|
|
2501
|
-
step was refused with SPEND_CAP_REACHED or the progress card offers "Finish it" or a choice past the budget.
|
|
2502
|
-
Then read the project and say cost.raise_quote in one line: "Finishing needs up to <by_credits>
|
|
2503
|
-
more credits, so your budget goes from <from_credits> to <to_credits>. OK?" Only after the
|
|
2504
|
-
customer's yes to that number: patch.approve { scope:"raise_cap", total_credits: <to_credits>,
|
|
2505
|
-
user_quote: "<their exact words>" }. total_credits is the new budget itself, never credits to
|
|
2506
|
-
add; do not send raise_cap_credits for one video. If they pick a smaller choice past the
|
|
2507
|
-
budget, send that choice's new budget as total_credits (never above to_credits). Sending the same
|
|
2508
|
-
total_credits again changes nothing (already_raised: carry on). An earlier yes, or "I don't care
|
|
2509
|
-
about the cost", is not approval of a new budget. If cost.raise_quote is null because the plan was saved
|
|
2510
|
-
again since its approval (plan_status is not "approved"), show the plan with its total and
|
|
2511
|
-
approve it again; otherwise the approved budget already covers the work: carry on, do not ask.
|
|
2512
|
-
After a raise, open a new render that reuses the saved pieces. A refused raise changes nothing:
|
|
2513
|
-
cap_raise_not_needed means carry on within the budget, or, when it says the plan was saved again,
|
|
2514
|
-
show the plan with its total and approve the plan again; cap_raise_total_required means read the
|
|
2515
|
-
project again and send total_credits equal to cost.raise_quote.to_credits after the customer
|
|
2516
|
-
approves that number; cap_raise_changed or cap_raise_too_large mean read the project again and
|
|
2517
|
-
show the current cost.raise_quote. Custom videos never use raise_cap.
|
|
2518
|
-
Send render.steps with the same neutral names each time and a live count only in the
|
|
2519
|
-
current detail; use render.choices when blocked.
|
|
2520
|
-
2. Now generate every PAID piece you showed as a prompt in Step 3 — the AI stills/video, lipsync
|
|
2521
|
-
clips, voice, music — through the media proxies (below), each from its approved prompt, with
|
|
2522
|
-
\`GW_PROJECT_ID\` exported. **Save as you go** (section above): skip any piece already saved
|
|
2523
|
-
with the same \`input_digest\` (download it), and upload each new piece with its
|
|
2524
|
-
\`ingredient_key\` + \`input_digest\` the moment it passes QC.
|
|
2525
|
-
Keep the approved script and review unchanged throughout production and QC; confirmed media
|
|
2526
|
-
and progress preserve resume state. Stop and replan/reapprove any material creative change.
|
|
2527
|
-
A voiceover made with \`data_post_provider\` (ElevenLabs \`…/with-timestamps\`) returns its
|
|
2528
|
-
\`alignment\` only in the reply: write it to \`working/vo/<scene>.timestamps.json\` at once
|
|
2529
|
-
(captions are timed from it) and record the returned \`media_id\` on the ingredient.
|
|
2530
|
-
**Brand pronunciations in every voiceover:** the text sent to the voice has each
|
|
2531
|
-
\`pronunciations[].term\` replaced by its \`say_as\` (\`create-vo-elevenlabs\`:
|
|
2532
|
-
\`gen_vo.py … --rules working/brand-rules.json\`; when a render atom calls the voice itself,
|
|
2533
|
-
swap the terms in the text you hand it). Captions, on-screen text and the review keep the
|
|
2534
|
-
written name. Write \`working/approved-script.txt\` (the Step 4.3 audio check) with the SPOKEN
|
|
2535
|
-
form. **Logo, font, product:** every logo is the file from Step 1.7 composited as-is; every
|
|
2536
|
-
product shot uses the Step 1.7 product images as its reference.
|
|
2537
|
-
Then assemble per the recipe (ffmpeg stitch; PIL captions / end card;
|
|
2538
|
-
Playwright record only where the format needs it and the host has Chromium → \`mix-master\` audio).
|
|
2539
|
-
**Report progress at each milestone** — about one update per milestone, never per poll:
|
|
2540
|
-
\`${exports.RENDER_ROW_TOOL} { brand_id, project_id, ${exports.RENDER_UPDATE_KEY}: { render_id, status: "running", workflow_stage, progress_note, progress_percent } }\`
|
|
2541
|
-
(\`progress_note\` = plain words the customer reads in the app, ≤200 chars; no model, tool or
|
|
2542
|
-
step names):
|
|
2543
|
-
- voiceovers done → \`"preparing"\`, \`"voices recorded"\`, 20
|
|
2544
|
-
- stills done → \`"preparing"\`, \`"scenes designed"\`, 35
|
|
2545
|
-
- each lipsync / video clip → \`"rendering"\`, e.g. \`"filming scene 5 of 8"\`, 35–75
|
|
2546
|
-
- assembly → \`"rendering"\`, \`"putting the video together"\`, 85
|
|
2547
|
-
- QC (4.3) → \`"final check"\`, 95
|
|
2548
|
-
**Hard stop that needs the user** → \`{ render_id, status: "running", workflow_stage: "blocked",
|
|
2549
|
-
error_message: "<what's wrong + what you need>" }\`; an unrecoverable failure → \`status: "failed"\`
|
|
2550
|
-
+ \`error_message\`. Completing (4.4) sets the bar to 100.
|
|
2551
|
-
3. **MANDATORY final-video QC gate — YOU review EVERY finished master before pinning it
|
|
2552
|
-
(\`patch.final_render_id\`), whatever the format (UGC or not).** This is your own automated quality
|
|
2553
|
-
check, separate from the user's Step-3 approval — it does not go back to the user. The render row
|
|
2554
|
-
is already open (4.1); this gate stands between a rendered master and PINNING/publishing it, so a
|
|
2555
|
-
bad render never gets set as final. A master that looks fine on a still can still have a
|
|
2556
|
-
mis-voiced word, a caption drifting off its line, a beat out of order, or a deformation — review
|
|
2557
|
-
the actual VIDEO, not stills. Run the passes that APPLY to this format:
|
|
2558
|
-
- **Audio ↔ script** — any master with SPEECH (VO or native/Seedance voice); **skip for
|
|
2559
|
-
music-only / no-speech formats.** \`review-ugc-render\` is format-agnostic despite the name —
|
|
2560
|
-
a deterministic Whisper transcript-vs-script diff: persist the approved spoken lines to
|
|
2561
|
-
\`working/approved-script.txt\`, fetch \`review-ugc-render\` (\`catalog_fetch\`) and run
|
|
2562
|
-
\`review_render.py --video <master>.mp4 --script-file working/approved-script.txt --json
|
|
2563
|
-
working/review-verdict.json\` (exit 0 PASS / 2 FAIL / 3 ERROR). For each brand pronunciation add
|
|
2564
|
-
\`--brand-term "<term>"\`, plus \`--brand-term\` for each word of \`say_as\` that is not an
|
|
2565
|
-
everyday word (the flag strips those tokens from the WHOLE diff, so never pass "a", "one",
|
|
2566
|
-
"works" alone): Whisper spells a respelled name back as the brand word ("Goose Works" heard
|
|
2567
|
-
as "Gooseworks"), so the diff must accept it. The proof of
|
|
2568
|
-
intended delivery is the text/settings you sent (keep them in the review); actual
|
|
2569
|
-
pronunciation/performance requires isolated and mixed-audio listening at normal speed.
|
|
2570
|
-
Preserve pauses/emphasis and final consonants; never mandate faster or louder delivery.
|
|
2571
|
-
Verify a transcript mismatch against the actual audio before calling it a defect. It flags a mis-voiced word
|
|
2572
|
-
(approved "human-vetted" → "human witted"), a dropped phrase, or silence. It routes Whisper
|
|
2573
|
-
through the gooseworks proxy when \`OPENAI_BASE_URL\` is set (sandbox:
|
|
2574
|
-
\`$GW_WHISPER_PROXY_URL/v1\`); with no backend at all, run \`fal-ai/whisper\` via the FAL proxy
|
|
2575
|
-
and diff the transcript yourself.
|
|
2576
|
-
- **Captions / subtitles** — ANY captioned format (the most common non-UGC defect); **skip for
|
|
2577
|
-
UGC/Seedance masters, which carry no subtitle track.** Diff the caption file you burned
|
|
2578
|
-
(SRT/ASS/PNG cue list) against the SAME Whisper transcript + word timings — every caption line
|
|
2579
|
-
must match the heard/scripted words and sit within ~0.3s of when they're spoken; then in the
|
|
2580
|
-
visual pass below, inspect each cue and its start/end boundaries in actual frames, plus
|
|
2581
|
-
full-speed playback at destination size, to confirm reading time, product visibility,
|
|
2582
|
-
hierarchy and no duplicate overlay or end-card collision. Silent/text-led formats use
|
|
2583
|
-
approved visible wording and reading windows, not nonexistent speech timings. Mismatched text or >0.3s drift fails the gate.
|
|
2584
|
-
- **Visual + structure** — always: run the \`watch\` skill on the master — beat/scene order + SFX,
|
|
2585
|
-
the brand's product (not the source's) is shown, the end card has the brand's logo file (or its name set in the brand font) + code, no
|
|
2586
|
-
deformation/artifact, duration within ~20% of the source.
|
|
2587
|
-
- **Finished ad + brand fidelity** — always: fetch \`review-finished-ad\` (\`catalog_fetch\`,
|
|
2588
|
-
\`pip install --quiet numpy pillow\` if needed) and run
|
|
2589
|
-
\`review_finished_ad.py --video <master>.mp4 --json working/review/finished-ad.json
|
|
2590
|
-
--sheet working/review/finished-ad-sheet.png --logo <the logo file the video composites>
|
|
2591
|
-
--palette "<kit palette, comma-separated>" --product-images <the Step 1.7 images>
|
|
2592
|
-
--font <brand font file> --brand-name "<name>" --endcard-s <end card length>\`. Pass the
|
|
2593
|
-
file that is ACTUALLY on screen (the kit logo, or the recipe's wordmark file). When the video
|
|
2594
|
-
shows only the brand name as text (\`"logo": {"mode": "text"}\`), omit \`--logo\` and judge the
|
|
2595
|
-
text on the sheet. Add \`--no-speech\` for a format with no VO or dialogue, \`--logo-at <s>\` for
|
|
2596
|
-
each mid-video logo, and any gate flags the recipe's instructions name (a chat format's
|
|
2597
|
-
reading holds need a longer \`--max-freeze-s\`). Exit 0 PASS / 2 FAIL / 3 ERROR. It
|
|
2598
|
-
checks size, hook, pacing, dead air, black frames, the kit logo on the end card
|
|
2599
|
-
(a wrong, redrawn or favicon logo fails) and the palette. **Then open the sheet it writes
|
|
2600
|
-
and judge every line of its \`judge_on_sheet\`:** captions/CTA/logo outside the red safe
|
|
2601
|
-
zones, the brand font, every product shot matching the product images, the product the same
|
|
2602
|
-
in every scene, the logo unaltered. A failed eye check is a FAIL like any other.
|
|
2603
|
-
- **Output size** — always **1080×1920 (9:16)**. Video ads are only ever 9:16. Lipsync / video
|
|
2604
|
-
models often return 720p or odd sizes — scale (and pad if the aspect differs) every clip to
|
|
2605
|
-
1080×1920 BEFORE the concat, never ship the model's native size.
|
|
2606
|
-
Save exact output checksum/version, first-to-last normal-speed playback and full-audio
|
|
2607
|
-
coverage. Frame sheets, transcripts and process success do not substitute for listening or
|
|
2608
|
-
continuous motion. Missing required capability leaves review incomplete/blocked. Each
|
|
2609
|
-
supported crop, duration, language or caption derivative needs its own actual-file review;
|
|
2610
|
-
unsupported destination requirements need a reviewed route, never a silent export change.
|
|
2611
|
-
Honor intended silence, loops and endings rather than forcing music or fades on every ad.
|
|
2612
|
-
If ANY applicable pass fails, FIX it (regenerate/stitch the offending window, re-composite the
|
|
2613
|
-
end card from the real logo file, rebuild captions) and re-run the passes — only a clean pass
|
|
2614
|
-
proceeds to pinning. **At most 2 repair rounds.** If a pass still fails after them, do NOT pin
|
|
2615
|
-
and do NOT present the video as finished: upload it (4.4) and close the row with exactly
|
|
2616
|
-
\`video_render_run { brand_id, project_id, render: { render_id, status: "complete",
|
|
2617
|
-
workflow_stage: "blocked", quality_status: "blocked", repair_pass_count: 2, output_url,
|
|
2618
|
-
thumbnail_url, quality_report } }\` (the failing checks as \`fail\` in the report), and tell the user plainly in
|
|
2619
|
-
chat which checks failed, what you tried, and the choices (fix a specific thing, re-roll, or
|
|
2620
|
-
use it anyway). Pin it only if they say to use it anyway. The app shows a blocked render as
|
|
2621
|
-
"Needs attention". **This gate is universal: it runs from this skill for every format, so a
|
|
2622
|
-
recipe never has to opt in.**
|
|
2623
|
-
4. **For a passing final, create the finished-video checkpoint first**, following "Finished video, interrupted saving"
|
|
2624
|
-
above. With the CLI, use its prepare/resume flow instead of duplicating the writes below; it
|
|
2625
|
-
saves the same already-opened render and pins only the checked output. Save the final review set
|
|
2626
|
-
and production manifest (Step 4.5/4.6) before preparing that checkpoint. Without it, follow the
|
|
2627
|
-
same durable protocol. A blocked version follows Step 4.3's existing upload/report-only path;
|
|
2628
|
-
never route it through the passing-final helper or pin it automatically.
|
|
2629
|
-
Publish: \`media_upload { brand_id, scope: "video_project", scope_id: project_id, kind: "render",
|
|
2630
|
-
path: "working/final.mp4", ingredient_key: "final", input_digest, source: { type: "file", filename: "final.mp4", content_type:
|
|
2631
|
-
"video/mp4" } }\` → PUT the master to \`upload.url\` with \`upload.required_headers\` →
|
|
2632
|
-
\`media_confirm { brand_id, media_id: media.id }\`. Same for the poster (\`kind: "thumbnail"\`, \`path: "working/final-thumb.jpg"\`, \`ingredient_key: "final-thumb"\`).
|
|
2633
|
-
Keep each \`upload.render_file_url\`. Verify the PUT returned 2xx and the file you uploaded is a
|
|
2634
|
-
real, non-empty MP4 (ffprobe it), and require both confirmations to succeed BEFORE marking
|
|
2635
|
-
the render complete.
|
|
2636
|
-
Then \`${exports.RENDER_ROW_TOOL} { brand_id, project_id, ${exports.RENDER_UPDATE_KEY}: { render_id, status: "complete", output_url, thumbnail_url } }\` (attach the Step 4.3 verdict as \`quality_status: "passed"\` (or
|
|
2637
|
-
\`"blocked"\` when the gate still fails after 2 repair rounds) + \`quality_report\` — ALWAYS
|
|
2638
|
-
attach it; a batch concept cannot complete without a passing one; exact shape, strict (no extra keys):
|
|
2639
|
-
\`{ version: 1, summary: string, checks: { source, brand, product, hook_and_scene_order,
|
|
2640
|
-
voice_and_script, captions, endcard_and_cta, duration_and_ratio, visual_artifacts }, detected_issues?:
|
|
2641
|
-
string[], repair_actions?: string[] }\` where EVERY check is \`{ status: "pass"|"fail"|"not_applicable",
|
|
2642
|
-
note?: string }\`). Fill each check from the Step 4.3 passes: \`brand\` ← logo_asset + logo +
|
|
2643
|
-
palette + font + logo unaltered; \`product\` ← product likeness + product consistency;
|
|
2644
|
-
\`hook_and_scene_order\` ← hook + pacing + the \`watch\` beat order; \`voice_and_script\` ← the
|
|
2645
|
-
Whisper diff (pronunciations included) + no \`never_say\` line; \`captions\` ← the caption diff +
|
|
2646
|
-
safe zones; \`duration_and_ratio\` ← ratio + duration; \`visual_artifacts\` ← black frames +
|
|
2647
|
-
frozen stretches + the \`watch\` pass; \`endcard_and_cta\` ← the end card holds the real logo +
|
|
2648
|
-
CTA. Put each failing check's note in \`detected_issues\` and each fix in \`repair_actions\`.
|
|
2649
|
-
**output_url MUST be the durable render-file URL**
|
|
2650
|
-
(\`upload.render_file_url\`, i.e. \`/api/ads/projects/<project_id>/render-file?path=working/final.mp4\`
|
|
2651
|
-
— the app re-presigns it on every view) — NEVER a raw proxy/CDN/presigned URL (those expire).
|
|
2652
|
-
Same for \`thumbnail_url\`.
|
|
2653
|
-
5. **Save the final review set BEFORE pinning** — it must describe the video you actually rendered.
|
|
2654
|
-
Only after all paid production, QC, repairs and pending provider work are finished and settled,
|
|
2655
|
-
save one final descriptive/provenance update: confirmed pieces, exact settings and repairs that
|
|
2656
|
-
preserve the approved creative choices. Material creative changes, including changed lines,
|
|
2657
|
-
look, timing, captions or music, require a changed complete plan, total and fresh approval BEFORE
|
|
2658
|
-
the changed production. Never relabel a changed plan as provenance or silently reuse approval.
|
|
2659
|
-
In the checkpoint flow, save the final review before Step 4.4; do not rewrite it afterward merely
|
|
2660
|
-
to follow the numbered order. Resume checks that this reviewed set stayed unchanged.
|
|
2661
|
-
When final provenance needs updating, upsert the review set once:
|
|
2662
|
-
\`video_project_upsert { brand_id, project_id, patch: { script: {
|
|
2663
|
-
script_drafts, script } } }\` with the final lines, final pieces (mark generated takes as done, not
|
|
2664
|
-
"not generated yet") and the settings you used. The project keeps this, not your chat: it is
|
|
2665
|
-
what the app shows, and what a Community remix of this video copies. Instructions that live only
|
|
2666
|
-
in this conversation are lost when it ends. **Keep the approved detail**: never shorten a piece to a
|
|
2667
|
-
summary (e.g. per-scene prompts or their "no shake / no letterbox" guards). Only update what changed.
|
|
2668
|
-
After this write, do not start new paid work. Save the production manifest, prepare the final
|
|
2669
|
-
checkpoint and complete the same render with its existing finishing allowance and guards.
|
|
2670
|
-
6. **Save the production manifest** — HOW you made it, so the next run (or a remix) starts from what
|
|
2671
|
-
worked instead of rediscovering it: \`video_project_upsert { brand_id, project_id, patch: { production:
|
|
2672
|
-
{ version: 1, pipeline: [{ step, model, purpose?, settings? }], style: { prompt, negative, notes? },
|
|
2673
|
-
characters: [{ name, prompt }], scenes: [{ id, line, still_prompt, motion_prompt, duration_s }],
|
|
2674
|
-
voice: { voice_id, name, model, settings }, music: { prompt, model, length_s }, assembly: { … },
|
|
2675
|
-
fixes: [{ problem, fix }], notes? } } }\`. Use the exact models and prompts you sent (full text, guards
|
|
2676
|
-
included), and list every fix you had to make (e.g. "VO ran 47s → tightened four lines, voice 1.08x";
|
|
2677
|
-
"hair drifted → restated the hair colour"). No URLs, keys or raw logs; it must stay under 48 KB.
|
|
2678
|
-
In the checkpoint flow, save this before Step 4.4 too and skip the duplicate write afterward.
|
|
2679
|
-
7. Pin it — only a \`passed\` render (or a \`blocked\` one the user said to use anyway):
|
|
2680
|
-
If checkpoint recovery already verified selection of this render, skip this duplicate write.
|
|
2681
|
-
An unfinished checkpoint must use the guarded selection protocol above; never replace it
|
|
2682
|
-
with an unguarded pin.
|
|
2683
|
-
\`video_project_upsert { brand_id, project_id, patch: { final_render_id: render_id } }\`,
|
|
2684
|
-
then use the returned card: widget hosts get one line and no duplicate links; text hosts get
|
|
2685
|
-
card.text_summary and the returned delivery links verbatim. Never end with a local file path.
|
|
2686
|
-
|
|
2687
|
-
Narrate each long step in one line via \`video_project_upsert { brand_id, project_id, patch:
|
|
2688
|
-
{ message: { role: "agent", content } } }\` — never sit silent on a queue > 90s. Write it for the
|
|
2689
|
-
customer ("Filming the scenes, about 5 more minutes"), per "How to talk to the customer" above.
|
|
2690
|
-
|
|
2691
|
-
## Media generation — the GooseWorks proxies (queue loop)
|
|
2692
|
-
|
|
2693
|
-
Media APIs go through GooseWorks proxies; do NOT use an SDK's default host (your token isn't a
|
|
2694
|
-
FAL/ElevenLabs token → 401, and in a sandbox a raw provider call is never allowed). Prefer the
|
|
2695
|
-
atoms' own \`media_proxy.py\` (\`fal_generate\`, \`fal_generate_video\`, \`eleven_music\`, …) — it already
|
|
2696
|
-
handles auth, the queue host-swap, project attribution (\`GW_PROJECT_ID\`) and failure logging.
|
|
2697
|
-
|
|
2698
|
-
- **Sandbox:** FAL base = \`$GW_FAL_PROXY_URL\`, ElevenLabs = \`$GW_ELEVENLABS_PROXY_URL\`, FAL
|
|
2699
|
-
storage = \`$GW_FAL_STORAGE_PROXY_URL\`; auth = \`?token=$GW_MEDIA_PROXY_TOKEN\` (or
|
|
2700
|
-
\`Authorization: Bearer\`), plus \`&project_id=$GW_PROJECT_ID\`. The token already names the agent.
|
|
2701
|
-
- **Local:** base = \`<api_base>/api/internal/<proxy>\` (\`fal-proxy\`, \`fal-storage-proxy\`,
|
|
2702
|
-
\`elevenlabs-proxy\`); pass \`?token=<api_key>&agent_id=<agent_id>&project_id=<project_id>\`
|
|
2703
|
-
(agent_id bills the Ads agent; project_id attributes the spend to this ad project so the user
|
|
2704
|
-
sees per-project spend in the app. ALWAYS pass it).
|
|
2705
|
-
|
|
2706
|
-
**FAL queue gotcha** (#1 waste of generations): submit returns \`status_url\`/\`response_url\` on
|
|
2707
|
-
\`queue.fal.run\` (the real host, not the proxy). Polling those 401s forever — rewrite their host
|
|
2708
|
-
to the proxy base (keep the path), re-add the auth params. Only the final \`*.fal.media\`
|
|
2709
|
-
file is a real public URL. Helper (works in both modes):
|
|
2710
|
-
|
|
2711
|
-
\`\`\`python
|
|
2712
|
-
import json, os, pathlib, time, requests
|
|
2713
|
-
from urllib.parse import urlparse
|
|
2714
|
-
|
|
2715
|
-
def _cfg():
|
|
2716
|
-
"""(fal_base, token, agent_id). Sandbox env first, then ~/.gooseworks/credentials.json."""
|
|
2717
|
-
tok = os.environ.get("GW_MEDIA_PROXY_TOKEN")
|
|
2718
|
-
if tok:
|
|
2719
|
-
base = os.environ.get("GW_FAL_PROXY_URL") or os.environ["GW_API_BASE"].rstrip("/") + "/api/internal/fal-proxy"
|
|
2720
|
-
return base.rstrip("/"), tok, None
|
|
2721
|
-
c = json.loads(pathlib.Path(os.path.expanduser("~/.gooseworks/credentials.json")).read_text())
|
|
2722
|
-
return c["api_base"].rstrip("/") + "/api/internal/fal-proxy", c["api_key"], c.get("agent_id")
|
|
2723
|
-
|
|
2724
|
-
def _params(tok, agent):
|
|
2725
|
-
p = {"token": tok}
|
|
2726
|
-
if agent: p["agent_id"] = agent
|
|
2727
|
-
pid = os.environ.get("GW_PROJECT_ID")
|
|
2728
|
-
if pid: p["project_id"] = pid # attributes the spend to this ad project
|
|
2729
|
-
return p
|
|
2730
|
-
|
|
2731
|
-
def fal_generate(model_path, payload, timeout_s=180, poll_s=3):
|
|
2732
|
-
"""model_path e.g. 'fal-ai/nano-banana-2/edit' (the recipe names the model).
|
|
2733
|
-
Export GW_PROJECT_ID first. Returns the result image URL (a public *.fal.media URL)."""
|
|
2734
|
-
base, tok, agent = _cfg()
|
|
2735
|
-
sub = requests.post(f"{base}/{model_path}", params=_params(tok, agent), json=payload).json()
|
|
2736
|
-
to_proxy = lambda u: base + urlparse(u).path
|
|
2737
|
-
status_url, response_url = to_proxy(sub["status_url"]), to_proxy(sub["response_url"])
|
|
2738
|
-
deadline = time.time() + timeout_s
|
|
2739
|
-
while time.time() < deadline:
|
|
2740
|
-
st = requests.get(status_url, params=_params(tok, agent)).json()
|
|
2741
|
-
if st.get("status") == "COMPLETED":
|
|
2742
|
-
return requests.get(response_url, params=_params(tok, agent)).json()["images"][0]["url"]
|
|
2743
|
-
if st.get("status") in ("FAILED", "ERROR"):
|
|
2744
|
-
raise RuntimeError(f"FAL failed: {st}")
|
|
2745
|
-
time.sleep(poll_s)
|
|
2746
|
-
raise TimeoutError("FAL polling exceeded timeout")
|
|
2747
|
-
\`\`\`
|
|
2748
|
-
|
|
2749
|
-
ElevenLabs (VO / music) is the same shape against the ElevenLabs proxy base. To feed FAL a local
|
|
2750
|
-
file (a product image, a VO track), it must be a PUBLIC URL: upload it with \`media_upload\`
|
|
2751
|
-
(\`scope: "video_project"\`, source \`file\`, no \`path\`) → PUT → \`media_confirm\` and use the returned
|
|
2752
|
-
\`media.url\` if it is a public https URL (curl it: HTTP 200 without auth), or host it through the
|
|
2753
|
-
FAL storage proxy. Never pass a \`render-file\` URL to a provider — it needs app auth.
|
|
2754
|
-
|
|
2755
|
-
## Follow-up actions use the watched version
|
|
2756
|
-
|
|
2757
|
-
Keep original note text, exact source render/time and intended viewer effect. Record an
|
|
2758
|
-
acceptance condition and disposition in existing feedback/project artifacts; applying a
|
|
2759
|
-
command means changed, not verified. Consolidate duplicates without deleting their source
|
|
2760
|
-
IDs. Conflicting “calmer” and “more urgent” instructions need the authorized decision owner's
|
|
2761
|
-
recorded choice, even if they touch different files. Offer concrete cheap alternatives for
|
|
2762
|
-
“more premium” inside the approved scope before escalating taste.
|
|
2763
|
-
|
|
2764
|
-
Map changed copy/performance/shot/pause to affected picture, timings, captions, music/SFX,
|
|
2765
|
-
approvals and derivatives; preserve unrelated approved work. Rewatch the full candidate and
|
|
2766
|
-
verify the original effect before resolving a note. Accepted final, candidate and original
|
|
2767
|
-
note source remain distinct across selection and rollback. Keep editable script/timeline,
|
|
2768
|
-
source assets/takes, stems, captions, package versions and prior decisions in the existing
|
|
2769
|
-
production manifest/history; retrieve applicable rejections/pronunciation/delivery rules
|
|
2770
|
-
before a related brief. Project taste is not a standing brand rule. Record audience results
|
|
2771
|
-
only with actual variant/audience/placement/objective/window; otherwise unavailable.
|
|
2772
|
-
|
|
2773
|
-
- “Fix this”: use the render/project context attached to the message (or named version, else
|
|
2774
|
-
the final one). Save patch.fix { of_render_id, changes, total_credits }. Never replace a supplied
|
|
2775
|
-
watched render with the final. After explicit approval save patch.approve { user_quote,
|
|
2776
|
-
total_credits, scope:"fix" }, then video_render_run { kind:"partial", fix_of_render_id }.
|
|
2777
|
-
Re-make only changed scenes, keep earlier versions and charge no second base fee.
|
|
2778
|
-
- “Make 3 more like this”: video_project_upsert { brand_id, name, remix_of_project_id,
|
|
2779
|
-
remix_of_render_id, vary, concepts:3 }. Preserve a provided watched render; omit only when none is named.
|
|
2780
|
-
- “Test 1 of each”: approve only:"test"; “Make the other N”: only:"rest". “Stop the rest”:
|
|
2781
|
-
job_cancel { job_id:<batch_id> }. Finished videos stay saved.
|
|
2782
|
-
- Share for review uses patch.share_for_review { subject }; return the real link.
|
|
2783
|
-
|
|
2784
|
-
## Rules
|
|
2785
|
-
|
|
2786
|
-
- **Canonical MCP tools first** (\`video_project_read\`, \`video_project_upsert\`, \`catalog_fetch\`,
|
|
2787
|
-
\`media_upload\` + \`media_confirm\`, the \`video_render_run\` render-row actions, \`account_whoami\`);
|
|
2788
|
-
legacy names only when the client lacks the canonical tool.
|
|
2789
|
-
- **A missing key is never a blocker.** Paid media goes through the proxy: a one-off image or clip
|
|
2790
|
-
is \`data_post_provider { provider: "fal", … }\` + \`job_get\` (see "Paid media over the MCP");
|
|
2791
|
-
never ask for FAL_KEY, never use \`photos_generate\` for anything but a physical product.
|
|
2792
|
-
- **The CLI and credentials.json are optional.** In a GooseWorks sandbox (\`GW_MEDIA_PROXY_TOKEN\`
|
|
2793
|
-
set) use the env proxies and \`catalog_fetch\`; never call a provider with a raw key.
|
|
2794
|
-
- **No Chromium in a sandbox** — a browser-rendered format stops there, before any spend, and says so.
|
|
2795
|
-
- **Toolchain before spend** — common checks use \`gooseworks doctor --no-browser\`; every selected
|
|
2796
|
-
browser renderer must also pass \`--renderer-script\` or its equivalent exact-runtime launch
|
|
2797
|
-
check in Step 2. Stop with the folder-specific fix if anything is missing.
|
|
2798
|
-
- **Assemble the whole review set first**, mirror it with \`video_project_upsert patch.script\`, and
|
|
2799
|
-
get ONE approval in this chat, recorded with \`patch.approve\`, BEFORE the expensive render
|
|
2800
|
-
(review-once). Never send the user to the app to approve; the app is only for reviewing.
|
|
2801
|
-
- **Show the REAL cheap pieces; PROMPT only the expensive render.** Generate the FREE + CHEAP-paid
|
|
2802
|
-
pieces (≤ ~100 credits — stills, creator frame, end card, short VO/music) and mirror the real
|
|
2803
|
-
assets; put ONLY the expensive video take/render in the panel as its exact prompt. That prompt
|
|
2804
|
-
must be in the panel before you ask to approve, so a single "go" runs the render + any remaining
|
|
2805
|
-
paid work (→ QC → publish) with no re-pausing.
|
|
2806
|
-
- **Operator may be absent (sandbox):** decide mechanical choices yourself; ask in chat only for a
|
|
2807
|
-
true taste call.
|
|
2808
|
-
- **Costs in CREDITS, never dollars.** credits ≈ round-up(provider-$ × 120) per generation + a flat
|
|
2809
|
-
200-credit base per video; never show a "$…" figure to the user.
|
|
2810
|
-
- **Never assemble the full video before approval.** The review shows the
|
|
2811
|
-
individual PIECES, never the finished cut (or their prompts) — not a
|
|
2812
|
-
stitched/composited cut; do not add a "full cascade" / finished-video clip
|
|
2813
|
-
as a review ingredient (GOOSE-2542). The assembled video is produced only in
|
|
2814
|
-
Step 4.
|
|
2815
|
-
- **Open the render row at the start of Step 4** (4.1, after the approval) and keep its stage /
|
|
2816
|
-
progress current; mark it \`complete\` only after the master passes QC. \`output_url\` = the
|
|
2817
|
-
durable render-file URL, never a CDN URL.
|
|
2818
|
-
- **Always export \`GW_PROJECT_ID\`** (and pass \`project_id\` on hand-rolled proxy calls) so the
|
|
2819
|
-
credits attribute to this ad project.
|
|
2820
|
-
- **Verify a real, non-empty MP4** (watch it) before marking the render complete.
|
|
2821
|
-
- **Reuse the brand** when its research is complete; never re-research.
|
|
2822
|
-
- **Brand rules first:** load kit + products + learnings (Step 1), write \`working/brand-rules.json\`
|
|
2823
|
-
(Step 1.7), and follow it: pronunciations in every voiceover, nothing from \`never_say\`, product
|
|
2824
|
-
facts only from the product rows, the kit's logo FILE (never a generated or favicon logo), the
|
|
2825
|
-
brand font, this product's own images.
|
|
2826
|
-
- **Save brand corrections** from chat with \`brand_update patch.facts\` in the same turn, and say so.
|
|
2827
|
-
- **Finished-ad gate on every master** (\`review-finished-ad\` + the sheet); at most 2 repair
|
|
2828
|
-
rounds, then publish as \`blocked\` with the report and warn the user — never pass off a failing
|
|
2829
|
-
video as finished.
|
|
2830
|
-
- On a hard error (auth/quota/model/timeout) set the render \`failed\` with a short
|
|
2831
|
-
\`error_message\` (\`${exports.RENDER_ROW_TOOL} { …, ${exports.RENDER_UPDATE_KEY}: { render_id, status: "failed", error_message } }\`) and stop — don't ship the source unchanged. **Also log
|
|
2832
|
-
it** (see "Report problems") so we can see + fix it.
|
|
2833
|
-
- Finish according to card.display_hint: widget hosts get one short line without duplicate links;
|
|
2834
|
-
text hosts get card.text_summary and the returned delivery links verbatim.
|
|
2835
|
-
${STORED_FOOTAGE_GUIDANCE}`;
|
|
2836
|
-
}
|
|
2837
|
-
/**
|
|
2838
|
-
* Returns the goose-product-photos entry SKILL.md content.
|
|
2839
|
-
*
|
|
2840
|
-
* GOOSE-3190: this skill already existed on disk (`skills/goose-product-photos/
|
|
2841
|
-
* SKILL.md`, hand-maintained) and was already served by the backend to hosted
|
|
2842
|
-
* connectors — but it was NOT in `getEntrySkills()`, so `npm run generate:skills`
|
|
2843
|
-
* never regenerated it and `install` / `update` / login-refresh never wrote or
|
|
2844
|
-
* refreshed it on a user's machine. Moving the body here makes the registry the
|
|
2845
|
-
* one source: one command emits all four entry skills.
|
|
2846
|
-
*
|
|
2847
|
-
* QA-26 / VWR14: chat apps fetch it with `catalog_fetch`, so it names only the
|
|
2848
|
-
* tools the connector lists (`photos_generate` / `photos_read` / `photos_update`,
|
|
2849
|
-
* `brand_read`, `brand_update`, `job_get`).
|
|
2850
|
-
*/
|
|
172
|
+
/** Product photos of the brand's real, physical products. */
|
|
2851
173
|
function getGooseProductPhotosSkillContent() {
|
|
2852
174
|
return `---
|
|
2853
175
|
name: goose-product-photos
|
|
2854
176
|
slug: goose-product-photos
|
|
2855
|
-
description:
|
|
2856
|
-
GooseWorks Product Photos — turn a brand's product images into publish-ready photography
|
|
2857
|
-
(clean studio shots, lifestyle scenes, on-model looks) while keeping the product faithful
|
|
2858
|
-
(silhouette, materials, logo, colorway). You pick a brand + product and submit; the GooseWorks
|
|
2859
|
-
backend runs the SAME server-side pipeline the Product Photos studio uses (compose → generate →
|
|
2860
|
-
judge → auto-retry) and bills credits. Use when the user says "make product photos", "shoot my
|
|
2861
|
-
product", "studio/lifestyle/on-model photo of <product>", "generate product photography", or
|
|
2862
|
-
references a product to photograph. Unlike goose-ads (ad creative) this produces clean PRODUCT
|
|
2863
|
-
photos that can then feed the ad workflow.
|
|
177
|
+
description: Make product photos (studio, lifestyle or on a model) of a brand's real products with GooseWorks in this chat. Start with brand_read and follow the next_step in every answer.
|
|
2864
178
|
category: ads
|
|
2865
|
-
version: 0.
|
|
179
|
+
version: 1.0.0
|
|
2866
180
|
author: GooseWorks
|
|
2867
|
-
tags: [gooseworks, ads, product-photos, photoshoot, product, ecommerce, studio, lifestyle, on-model]
|
|
2868
181
|
---
|
|
2869
182
|
|
|
2870
|
-
# GooseWorks
|
|
2871
|
-
|
|
2872
|
-
The GooseWorks Product Photos skill. You **pick a brand + product and submit one generation**;
|
|
2873
|
-
the **backend** runs the whole pipeline (compose the shot prompt → generate → judge for product
|
|
2874
|
-
fidelity → auto-retry a few times for free) and stores the results. You do NOT
|
|
2875
|
-
generate images, call a model, or manage files — this is the exact same workflow the Product
|
|
2876
|
-
Photos studio uses, so the skill and the app can never drift. The point is to **enrich a brand's
|
|
2877
|
-
usable product imagery** — approved photos join the brand kit and can then feed the ad workflow
|
|
2878
|
-
(\`goose-ads\`).
|
|
2879
|
-
|
|
2880
|
-
It shoots a **physical catalog product** (apparel, beauty, consumer goods). A software
|
|
2881
|
-
screenshot or an app mockup is not a product photo: that is an image edit, not this skill.
|
|
2882
|
-
|
|
2883
|
-
${CUSTOMER_TALK}
|
|
2884
|
-
|
|
2885
|
-
${CLI_TOOL_BRIDGE}
|
|
2886
|
-
|
|
2887
|
-
${connectorPrerequisite('photos_generate')}
|
|
2888
|
-
|
|
2889
|
-
## Start from the brand context — don't re-ask what it already answers
|
|
2890
|
-
|
|
2891
|
-
If the \`gooseworks\` router handed you brand context, USE IT. If you were invoked directly, call
|
|
2892
|
-
\`brand_read { brand_id, sections: ["summary","kit","products","learnings"] }\` yourself first, then
|
|
2893
|
-
\`knowledge_search { brand_id, query: "<the shoot, in the user's words>" }\` for saved rules and past
|
|
2894
|
-
feedback (an archived photo's reason is saved as a \`dont\` rule). They answer most of the setup
|
|
2895
|
-
questions below, so **do not ask the user for them**:
|
|
2896
|
-
|
|
2897
|
-
- **Which product?** — the context's \`products\` are the real catalog entries. Offer them; never
|
|
2898
|
-
invent a product or ask the user to describe one you can already see.
|
|
2899
|
-
- **What does it look like / what is it made of?** — grounded in the product's stored images and
|
|
2900
|
-
description. Never guess a material, colorway, or silhouette.
|
|
2901
|
-
- **What vibe / who is it for?** — the context's voice, positioning, and audience already say. Let
|
|
2902
|
-
them shape the scene and styling instead of asking "what mood do you want?".
|
|
2903
|
-
- **Brand look** — logo, colors, and fonts are owned by the backend research pass. Read them, never
|
|
2904
|
-
re-derive them.
|
|
2905
|
-
|
|
2906
|
-
Ask only for the genuinely open choices: the shot \`category\`, how many photos, quality, and
|
|
2907
|
-
whether a human model is wanted (which needs explicit consent — see the rules).
|
|
2908
|
-
|
|
2909
|
-
## Credits — state the total, then get a yes
|
|
183
|
+
# GooseWorks product photos
|
|
2910
184
|
|
|
2911
|
-
|
|
2912
|
-
|
|
2913
|
-
\`dry_run: true\`. It reserves nothing and returns \`creditsPerOutput\` and \`totalCredits\`. Pass
|
|
2914
|
-
\`count\` and \`quality\` explicitly in both calls so the quote matches the run.
|
|
2915
|
-
- **Nothing paid runs without the user's explicit yes in this chat, given after you state that
|
|
2916
|
-
credit total.** Then submit the same call without \`dry_run\`.
|
|
2917
|
-
- The submit reserves the quoted credits and bills only the photos that pass the judge:
|
|
2918
|
-
**automatic retries are free**, and a photo the judge can't get right (\`flagged\`) is shown but
|
|
2919
|
-
**never billed**. The balance is \`credits.available_credits\` from \`account_whoami\`. If the
|
|
2920
|
-
wallet is short, say so plainly with the total and the balance, and stop.
|
|
185
|
+
Use GooseWorks to photograph the customer's physical products, here in this chat. A software
|
|
186
|
+
screen or an app is not a product photo.
|
|
2921
187
|
|
|
2922
|
-
|
|
188
|
+
- Offer the brand's real products from brand_read; never describe one you can't see. A product
|
|
189
|
+
that isn't listed yet: brand_update adds it from its page. A photo the customer sends:
|
|
190
|
+
media_upload.
|
|
191
|
+
- photos_generate makes the photos: get its price first, tell the customer the credit total, and
|
|
192
|
+
make them only after their yes. Show a person only when the customer asks for one and confirms
|
|
193
|
+
they have the rights.
|
|
194
|
+
- Follow the photos with photos_read until they are ready.
|
|
195
|
+
- Keep or drop photos with media_update. Only kept photos join the brand kit and reach ads.
|
|
2923
196
|
|
|
2924
|
-
|
|
2925
|
-
- \`brand_read\` with no \`brand_id\` — the user's brands (each row's \`id\` is the \`brand_id\`).
|
|
2926
|
-
- \`brand_read { brand_id, sections: ["products"], products_query: "<name>" }\` — the brand's
|
|
2927
|
-
imported products in \`products.items\`; a product's \`id\` is the \`product_id\` to shoot.
|
|
2928
|
-
\`products_query\` matches name / type / variant / SKU / description.
|
|
2929
|
-
- Import a product that isn't in the catalog yet (free):
|
|
2930
|
-
\`brand_update { brand_id, patch: { products: [{ import_url, import_kind, name? }] } }\`.
|
|
2931
|
-
\`import_kind\` is \`product_url\` (a single product page), \`shopify_store\` (a store URL → imports
|
|
2932
|
-
the catalog), or \`image_url\` (a direct image; also needs \`name\`). It returns \`jobs[]\`: poll
|
|
2933
|
-
\`job_get { job_id, kind: "product_import" }\` until it finishes, then read the products again.
|
|
2934
|
-
To add a photo the user attached to an existing product:
|
|
2935
|
-
\`media_upload { brand_id, scope: "product", scope_id: <product_id>, kind: "reference", source: { type: "bytes", filename, content_base64 } }\`.
|
|
2936
|
-
|
|
2937
|
-
**Generate**
|
|
2938
|
-
- \`photos_generate { brand_id, product_id, variant_id?, category, controls?, prompt?, count,
|
|
2939
|
-
quality, reference_image_urls?, attestation_accepted?, dry_run? }\` — **the one call that makes
|
|
2940
|
-
photos** (and, with \`dry_run: true\`, its free quote). \`category\` is \`apparel\` | \`beauty\` |
|
|
2941
|
-
\`cpg\` (seeds sensible scene/framing defaults). \`count\` is 1, 2, 4, or 8; \`quality\` is
|
|
2942
|
-
\`low\` | \`medium\` | \`high\`. Omit \`controls\` to use the category preset; pass \`prompt\` as
|
|
2943
|
-
free-text steering **added on top of** the settings (it doesn't replace them). Returns the
|
|
2944
|
-
generation with its \`id\` **immediately**.
|
|
2945
|
-
**If you request a human model** (\`controls.model.presence\` is not \`none\`) you MUST pass
|
|
2946
|
-
\`attestation_accepted: true\` to confirm the user has the rights for model imagery.
|
|
2947
|
-
- \`photos_read { brand_id, generation_id }\` — poll until \`status\` is \`complete\`,
|
|
2948
|
-
\`partial_failure\`, or \`failed\` (\`job_get { job_id: <generation id>, kind: "photo_generation" }\`
|
|
2949
|
-
works too). Each \`outputs[]\` entry has its own \`id\`, \`status\` and, once ready, a
|
|
2950
|
-
\`final_image_url\`. A \`flagged\` output is the best attempt but wasn't billed.
|
|
2951
|
-
|
|
2952
|
-
**Use the results**
|
|
2953
|
-
- \`photos_read { brand_id, archived?, product_id?, status? }\` — the brand's generated photos
|
|
2954
|
-
(\`archived: false\` = active, \`true\` = archived).
|
|
2955
|
-
- \`photos_update { brand_id, output_id, action: "approve" }\` — approve a photo: links it to the
|
|
2956
|
-
product and makes it available in the **brand kit**, so \`goose-ads\` can use it. **Photos are
|
|
2957
|
-
not used anywhere until approved.**
|
|
2958
|
-
- \`photos_update { brand_id, output_id, action: "archive", reason? }\` — archive a photo; archived
|
|
2959
|
-
photos are **excluded** from ad generation, and the reason is saved as a \`dont\` rule.
|
|
2960
|
-
|
|
2961
|
-
## Workflow — shoot a product
|
|
2962
|
-
|
|
2963
|
-
1. **Load the brand context** (\`brand_read\` + \`knowledge_search\`, or reuse what the router passed
|
|
2964
|
-
you) and **resolve the brand + product.** Pick a \`product_id\` from the catalog you already
|
|
2965
|
-
know about. If the product genuinely isn't there, import it and poll the import.
|
|
2966
|
-
2. **Quote the cost.** \`photos_generate\` with \`dry_run: true\` and the exact \`brand_id\`,
|
|
2967
|
-
\`product_id\`, \`category\`, \`count\` and \`quality\` → tell the user the credit total and wait
|
|
2968
|
-
for their explicit yes.
|
|
2969
|
-
3. **Generate.** The same \`photos_generate\` call without \`dry_run\` (add \`prompt\` built from the
|
|
2970
|
-
brand's voice/positioning you already have — don't interview the user for it). Returns a
|
|
2971
|
-
generation \`id\` right away.
|
|
2972
|
-
4. **Poll.** \`photos_read { brand_id, generation_id }\` every ~20-30s until terminal; show each
|
|
2973
|
-
\`final_image_url\`.
|
|
2974
|
-
5. **Approve the keepers.** Show the results and let the user pick; \`photos_update\` with
|
|
2975
|
-
\`action: "approve"\` the ones they'd publish (that's what puts them in the brand kit for ads),
|
|
2976
|
-
\`action: "archive"\` the rest.
|
|
197
|
+
Then follow the next_step in every answer.
|
|
2977
198
|
|
|
2978
199
|
## Rules
|
|
2979
200
|
|
|
2980
|
-
|
|
2981
|
-
user to reconnect or refresh GooseWorks. Never send a chat-app user to a terminal or a CLI
|
|
2982
|
-
install.
|
|
2983
|
-
- **Never invent product facts.** The backend grounds the shot on the product's real images; don't
|
|
2984
|
-
describe a product you can't see.
|
|
2985
|
-
- **Use the brand context instead of interviewing the user.** Product, audience, voice, positioning,
|
|
2986
|
-
logo/colors/fonts all come from \`brand_read\` / the brand kit. Ask only for the shot
|
|
2987
|
-
category, count, quality, and model consent.
|
|
2988
|
-
- **Ask before spending.** State the dry-run credit total and get the user's explicit yes before
|
|
2989
|
-
the real \`photos_generate\` — it reserves credits.
|
|
2990
|
-
- **Poll, don't re-submit.** A generation that's still \`running\` is not stuck; re-submitting
|
|
2991
|
-
double-bills. A \`failed\` generation may still hold \`flagged\` photos (shown, never billed):
|
|
2992
|
-
show those first, and run again only after a new quote and the user's yes.
|
|
2993
|
-
- **Model imagery needs consent.** Only set a human model when the user asks, and pass
|
|
2994
|
-
\`attestation_accepted: true\`.
|
|
2995
|
-
- **Approval is the hand-off to ads.** Remind the user that only **approved** photos reach the brand
|
|
2996
|
-
kit / ad workflow; archived ones never do.
|
|
201
|
+
${server_entry_skills_1.SERVER_ENTRY_SKILL_RULES.photos}
|
|
2997
202
|
`;
|
|
2998
203
|
}
|
|
2999
|
-
/**
|
|
204
|
+
/** Our server's goose-video entry skill, as built. */
|
|
205
|
+
function getGooseVideoSkillContent() {
|
|
206
|
+
return server_entry_skills_1.SERVER_VIDEO_ENTRY_SKILLS['goose-video'];
|
|
207
|
+
}
|
|
208
|
+
/** Our server's make-custom-video entry skill, as built. */
|
|
3000
209
|
function getMakeCustomVideoSkillContent() {
|
|
3001
|
-
return
|
|
210
|
+
return server_entry_skills_1.SERVER_VIDEO_ENTRY_SKILLS['make-custom-video'];
|
|
211
|
+
}
|
|
212
|
+
/** One line: the kit makes the video when the server says so. */
|
|
213
|
+
function getGooseVideoLocalSkillContent() {
|
|
214
|
+
return `---
|
|
215
|
+
name: goose-video-local
|
|
216
|
+
description: Make an approved GooseWorks video on this computer when the server's next_step says to.
|
|
217
|
+
version: 1.0.0
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
Run \`${exports.KIT_MAKE_COMMAND}\` when the server's next_step says so.
|
|
221
|
+
`;
|
|
3002
222
|
}
|
|
3003
223
|
//# sourceMappingURL=master-skill.js.map
|